@dombaras/agent-harness 0.1.15 → 0.1.17

package/README.md

@@ -43,7 +43,8 @@ npx @dombaras/agent-harness init --target . --dry-run
 | `.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) |
@@ -121,7 +122,8 @@ warns but does not block; the guarantee only applies to registered flows.
   agents (planner, system-architect, security-engineer, diagnostics-expert,
   product-manager, qa-architect) in one step. Aliases: `deepseek`/`direct` →
   `deepseek/deepseek-v4-pro` (default, direct API key), `zen`/`opencode` →
-  `opencode/deepseek-v4-pro` (gateway), `pickle` → `opencode/big-pickle`, or any
+  `opencode/deepseek-v4-pro` (gateway), `pickle` → `opencode/big-pickle`,
+  `nvidia`/`kimi`/`kimi-k3` → `nvidia/moonshotai/kimi-k3` (NVIDIA NIM), or any
   explicit `provider/model`. Restart opencode after switching (config reads once).
 - **`/board` command** — every deploy ships an opencode command
   (`.opencode/command/board.md`) that reads the local `BACKLOG.md` and renders a
@@ -155,7 +157,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`.
 
@@ -170,7 +172,7 @@ 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`, `test:docs`) into the target's `package.json` (merged, add-only).
 - **Auto-commits** the harness files it changed (`chore(harness): @dombaras/agent-harness
@@ -178,7 +180,7 @@ npx @dombaras/agent-harness update --target /path/to/project
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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"

package/templates/.agents/AGENTS.md

@@ -55,17 +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
@@ -141,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,7 @@ 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`,

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,11 +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

@@ -46,6 +46,43 @@ non-redundant.
 - `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`):

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

@@ -22,5 +22,6 @@ You are the {{PROJECT_NAME}} Documentation Keeper. Read and follow the complete
 - 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/.opencode/command/switch-model.md

@@ -8,6 +8,7 @@ Valid values:
 - `deepseek` / `direct` (default) -> `deepseek/deepseek-v4-pro` (direct API key)
 - `zen` / `opencode` -> `opencode/deepseek-v4-pro` (Zen gateway)
 - `pickle` / `big-pickle` -> `opencode/big-pickle`
+- `nvidia` / `kimi` / `kimi-k3` -> `nvidia/moonshotai/kimi-k3` (NVIDIA NIM)
 - any other explicit model id (e.g. `opencode/gpt-5.6-luna`)
 
 Run:

package/templates/AGENTS.md

@@ -5,7 +5,7 @@ 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.

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/scripts/qa/models.allowlist.txt

@@ -62,3 +62,4 @@ opencode/qwen3.6-plus
 deepseek/deepseek-v4-flash
 deepseek/deepseek-v4-flash-vision-exp
 deepseek/deepseek-v4-pro
+nvidia/moonshotai/kimi-k3

package/templates/scripts/switch-reasoning-model.ps1

@@ -15,6 +15,9 @@ $aliases = @{
   "big-pickle"     = "opencode/big-pickle"
   "pickle"         = "opencode/big-pickle"
   "bigpickle"      = "opencode/big-pickle"
+  "nvidia"         = "nvidia/moonshotai/kimi-k3"
+  "kimi"           = "nvidia/moonshotai/kimi-k3"
+  "kimi-k3"        = "nvidia/moonshotai/kimi-k3"
 }
 
 $targetModel = $Target
@@ -28,7 +31,8 @@ elseif (-not ($targetModel -match "^[a-zA-Z0-9._-]+/")) {
 $reasoningModels = @(
   "deepseek/deepseek-v4-pro",
   "opencode/deepseek-v4-pro",
-  "opencode/big-pickle"
+  "opencode/big-pickle",
+  "nvidia/moonshotai/kimi-k3"
 )
 
 $files = @(

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
--