@dougharness/cli 1.0.1

package/node_modules/@dougharness/flow/skills/harness-fix/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: harness-fix
+description: The by-hand procedure for changing Doug's own harness code (plugins/doug-flow, plugins/doug-gates, packages/doug-codex, packages/doug-cli, evals) without running it through the flow (decision 0005). Which test file covers which module, a single test file while iterating, the full gate before a commit, gate scripts copied into .doug/hooks/scripts, no attribution trailers, and a docs/live-runs.md line when a measurement changes. Use it for any edit under those directories, and from /core-next.
+allowed-tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+# harness-fix
+
+Harness code is built directly in the checkout: tests first, the full gate, a plain commit. This is the procedure; `/core-next` follows it for every hand-track card, and it applies just as well to a one-line fix made outside a card.
+
+## 0. Who does the work
+
+The lead briefs and gates; it never implements, verifies, or reviews the change itself. Before the coder, the `tester` agent (`.claude/agents/tester.md`), spawned with the Agent tool on the `implement` row of the CLAUDE.md Models table, writes or extends the test file first, from the goal; the coder implements against it. A tester that leaves tests red by design ends with its tests_red_by_design claim, in its final plain-text message or its hand-back call; the SubagentStop gate reads both. The `coder` agent, on the same row, may not edit a test except with a stated reason in its report. The `reviewer` agent, on the `review` row, reviews, and checks that rule. Verification on the hand track is the gate itself (`pnpm typecheck` and `pnpm test:unit`), which the reviewer runs and the lead re-runs before the commit. This holds on both tracks, swarm or not; a hand-track lead is the session model. For a card whose acceptance is that a mechanism exists, the reviewer is expected to mutate the mechanism and rerun the test rather than only read the diff (rule 7), rerunning the brief's mutation list and adding its own; the flow track's `plugins/doug-flow/agents/reviewer.md` does not carry this instruction — it is read-only by tool policy, and its verifier and adversary stages run the code afterward instead. On a tests-only card (the goal says tests only, no production change) there is no coder: the tester runs the brief's mutation list itself in a scratch copy or git worktree under `.doug/.state`, never editing a production file in the live checkout, and reports each result.
+
+## 1. Find the test that covers the module
+
+Under a card, the tester writes or extends the test before the change, in the file that already covers the module, and the coder runs only that file while iterating: `pnpm exec vitest run <path/to/file.test>`. For a one-line fix outside a card there is no tester: its author writes the test first, in the same file, and runs only that file.
+
+| Module | Test file |
+|---|---|
+| `plugins/doug-flow/workflows/doug-implement.js` (the loop, the ledger, the prompts), `agents/*.md`, `skills/*/SKILL.md`, the plugin manifest | `plugins/doug-flow/tests/template.test.mjs` |
+| `plugins/doug-flow/lib/board.mjs`, `scripts/board.mjs` | `plugins/doug-flow/tests/board.test.mjs` |
+| `plugins/doug-flow/lib/plan.mjs` validation, levels, rendering, `mergePlans` | `plugins/doug-flow/tests/plan.test.mjs` |
+| `scripts/plan.mjs set`, `plan.mjs merge` (several cards in one plan) and `--file`, config defaults for install and adversary | `plugins/doug-flow/tests/plan-set.test.mjs` |
+| `lib/plan.mjs` specHash, reusePlan, `plan.mjs replan` | `plugins/doug-flow/tests/replan.test.mjs` |
+| `plugins/doug-flow/lib/land.mjs`, `plan.mjs land`, worktree pruning | `plugins/doug-flow/tests/land.test.mjs` |
+| `plugins/doug-flow/lib/worktrees.mjs` (worktree removal, used by `land.mjs`; branch retirement, used by `scripts/plan.mjs`) | `plugins/doug-flow/tests/land.test.mjs` (removal), `plugins/doug-flow/tests/replan.test.mjs` (retirement) |
+| `plugins/doug-flow/lib/models.mjs` (the CLAUDE.md Models table) | `plugins/doug-flow/tests/models.test.mjs` |
+| `plugins/doug-flow/lib/cost.mjs`, `scripts/cost.mjs` (a run's cost from local transcripts; the price table) | `plugins/doug-flow/tests/cost.test.mjs` |
+| `plugins/doug-flow/lib/embeddings.mjs` (the embedding provider layer: openai-compatible and voyage adapters, probeProvider, doctorReport) | `plugins/doug-flow/tests/embeddings.test.mjs` |
+| `plugins/doug-flow/lib/code-index.mjs` (the opt-in semantic code index: file listing, chunking, incremental build, status, search) | `plugins/doug-flow/tests/code-index.test.mjs` |
+| `plugins/doug-flow/lib/learn.mjs`, `scripts/learn.mjs` (deterministic proposals from outcomes/lessons signals and the run trace; card learn-signals) | `plugins/doug-flow/tests/learn.test.mjs` |
+| `plugins/doug-flow/lib/decisions.mjs` (proposal diffs for docs/decisions/ ADRs and .claude/rules/ conventions; card memory-decisions), `scripts/memory.mjs`'s `decision`/`rule` cases | `plugins/doug-flow/tests/decisions.test.mjs` |
+| `plugins/doug-flow/lib/memory.mjs`, `scripts/memory.mjs` (the outcome log and lesson store: recall, the outcome record, reflect, and the memory.mjs CLI's index dispatch; card memory-lib) | `plugins/doug-flow/tests/memory.test.mjs`, `plugins/doug-flow/tests/memory-cli.test.mjs` |
+| `plugins/doug-flow/lib/memory-import.mjs` (the `memory.mjs import` command; card memory-import) | `plugins/doug-flow/tests/memory-import.test.mjs` |
+| `plugins/doug-gates/scripts/*.mjs` end to end (protect-paths, guard-bash, format-on-edit, edit-loop, stop-gate, reanchor, checkpoint) | `plugins/doug-gates/tests/hooks.test.mjs` |
+| `plugins/doug-gates/lib/bash-rules.mjs` | `plugins/doug-gates/tests/bash-rules.test.mjs` |
+| `plugins/doug-gates/lib/scope.mjs` (plan scope) | `plugins/doug-gates/tests/scope.test.mjs` |
+| `plugins/doug-gates/lib/secret-rules.mjs`, `scripts/secret-scan.mjs` | `plugins/doug-gates/tests/secret-scan.test.mjs` |
+| `plugins/doug-gates/lib/checkpoint.mjs` | `plugins/doug-gates/tests/checkpoint.test.mjs` |
+| `plugins/doug-gates/lib/config.mjs`, state and paths | `plugins/doug-gates/tests/config-state.test.mjs` |
+| `plugins/doug-gates/lib/proposals.mjs` (the applied-proposal ledger reader; card memory-decisions) | `plugins/doug-gates/tests/hooks.test.mjs` (protect-paths/stop-gate proposal-path blocks) |
+| `plugins/doug-gates/lib/glob.mjs` | `plugins/doug-gates/tests/glob.test.mjs` |
+| `plugins/doug-gates/lib/anchor.mjs` (the PreCompact snapshot in the anchor) | `plugins/doug-gates/tests/hooks.test.mjs` (reanchor on PreCompact) |
+| `plugins/doug-gates/lib/evidence.mjs` (verification evidence: which recorded commands count) | `plugins/doug-gates/tests/evidence.test.mjs`; the stop-gate and guard-bash sides in `hooks.test.mjs` |
+| `plugins/doug-gates/lib/trace.mjs` (the run trace: line shape, transcript usage, replay, attribution) | `plugins/doug-gates/tests/trace.test.mjs`; the `trace` script end to end in `hooks.test.mjs` |
+| `plugins/doug-gates/scripts/statusline.mjs` | `plugins/doug-gates/tests/statusline.test.mjs` |
+| the checked-in pre-commit hook | `plugins/doug-gates/tests/git-hooks.test.mjs` |
+| `packages/doug-cli/src/board.ts` (`doug board`) | `packages/doug-cli/tests/board.test.ts` |
+| `packages/doug-cli/src/board-page.ts`, `board-serve.ts`, `templates/board-app.js` | `packages/doug-cli/tests/board-page.test.ts` (serve tests skip with a reason where a local listener is denied: `board-page-skip.test.ts`) |
+| `packages/doug-cli/src/detect/*` | `packages/doug-cli/tests/detect.test.ts` |
+| `packages/doug-cli/src/generate/*` (config, CLAUDE.md, settings, proposal, apply) | `packages/doug-cli/tests/proposal.test.ts` |
+| `packages/doug-cli/src/diff.ts` | `packages/doug-cli/tests/diff.test.ts` |
+| `packages/doug-cli/src/ablate.ts` (`doug ablate`: eval results per condition, the runner pass-through) | `packages/doug-cli/tests/ablate.test.ts` |
+| `packages/doug-cli/src/trace.ts` (`doug trace`: replay and per-agent attribution of a run trace) | `packages/doug-cli/tests/trace.test.ts` |
+| `packages/doug-codex/src/prompt.ts` | `packages/doug-codex/tests/prompt.test.ts` |
+| `packages/doug-codex/src/parse.ts` (Codex JSONL, verdict, exit codes) | `packages/doug-codex/tests/parse.test.ts` |
+| `packages/doug-codex/src/run.ts` (spawning codex, timeout, worktree check) | `packages/doug-codex/tests/run.test.ts` |
+| `packages/doug-codex/src/contract.ts` and `docs/worker-contract.md` | `packages/doug-codex/tests/contract.test.ts` |
+| `packages/doug-codex/src/bin.ts` (`codex-review`) | `packages/doug-codex/tests/cli.test.ts` |
+| `evals/run.mjs` (the scorer: tool calls from stream-json, leaks, must-run commands) and `evals/tasks/*.json` | `evals/tests/run.test.mjs` |
+| `plugins/doug-flow/scripts/rehearse.mjs`, `lib/rehearse.mjs` (the on-demand live rehearsal runner: estimates, fixture, stream assertions, recording) | `plugins/doug-flow/tests/rehearse.test.mjs` |
+| the `reviewIssues` report key (doug-implement.js) round-tripping into `lib/memory.mjs`'s `review_issue_count`/`review_issues`, through `board.mjs record`, `board.mjs summary`, and `plan.mjs replan` (card seam-contracts) | `plugins/doug-flow/tests/seams.test.mjs` |
+| every `board.mjs`/`plan.mjs`/`memory.mjs` subcommand a `skills/*/SKILL.md`, `CLAUDE.md`, or `docs/worker-contract.md` names being a real dispatch case (card seam-contracts) | `plugins/doug-flow/tests/seams.test.mjs` |
+| `claude plugin validate` actually catching a broken plugin manifest (card seam-contracts) | `plugins/doug-flow/tests/seams.test.mjs` |
+| `doug init`'s PreToolUse wiring firing for real (protect-paths.mjs deny/allow, not just a string comparison of the wiring) (card seam-contracts) | `packages/doug-cli/tests/init-hooks.test.ts` |
+
+`packages/doug-codex/tests/codex-live.test.ts` spawns the real Codex and is excluded from the gate; leave it out of iteration.
+
+## 2. Rules while changing harness code
+
+1. The workflow file `doug-implement.js` may not import, call `Date.now` or `Math.random`, or name a model; its template tests assert that, and it must parse when wrapped the way the Workflow runtime wraps it. A top-level `return` in it is expected, so `node --check` fails on it by design.
+2. The Workflow tool runs the plugin copy loaded at session start. An edited workflow is launched with `scriptPath` pointing at the file, or the session is restarted.
+3. After editing a gate script under `plugins/doug-gates/scripts/`, copy it to `.doug/hooks/scripts/` too: this repository has Doug installed on itself and its hooks run from there.
+4. A change to `plugins/doug-flow/lib/board.mjs` or `lib/plan.mjs` reaches `packages/doug-cli` through the `@dougharness/flow` workspace dependency; the CLI's `src/flow-board.d.ts` declares the shapes, so a new field or option is added there as well or `pnpm typecheck` fails.
+5. Keep the change to what the card or fix asks. A defect found on the way becomes its own hand-track card.
+6. If a hook blocks a step, report it; do not work around it.
+7. When the card's acceptance is that a mechanism exists, prove it before reporting done: mutate or remove the mechanism, run the new test file, confirm it fails, then revert the mutation and report which assertion failed. That is the line: a card whose acceptance is that a mechanism exists needs it; a card that only changes prose, a message, or a docs line does not. To prove it, the brief lists one mutation per case the card's goal names, each with the test that must fail; the coder runs every listed mutation and reports each result; the reviewer reruns the list and adds its own. Apply each mutation in a scratch copy or git worktree under `.doug/.state`, run the one test file there, and remove the copy.
+8. A card that changes a workflow's or a skill's user-visible behaviour runs the live scenario that covers it before landing: `node plugins/doug-flow/scripts/rehearse.mjs <flow|swarm|hand> --card <id> --spend`, and its landing note quotes the outcome. The swarm scenario is the one that proves plugin loading and agent-name resolution in the real runtime. `docs/rehearsals.md` says what each scenario proves, how to read a result, and how to add one.
+
+## 3. The gate, the commit, the record
+
+1. Before the commit run the full gate: `pnpm typecheck` and `pnpm test:unit`. Never `pnpm test`, which spawns Codex. Say what ran and the counts.
+2. Commit without attribution trailers, one commit per coherent change, with a message that says what changed and why. Leave `.doug/plan.json` and `.doug/anchor.md` out unless the change is about them.
+3. When the change alters a measurement (a run's cost, wall clock, pass count, or what a stage does), add a line to `docs/live-runs.md`; a change to the board record shows on the served page (`doug board serve`).

package/node_modules/@dougharness/flow/skills/research/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: research
+description: The research step before a plan, for a card whose goal depends on facts outside the repository (a Claude Code hook contract, a CLI's output format, a third-party API). One researcher, or several in parallel with distinct questions, write one cited note the planner and the builder work from; uncertainty is stated, never guessed. Invoked by /core-next, /doug-plan, and /doug-next before planning, or on its own.
+allowed-tools: Agent, Read, Write, Bash(mkdir *), Bash(cat *), Bash(node *plan.mjs *)
+---
+
+# research
+
+Facts first. A plan built on a guessed contract becomes a task the verifier cannot pass and an adversary blocker nobody can fix; on 2026-09-06 the run-trace and precompact-anchor cards each needed the claude-code-guide agent ad hoc before their plans were right. This is the procedure that was missing.
+
+## When to take it
+
+Take the step when the card's goal (or the request) depends on a fact that is not in the repository and not in the conversation: the exact shape of a Claude Code hook input, the fields of a CLI's JSON output, a third-party API's behavior, a package's version constraints. Skip it when every fact the plan needs can be read from the checkout. When in doubt, take it: one researcher costs less than one blocked pass.
+
+## Who runs it
+
+- Questions about Claude Code itself (hooks, skills, agents, the Workflow tool, the SDK, the API): `Agent({ subagent_type: "claude-code-guide", prompt: "<the question>" })`. Reuse a guide agent already running in the session with SendMessage rather than spawning another. The fetch budget (research.maxFetches) counts per agent, so a reused guide shares one budget across every question sent to it; when a question needs its own budget, spawn a fresh guide instead. This agent keeps its own model.
+- Anything else: the plugin's `researcher` agent, read-only with WebFetch and WebSearch, which answers one question from primary sources, quotes each source with its URL or the command and its output, never installs or writes, and marks what it could not confirm. It runs on the `plan` row, the same row the planner uses: read it with the `plan.mjs models` command, `node "${CLAUDE_PLUGIN_ROOT}/scripts/plan.mjs" models`, which prints the parsed table as JSON (`roles.plan.model`), and pass that row's model (omit `model` when the row says `inherit`): `Agent({ subagent_type: "doug-flow:researcher", model: "<the plan row's model>", prompt: "<the question>. Other researchers are answering: <their questions, if any>." })`. It returns findings, not a file; this skill writes the note. The Agent tool carries no effort parameter, so the row's effort applies through the researcher agent's own frontmatter (`effort: high`, the plan row's default); a repository whose plan row sets another effort changes that frontmatter line.
+
+The session model never researches itself; it asks the questions and writes the note from the answers.
+
+## One researcher or several
+
+One question, one researcher. Several independent questions get several researchers in the same message, in parallel, each with one distinct question and told not to answer the others'; their answers merge into one note. A request or card that names a crew of researchers (`crew: { "researchers": 2 }` in the plan's terms) gets that many, each with its own question. Do not give two researchers the same question: a disagreement between two guesses is not a check. Each question names the budget (at most 6 WebSearch plus WebFetch calls, research.maxFetches) and lists the raw URLs to try, in priority order.
+
+## The note
+
+Write the findings to `.doug/.state/research/<card-id>.md` (session state, ignored by git; `mkdir -p` the directory first), one section per question:
+
+- the fact, in one or two sentences, as the plan will use it;
+- the sources: a URL, a file path with a line, or a command and its output, one per fact;
+- what stayed unverified, marked `unverified`, with what was tried. Never guess a fact into the note; an unverified line is what keeps the planner from building on it.
+
+The note is written under the card's id, not the question's, because the id is also the promotion key: a note for a card that lands is promoted to `docs/research/<card-id>.md`, `board.mjs record` copying it there when it records the landing so a commit that cites the note has something to read afterward. A note for a card that never lands (dropped, replanned under another id) stays in state and is eventually swept with the rest of `.doug/.state/`.
+
+Then hand it on:
+
+- Flow track (`/doug-plan`, `/doug-next`): give the planner the note's path in its prompt. The planner writes the facts it relied on into the plan's goal with their sources and marks any unverified one.
+- Hand track (`/core-next`): the builder reads the note before the test, cites the sources in the commit message where a fact decided the design, and names the note in the landing's `--note`.
+
+The step spends agents only when invoked and publishes nothing.

package/node_modules/@dougharness/flow/skills/run-report/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: run-report
+description: End a card's run with one command: append the docs/live-runs.md entry for a workflow report (or a hand-track landing), and print the three-line summary that goes in the chat. Called by /doug-next after land and by /core-next after the commit; usable on any saved report.
+allowed-tools: Agent, Read, Bash
+---
+
+# run-report
+
+One card's landing, recorded and summarized. The entry and the summary are rendered by `scripts/board.mjs`, never written by hand, so every run is recorded in the same shape.
+
+## A workflow run (flow track)
+
+With the card id, the report (`.doug/.state/last-report.json` unless another path is given), the run id the Workflow tool printed (`wf_...`), the wall clock, and the landing commit:
+
+1. `node "${CLAUDE_PLUGIN_ROOT}/scripts/cost.mjs" <run-id>`: the run's real cost, summed from the local Claude Code transcripts of every agent in the run and priced from the dated table in the script (no network). Its last lines are the run total and any agent it could not price. The number after `Run total:` is the cost; when the run cannot be found or every agent is unpriced, there is no cost. The workflow itself does not report cost; never estimate one. The Codex line after it, when present, is the Codex adversary's cost: pass its USD as --codex-cost <usd> to record and summary; it is never added to --cost.
+2. Classify every adversary block in the report. A block is a finding the adversary raised as a blocker (its ledger id, `F1`; for a report from before the ledger, `pass-<n>`); `board.mjs record` refuses an id the report does not have and lists the ones it has. This is judgment work and runs on the `review` row: read it with the `plan.mjs models` command, `node "${CLAUDE_PLUGIN_ROOT}/scripts/plan.mjs" models` (`roles.review.model`, `roles.review.effort`), and spawn `Agent({ subagent_type: "doug-flow:reviewer", model: "<review row model>", prompt: "There is no worktree and no diff for this job: read the report at <report path> (repository root, read-only) and classify every adversary block in it as real (a defect a user would hit), marginal (true to the spec, no user impact), or false (wrong), each with a one-line reason drawn from the fix passes and the checks in the report, not from the adversary's summary. Return exactly one line per block, nothing else: F1=<real|marginal|false>: <one-line reason> (pass-<n>=... for a pre-ledger report). Edit nothing." })`. The lead passes each returned line into `--adversary` verbatim and never reclassifies.
+3. `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" record <id> <report.json> --wall "<m> min" --commit <sha> --cost <usd> [--codex-cost <usd>] --adversary "F1=<class>: <reason>"` with `--adversary` repeated once per block, leaving `--cost` out when step 1 gave no number and `--codex-cost` out when step 1 showed no Codex line. This appends the entry to `docs/live-runs.md`: the measures table with the precision line (n real / n marginal / n false), the per-level, per-task table, and one line per classified block. It also promotes `.doug/.state/research/<id>.md` to `docs/research/<id>.md` when that note exists, printing one line saying so; add that path to the landing commit alongside `docs/live-runs.md`.
+4. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" import`: rolls any auto-memory file written since the last import into the lessons store — it is idempotent, a rewritten file supersedes its old row, and it never writes under the auto-memory directory. Its one-line output goes in the chat; an exit 1 naming Node is said in the chat and the landing goes on, the same as record below.
+5. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" record <report.json> --run <run-id> --card <id> --commit <sha> --adversary "F1=<class>: <reason>"` with `--adversary` repeated once per block, the same values step 3 used, and `--commit` left out for a run that stopped. It appends one row per task of the report to the local outcome log `.doug/.state/memory/memory.db` (uncommitted; run id, card, spec hash, owned files from the plan, size, shape, models, verify and review results, the classified adversary blocks, fix passes, budget, tokens and USD measured from the same transcripts `cost.mjs` read, or null where nothing was measured). It needs Node >=22.16 (node:sqlite). When it exits 1 naming Node, say so in the chat and go on, since the record is a log, not a gate.
+6. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" reflect <report.json> --run <run-id> --card <id> --commit <sha> --adversary "F1=<class>: <reason>"` with `--adversary` repeated once per block, the same values step 5 used. It applies deterministic helpful/harmful counters to any lesson a task's `memoryUsed` names, then runs a cheap-row `claude -p --json-schema` pass that proposes and appends at most three lessons from the report, filtered in code. Its one-line summary (with the measured cost) goes in the chat. An exit 1 naming the LLM pass is said in the chat and the landing goes on regardless — reflect is a log, not a gate, the same as record.
+7. `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" summary <report.json> --wall "<m> min" --commit <sha> [--codex-cost <usd>]` (same `--cost` rule) and put its three lines in the chat verbatim, in a fenced code block: the outcome, the tasks, and what stopped or was not met.
+
+A run that stopped is recorded the same way, without `--commit`; the summary's third line quotes each task's stop reason.
+
+## A batch (several cards in one plan)
+
+When `.doug/plan.json` carries `cards` (made by `plan.mjs merge`), the run is recorded once per card:
+
+1. `node "${CLAUDE_PLUGIN_ROOT}/scripts/cost.mjs" <run-id> --by-card`: after the usual tables, a per-card table with each card's tasks' agents summed for that card and one row for the shared integration agents (the integrate and level-adversary agents, task `level-<n>`). The card rows are each card's `--cost`; the shared row is `--shared-cost`, the same number for every card. Pass the Codex line's USD as --codex-cost to the first card's record only.
+2. Classify the adversary blocks per card: `board.mjs record` lists only that card's tasks' blocks and refuses the others' ids.
+3. For each card, in the plan's `cards` order: `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" record <id> <report.json> --wall "<m> min" --commit <sha> --cost <that card's usd> --shared-cost <shared usd> [--codex-cost <usd>, first card only] --adversary ...`. Record reads the batch from the plan file: the entry names the other cards, shows only that card's tasks and the integration rows of their levels, and counts the shared cost once, under the first card.
+4. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" import` once for the whole report, the same as the workflow-run form's step 4: its one-line output goes in the chat, an exit 1 naming Node is said in the chat and the landing goes on, and it is idempotent, a rewritten file supersedes its old row, and it never writes under the auto-memory directory.
+5. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" record <report.json> --run <run-id> --commit <sha> --adversary ...` once for the whole report, with every card's block classes (each task carries its card in a batch report; no `--card`).
+6. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" reflect <report.json> --run <run-id> --commit <sha> --adversary ...` once for the whole report, no `--card` (each appended lesson's card comes from its own task).
+7. `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" summary <report.json> --card <id> --wall "<m> min" --commit <sha>` per card (same `--cost` rule), and put each card's three lines in the chat. Its "Acceptance not met" line reads only that card's own tasks by their `[<card>] ` tag (or the final integration level's acceptance, when the report carries it), so another card's failing command, or a command that depends on a level not yet run, never shows as this card's; the line names which source it used.
+
+## A hand-track landing
+
+With the card id, the landing commit, the wall clock, and the gate line (`typecheck 0; unit <n> passed`):
+
+1. `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" record <id> --hand --commit <sha> --wall "<m> min" --gate "typecheck 0; unit <n> passed"`, with `--note "<one line>"` when something about the build is worth keeping. This appends the hand-track entry to `docs/live-runs.md`; its table is the summary. It also promotes `.doug/.state/research/<id>.md` to `docs/research/<id>.md` when that note exists, printing one line saying so; add that path to the landing commit alongside `docs/live-runs.md`.
+2. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" import`, the same as above: its one-line output goes in the chat, an exit 1 naming Node is said in the chat and the landing goes on, and it is idempotent, supersedes a rewritten file, and never writes under the auto-memory directory.
+3. `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs" record <id> --hand --commit <sha> --wall "<m> min" --gate "typecheck 0; unit <n> passed" [--note "<one line>"]`, the same values step 1 used. It records one row in the local outcome log `.doug/.state/memory/memory.db` (uncommitted), keyed `hand:<sha>` so re-recording the same commit updates that row and track `hand`; a card that lands twice, in two commits, gets two rows. Its workflow-only columns (verified, review counts, adversary verdict, blocks, fix passes, budget, tokens, USD, the report itself) are null because they do not exist on this track, never because they measured zero: no independent verifier ran, and the gate's own text is the `gate` column instead. It needs Node >=22.16 (node:sqlite). When it exits 1 naming Node, say so in the chat and go on, since the record is a log, not a gate.
+
+`memory.mjs reflect` does not run on a hand-track landing: there is no report for the cheap-row pass to read.
+
+Say the commit, the wall clock, and the gate line in the chat.
+
+## Then
+
+Moving the card and committing the record and the log belong to the calling skill (`/doug-next` step 5, `/core-next` step 4); a record change shows on the served page (`doug board serve`).

package/node_modules/@dougharness/flow/skills/swarm-launch/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: swarm-launch
+description: Run an approved plan that opts into the swarm (plan.mjs set swarm on) through the doug-implement workflow, where a lead agent splits each full-shape task into worker briefs, workers implement them in parallel on the worker row, and the lead merges before the usual verify, review, adversary, and integrate stages. The launch step /doug-implement and /doug-swarm share; a swarm never runs without an approved plan.
+allowed-tools: Bash(node *plan.mjs *), Workflow, Read
+---
+
+# swarm-launch
+
+The swarm lives inside a plan task (decision 0001 as amended 2026-09-06): the plan is the contract, the task's owned files are the workers' boundary, and the same gates read the merged result. This skill is the one launch step every caller shares, so the rules live in one place.
+
+## Preconditions
+
+1. `node "${CLAUDE_PLUGIN_ROOT}/scripts/plan.mjs" validate`: the plan must be `approved`. Nothing runs on a draft; approval is the user's act (`/doug-approve`), never this skill's.
+2. `node "${CLAUDE_PLUGIN_ROOT}/scripts/plan.mjs" show` prints `Swarm: on` when the plan opted in with `plan.mjs set swarm on`. Without it the same workflow runs the fixed pipeline; do not set it here on your own, because the opt-in is the user's (each swarm task spends a lead, N workers, and a merge instead of one implementer). The swarm pays on a task with independent deliverables that share no new symbol; a plan of small coupled tasks runs as the pipeline (`docs/decisions/0001-hierarchical-swarms.md`, Amendment 2026-09-20: one brief per task at +2.67 USD and +6.1 min against the pipeline on 2026-09-11; five briefs, 8/8 hidden tests, 8.31 USD, 8.5 min on 2026-09-19).
+3. The caller is a user-invoked skill or command (`/doug-implement`, `/doug-next`, `/doug-swarm`, `/core-next` for a size M or L hand-track card the user chose to swarm): that invocation is the opt-in the Workflow tool requires. No swarm runs in the background or on a schedule.
+
+## Launch
+
+`node "${CLAUDE_PLUGIN_ROOT}/scripts/plan.mjs" json`, then `Workflow({ name: "doug-flow:doug-implement", args: <plan object> })` (or `scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/doug-implement.js"` when the name is not found). The plan object is passed verbatim; `swarm` travels in it.
+
+## What happens per task
+
+A size-S task keeps its single implementer. For every other task: the `lead` agent (the `lead` row of the Models table) creates the task branch and splits the task into briefs, each owning a disjoint subset of the task's files; a brief that names any other file blocks the task before a worker runs. The workers (`implementer` agents on the `worker` row, one worktree each, labels `worker:<task>:<n>`) implement their briefs in parallel and commit on `doug/task-<id>-w<n>`. The lead merges the branches into `doug/task-<id>`, runs the task's verify command, and returns an implementer result; verify, review, the adversary, the ledger, the budget, and integration run on it unchanged, and a fix pass is one implementer in the lead's worktree. The report records `workers` per task (brief, files, branch, commit, block) and the lead and worker tiers under `models`; `cost.mjs` shows each worker's cost. A deterministic shape gate keeps a full-shape task whose owned files are one source file plus its tests off the lead as well, and the lead's split always carries a required `splitReason` the report can read to tell an unsplittable task from one nobody tried to split. A worker that blocks gets the lead back once to re-brief the unfinished pieces (label `lead-rebrief:<task>`) before the task blocks; a worker still partial after its resume, or a second block, ends the task as before. `plan.mjs set workerCheck on` (off by default) adds a deterministic check after each round, before the merge: a worker whose filesTouched strayed outside its brief, or who never committed, is blocked the same way, with `checkFailed: true`.
+
+## Report
+
+Read the report as `/doug-implement` does. Name each task's briefs and which worker blocked when one did; a lead block says `lead brief <id> names a file the task does not own` when the split tried to widen, and the fix is a wider task at approval, never a wider brief.