ops(archive): TASK prompts and REPORT verifications, studies through V1

2026-08-29 05:22:43 -05:00
parent bd0cea1757
commit b2c4b74d76
37 changed files with 2049 additions and 0 deletions
@@ -0,0 +1,60 @@
+# TASK: Docs standards pass — READMEs and docs/ across ukrrs repos
+
+## Context
+Charles decreed (2026-08-28 ~21:00): ALL project docs must be informative,
+well-formatted, beautiful, and useful. Current MOPAC harness README is 16
+skeleton lines with a stale Gitea path (says reachableceo/MOPAC; org moved to
+ukrrs/MOPAC). This standard applies to every repo we own from now on.
+
+## Scope (in priority order)
+1. `~/projects/meta/MOPAC/harness/` — README.md full rewrite; docs/ polish.
+2. `~/projects/meta/MOPAC/harness/` siblings cloned from Gitea: clone
+   `https://git.knownelement.com/ukrrs/mopac-keyproxy` and
+   `https://git.knownelement.com/ukrrs/mopac-bitwarden-go` under
+   `~/projects/meta/MOPAC/` and upgrade their READMEs (they are spec seeds).
+3. `~/projects/siblings/KNEL-AIMiddleware` (if present) — README audit:
+   fix only what is wrong/stale; do not rewrite working docs wholesale.
+
+## The doc standard (apply to every README; checklist)
+- **Front matter**: H1 title, one-paragraph purpose (what/why/who-for, no
+  throat-clearing), then a `Status:` line — date + one-word state
+  (e.g. `Status: 2026-08-28 — skeleton, MVP demo path live`).
+- **Quickstart**: copy-paste commands that actually work, each block followed
+  by a short expected-output snippet. Verify every command by RUNNING it
+  (e.g. `./bin/harness once --dry-run --demo`, `./bin/harness help`).
+  Never document an unverified command.
+- **Architecture**: a mermaid flowchart of the conductor loop
+  (intake -> routing -> bounded turn -> REPORT) plus one paragraph of prose.
+- **Reference tables** (not prose walls):
+  - CLI: subcommands, flags, exit codes (0/1/2/4) — from actual help output.
+  - Config: every `harness.toml` section with one-line meaning (from
+    harness.toml.example + internal/config).
+  - Model routing: the `[models]` tier map as a table (class -> model).
+- **Status table**: Works / Stubbed / Next — sourced from REPORT.md, kept
+  honest.
+- **Formatting**: fenced code with language tags; headings never skip levels;
+  consistent terminology (harness, conductor, turn, REPORT capitalized as
+  shown); no dead links; no TODO markers without an owner; correct repo
+  URLs (git.knownelement.com/ukrrs/...).
+- For keyproxy/bitwarden-go seeds: purpose, scope, non-goals (no admin UI,
+  memory-only), license (AGPLv3), status line, and what exists today vs
+  planned — the spec READMEs already carry the design; make them navigable.
+
+## docs/ polish (MOPAC only)
+- Each PORTING-NOTES-*.md gets the Status front-matter line.
+- DESIGN.md gets a short table of contents after its intro (section list,
+  anchor links). Do NOT rewrite or reorder existing sections.
+
+## Constraints
+- DOCS ONLY. No source code changes. No new sections in DESIGN.md.
+- This turn runs AFTER pmo-ops and events-receiver complete (dispatch is
+  gated); the repo working tree will be clean and pushed when you start.
+- Verify-then-write: read the code/help/config you are documenting.
+- Commit per repo with clear messages; push to ukrrs remotes.
+
+## Deliverables
+- Commits + pushes: MOPAC (README + docs/), mopac-keyproxy, mopac-bitwarden-go,
+  (KNEL-AIMiddleware if touched).
+- `REPORT-20260828-docs-standards.md` in `~/.coordinate/inbox-pmo/`: per-repo
+  summary of changes, the checklist items applied, any doc rot found that you
+  could NOT fix in this pass (list for follow-up).