115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# 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)
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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).
|
|
4. **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.
|
|
5. **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).
|
|
6. **Harness bin/ is gitignored but README quickstart builds into it** —
|
|
correct as designed; noting only so nobody "fixes" it away.
|