@naswerks/engineering-loop 0.1.0

package/references/engineering-loop.md

@@ -0,0 +1,298 @@
+<!-- naswerks-loop: version=0.1.0 -->
+# The Engineering Loop — flow, seats, skills, and the ceremony
+
+> The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
+> execution), the seats (Human / Coordinator / Seat, plus the read-only Witness), the ceremony per
+> session, and a bare-bones exchange showing the back-and-forth. Point newcomers at this plus
+> [doc-index](doc-index.md) + [docs-workflow](docs-workflow.md). Operational templates live in the
+> `spec-parent` skill; the seat contract in `spec-seat`.
+<!-- meta: type=guide; status=current; verified={date}; lineage=1 -->
+
+---
+
+## The loop at a glance
+
+**As states, which is what answers "where is this effort right now" — and the shape decides where
+`processed` falls relative to the merge:**
+
+```
+idea -> chartered -> building -> REVIEWED -> fixed? -> retro -> PR'd -> ?
+
+   with a P row      -> processed -> merged <- HUMAN     P runs on the BRANCH and rides the PR, so the
+                                                       living docs and the archive land WITH the code —
+                                                       and its patches are contingent on that merge
+
+   without one       -> merged <- HUMAN -> processed    a cold session later, on the base branch, over
+                                                       one or several finished efforts at once
+```
+
+**That fork is the whole of the P-row decision.** In-pipeline buys docs and code landing together;
+out-of-pipeline buys a clean PR diff and no contingency. Nothing else about the sequence changes.
+
+**As skills:**
+
+```
+Idea                    -> docs-backlog          -> research doc in docs/research/
+Research matures        -> a plan (a plan-approval mode, if the harness has one)
+Plan graduates          -> spec-pipeline         -> docs/research/{topic}/: umbrella + one spec
+                                                    per session + project-status.md (the plan is
+                                                    now throwaway — the specs carry every crumb)
+Same session — CHOOSE THE SEAT:
+  hand-cranked          -> spec-parent           -> this session becomes the COORDINATOR and cuts
+                                                    Prompt #1 (you relay every message)
+  hosted                -> spec-ignite           -> this session becomes the IGNITION COPILOT:
+                                                    verify the brief, derive the stage card, YOU
+                                                    click Create, "kick it", a hosted coordinator
+                                                    runs the whole pipeline; you own parks +
+                                                    completes + the kill-switch
+Per spec (new session)  -> BUILD SEAT            -> recon, PLAN TLDR, rulings, build,
+                                                    FINAL TLDR, docs-write, commit (on call)
+Builds done, if chosen  -> spec-review           -> the OUTSIDE look, before the retro and before the
+  (a pipeline row)                                  PR: code + patterns + composition across seams +
+                                                    the loop's own comms; sessions/code-review.md.
+                                                    Classifies which findings earn a fixit
+  if it found one       -> FIXIT row             -> one per pipeline MAX, coordinator-ruled, only when
+                                                    the pipeline would otherwise ship something untrue
+Close (coordinator)     -> spec-retro            -> the INSIDE look: the ceremony audit, the ledger
+                                                    reconciliation, the true economics; then
+                                                    BUILD COMPLETE + the PR
+Effort done             -> docs-process          -> living docs patched (consuming the working docs
+  (fresh session, or a                              AND code-review.md); specs + working docs
+   pipeline row if chosen)                          archived together to docs/archive/{topic}/
+Then, and ONLY these    -> the human MERGES the PR, and runs the live-checks rows <- THE TWO HUMAN GATES
+Anytime / periodic      -> docs-status, docs-audit-feature, docs-audit-full  <- NEVER a pipeline row
+Alongside, optional     -> spec-witness — a session OUTSIDE the worktree, read-only, zero writes: a
+                           window into a running pipeline so the human can take its pulse without the UI
+```
+
+**Two things are the human's, permanently and by design:** the **merge** (a person in the merge path is
+the point, not a gap) and the **live-checks** rows (a machine cannot hand-test a UI). Everything between
+`idea` and `archived` a pipeline can do for itself.
+
+**`docs-audit-*` is never a pipeline row.** It runs off-hours and scheduled, over the whole doc tree — not
+inside an effort, and not at an effort's close. A stale living doc is not something a pipeline must stop for.
+
+**The pipeline's SHAPE is decided at authoring, not by a runtime flag.** `spec-pipeline` asks whether the
+effort wants a review row and a docs-process row, and writes them into the row table — so the coordinator
+learns the shape by reading its own sequence, and nothing needs a toggle. A pipeline can be plain,
+`+review`, `+review +process`, or `+process`.
+
+## Two loops — both hand-crankable
+
+- **`docs-*` is the knowledge loop** and runs standalone, forever: small/everyday efforts are
+  just *plan, build, `docs-write`, `docs-process`* — no pipeline, no coordinator, a flat working
+  doc. This is the default and it never requires a control plane.
+- **`spec-*` is the execution loop** for work that is more than one session: `spec-pipeline`
+  graduates the plan, `spec-parent` takes the seat, build seats build one spec each. **Each spec is sized
+  for ONE session** — recon, plan, build, suite and FINAL TLDR before the session's context compacts —
+  and the spec count falls out of that: a pipeline of two specs is a pipeline, and so is one of ten. It
+  hands off to the knowledge loop at both ends (research docs in, working docs out).
+- **Either loop runs by hand or hosted.** The manual version is this document's ceremony with the human
+  relaying; the hosted version is the control plane running the same ceremony, machine-relayed. When they
+  drift, this doc + the `spec-parent` skill are the requirements; the control plane follows.
+
+## The seats
+
+| Seat | Who | Holds | Never does |
+|---|---|---|---|
+| **Human** | you | final approvals (plan-approve click, hard questions, push/publish, hand-testing), the relay in manual mode | writes feature code mid-pipeline |
+| **Coordinator** | one long-lived session per effort | the north star + full pipeline context; cuts each seat prompt from the previous session's *actual* results; judges PLAN/FINAL TLDRs; rules with rationale; verifies load-bearing claims itself; owns `project-status.md` | writes feature code; trusts self-reported "N green" |
+| **Seat** | one fresh session per spec | exactly ONE spec; recons the real code first; builds; reports honestly | touches the tracker or memory; commits without the relayed call; runs `docs-write` unprompted |
+| **Witness** *(optional, `spec-witness`)* | a read-only session with substrate access | testifies from rows/transcripts/git when claims conflict or a pipeline looks wedged; answers "whose turn is it" | writes anything; injects anything; rules on anything |
+
+The seat, not the chat, is the product: `project-status.md` must stay current enough that a
+fresh session can resume as coordinator losslessly (`spec-parent {topic}`).
+
+## The skills
+
+| Skill | Loop | When | One line |
+|---|---|---|---|
+| `docs-backlog` | docs | an idea, no time to build | park it as a research doc |
+| `docs-status` | docs | session start | orient: archived / in flight / waiting |
+| `docs-write` | docs | end of any build session (in a pipeline: on the coordinator's call) | finalize the working doc into `docs/working/` |
+| `docs-process` | docs | effort done, fresh session | patch living docs (verified vs code), archive |
+| `docs-audit-feature` / `docs-audit-full` | docs | doc suspected stale / monthly | deep-audit docs against code |
+| `spec-pipeline` | spec | a plan came through and you're committing to it | explode the plan into a numbered spec pipeline — *spare no crumb* |
+| `spec-parent` | spec | right after `spec-pipeline` (same session) or fresh with the topic | assume the coordinator seat |
+| `spec-seat` | spec | **every** seat the coordinator arms, invoked FIRST | **the CONTRACT, not a seat** — the shared half of every seat's procedure. `spec-parent` does NOT compose it: the coordinator writes rulings rather than receiving them |
+| `spec-child` | spec | igniting a build or fixit seat — manual (`spec-child {role} {spec}`) or hosted | **the BUILD JOB only** — one spec, the role's adds, the pin taxonomy, the suite protocol, the fixit variant. Its ceremony comes from `spec-seat` |
+| `spec-ignite` | spec | when an authored pipeline runs HOSTED (the `spec-parent` alternative) | the ignition copilot, and it can run COLD: gates, re-verify the brief's baselines + platform state against live HEAD, derive the stage card (human clicks Create), "kick it" with the brief's own kick text as the task; every UI gap a named finding |
+| `spec-review` | spec | a pipeline's builds are done, if it has a review row | the OUTSIDE look, before the retro and before the PR: correctness/security/**composition across session seams** · the patterns, with every departure identified · the loop's own comms. Two independent passes, consolidated. Classifies which findings earn a fixit; **its value is having none of the pipeline's context** |
+| `spec-retro` | spec | the coordinator's LAST act, after any review and any fixit | the INSIDE look: a substrate-verified grade, the ceremony audit (did the acts write rows?), the ledger reconciliation, the true economics, the blindnesses, the ranked fixit backlog — *a retrospective that cannot indict its own author is marketing* |
+| `spec-witness` | spec | a pipeline looks wedged, or actors' claims conflict | the read-only fourth seat: substrate access, zero writes, zero rulings |
+| `init` | — | a repository that has none of this yet | create the `docs/` shape, the method docs, first drafts of every doc the skills read; `init doctor` says what is missing |
+
+### Where a rule lives — policy, procedure, task
+
+The thing that keeps prompts and skills from drifting apart:
+
+| Kind | Home | Why there |
+|---|---|---|
+| **POLICY** | the un-skippable system-prompt suffix the control plane supplies at open | cannot be skipped, present on every turn |
+| **PROCEDURE — shared** | `spec-seat` | the contract for ANY seat the coordinator arms: blackboard, question lane, parked-call discriminator, verdicts, BELIEFS sha, git shapes, six-section FINAL TLDR, close-out order |
+| **PROCEDURE — per job** | `spec-child` · `spec-review` · `docs-process` | what THIS seat does. The job skill **refines** the seat contract and never contradicts it; a genuine conflict is a finding, not a fork |
+| **TASK** | the seed prompt + the pipeline's `00-ignition-brief.md` | per-run; dies with the run |
+
+A seed's first act is therefore to **invoke its skills** — `spec-seat`, then the job — not to restate them.
+One copy per rule: where a prompt and a skill would say the same thing, the prompt points and the skill
+holds it.
+
+**Why the split exists.** A single base contract every seat kind shared, with the build job mixed in,
+sends the REVIEW row into the umbrella its own charter excludes and offers the DOCS-PROCESS row a
+`docs-write` from a build skill's close-out — the row that has just *emptied* `docs/working/`. One base
+class, three wrong instructions, and none of it visible until the loop runs end to end.
+
+Session boundaries: plan/spec authoring is one session; each spec is one build session;
+`docs-process` is deliberately a *fresh* session; the pipeline's final spec audits the cumulative
+diff.
+
+## The ceremony (one build session)
+
+1. **Coordinator cuts the seat prompt** from the PREVIOUS session's actual shipped shapes — never
+   from the spec's guesses alone. (Template: `spec-parent` skill.)
+2. **Seat recons, states its beliefs** (HEAD sha, dirty files, versions, baselines), then a
+   **PLAN TLDR as plain text** — before any plan-approval presentation — with **questions as
+   numbered options + an embedded recommendation, then STOP**. Never an interactive question tool.
+3. **Coordinator rules**: verdict (`accept` / `accept-with-riders` — fold in and go /
+   `blocking-precondition` / `read-full-plan`), one CAPS ruling per question, decision first
+   then the WHY. The coordinator diffs the seat's beliefs against the ledger before ruling.
+4. **Plan-approve = the freedom moment** (manual: approve + bypass-permissions; hosted: the gate
+   flips). The seat builds uninterrupted; mid-run questions repeat the relay loop.
+5. **Seat ends with the six-section FINAL TLDR** — shipped+verification, verbatim runner
+   summaries (with invocation commands), honest gaps, deferred findings, live checklist
+   entries, staging list + commit HELD + session cost.
+6. **Coordinator verifies one load-bearing claim itself** (receipts compared first; rerun only in
+   doubt), then the **close-out call**: optional fix/rerun, `docs-write` with an itemized
+   carry, COMMIT CALL with the seat's own staging list, push (human approves the push).
+7. **Coordinator flips the tracker row** to SHIPPED + hash and transcribes deferred findings — the
+   seat never writes the tracker. **The coordinator also commits the closing seat's post-push
+   close-out append, byte-untouched, as part of closing the row** — the append lands after the
+   seat's own commit, so left alone it hands the NEXT seat a dirty tree. Goto 1.
+
+**Hard rules:** no commit/push without the relayed call; explicit staging, never `git add -A`, verified
+with `verify-staged`; codegen only through the command `patterns/codegen.md` names; component files as
+`patterns/frontend-patterns.md` states; additive-only, never amend pushed commits; parallel sessions only
+when specs share no files — commits sequence regardless; seats run the pipeline's declared default model
+(allowlist-exact, set at creation), and an investigation-heavy seat may warrant a reasoning-heavier one.
+
+## The exchange, bare bones (headers only — what a session looks like)
+
+```
+COORDINATOR -> Prompt #N: docs preamble, ##PROMPT##, ONE spec + context docs + prior ACTUAL shapes
+               + CEREMONY block
+SEAT        -> PLAN TLDR (BELIEFS: head/dirty/versions/baselines · the plan, 5-10 lines ·
+               QUESTIONS 1..n, options + recommendation), STOP
+COORDINATOR -> PARENT RESPONSE — PLAN {ACCEPTED / ACCEPTED-WITH-RIDERS / …} · rulings 1..n
+               (DECISION — why) · riders · "Go build."
+SEAT        -> (builds free; mid-run question: numbered text, STOP; COORDINATOR ruling; resume)
+SEAT        -> FINAL TLDR — (a) SHIPPED+VERIFICATION (b) VERBATIM RUNNER SUMMARIES (c) HONEST GAPS
+               (d) DEFERRED FINDINGS (e) LIVE CHECKLIST (f) STAGING + commit HELD + cost
+COORDINATOR -> FINAL TLDR ACCEPTED (+ what the coordinator verified itself) · 1. docs-write, carry: …
+               · 2. COMMIT CALL — message: … · then push, report hash
+SEAT        -> books the working doc, commits, pushes, reports hash + post-push status
+COORDINATOR -> tracker row SHIPPED {hash}; transcribes findings; cuts Prompt #N+1
+```
+
+## The blackboard — where the exchange lives
+
+The exchange above is not just chat — it is a pair of FILES per build session:
+
+- **`tldr.md` — the chat.** Append-only, two voices: the seat's PLAN TLDR + numbered
+  questions, the coordinator's ruling appended beneath them, optional mid-build updates +
+  `## PARENT NOTE`s, then the FINAL TLDR. Read top-to-bottom it IS the session's whole
+  conversation, greppable by anchor.
+- **`plan.md` — the document.** The full plan, posted once, corrected on pushback. PULL-only:
+  the coordinator reads it on a `read-full-plan` verdict; it is never force-fed into a wake or chat.
+
+**`sessions/` is the pipeline's conversation, and the whole effort's durable record.** One folder per
+pipeline, **brought into existence by the FIRST seat's close-out commit** — never authored when the
+pipeline is written, and never with a placeholder — then written into by every later seat, and archived
+with the effort:
+
+```
+docs/research/{topic}/sessions/         <- per-session work in {spec-slug}/, effort-wide at the root
+  {spec-slug}/plan.md        each seat   the full plan, posted once, corrected on pushback (PULL-only)
+  {spec-slug}/tldr.md        each seat   the two-voice chat — seat turns AND coordinator rulings interleaved
+  code-review.md             the review  the outside look, if the pipeline had a review row
+  parent-retrospective.md    the coord.  the close-out audit (the inside look)
+  witness-ledger-*.md        a human     the witness is zero-writes, so its ledger arrives by hand
+```
+
+Two files per build session; questions ride the TLDR, and there are no status snapshots because the
+tracker is committed live. **It is TESTIMONY** — an archive pass repairs links elsewhere and leaves
+`sessions/**` byte-untouched, because editing a record to make it tidy is how it stops being one.
+
+Where they live — **hand-cranked:** `docs/research/{topic}/sessions/{spec-slug}/` (ordinary
+repo files, staged at close-out; the coordinator appends rulings with its own file tools; the
+human's relay is a one-line nudge each way).
+
+<!-- control-plane-specific -->
+**Hosted — there is no folder tree the controller can read.** A seat **carries its bytes** to
+`post_plan` / `post_tldr` (verbs under `acts:write`, so a witness ticket structurally cannot post), and
+everything identifying is **server-derived** — pipeline and seat from the verified ticket, and **the rev**
+(newest + 1). *A rev nobody can misstate cannot regress by accident.* The append-only guard is what
+survives the transport: the ladder only climbs, a shorter file is refused, and the same rev with
+different bytes is refused — so the mirror **cannot be clobbered or rewound by a caller that lies, even
+though it can be fed.**
+
+**The coordinator's voice is NOT in the seat's file on the hosted plane.** A coordinator answers with
+`callout` (its sixth drive verb, machine-written, the only downward path), which persists on its own
+artifact lane and closes the question in the **acts ledger**. So **the file says whether a question was
+ASKED; the ledger says whether it was ANSWERED**, and a seat typing a parent-voice heading into its own
+TLDR closes nothing. `callout` **refuses when the charge has no live session** — a coordinator must
+`seat_spawn` before it can rule — and reports **"RULING RECORDED, NOT DELIVERED"** in those words if the
+transport drops it.
+
+The parent-voice block (machinery-written hosted; the hand-cranked coordinator writes it — hand-cranked
+there is no rev counter, so the heading is `## PARENT RULING (plan — {verdict})`; the stable grep prefix
+`## PARENT RULING` is the contract in both modes):
+
+```
+## PARENT RULING (plan rev N — {accept | accept-with-riders | blocking-precondition})
+
+PARENT RESPONSE — PLAN TLDR {VERDICT}. {one sentence naming the best thing in the plan}
+Answers:
+1. {RULING IN CAPS} — {decision first, then the why}.
+...
+Go build. Fold the riders in — no re-approval round-trip.
+```
+
+Callouts and nudges append as `## PARENT NOTE` (actor-suffixed when known, e.g. `(operator)`).
+
+**The seat's own two anchors:**
+
+```
+## [child·{slug} · run {id}] CLOSE-OUT RECEIPT     <- after the push
+## [child·{slug} · run {id}] HOLDING              <- "I have pushed and I am waiting"
+```
+
+**A question heading, a HOLDING and a close-out receipt are ALL non-staling** — the gates bind an
+acceptance to the accepted CONTENT, not to the revision number, so appending your own *state* leaves it
+intact. Only **new content** stales. A seat that has pushed and is waiting is otherwise indistinguishable
+from a seat that has done nothing, and a coordinator reading a wake led by its own acceptance concludes
+there is nothing to rule — the HOLDING anchor is what prevents that. The token is the literal `child·`
+whatever seat you are — it is a protocol anchor, not a description of you.
+
+### Questions ride the same blackboard
+
+**When you need a decision at any point after your plan:** append a `## MID-BUILD QUESTION` section
+(during recon/plan time the heading is `## QUESTIONS` — two literal headings, one lane, both poke) —
+**that literal heading, in every phase including close-out**, because the detector is heading-matched and a
+synonym is a question no banner announces and no re-raise can reach — to your own `tldr.md`, post it, and
+**end your turn**. The coordinator is woken with your question, and its ruling *is* the answer — so you
+pick it up from your own file and resume. Your turn never stays open waiting, and asking costs the
+pipeline nothing but the round-trip. Plan-time questions and mid-build questions are the same lane and the
+same shape.
+
+An unanswered question is re-raised to the coordinator on a cooldown until a ruling lands, so if the
+coordinator cannot rule yet it appends a note saying so — one append ends the reminder.
+
+<!-- control-plane-specific -->
+**The human-touch receipt is the loop's own instrument.** Every hand-delivered message to a seat leaves an
+`injected_by_human` row, so "how autonomous was this run" is a number, not a floor. The control plane
+mints it on the one authenticated steering door, before the bytes move. The count's credibility rests on
+the credential: **a receipt the audited party can mint is not a receipt** — which is why the steering
+door takes the human's own token and never a seat's job ticket.
+
+## Lineage
+- **Related** — [docs-workflow](docs-workflow.md) · [doc-index](doc-index.md) · the `spec-parent` and `spec-seat` skills (the operational templates and the seat contract)

package/skills/docs-audit-feature/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: docs-audit-feature
+description: Deep-audit one or more living docs (features, infrastructure, or patterns) against the actual code — write an audit report per doc and correct the doc. Use right after touching an area, when a doc is suspected stale, or run docs-audit-feature <doc-path...> (a single doc, a list, or a whole folder).
+---
+
+# docs-audit-feature
+
+Verify living docs against the real implementation and correct them. Works on a single doc, a list of
+docs, or a whole folder — in `docs/features/`, `docs/infrastructure/`, or `docs/patterns/`. This is
+the one audit skill for "does this doc still match the code"; it produces both the **audit report**
+and the **corrected living doc**.
+
+> **The system:** `docs/_meta/doc-index.md` (the menu of living docs) + `docs/_meta/docs-workflow.md`
+> (the loop, folders, templates) explain how the docs are organized. Skim them if you need to place a
+> doc or find its siblings.
+
+> **Audit direction depends on the doc type.** Descriptive docs (`infrastructure/`, `features/`) —
+> **code is truth**: where they disagree, fix the doc. Prescriptive docs (`patterns/`, `guides/`) — the
+> doc is the **decided rule**: audit whether the *code conforms to the doc*; a mismatch is usually a
+> code problem to flag (or a convention to confirm), **not** a doc to rewrite — only edit the doc if the
+> rule itself genuinely changed.
+
+**One doc or many.** Pass a single doc, a group, or a folder — e.g.
+`docs-audit-feature auth signalr postgres` or `docs-audit-feature docs/features/`. Apply the Steps
+below to **each doc in turn** — one full read, verify, report, fix pass per doc, never batching the
+writes across docs. End with a one-line-per-doc summary (stale-count / added-count / clean).
+
+## Steps (per doc)
+
+1. **Read the living doc** (`docs/features/{x}.md`, `docs/infrastructure/{x}.md`, or
+   `docs/patterns/{x}.md`).
+
+2. **Read the corresponding code** — the backend `Features/{Feature}/` slice and matching frontend
+   feature folder for feature docs; the relevant subsystem for infrastructure/pattern docs. Confirm
+   entities, endpoints, stores, routes, services, config, key files.
+
+3. **Check against conventions** — cross-check the doc's claims against `docs/patterns/` (and
+   `docs/infrastructure/` where relevant) so the doc matches how things are actually built.
+
+4. **Report findings** — write a short audit report to `docs/archive/audit/{group}/{doc-name}-audit.md`,
+   where `{group}` mirrors the living doc's folder (`guides/`, `patterns/`, `infrastructure/`, or
+   `features/`; create the subfolder if absent). Date in header: what was accurate, what was stale,
+   what's undocumented, and any **code risks / bugs / tech-debt** you noticed against the source.
+   (The master `health-report-*.md` from `docs-audit-full` stays at the `audit/` root — it's cross-cutting.)
+
+5. **Update the living doc** with the corrections and bump its "Last verified" date — **and refresh the
+   `<!-- meta: … -->` line in lockstep** (`verified` = today, update `status`, recompute `lineage=N`). This is
+   allowed here only because you just did the full doc-vs-code pass; the meta `verified` obeys the same
+   anti-fabrication rule as the blockquote date (the two always move together). **Verify the `## Lineage`
+   footer** — check every link resolves; flag any dead breadcrumb into `## Open Issues` (or the audit report)
+   and recompute `lineage=N` to match. **Soft-check `Spec` / `Built` symmetry** — for a spec-driven feature, a
+`Built` session whose per-slice spec is absent from `Spec` (or vice-versa) is usually an under-scoped row;
+note it and complete it *unless* the doc is deliberately scoped tighter than the effort (judgment, not a hard
+fail — see the Lineage rules in `docs-workflow.md`). **Reconcile its `## Open Issues` section** — add any real, code-verified
+   risk/bug/tech-debt you found (dated, with `file:line`), and remove any listed issue the code now resolves.
+   (The archived report is the history; `## Open Issues` is the live signal `docs-status` reads.)
+
+## When auditing a whole folder (optional completeness pass)
+
+If pointed at a folder rather than named docs, first **list it and diff against the code** so nothing
+is missed:
+- **In code, no doc**: a real feature/subsystem with no living doc. Create the doc (Steps 1-5 against
+  the code), or at minimum flag it in the summary.
+- **Doc, no code**: the thing it documents is gone. Flag for archiving/deleting the doc.
+- **Both exist**: run the per-doc audit above.
+
+For `docs/features/`, the folder (one doc per feature) IS the inventory — there is no separate
+catalog. Build the real list from `Features/` + the frontend feature folders/routes via actual
+`ls`/`find` output in this run, then diff.
+
+## Anti-fabrication rule
+
+- **Read the code before you write a word of the doc or report.** Steps 1-3 (read doc, read code,
+  check conventions) must complete and their output be visible before step 4/5 write anything. Never
+  batch the write with the reads.
+- **Every claim traces to a file you opened in this run** — entity names, endpoints, routes, key
+  files, line references. No identifiers or dates from memory. When listing a folder, build the
+  feature/doc lists from real `ls`/`find` output, not memory.
+- Only stamp **"Last verified: <today>"** on a doc you actually checked against code in this run.
+  Stamping a date you didn't verify is the exact failure this rule exists to prevent.
+- The `<!-- meta: verified=… -->` date is bound by the **same** rule and always equals the blockquote's
+  `Last verified` — refresh `verified` / `status` / `lineage=N` only after the full doc-vs-code pass this run.
+
+## Notes
+- **Descriptive docs (`infrastructure/`, `features/`):** code is truth — where doc and code disagree,
+  the code wins, fix the doc. **Prescriptive docs (`patterns/`, `guides/`):** the doc is the decided
+  rule — a mismatch usually means the *code* should change (flag it); only edit the doc if the rule
+  itself changed.

package/skills/docs-audit-full/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: docs-audit-full
+description: Master health check across all docs — staleness/age scan, convention spot-checks, research that looks resolved — producing a prioritized re-verify plan. Use monthly, after an extended absence, or run docs-audit-full.
+---
+
+# docs-audit-full
+
+A deep-clean sweep. Does NOT re-audit every feature in depth — it produces the prioritized plan of
+what to audit next.
+
+## Steps
+
+1. **Freshness scan** — read "Last verified" dates across all living docs (`guides/ patterns/
+   infrastructure/ features/`). Flag anything older than ~14 days; sort oldest-first.
+
+2. **Feature completeness** — quick `docs/features/` folder pass (per `docs-audit-feature`'s
+   folder mode): any features in code with no doc, or docs whose feature is gone.
+
+3. **Convention spot-check** — sample 2-3 source files per major convention against the
+   `docs/patterns/` docs; note drift.
+
+4. **Research scan** — scan `docs/research/`; flag ideas that look already-implemented (so they can be
+   graduated/removed) and ideas worth surfacing.
+
+5. **Working/archive sanity** — note any docs lingering in `docs/working/` that look done (should be
+   filed via `docs-write`), and confirm `archive/` topic folders are intact.
+
+6. **Read the previous report first.** Before writing anything, find the most recent
+   `docs/archive/audit/health-report-*.md` and read it in full. The new report continues from it:
+   note what was flagged last time and is now fixed, what's still outstanding, and anything that
+   regressed. If there is **no** prior report, say so — this run is the baseline.
+
+7. **Produce a health report** at `docs/archive/audit/health-report-{date}.md` with a prioritized,
+   actionable list (which `docs-audit-feature` runs, which docs to re-verify, which research to clear).
+   Open with a **"Since last report"** section that diffs against the report from step 6 (or marks this
+   as the baseline if none existed).
+
+## Anti-fabrication rule (read before writing the report)
+
+The report is a **pure function of the scan output above it**. Fabricated dates, feature lists, and
+counts are the main failure mode of this skill.
+
+- **Gather first, write last.** Run ALL of steps 1-6 and SEE their output before you create the
+  report file. Never put the report `Write` in the same batch as the commands that feed it — they run
+  together, so the report would be written from memory, not data.
+- **Every factual cell traces to a command in THIS run.** Dates, file names, feature names, counts —
+  if you can't point at the tool output that produced it, it does not go in the report.
+- **No identifiers from memory.** Feature names, endpoint names, and dates must come from a fresh read
+  of the tree in this run, not from recollection of the codebase or earlier-session summaries.
+- If a scan didn't run or its output is unclear, say "not verified" — never guess a plausible value.
+
+## Notes
+- Output is a plan + report, not a mass edit. Run the recommended `docs-audit-feature` / `docs-process`
+  actions separately.

package/skills/docs-backlog/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: docs-backlog
+description: Capture an idea, improvement, or future-state design as a research doc in docs/research/. Use when the user has thoughts/ideas to park for later, wants to capture research, or runs docs-backlog.
+---
+
+# docs-backlog
+
+Capture ideas as research docs. `docs/research/` is the idea inbox — the folder itself is the queue.
+
+## Steps
+
+1. **Scan existing research titles** in `docs/research/` — quick check for an obvious duplicate or a
+   doc this should extend instead of duplicate.
+
+2. **For each idea, create a research doc** at `docs/research/{topic}.md` using the research-doc
+   template in `docs/_meta/docs-workflow.md`: Current State, Desired End State, Design Options /
+   Recommendation, Open Questions. Capture the idea while it's fresh — verify "Current State" against
+   code if quick, otherwise note it's unverified.
+
+   **The research doc must be self-contained.** It's the durable jump-off point; assume everything else
+   from this session disappears. Inline the substance — plans, code sketches, config, command output,
+   findings — directly into the doc. Do **not** point at ephemeral artifacts as the source of truth: a
+   scratch plan file (Claude Code: `~/.claude/plans/*`), a chat transcript, a subagent's report, a temp file, or
+   "see the plan above." Those vanish; the research doc stays. Cross-links to *other durable docs*
+   (living docs, sibling research docs) are fine — links to throwaway state are not. If the idea came
+   from a plan or long exploration, copy the load-bearing content in (an Appendix is fine) rather than
+   referencing where it lived.
+
+3. **Output**: new research doc(s) only.
+
+## Notes
+- Does NOT create working docs, patch living docs, or archive anything. Research docs are the output.
+- **Self-contained or it failed its job.** Before finishing, reread the doc and strip any reference that
+  makes it depend on something that won't survive the session (plan-file paths, "the plan I just made",
+  transcript/tool-output you didn't inline). If you mention an artifact, its content must already be in
+  the doc.
+- When an idea is later picked up and built, link it via the session doc's **Source** field. The
+  research doc **stays in `research/` through the build** (it's the running tab, and a build may span
+  several sessions / working docs). When the effort finishes, `docs-process` archives the research doc
+  **alongside its working doc(s)** in the same `archive/{topic}/` folder — research and the work that
+  delivered it are filed together, not deleted.

package/skills/docs-process/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: docs-process
+description: Patch the living docs from a session doc's "Living Docs to Update" checklist, verified against code. Use at the start of a session, when the user points at a working/archived session doc and asks to update the living docs, or run docs-process.
+---
+
+# docs-process
+
+The **second** half of the bookend. Take a finished session doc (in `docs/working/` or its topic
+folder under `docs/archive/`) and bring the living docs up to current state.
+
+## Running as a pipeline row (`docs-process` seat)
+
+Most of the time a human runs this cold, after a merge, and this section does not apply.
+
+**When a pipeline arms you as its `docs-process` seat**, your contract is **`spec-seat`** — invoke it first if
+you have not. It carries the blackboard, the question lane, the PLAN TLDR, the verdict vocabulary, the
+six-section FINAL TLDR, and the close-out order. Two things are yours specifically:
+
+- **You are handed a MANIFEST of this effort's working docs BY NAME. `docs/working/` is a SHARED QUEUE
+  — never infer membership from the folder.** A seat that archives a neighbouring effort's docs cannot
+  undo it. If your prompt did not name them, ask before you move anything.
+- **Do NOT run `/docs-write`.** You are that skill's CONSUMER, never its caller — a working doc from you
+  would be an orphan in the queue you just emptied, for an effort you just archived. Your artifacts are
+  the patched living docs and the archive; go straight to the commit call.
+
+**In-pipeline, your living-doc patches are contingent on the merge** — you verify against the pipeline's
+branch, which is the truth for that PR, and you say so at close.
+
+## Steps
+
+1. **Read the session doc(s) for the effort** from `docs/working/` — that's where `docs-write` leaves
+   them (it does not archive). A folder's `README.md` is never a queue entry. One effort may be a **SEQUENCE of working docs** across sessions (each
+   `Builds on` the prior, all sharing one `Source:` research doc); treat the sequence as one unit. The
+   combined **Living Docs to Update** sections are your checklist; the `## Archive` line names the topic
+   folder you'll file everything into in the last step. Run this when the effort is done (it's the
+   finalizer) — mid-effort, just keep adding working docs and continue.
+
+   **`docs/working/` is a SHARED QUEUE — it may hold other efforts' docs.** Invoked by hand you scope
+   the effort yourself from the `Source:` / `Builds on` sequence. **Spawned as a pipeline seat you should have
+   been handed the effort's working docs BY NAME, plus its archive target and its research/spec folder —
+   if you were not, ask for the list rather than inferring membership from the folder.** Sweeping a
+   neighbouring effort's docs into this archive is the failure this guards, and it is not reversible by
+   the seat that does it.
+
+   **If the effort was a spec pipeline, you have a SECOND input: `sessions/code-review.md`** — the review
+   seat's outside look, filed beside `parent-retrospective.md`. Read both. **Every review finding gets a
+   disposition, and the disposition is TOTAL:** a living-doc patch here · an existing fixit seat · a
+   chartered follow-up · a new spec pipeline · or killed on record with the reason. **A finding with no named
+   home is dropped, not deferred** — and the review's own classification (fixit candidate / deferred /
+   documented / trivial) is its recommendation, not your ruling.
+
+   **When you run as a seat INSIDE the pipeline** (before the PR merges) your living-doc patches describe
+   code that is *about to* land. That is fine and deliberate — docs and code ride one PR instead of
+   drifting — but say so in your summary: **the patches are contingent on the merge.** Verify against the
+   pipeline branch's code, which is the truth for that PR.
+
+2. **For each listed living doc** (in `guides/`, `patterns/`, `infrastructure/`, `features/`):
+   - Read the living doc and the session doc's description of what changed.
+   - **Patch the stale sections** — don't rewrite. Preserve everything still accurate.
+   - **Verify against code** — open the actual source file for each claimed change. Code is truth.
+   - **Leave the "Last verified" date alone.** You verified the *specific* checklist changes against
+     code — but you did NOT re-read the whole doc against the whole codebase, and "Last verified" is a
+     *whole-doc* claim. Stamping it for a targeted patch (rename or substantive alike) overclaims and
+     hides real staleness in the untouched sections from the next `docs-status` scan. That date is
+     `docs-audit-feature`'s to set (it does the full doc-vs-code pass — see its anti-fabrication rule).
+     **Exception:** a doc you *create from scratch* here by reading the code is verified-today by
+     definition — set its date.
+   - **Update the Key Files table** if files were renamed, created, or deleted.
+   - **Write / update the meta-comment + `## Lineage`** (see "Doc metadata" in `docs-workflow.md`):
+     - *Creating a doc from scratch* here: emit the `<!-- meta: type=…; status=current; verified={today};
+       lineage=N -->` line (its `verified` = today, matching the blockquote you just set) **and** a
+       `## Lineage` footer. You already know the `Source:` research doc (the `Idea` row), any spec pipeline
+       (the `Spec` row), and the working-doc sequence / `## Archive` target (the `Built` row); derive `Related` from
+       existing peer links. Set `lineage=N` to the link count. **Keep `Spec` and `Built` symmetric** —
+       list **every per-slice spec that a `Built` session implemented** (the umbrella + `00-operating-frame`
+       go in `Idea`, not `Spec`); a `Built` session whose spec is missing from `Spec` is the smell (see the
+       Lineage rules in `docs-workflow.md`).
+     - *Patching an existing doc*: bump `status` if it changed and recompute `lineage=N`; append any new
+       `Built`/`Spec` rows for this effort. **Do NOT restamp `verified`** — same anti-fabrication rule as the
+       `Last verified` date above (a targeted patch is not a whole-doc re-verify).
+     - **Migrate `## Related Docs`.** If the doc still carries a `## Related Docs` section, fold its links into
+       the `## Lineage` `Related` row and remove the old section (the convention supersedes it).
+   - **Flag code risks you spot.** If you notice a genuine bug / risk / tech-debt *outside* what you're
+     documenting — while verifying against code, or as a still-unresolved item in the working doc's
+     **Watch-Outs** — add a dated one-line bullet (with `file:line`) to that doc's `## Open Issues`
+     section (create the section if absent). Only what you actually saw in the code this pass — never
+     speculation. A sizable design idea goes to `docs-backlog` (research/) instead. `docs-status`
+     surfaces these so they aren't lost.
+
+3. **New feature?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
+   feature) and add it to the menu in `docs/_meta/doc-index.md`.
+
+4. **Closing grep** — if the session doc notes deletions or renames, grep all living
+   docs (`guides/ patterns/ infrastructure/ features/ _meta/`) for stale references and fix them. Do
+   NOT touch `archive/` — that's frozen history.
+
+5. **Archive the effort — research/spec docs AND working doc(s), together.** Now that the living docs are
+   patched and verified, file the whole effort into one **topic folder** under `docs/archive/{topic}/`
+   (use the `## Archive` line; reuse the folder if it exists, create it if new; descriptive names, **no
+   numeric prefixes on working docs** — `Builds on` is the ordering):
+
+   **FIRST, RECONCILE THE DESTINATIONS — `rg '^\s*`?docs/archive/' <every working doc in the effort>`.**
+   This step says *"one topic folder"* and *"use the `## Archive` line"* — a singular read over a PLURAL
+   source, so the set is checked before any move. **If the docs disagree, STOP and ask.** Do not pick the
+   majority, do not pick the first, and do not pick the one you happen to be reading. The failure is not
+   recoverable by you: one working doc naming a different, populated effort's folder is enough to sweep
+   this effort's docs into a neighbour's archive, and `archive/` is frozen history. No seat can see it
+   alone — each wrote one working doc and each line is individually plausible; the divergence exists only
+   in the SET, which is why the check belongs here and not upstream.
+   - Move **every working doc** in the effort from `docs/working/` into the topic folder.
+   - Move the **`Source:`** research/spec docs from `docs/research/` into the **same** topic folder — the
+     idea and the work that delivered it are filed together. Do NOT delete and do NOT leave in `research/`
+     (that's what kept shipped ideas cluttering the running tab).
+   - **Pick the folder shape** (see "Two topic-folder shapes" in `docs-workflow.md`):
+     - **Flat** (no spec pipeline — the default for small/single-session efforts): working doc(s) + any
+       research doc at the topic-folder root.
+     - **Split** (the effort used `spec-pipeline`, so a numbered spec set exists): `git mv` the numbered
+       specs + umbrella into **`specs/`**, the working docs into **`implementation/`**, and leave
+       **`project-status.md` at the topic-folder root** as the index, plus any `live-checks.md`; a
+       `sessions/` folder (**two files per session — the filed `plan.md` + `tldr.md`**; older archives may
+       also hold `questions.md` / `status-after-*.md`, which is historical record, not the convention)
+       moves wholesale alongside them. `git mv` STAGES immediately — in a shared working tree, another
+       session's commit can silently sweep your staged renames. Commit promptly after the moves, or
+       announce the staged state before yielding the tree.
+     - **Follow-on round** (the effort continues an already-archived family — e.g. a round-2 pipeline for
+       a shipped feature): its own **sibling** topic folder with the full split shape, named
+       `{family-prefix}-{subtopic}` — **never file into the frozen prior-round folder**. The family
+       index is the living feature doc's `## Lineage` (append this round's Idea/Spec/Built rows beside
+       the prior round's); the new round's back-links to the old archive stay as-is (historical
+       cross-effort links). See the section named `Follow-on pipelines` in `docs-workflow.md`.
+   - **Repair the intra-effort links the move breaks** (relative depths change). On a split, fix: each
+     working doc's `Source:` becomes `../specs/NN-*.md`; the spec / `project-status` links; and the **live feature
+     doc's `## Lineage`** rows (`Spec` to `…/specs/…`, `Built` to `…/implementation/…`). On a flat archive, a
+     working doc's `Source: ../research/{topic}/x.md` becomes the now-sibling `x.md`. **Leave pre-existing
+     cross-effort links** (to *other* topic folders / research folders) as historical record. Verify with a
+     link-resolution pass before finishing.
+   This clears both the `working/` queue and the research idea. After this the docs are frozen history.
+
+6. **Summary** — list which living docs were updated, what changed in each, which source files you read
+   to confirm accuracy, and where the session doc was filed.
+
+## Notes
+- Skip doc updates for pure bug fixes that restored behavior the doc already described correctly.
+- `docs-write` leaves the doc in `working/`; **this skill is what archives it** (step 5) — only after the
+  living docs are current. That keeps `working/` an honest queue of unprocessed sessions.
+- No releases/changelog step — git history covers that.