ops(archive): TASK prompts and REPORT verifications, studies through V1
This commit is contained in:
@@ -0,0 +1,114 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user