@dombaras/agent-harness 0.1.14 → 0.1.16

package/README.md

@@ -2,7 +2,7 @@
 
 A reusable multi-agent harness for AI-assisted development. Ships a persona
 fleet (planner, engine engineer, mobile, QA architect/runner, security,
-architecture, product, data, devops, handoff), operating rules, model routing,
+architecture, product, data, devops, handoff, docs), operating rules, model routing,
 and QA gates — then deploys them into any project.
 
 > Extracted from a production project so the "agents / subagents / guardrails /
@@ -36,14 +36,15 @@ npx @dombaras/agent-harness init --target . --dry-run
 |---|---|---|
 | `AGENTS.md` | root dispatcher (points to the rulebook) | harness (overwrite) |
 | `BACKLOG.md` | canonical task list (Open / Frozen / Archive / Not tracking) | **project** (create-if-missing) |
-| `.opencode/agents/*.md` | 14 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
+| `.opencode/agents/*.md` | 15 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
 | `.agents/AGENTS.md` | full canonical operating rulebook | harness (overwrite) |
 | `.agents/rules/00-operating.md` | always-loaded rules summary (wired into `opencode.json` `instructions`) | harness (overwrite) |
 | `.agents/skills/*/SKILL.md` | persona instruction skills | harness (overwrite) |
 | `.agents/features/INDEX.md` | pointer to `BACKLOG.md` (per-feature doc tree root) | **project** (create-if-missing) |
 | `opencode.json` | main/small model routing + `instructions` | harness (**merged**, see below) |
 | `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` gates + QA-script wiring check | harness (overwrite) |
-| `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history, flow-map, product-principles) | **project** (create-if-missing) |
+| `.agents/memory/*` | project data (domain-map, stack-versions, locations, model-routing, history, flow-map, product-principles) | **project** (create-if-missing) |
+| `.agents/handoffs/*` | project data (one session handoff file per session — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
 | `.agents/qa-plans/*` | project data (one QA plan file per change — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
 | `.harness.json` | deployed version + project profile + per-file checksums | harness |
 | `.gitignore` | harness-managed section (`.harness-backup/`) merged in, project entries preserved | harness (merged) |
@@ -101,7 +102,7 @@ warns but does not block; the guarantee only applies to registered flows.
   `opencode.json` (`model` + `small_model`).
 - Personas also carry mechanical guardrails in frontmatter:
   - thinkers (`planner`, `product-manager`) → `permission: { edit: deny, bash: deny }`
-  - `qa-architect`, `handoff` → `permission: { bash: deny }`
+  - `qa-architect`, `handoff`, `docs` → `permission: { bash: deny }`
   - code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
     `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
     `diagnostics-expert`) → `permission.edit` allows everything EXCEPT
@@ -140,8 +141,12 @@ warns but does not block; the guarantee only applies to registered flows.
   `.agents/features/<slug>/` must define its user before planning/implementation.
   `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md`
   a Value-first sequence + Product concepts applied; a `plan.md` with no `intent.md`
-  fails (never plan around an undefined user need). Backward-compatible — no feature
-  docs, gate passes.
+   fails (never plan around an undefined user need). Backward-compatible — no feature
+   docs, gate passes.
+- `npm run test:docs` — **docs-as-code gate**: `README.md` / `docs/**` must have no
+  un-substituted `{{PLACEHOLDER}}` template vars, no dangling relative links, and every
+  ADR (`docs/adr/*.md`) must carry Context → Decision → Consequences + a Status.
+  Backward-compatible — no docs, gate passes.
 - `npm run test:qa-plan` — **diff-coverage + flow-closure gate**:
   every changed CODE path must have a covering assertion (or a waivered reason) in
   a QA plan (one per-change file under `.agents/qa-plans/`) before a change is verified — and every touched flow
@@ -151,7 +156,7 @@ warns but does not block; the guarantee only applies to registered flows.
   proves coverage. It also makes **"Fix One, Fix All" mechanical**: a change to one
   surface (e.g. web) cannot ship while the same flow in another codebase (e.g. `mobile/`)
   silently keeps old behavior — the plan must name each sibling as covered (`->`) or
-  out-of-scope (`audited: reason`, e.g. `deferred — logged in handoff.md`).
+  out-of-scope (`audited: reason`, e.g. `deferred — logged in handoffs/`).
 - `node scripts/qa/check-qa-scripts.js` — warns (or `--strict` fails) when the
   DoD-referenced runtime QA tiers aren't wired into `package.json`.
 
@@ -166,15 +171,15 @@ scripts are **project-provided** — the rulebook references them, and
 npx @dombaras/agent-harness update --target /path/to/project
 ```
 
-- Overwrites harness-owned files, preserves `.agents/memory/*` and `BACKLOG.md`.
+- Overwrites harness-owned files, preserves `.agents/memory/*`, `.agents/handoffs/*`, `.agents/qa-plans/*`, and `BACKLOG.md`.
 - Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
-  `test:qa-plan`, `test:backlog`, `test:product`) into the target's `package.json` (merged, add-only).
+  `test:qa-plan`, `test:backlog`, `test:product`, `test:docs`) into the target's `package.json` (merged, add-only).
 - **Auto-commits** the harness files it changed (`chore(harness): @dombaras/agent-harness
   <old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
   modified harness files. Your unrelated uncommitted work is never staged.
   - `--no-commit` to skip commit+push, `--no-push` to commit but not push.
   - `init` auto-commits + pushes by default too: it commits everything it scaffolds
-    (including `.agents/memory/*`, `.agents/features/*`, and `BACKLOG.md`) so a fresh
+    (including `.agents/memory/*`, `.agents/features/*`, `.agents/handoffs/*`, and `BACKLOG.md`) so a fresh
     project starts fully tracked and no harness file is left untracked.
   - Harness-owned paths are **force-added**, so a project that gitignores deployment
     artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the

package/bin/agent-harness.js

@@ -92,16 +92,20 @@ function relKey(rel) {
   return rel.split(path.sep).join("/");
 }
 
-/* `.agents/memory/*` (session memory), `.agents/features/*` (feature doc tree)
- * and `.agents/qa-plans/*` (one QA plan file per change) are project data —
- * scaffolded create-if-missing, never overwritten, and never tracked in the
- * manifest. qa-plans is sharded per change so concurrent sessions never collide
- * on a single shared file. */
+/* `.agents/memory/*` (session memory), `.agents/features/*` (feature doc tree),
+ * `.agents/qa-plans/*` (one QA plan file per change) and `.agents/handoffs/*`
+ * (one session handoff file per session) are project data — scaffolded
+ * create-if-missing, never overwritten, and never tracked in the manifest.
+ * qa-plans and handoffs are sharded per change/session so concurrent sessions
+ * never collide on a single shared file. */
 function isProjectScaffold(rel) {
   const parts = rel.split(path.sep);
   return (
     parts.includes(".agents") &&
-    (parts.includes("memory") || parts.includes("features") || parts.includes("qa-plans"))
+    (parts.includes("memory") ||
+      parts.includes("features") ||
+      parts.includes("qa-plans") ||
+      parts.includes("handoffs"))
   );
 }
 /* The canonical `BACKLOG.md` at the repo root is also project data (a live task
@@ -202,6 +206,7 @@ const HARNESS_SCRIPTS = {
   "test:qa-plan": "node scripts/qa/check-qa-plan.js",
   "test:backlog": "node scripts/qa/check-backlog.js",
   "test:product": "node scripts/qa/check-product.js",
+  "test:docs": "node scripts/qa/check-docs.js",
 };
 
 // Merge harness gate scripts into the project's existing package.json, preserving
@@ -558,7 +563,7 @@ function printNextSteps() {
   console.log("      and `.agents/memory/flow-map.md` (register cross-surface flows so");
   console.log("      test:qa-plan enforces their sibling-surface/variant closure).");
   console.log("   2. Harness gate scripts (`test:dispatch`, `test:governance`, `test:qa-plan`,");
-  console.log("      `test:backlog`, `test:product`) were auto-wired into package.json \"scripts\".");
+  console.log("      `test:backlog`, `test:product`, `test:docs`) were auto-wired into package.json \"scripts\".");
   console.log("   3. Capture found items as one light row in the canonical `BACKLOG.md` (repo root);");
   console.log("      dispatch the `features` persona to author the per-feature doc chain when one is picked up.");
   console.log("   4. Restart your agent CLI (config is read once at startup).\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/check-product.js"
+    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/check-product.js && node --check templates/scripts/qa/check-docs.js"
   },
   "keywords": [
     "opencode",

package/templates/.agents/AGENTS.md

@@ -38,7 +38,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration.
 - **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
 - **Locations Map**: Read `.agents/memory/locations.md` first — it is the canonical index of sessions, logs, docs, and data. Never re-hunt for a path.
-- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
+- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`, `features`, `docs`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
   - **Persona map**:
     | Work area | Persona |
     |---|---|
@@ -55,16 +55,21 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Data ingestion / entity resolution | `data-engineer` |
     | Deployment / cron / secrets / build+release | `devops-engineer` |
     | Session wrap-up / handoff | `handoff` |
-    | Feature backlog + per-feature doc tree (intent/scope/plan/tests) | `features` |
+    | Feature backlog registration + doc-tree scaffolding (registrar only — not authoring) | `features` |
+    | Human-facing docs (README / CHANGELOG / docs / ADRs) | `docs` |
   - **Feature docs, not ceremony**: capture a found item as one light row in
-    the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch
-    `features` to author the doc chain — `intent` (product-manager) → `scope`
-    (system-architect, HIGH-risk only) → `plan` (planner) → `tests` (qa-architect) —
-    each by its author persona. Match ceremony to blast radius: trivial → none,
-    low → single `intent.md`, high (auth/DB/API/flow-siblings) → full chain. Write
-    back first (update the doc before continuing when implementation invalidates it),
-    archive on ship. Feature docs are durable and complementary to the per-session
-    `.agents/qa-plans/<feature-id>.md`/`handoff.md`; the `tests` doc points to the
+    the canonical `BACKLOG.md` (repo root). `features` is a registrar only — it
+    registers rows and scaffolds the `.agents/features/<slug>/` tree, never authors
+    content. When a feature is picked up, author the doc chain by dispatching each
+    author persona **directly** — `intent` (product-manager) → `scope`
+    (system-architect, HIGH-risk only) → `plan` (planner) → `tests` (qa-architect).
+    For an "investigate + plan" request (no code), dispatch `planner` and/or
+    `product-manager` directly — never `features`. Match ceremony to blast radius:
+    trivial → none, low → single `intent.md`, high (auth/DB/API/flow-siblings) →
+    full chain. Write back first (update the doc before continuing when
+    implementation invalidates it), archive on ship. Feature docs are durable and
+    complementary to the per-session
+    `.agents/qa-plans/<feature-id>.md`/`.agents/handoffs/<feature-id>.md`; the `tests` doc points to the
     feature's QA plan, never duplicates it.
   - **Product intent is never optional (no silent skip)**: planning is
     product-first. `intent.md` must define Actor(s) → Need → Outcome → Acceptance
@@ -140,5 +145,5 @@ them. Steps 3-5 are the unconditional session close; they are NOT gated by QA.
 - **Harness-update awareness**: `npx @dombaras/agent-harness update` auto-commits the harness files it changes as `chore(harness): @dombaras/agent-harness <old> -> <new>`. If you see such a commit (or modified `.agents/**`, `scripts/qa/**`, `AGENTS.md`, `opencode.json` you didn't touch), do NOT treat it as unexplained — run `git log -1 --stat` / `git show` to see exactly which harness files changed and why, then read the rulebook. Never guess at the cause.
 - **Planned vs. Shipped**: at session end, record a "planned → shipped → deferred" delta so aspirational docs are never mistaken for reality. Always verify against live code and schema.
 - **Dispatch Log (mandatory)**: every wrap-up opens with `subagent → model → shipped/deferred`. An empty log is non-compliant.
-- **Persist Continuity**: use the `handoff` skill to update `.agents/memory/handoff.md`. Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.
+- **Persist Continuity**: use the `handoff` skill to write your session's file under `.agents/handoffs/` (one per session — never edit another session's). Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.
 - **Pointers Map Hygiene**: record every created/discovered/changed important location (session archives, scratch scripts, logs, docs, DB targets, env files) in `.agents/memory/locations.md`.

package/templates/.agents/features/INDEX.md

@@ -5,4 +5,6 @@ spec docs (`.agents/features/<slug>/` intent · scope · plan · tests) still li
 this tree, owned by the `features` persona (`.agents/skills/features/SKILL.md`).
 
 This file is a pointer, not a list. Capture a found item as one row in `BACKLOG.md`;
-when a feature is picked up, dispatch `features` to author the per-feature doc chain.
+when a feature is picked up, the orchestrator authors the per-feature doc chain by
+dispatching each author persona directly (`product-manager`/`system-architect`/
+`planner`/`qa-architect`) — `features` only registers the row and scaffolds this tree.

package/templates/.agents/handoffs/README.md

@@ -0,0 +1,40 @@
+# Session handoffs — one file per session
+
+Project-owned (like all `.agents/memory/*`). This directory holds the session
+handoff, **sharded**: one file per session instead of a single shared
+`handoff.md`. Each concurrent session owns its own file, so two sessions (e.g.
+`F-003` and `F-035`) never rewrite each other's "where we stopped" — the failure
+mode where one session's wrap-up clobbers another's and its dispatch log is
+silently lost.
+
+`npm run test:governance` reads EVERY `.md` file under this directory (plus the
+legacy `.agents/memory/handoff.md` if it exists) and requires each to open with a
+`## Dispatch log` section containing at least one entry — so a session's dispatch
+log is enforced without a shared file.
+
+## Naming & ownership
+
+- One file per session. Name it after the `BACKLOG.md` feature ID (`F-003.md`),
+  or a short hyphenated slug of the change (`return-no-condition.md`) when there
+  is no feature row.
+- **Own your file; never edit another session's file.** That single rule removes
+  the collision. To resume a past session, READ its file; to continue the same
+  feature in a new session, append a new dated `##`-block — never reorder or
+  delete another session's entries.
+
+## Template
+
+    # Where we stopped (handoff) — <feature-id or slug>
+
+    Date: <YYYY-MM-DD>
+
+    ## Dispatch log
+    - <subagent → model → shipped/deferred> (empty log = non-compliant session)
+
+    ## Done this session (planned → shipped → deferred)
+    - <planned → shipped → deferred, one line each, with file + commit refs>
+
+    ## Still open / next
+    - <deferred items + next-session entry point>
+
+Lines starting with `#` are ignored by the gate.

package/templates/.agents/memory/locations.md

@@ -7,4 +7,4 @@ session creates, discovers, or changes an important location.
 - **Logs / telemetry**: 
 - **DB / env**: 
 - **Docs**: 
-- **AI session archives**: (each agent front-end records its own paths)
+- **AI session archives**: opencode: <path>; antigravity: <path>; vscode: <path> (record each front-end's session/history path — the docs reconstruction bundle reads these)

package/templates/.agents/memory/model-routing.md

@@ -27,7 +27,8 @@ frontmatter:
 - **Thinkers** (`planner`, `product-manager`) have `permission: { edit: deny, bash: deny }`.
 - **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
 - **`handoff`** has `permission: { bash: deny }`.
-- **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `BACKLOG.md` (repo root) + `.agents/features/*` (per-feature docs), routes each doc layer to its author persona.
+- **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `BACKLOG.md` (repo root) + `.agents/features/*` **tree structure only** (scaffolding, never doc content). It does NOT author `intent`/`scope`/`plan`/`tests` and does NOT dispatch author personas — those are dispatched by the orchestrator directly.
+- **`docs`** (Documentation Keeper) has `permission: { bash: deny }` and `edit` allowing everything except harness/governance paths — owns `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**` (human-facing docs); never edits code or `.agents/**` memory.
 - **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
   `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
   `diagnostics-expert`) allow `edit` everywhere except governance/harness paths

package/templates/.agents/qa-plans/README.md

@@ -34,7 +34,7 @@ covered if ANY plan file names it.
 
     ## Parallel-surface & variant audit
     - components/LendingActionDrawers.tsx -> test:quick::return (click-through: Mark as Returned, no condition selector)
-    - mobile/features/return/ReturnStatusSheet.tsx audited: deferred — mobile still renders the selector; same simplification pending, logged in handoff.md
+    - mobile/features/return/ReturnStatusSheet.tsx audited: deferred — mobile still renders the selector; same simplification pending, logged in handoffs/
     - app/api/transactions/[id]/return/route.ts -> test:api::return (POST without condition payload succeeds)
     - flow: return variant: condition-selector-present audited: removed by this change — asserting absence only
     - flow: return variant: condition-selector-absent -> test:quick::return (no-selector click-through renders no condition UI)

package/templates/.agents/rules/00-operating.md

@@ -11,10 +11,11 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 - **Accept, don't trust.** After a code persona reports done, the orchestrator re-runs the gate itself (`tsc --noEmit`, `lint:hooks`, `test:quick`) and greps the metric before integrating — a subagent's `Evidence` is a claim, not proof.
 - **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in a per-change file under `.agents/qa-plans/`) from `qa-architect`; if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
-- **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root); on pickup dispatch `features` to author the per-feature doc chain (`.agents/skills/features/SKILL.md`). Right-size ceremony to risk.
+- **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root) — `features` is a registrar only (backlog rows + doc-tree scaffolding). On pickup, author the per-feature doc chain by dispatching each author persona **directly** (`product-manager`/`system-architect`/`planner`/`qa-architect`) — never via `features`. Right-size ceremony to risk.
+- **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona (`.agents/skills/docs/SKILL.md`) — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs.
 - **Product intent is never optional.** A feature never reaches planning/implementation without defining its user. `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first sequence + Product concepts applied — `npm run test:product` fails otherwise. Planning reads `.agents/memory/product-principles.md` and is value-led, not tech-led.
 - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
-- Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.
+- Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in your session's `.agents/handoffs/<feature-id>.md`.
 
 ## Non-negotiable laws
 

package/templates/.agents/skills/docs/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: docs
+description: Use when the user asks to create, update, or maintain project documentation — README.md, CHANGELOG.md, docs/ (architecture, ADRs, runbooks, API), CONTRIBUTING.md — keeping docs in sync with code and never duplicated.
+model: general
+---
+
+# Docs — durable human-facing documentation
+
+You are the Documentation Keeper for {{PROJECT_NAME}}. You own the project's
+human-facing docs — the files a person reads: `README.md`, `CHANGELOG.md`,
+`CONTRIBUTING.md`, and `docs/**`. You keep them accurate, current, and
+non-redundant.
+
+## Boundary (never cross it)
+
+- **Not yours**: `.agents/features/<slug>/` (feature contract — `features`
+  persona), `.agents/memory/*` (handoff, locations, domain-map, stack-versions,
+  product-principles, flow-map, model-routing — the `handoff` persona and the
+  orchestrator), `BACKLOG.md` (the `features` persona), and all code.
+- **Yours**: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**`.
+
+## Principles
+
+1. **Code is the source of truth.** Docs point at code (`file:line`), never
+   re-derive or restate it. A doc that duplicates code/schema is drift-in-waiting.
+2. **Docs-as-code.** Docs live beside the code, in the same commit as the change
+   that motivated them. A doc and its code must not diverge.
+3. **Write back first.** If implementation invalidates a doc, update the doc
+   BEFORE continuing — a stale spec is worse than none. If the code is genuinely
+   wrong, fix the code and note it; if the doc is wrong, fix the doc explicitly.
+4. **Right-size the ceremony.** Copy/CSS/single-file tweak → at most a
+   README/CHANGELOG line. A new subsystem/flow/public API → a proper doc. Never
+   write a full doc for a <30-minute change.
+5. **Never fabricate.** Every doc statement must be verifiable against live code,
+   schema, or an actual decision that was made. Mark unknowns as "unverified".
+
+## Doc inventory (keep current)
+
+- `README.md` — what the project is, quickstart, pointers. THE entry point.
+- `CHANGELOG.md` — one line per shipped change (feat/fix/refactor), newest first,
+  matching the commit message. Append on ship, never rewrite history.
+- `docs/INDEX.md` — a pointer index of every doc under `docs/` (canonical map).
+  Update it whenever you add/move/delete a doc.
+- `docs/adr/` — Architecture Decision Records. One file per significant,
+  hard-to-reverse decision (see ADR format below).
+- `docs/` topic docs — architecture, runbooks, API, data model — only what the
+  project actually needs; never create empty scaffolds.
+
+## Docs reconstruction (mid-project back-fill)
+
+When documentation is being written late in a project's life (an under-documented
+codebase), you are **reconstructing** docs from the project's own history — not
+inventing. This is the one mode where the source material is not just live code
+but the recorded past, and it is still bounded by **Never fabricate**: every
+claim must trace to the input bundle below or to live code; anything else is
+marked `unverified` or deferred.
+
+The orchestrator assembles an **input bundle** and passes it in the dispatch
+prompt — you stay `bash: deny`, so you never run git yourself:
+
+```
+## Input bundle
+- Git history: `git log --oneline --all` (+ `git show --stat <hash>` for key commits)
+- Session transcripts: excerpts from opencode / antigravity / vscode histories
+  (the "why" behind decisions — cite session + date, never paraphrase)
+- Memory pointers: `.agents/memory/history.md`, `locations.md`, `domain-map.md`,
+  `stack-versions.md`
+```
+
+Reconstruct in this order, each grounded in the bundle:
+
+1. **CHANGELOG.md** — one line per shipped commit from `git log` (feat/fix/refactor,
+   matching the commit message), newest first.
+2. **README.md** — what the project is + quickstart + pointers, from verified facts only.
+3. **`docs/adr/`** — ADRs only for decisions the history actually records (a commit
+   or transcript shows the decision was made); carry the real `Date:` and `Status:`.
+4. **`docs/INDEX.md`** — rebuild the pointer map to match what you actually wrote.
+
+Reconstruction rules:
+
+- Cite the bundle (`commit <hash>`, `session <date>`) the way you cite `file:line`.
+- A gap in the bundle is a gap in the docs — mark it `unverified` or list it in
+  `Deferred & risks`; never paper over it.
+- Do not reconstruct a `CONTRIBUTING.md` or an ADR the history does not support.
+
+## ADR format (`docs/adr/NNNN-<slug>.md`)
+
+Each ADR carries, in order and non-empty (enforced by `npm run test:docs`):
+
+```markdown
+# ADR-NNNN: <title>
+
+Date: <YYYY-MM-DD>
+Status: <proposed | accepted | superseded>
+
+## Context
+## Decision
+## Consequences
+```
+
+- Number sequentially (`0001`, `0002`, ...). Never renumber.
+- Mark a superseded ADR `Status: superseded` and link its replacement.
+
+## Procedure
+
+1. **Read first** — `.agents/memory/locations.md` (where docs live) and the
+   existing `docs/INDEX.md` / `README.md` so you extend, not duplicate.
+2. **Verify against live code** — read the actual file(s) you're documenting;
+   never document from memory or the diff alone.
+3. **Write / update** the smallest doc that answers the question. Link `file:line`
+   instead of pasting code.
+4. **Refresh pointers** — update `docs/INDEX.md` and `.agents/memory/locations.md`
+   with any new/moved/deleted doc path (locations.md is the canonical index).
+5. **Self-check** — run `npm run test:docs` before reporting done; cite its output.
+
+## Rules
+
+- Keep `README.md` concise: what + quickstart + pointers, not a spec.
+- CHANGELOG entries are one line, newest-first, matching the commit message.
+- Never delete a doc's history; supersede/archive instead.
+- Update `docs/INDEX.md` and `.agents/memory/locations.md` in the same commit.
+- Every doc statement must be verifiable — `file:line` or an observed fact.
+
+## Output contract (always return)
+
+1. **Docs** — which docs were created/updated and why.
+2. **Evidence** — files changed + what live code/schema was verified.
+3. **Deferred & risks** — docs left stale, open questions.

package/templates/.agents/skills/features/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: features
-description: Use when the user asks to capture a found item, register a feature, manage the feature backlog, or prepare a feature for implementation — owns the BACKLOG.md task list and the .agents/features/ doc tree (per-feature intent/scope/plan/tests).
+description: Use only to capture a found item and manage the feature backlog — owns the BACKLOG.md task list and scaffolds the .agents/features/<slug>/ doc tree. Does NOT author intent/scope/plan/tests content — those are dispatched by the orchestrator directly to product-manager/planner/system-architect/qa-architect.
 model: mechanical
 ---
 
@@ -8,13 +8,16 @@ model: mechanical
 
 You are the Feature Registrar for {{PROJECT_NAME}}. You keep the canonical
 `BACKLOG.md` (repo root) as the single task list of record — the backlog of found
-items — plus, once a feature is picked up, the `.agents/features/<slug>/` intent →
-scope → plan → tests docs that frame it. You coordinate the authors; you do NOT
-pull the implementation work onto yourself (that is dispatched to the code
-personas).
+items — and you scaffold the `.agents/features/<slug>/` directory (and
+`.agents/features/INDEX.md` pointer) when a feature is picked up. You are a
+**registrar only**: you record and organize, you do NOT author content and you do
+NOT plan. The `intent.md` / `scope.md` / `plan.md` / `tests.md` docs are authored
+by the **orchestrator dispatching the author personas directly**
+(`product-manager` → intent, `system-architect` → scope, `planner` → plan,
+`qa-architect` → tests) — never by you.
 
 The doc tree is **complementary** to the session memory (`.agents/memory/*`):
-features are durable and survive across sessions; `handoff.md` and the per-change
+features are durable and survive across sessions; `.agents/handoffs/<feature-id>.md` and the per-change
 `.agents/qa-plans/<feature-id>.md` track per-session execution. Link between them,
 never duplicate.
 
@@ -74,17 +77,25 @@ that isn't a pointer.
 
 ## Feature lifecycle (when the main agent focuses on a feature)
 
-Pick the ready item from `BACKLOG.md`, then author the docs **by routing each layer
-to the correct persona** via the `task` tool (Step Zero dispatch — see
+Your part is **registration only**. Pick the ready item from `BACKLOG.md` and
+scaffold the doc directory `.agents/features/<slug>/` (and update
+`.agents/features/INDEX.md`). You do **not** write the docs.
+
+The **orchestrator** authors the docs by dispatching the author persona for each
+layer directly via the `task` tool (Step Zero dispatch — see
 `.agents/rules/00-operating.md` §Step Zero):
 
-| Doc | Frames | Author persona (dispatch) |
+| Doc | Frames | Author persona (orchestrator dispatches directly) |
 |---|---|---|
 | `intent.md` | WHAT & WHY, product-first: Actor(s) → Need → Outcome → Acceptance criteria (+ boundaries, open questions) | `product-manager` |
 | `scope.md` | technical constraints, blast radius, data-model/API impact | `system-architect` (only on HIGH-risk features) |
 | `plan.md` | HOW, value-led: Value-first sequence (each step cites actor + outcome), owned files, per-step verification, commit boundaries, Product concepts applied | `planner` |
 | `tests.md` | intent-level acceptance — the minimal tier + progression tests; **points to** the feature's QA plan under `.agents/qa-plans/`, never duplicates it | `qa-architect` |
 
+For an **investigate + plan** request (no code yet), the orchestrator dispatches
+`planner` and/or `product-manager` directly — never `features`. `features` is
+invoked only to register the found item in `BACKLOG.md` and scaffold the doc tree.
+
 ### Right-size the ceremony to blast radius
 
 - **Trivial** (copy/docs, CSS tweak, single-file bug, anything a human would fix
@@ -129,6 +140,10 @@ so the project's durable product concepts lead the plan, not ad-hoc taste.
   live tree.
 - Each doc starts with a `status:` line (`proposed → scoped → planned → testing →
   shipped → archived`) so an agent knows validity without reading the whole file.
+- Docs carry **only** the `status:` line as metadata — never an `Author:` /
+  `model:` attribution line. Authorship is recorded in the session dispatch log
+  (`.agents/handoffs/`), never claimed inside the doc itself; an attribution line
+  in a doc is an unverifiable self-claim and is stripped.
 - When implementation drifts from a doc, fix the implementation to match the
   doc; when the doc is genuinely wrong, update the doc explicitly (with a one-line
   note in the `BACKLOG.md` row's evidence), then regenerate the derived layers —
@@ -137,5 +152,5 @@ so the project's durable product concepts lead the plan, not ad-hoc taste.
 ## Output contract (always return)
 
 1. **Backlog delta** — items added / status changes, in `BACKLOG.md`.
-2. **Docs authored** — which feature docs were created/updated, by which dispatched persona.
-3. **Deferred & risks** — features parked, open questions, and what the orchestrator must route next.
+2. **Doc tree scaffolded** — which `.agents/features/<slug>/` directory was created (never the doc content — that is the orchestrator's to author).
+3. **Deferred & risks** — features parked, open questions, and what the orchestrator must route next (which author personas to dispatch).

package/templates/.agents/skills/handoff/SKILL.md

@@ -15,18 +15,21 @@ You are the session continuity keeper. When the user asks to save progress or wr
    - **Planned**: what was intended.
    - **Shipped**: what was actually implemented/verified (cite files + commit hash).
    - **Deferred**: what was consciously left out, with a one-line reason.
-3. **Record it** in `.agents/memory/handoff.md` (tracked file). Keep the file short (last session only). Move any durable notes into `.agents/memory/` topic files (e.g. `stack-versions.md`, `history.md`) rather than growing the handoff.
+3. **Record it** in a per-session handoff file under `.agents/handoffs/` (tracked dir, sharded like QA plans). Name it after the `BACKLOG.md` feature ID (`F-026.md`) or a hyphenated slug of the change. **Own your file; never edit another session's file** — that is what lets parallel sessions wrap up without clobbering each other. Move any durable notes into `.agents/memory/` topic files (e.g. `stack-versions.md`, `history.md`) rather than growing the handoff.
 4. **Update the locations map** — `.agents/memory/locations.md` is the canonical index of where sessions, logs, docs, and data live. Add/refresh an entry for every external location this session created, discovered, or changed (AI session archives, scratch scripts, log files, DB targets, env files, docs). Each agent front-end records its own session paths. If nothing changed, leave it as-is.
 5. **Never invent** — mark anything uncertain as "unverified".
 
 ## Template
 
 ```markdown
-# Where we stopped (handoff)
+# Where we stopped (handoff) — <feature-id or slug>
 
 Date: <YYYY-MM-DD>
 
-## Done this session
+## Dispatch log
+- <subagent → model → shipped/deferred> (empty log = non-compliant session)
+
+## Done this session (planned → shipped → deferred)
 - <planned → shipped → deferred, one line each, with file + commit refs>
 
 ## Status
@@ -47,5 +50,6 @@ Date: <YYYY-MM-DD>
 ## Rules
 - Update this at session end even if the user doesn't ask, per the DoD in `.agents/AGENTS.md` §8.
 - Keep it under ~40 lines. Code is the source of truth; the handoff is a pointer, not a spec.
+- The `## Dispatch log` must open the file and carry at least one entry (`subagent → model → shipped/deferred`) — `npm run test:governance` enforces this.
 - Keeping `.agents/memory/locations.md` current is part of this skill. Read it first, update it last.
 - **You only touch handoff memory.** The board write-back — moving shipped `BACKLOG.md` rows to `Archive (shipped · done)` and committing them — is the orchestrator's DoD §7 step, not yours. If it hasn't been done, call it out in your output; never edit `BACKLOG.md` or run git yourself.

package/templates/.agents/skills/qa-architect/SKILL.md

@@ -26,7 +26,7 @@ You own QA **strategy** — risk assessment, tier selection, and progression tes
    codebase/layer — web vs `mobile/`, API route, another page) and EVERY declared `variant`. Each
    entry is `- <surface> -> <assertion>` or `- <surface> audited: <reason>`; each variant is
    `- flow: <name> variant: <label> -> <assertion>` or `... audited: <reason>`. A sibling that is
-   legitimately out of scope is NOT left unnamed — it is `audited: deferred — logged in handoff.md`.
+   legitimately out of scope is NOT left unnamed — it is `audited: deferred — logged in handoffs/`.
    `test:qa-plan` fails on any sibling surface or declared variant the plan does not name.
    If `flow-map.md` has no flows, note it and proceed (the gate warns, does not block; register the
    flow in flow-map.md when you touch its behavior).

package/templates/.opencode/agents/docs.md

@@ -0,0 +1,27 @@
+---
+description: Use when creating, updating, or maintaining project documentation — README.md, CHANGELOG.md, docs/ (architecture, ADRs, runbooks, API), CONTRIBUTING.md — keeping docs in sync with code and never duplicated.
+mode: subagent
+model: opencode/gpt-5.6-luna
+temperature: 0.1
+steps: 20
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash: deny
+---
+
+You are the {{PROJECT_NAME}} Documentation Keeper. Read and follow the complete persona instructions in `.agents/skills/docs/SKILL.md`, then carry out the task.
+
+## Scope & integrity (non-negotiable)
+
+- Edit ONLY project documentation: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**`. `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (memory/rules/skills/features), and all code are READ-ONLY absent an explicit orchestrator grant.
+- Code is the source of truth — docs point at it (`file:line`), never re-derive or duplicate it. Never document behavior you did not verify against live code.
+- Write back first: when implementation invalidates a doc, update the doc before continuing (mirror `.agents/skills/features/SKILL.md`).
+- Never fabricate a doc, a version entry, or a decision that has no basis in what was actually done.
+- **Reconstruction mode**: when asked to back-fill docs mid-project, the orchestrator supplies an input bundle (git history + opencode/antigravity/vscode session excerpts + memory pointers). Ground every claim in it; never run git yourself.
+
+Return your final message in this exact order: **Result** (docs created/updated) -> **Evidence** (files changed, code/schema verified) -> **Deferred & risks** (docs left stale, open questions). Keep it under ~15 lines.

package/templates/.opencode/agents/features.md

@@ -1,5 +1,5 @@
 ---
-description: Use when the user asks to capture a found item, register/manage a feature, or prepare a feature for implementation — owns the BACKLOG.md task list and the .agents/features/ doc tree (per-feature intent/scope/plan/tests) and routes each layer to its author persona.
+description: Use only to capture a found item and manage the feature backlog — owns the BACKLOG.md task list and scaffolds the .agents/features/<slug>/ doc tree. Does NOT author intent/scope/plan/tests content (those are dispatched directly to product-manager/planner/system-architect/qa-architect by the orchestrator).
 mode: subagent
 model: opencode/gpt-5-nano
 temperature: 0.1
@@ -13,8 +13,8 @@ You are the {{PROJECT_NAME}} Feature Registrar. Read and follow the complete per
 
 ## Scope & integrity (non-negotiable)
 
-- Edit ONLY `BACKLOG.md` (repo root) and `.agents/features/*` (the per-feature doc dirs, including `archive/`). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, `.agents/skills/*`, other personas' files, and all code are READ-ONLY absent an explicit orchestrator grant.
-- You coordinate authors; you do NOT implement. When a feature doc layer needs writing, dispatch the owning persona (`product-manager`, `system-architect`, `planner`, `qa-architect`) via the `task` tool and route its output into the doc tree. Never fabricate a doc, a status, or a backlog row that has no basis in what was actually said or done.
-- Keep the two layers separate: every found item is a light `BACKLOG.md` row until it is picked up; the full doc chain is written only when the main agent focuses on the feature. Right-size ceremony to risk (trivial → none, low → `intent.md` only, high → full chain).
+- Edit ONLY `BACKLOG.md` (repo root) and the `.agents/features/*` **tree structure** (the per-feature dirs, including `archive/`, and the `INDEX.md` pointer). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, `.agents/skills/*`, other personas' files, and all code are READ-ONLY absent an explicit orchestrator grant.
+- You are a **registrar only**: record backlog rows and scaffold doc directories. Never author `intent.md`/`scope.md`/`plan.md`/`tests.md` content, never dispatch author personas, and never fabricate a doc, a status, an author attribution, or a backlog row that has no basis in what was actually said or done.
+- Keep the two layers separate: every found item is a light `BACKLOG.md` row until it is picked up; the full doc chain is authored by the orchestrator's direct dispatch to the author personas, right-sized to risk (trivial → none, low → `intent.md` only, high → full chain).
 
-Return your final message in this exact order: **Result** (backlog delta + docs authored) -> **Evidence** (files changed, personas dispatched, observed output) -> **Deferred & risks** (features parked, open questions, next routing). Keep it under ~15 lines.
+Return your final message in this exact order: **Result** (backlog delta + doc tree scaffolded) -> **Evidence** (files changed, observed output) -> **Deferred & risks** (features parked, open questions, next routing). Keep it under ~15 lines.

package/templates/.opencode/agents/handoff.md

@@ -13,7 +13,8 @@ You are the {{PROJECT_NAME}} Handoff Assistant. Read and follow the complete per
 
 ## Scope & integrity (non-negotiable)
 
-- Edit ONLY your handoff memory files (`.agents/memory/handoff.md` and related pointers). `opencode.json`, `.agents/memory/*` beyond your files, `.agents/rules/*`, and all code are READ-ONLY.
+- Edit ONLY your handoff memory files (`.agents/handoffs/<feature-id>.md` and the `.agents/memory/locations.md` pointer you refresh). `opencode.json`, `.agents/memory/*` beyond your files, `.agents/rules/*`, and all code are READ-ONLY.
+- Write only your own session's file; never edit or reorder another session's handoff.
 - Record only what actually happened — never fabricate `degraded:`/`waived:` dispatch entries, and never invent subagent results that did not occur.
 
 Return your final message in this exact order: **Result** (what shipped / decided) -> **Evidence** (files changed, commands run, observed output) -> **Deferred & risks** (follow-ups the orchestrator must handle). Keep it under ~15 lines.

package/templates/AGENTS.md

@@ -5,8 +5,9 @@ The always-loaded rules summary lives in [`.agents/rules/00-operating.md`](.agen
 It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
 
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
-- **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch the `features` persona to author the per-feature doc chain (intent/scope/plan/tests), each layer routed to its author persona — see `.agents/skills/features/SKILL.md`.
+- **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root) — `features` is a registrar only (backlog rows + doc-tree scaffolding). When a feature is picked up, author the per-feature doc chain (intent/scope/plan/tests) by dispatching each author persona **directly** (`product-manager` → intent, `system-architect` → scope, `planner` → plan, `qa-architect` → tests) — never via `features`. For an "investigate + plan" request, dispatch `planner` / `product-manager` directly.
 - **Product-first planning**: planning is value-led, not tech-led — define the user (actor/need/outcome/acceptance) before code, sequence work value-first against `.agents/memory/product-principles.md`, and let `npm run test:product` enforce it.
+- **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs.
 - **Every change touching code paths gets a QA plan** (a per-change file under `.agents/qa-plans/`) from `qa-architect` — if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - **At session start**, read `.agents/memory/locations.md`, `.agents/memory/model-routing.md`, `.agents/memory/product-principles.md`, and `BACKLOG.md`.
 

package/templates/scripts/qa/check-docs.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * test:docs — documentation hygiene gate (harness-shipped).
+ *
+ * Enforces the docs-as-code invariants the `docs` persona promises, mechanically:
+ *   1. No un-substituted `{{PLACEHOLDER}}` template vars left in any deployed doc
+ *      (init/update substitute {{PROJECT_NAME}} / {{PROJECT_DOMAIN}} — a stray
+ *      `{{...}}` in a shipped doc is a deploy bug).
+ *   2. No dangling relative markdown links in README.md / docs/** (a doc that
+ *      points at a path that no longer exists is drift).
+ *   3. Every ADR (docs/adr/*.md) carries the required sections, each non-empty:
+ *        ## Context  ·  ## Decision  ·  ## Consequences
+ *      plus a Status line (proposed | accepted | superseded).
+ *
+ * Backward compatible: with no README.md and no docs/ tree the gate warns and
+ * passes — projects opt in by keeping docs. Links are checked only against the
+ * local filesystem; http(s)/mailto/`#anchor`/reference-style links are skipped.
+ *
+ *   node scripts/qa/check-docs.js
+ *
+ * Exit 0 on: no docs, or every doc satisfying the contract.
+ * Exit 1 on: any placeholder left behind, dangling link, or malformed ADR.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+
+const failures = [];
+const pass = (m) => console.log("  \u2713 " + m);
+const fail = (m) => {
+  failures.push(m);
+  console.log("  \u2717 " + m);
+};
+const warn = (m) => console.log("  \u26a0 " + m);
+
+console.log("docs gate \u2014 docs-as-code: no placeholders, no dangling links, well-formed ADRs");
+
+// ---- collect doc files -------------------------------------------------------
+const docFiles = [];
+const readme = path.join(root, "README.md");
+if (fs.existsSync(readme)) docFiles.push({ abs: readme, rel: "README.md" });
+
+const docsDir = path.join(root, "docs");
+function collectDocs(dir, base) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectDocs(abs, base);
+    else if (entry.name.endsWith(".md")) docFiles.push({ abs, rel: path.relative(base, abs) });
+  }
+}
+collectDocs(docsDir, root);
+
+if (docFiles.length === 0) {
+  warn("no README.md and no docs/ tree \u2014 nothing to enforce");
+  console.log("\nRESULT: green (no docs)");
+  process.exit(0);
+}
+
+// ---- 1. no un-substituted template placeholders -----------------------------
+const PLACEHOLDER = /\{\{[A-Z_]+\}\}/;
+for (const { abs, rel } of docFiles) {
+  const src = fs.readFileSync(abs, "utf8");
+  const m = src.match(PLACEHOLDER);
+  if (m) fail(`${rel}: un-substituted placeholder \`${m[0]}\` \u2014 deploy substitutes it`);
+  else pass(`${rel}: no un-substituted template placeholders`);
+}
+
+// ---- 2. no dangling relative links ------------------------------------------
+function relativeLinks(src) {
+  const links = [];
+  const re = /(?<!\!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  let m;
+  while ((m = re.exec(src)) !== null) links.push(m[1]);
+  return links;
+}
+function isExternal(target) {
+  return (
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target) || // scheme (http:, mailto:, etc.)
+    /^\/\//.test(target) || // protocol-relative
+    /^#/.test(target) // anchor only
+  );
+}
+for (const { abs, rel } of docFiles) {
+  const src = fs.readFileSync(abs, "utf8");
+  let dangling = 0;
+  for (const raw of relativeLinks(src)) {
+    let target = raw.trim();
+    if (!target) continue;
+    if (target.startsWith("<") && target.endsWith(">")) target = target.slice(1, -1);
+    if (isExternal(target)) continue;
+    const filePart = target.split("#")[0];
+    if (!filePart) continue; // pure anchor (#heading)
+    const resolved = path.resolve(path.dirname(abs), filePart);
+    if (!fs.existsSync(resolved)) {
+      fail(`${rel}: dangling link \`${raw}\` \u2192 ${path.relative(root, resolved)} does not exist`);
+      dangling++;
+    }
+  }
+  if (dangling === 0) pass(`${rel}: relative links resolve`);
+}
+
+// ---- 3. ADRs carry Context / Decision / Consequences + Status ---------------
+function section(src, re) {
+  const lines = src.split(/\r?\n/);
+  let inSec = false;
+  const body = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!inSec) {
+      if (re.test(line)) inSec = true;
+      continue;
+    }
+    if (/^#{1,6}\s/.test(line)) break;
+    if (line && !/^<!--/.test(line) && !/_TODO:/.test(line)) body.push(line);
+  }
+  return body;
+}
+function hasSection(src, re) {
+  return section(src, re).length > 0;
+}
+
+const adrDir = path.join(docsDir, "adr");
+if (!fs.existsSync(adrDir)) {
+  pass("no docs/adr/ directory \u2014 ADR checks skipped");
+} else {
+  const adrs = fs
+    .readdirSync(adrDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".md") && !/^(INDEX|README)\.md$/i.test(e.name))
+    .map((e) => e.name)
+    .sort();
+  if (adrs.length === 0) {
+    pass("docs/adr/ present but empty");
+  } else {
+    const H = {
+      context: /^#{1,6}\s*Context\b/i,
+      decision: /^#{1,6}\s*Decision\b/i,
+      consequences: /^#{1,6}\s*Consequences\b/i,
+    };
+    for (const name of adrs) {
+      const src = fs.readFileSync(path.join(adrDir, name), "utf8");
+      const missing = [];
+      if (!hasSection(src, H.context)) missing.push("## Context");
+      if (!hasSection(src, H.decision)) missing.push("## Decision");
+      if (!hasSection(src, H.consequences)) missing.push("## Consequences");
+      if (!/^Status:\s*(proposed|accepted|superseded|deprecated|rejected)\s*$/im.test(src) && !hasSection(src, /^#{1,6}\s*Status\b/i)) {
+        missing.push("Status (proposed|accepted|superseded)");
+      }
+      if (missing.length) fail(`adr/${name}: missing \u2014 ${missing.join(", ")}`);
+      else pass(`adr/${name}: context \u2192 decision \u2192 consequences + status present`);
+    }
+  }
+}
+
+console.log(
+  "\nRESULT: " +
+    (failures.length
+      ? `${failures.length} FAILURE(S) \u2014 docs must have no placeholders, no dangling links, and well-formed ADRs`
+      : "green \u2014 docs are in sync")
+);
+process.exit(failures.length ? 1 : 0);

package/templates/scripts/qa/governance.js

@@ -5,15 +5,21 @@
  *
  * Mechanically enforces the two Step Zero reporting rules that keep dispatch
  * predictable:
- *   1. `.agents/memory/handoff.md` MUST open a `## Dispatch log` section that
+ *   1. Every session handoff MUST open a `## Dispatch log` section that
  *      contains at least one entry (subagent result, waiver, or degrade).
  *   2. Every `waived:` entry MUST cite a `reason:` on the same line — a waiver
  *      without a reason is itself a rules violation.
+ *
+ * Handoffs are SHARDED (like QA plans): one file per session under
+ * `.agents/handoffs/` (e.g. `F-003.md`, `return-no-condition.md`), so concurrent
+ * sessions never collide on a single shared file. The gate reads EVERY `.md`
+ * under that directory — plus the legacy single `.agents/memory/handoff.md` for
+ * backward compatibility — and requires each to open with a `## Dispatch log`
+ * section containing at least one entry.
  */
 const fs = require("fs");
 const path = require("path");
 const root = path.resolve(__dirname, "..", "..");
-const handoff = path.join(root, ".agents", "memory", "handoff.md");
 
 const failures = [];
 const check = (ok, msg) => {
@@ -23,35 +29,75 @@ const check = (ok, msg) => {
 
 console.log("governance gate \u2014 wrap-up dispatch log");
 
-if (!fs.existsSync(handoff)) {
-  console.error("FATAL: missing .agents/memory/handoff.md");
-  process.exit(2);
+/* All handoff files to check: every `.md` under `.agents/handoffs/` (recursive),
+ * plus the legacy single `.agents/memory/handoff.md` if present (backward compat
+ * for projects deployed before sharding). `README.md` files are documentation,
+ * not handoffs, so they are skipped. Sorted for deterministic output. */
+function handoffFiles(root) {
+  const files = [];
+  const collect = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) collect(abs);
+      else if (
+        entry.name.toLowerCase().endsWith(".md") &&
+        entry.name.toLowerCase() !== "readme.md"
+      )
+        files.push(abs);
+    }
+  };
+  collect(path.join(root, ".agents", "handoffs"));
+  const legacy = path.join(root, ".agents", "memory", "handoff.md");
+  if (fs.existsSync(legacy)) files.push(legacy);
+  return files.sort();
 }
-const src = fs.readFileSync(handoff, "utf8");
-
-const heading = src.match(/^#{1,6}\s*Dispatch log\s*$/im);
-check(!!heading, "handoff.md opens a `## Dispatch log` section");
-if (heading) {
-  const after = src.slice(heading.index + heading[0].length);
-  const sectionTail = after.match(/^#{1,6}\s/m);
-  const section = (sectionTail ? after.slice(0, sectionTail.index) : after).trim();
-  const entry = section.match(/^\s*[-*]\s*\S/m);
-  check(
-    !!entry,
-    "dispatch log contains at least one entry line (subagent result, waived:, or degraded:)"
+
+const files = handoffFiles(root);
+
+if (files.length === 0) {
+  console.error(
+    "FATAL: missing session handoff \u2014 add one under .agents/handoffs/<feature-id>.md"
   );
+  process.exit(2);
+}
+
+console.log(
+  "  checked against: " + files.map((f) => path.relative(root, f)).join(", ")
+);
+
+const waivers = [];
+for (const file of files) {
+  const rel = path.relative(root, file);
+  const src = fs.readFileSync(file, "utf8");
+
+  const heading = src.match(/^#{1,6}\s*Dispatch log\s*$/im);
+  check(!!heading, `${rel} opens a \`## Dispatch log\` section`);
+  if (heading) {
+    const after = src.slice(heading.index + heading[0].length);
+    const sectionTail = after.match(/^#{1,6}\s/m);
+    const section = (sectionTail ? after.slice(0, sectionTail.index) : after).trim();
+    const entry = section.match(/^\s*[-*]\s*\S/m);
+    check(
+      !!entry,
+      `${rel} dispatch log contains at least one entry line (subagent result, waived:, or degraded:)`
+    );
+  }
+
+  for (const w of src.matchAll(/\bwaived:\s*([^\n,]+)/gi)) {
+    const line = src.split(/\r?\n/)[src.slice(0, w.index).split(/\r?\n/).length - 1];
+    waivers.push({ line: line.trim(), rel });
+  }
 }
 
-const waivers = [...src.matchAll(/\bwaived:\s*([^\n,]+)/gi)];
 for (const w of waivers) {
-  const line = src.split(/\r?\n/)[src.slice(0, w.index).split(/\r?\n/).length - 1];
   check(
-    /\breason:\s*\S/.test(line),
-    `every waived entry cites a reason: \`${line.trim()}\``
+    /\breason:\s*\S/.test(w.line),
+    `every waived entry cites a reason (${w.rel}): \`${w.line}\``
   );
 }
 
 console.log(
   `\nRESULT: ${failures.length ? `${failures.length} FAILURE(S)` : "governance green"}`
 );
-process.exit(failures.length ? 1 : 0);
+process.exit(failures.length ? 1 : 0);

package/templates/.agents/memory/handoff.md

@@ -1,12 +0,0 @@
-# Where we stopped (handoff)
-
-Date: <YYYY-MM-DD>
-
-## Dispatch log
-- <subagent → model → shipped/deferred> (empty log = non-compliant session)
-
-## Done this session (planned → shipped → deferred)
-- 
-
-## Still open / next
--