REPORT: docs standards pass — READMEs and docs/ across ukrrs repos

Date: 2026-08-28 Operator: docs-standards turn (TASK-20260828-2100-docs-standards) Status: COMPLETE — 4 repos committed and pushed; verification-first throughout

Method

Read code/help/config before writing a word. Ran every documented command: build/vet/test inside the Docker builder (golang:1.26-bookworm, pulled, pre-authorized), ./bin/harness help, ./bin/harness once --dry-run --demo, and the no-key live-demo error path (exit 1, clean message). Gitea anchor slugs for the DESIGN.md TOC were taken from the rendered page, not guessed.

Per-repo summary

ukrrs/MOPAC (harness) — commit c6da05f, pushed to main

README.md: full rewrite from the 16-line skeleton. H1 + purpose paragraph + Status line; verified quickstart (Docker builder, cp harness.toml.example, dry-run with real output, live-demo bar incl. verified no-key failure output); mermaid conductor flowchart (INTAKE -> ROUTING -> bounded TURN -> REPORT, chaining by re-invocation) + prose; reference tables for CLI (subcommands, flags, exit codes 0/1/2/4 from actual help), config (every harness.toml section + defaults from internal/config), model routing (tier table + class -> tier -> model table); Status table (Works/Stubbed/ Next) sourced from REPORT.md; docs/link section; AGPLv3. Stale reachableceo/MOPAC path replaced with git.knownelement.com/ukrrs/MOPAC.
docs/: all three PORTING-NOTES-*.md got Status front-matter lines (crush/maki: complete, drift possible; secrets: complete, 7 open questions pending Charles, feeds mopac-bitwarden-go). PORTING-NOTES-secrets.md was untracked in the working tree (pre-existing) — now committed.
DESIGN.md: Contents section (19 anchor links, verified against Gitea's rendered ids) after the intro. No sections rewritten, reordered, or added beyond the TOC.

ukrrs/mopac-keyproxy — commit 325a36c, pushed to master

Cloned fresh from Gitea. README upgraded, purpose prose kept: Status line (spec seed, no code yet); Scope (mpk_ placeholders, BW Secrets Manager REST + Vault KV v2/AppRole backends, HTTP hop + keyproxy get CLI); Non-goals (no admin UI ever, not a secrets manager, no disk persistence, no org assumptions); Today-vs-planned table; Design references linking into ukrrs/MOPAC DESIGN.md key-proxy + FLOSS-repos sections (anchors verified) and the sibling repos; AGPLv3.

ukrrs/mopac-bitwarden-go — commit d8c781d, pushed to main

Cloned fresh from Gitea. README upgraded, purpose prose kept: Status line (spec seed, reference study complete, open questions pending Charles); Scope (stdlib REST, no SDK, machine-account auth, porcelain/plumbing, memory-only session handling); Non-goals (no admin UI, not a vault server, no disk cache of values); Today-vs-planned table naming the KNELSecretsManager ADR-002 wrapper as the production interim; Design references into PORTING-NOTES-secrets.md (incl. its 7 open questions), DESIGN.md toolchain-policy + key-proxy anchors, keyproxy sibling; AGPLv3.

ukrrs/KNEL-AIMiddleware — commit 6476304, pushed to main

Audit-only pass (working clone: projects/meta/MOPAC/siblings/ KNEL-AIMiddleware; the task's ~/projects/siblings path does not exist). Fixed only wrong/stale facts:
- License badge + footer said MIT; LICENSE is AGPLv3. Corrected both.
- Production numbers said 31/42 (MCP 27/38); PRODUCTION-READY.md says 33/42 (MCP 29/38). Badge + summary table corrected.
- Clone URL was github.com/KNEL/...; corrected to git.knownelement.com/ukrrs/KNEL-AIMiddleware.git.
- Project structure tree predated tooling-cli/ (redmine, discourse, dns, KNELCredsManager), the 40+ mcp-/lsp-wrapper scripts, run.sh, maintenance.sh, PRODUCTION-READY.md, LSP_SETUP.md — all added.
- scripts/ section missing validate-mcp.sh / validate-all.sh — added.
- Status front-matter line added (org standard) without restructuring.

Checklist applied

Front matter (H1, purpose paragraph, Status line): all 4 repos.
Quickstart verified by running: MOPAC (build/vet/test in Docker builder, help, dry-run, no-key live path; with-key path proven live 2026-08-28 19:29 per log + reports/REPORT-latest.md). Seeds have no runnable code — quickstarts intentionally absent until commands exist (standard: never document an unverified command).
Architecture mermaid + prose: MOPAC (conductor loop).
Reference tables (CLI/flags/exit codes, config sections, routing map): MOPAC.
Status table from REPORT.md: MOPAC.
Terminology (harness/conductor/turn/REPORT), fenced code with language tags, no heading-level skips, no ownerless TODOs: all 4.
Links checked: relative files exist; Gitea anchors verified against rendered HTML; no dead links introduced.
Correct repo URLs (git.knownelement.com/ukrrs/...): all 4.

Doc rot found, NOT fixed in this pass (follow-up list)

go.mod module path stale: git.knownelement.com/reachableceo/MOPAC/ harness (and all internal import paths) predate the ukrrs transfer. Source change — excluded from a docs-only pass. Fix in a code turn, then drop the parenthetical note in the harness README quickstart.
DESIGN.md line ~154 still lists mopac-bitwarden-go as "later" — it is created and seeded now. DESIGN edits were out of scope (TOC only); fold into the next DESIGN append turn.
Duplicate KNEL-AIMiddleware clone: ~/projects/KNEL-AIMiddleware (older location) is now one commit behind the siblings/ clone I pushed. Someone should git pull it or remove it (MIGRATION-projects.md territory).
KNEL-AIMiddleware STATUS.md / PRODUCTION-READY.md / LSP_SETUP.md / JOURNAL.md: not audited this pass (scope was the README); README now trusts PRODUCTION-READY.md's 33/42, which matched its own internal tables. A deeper docs pass could reconcile STATUS.md the same way.
golang:1.26-alpine builder breaks the harness test suite (no bash in the image; internal/tools tests fail). Bookworm image works and is what the README documents. Worth pinning digest + documenting image choice when the builder container is formalized (DESIGN all-dev-in-docker rule).
Harness bin/ is gitignored but README quickstart builds into it — correct as designed; noting only so nobody "fixes" it away.

6.2 KiB Raw Blame History