freeharness 0.4.1 → 0.4.2

package/canonical/skills/subagent-driven-development/reference/brief.md

@@ -1,36 +1,169 @@
 # Brief template
 
-One brief per task (or per batch of small same-shape tasks) at
-`.freeharness/sdd/<change>/<task>.brief.md`. The brief is the single source of
-requirements for the implementer: exact values, signatures and test names live here,
-never in the dispatch prompt. The implementer reads the brief, the files it names and
-nothing else; never the whole plan, never the session history.
-
-Header lines are `Key: value`, one per line, in this order. `Spec` is the OpenSpec
-change id (the implementer runs `openspec status --change <id>` and reads the delta
-specs it needs); never a copied spec, never a path. `Write scope` lists every file the
-implementer may create or modify, one entry per line in one of three forms: an exact
-file path; a directory with a trailing `/`, matching everything under it; or a glob,
-`*` matching within one path segment and `**` matching across segments. A path under
-`.freeharness/` is never charged to a worker, in or out of the write scope. Briefs
-dispatched together have disjoint scopes, and `scripts/validate-handoff.mjs briefs
-<dir>` refuses the batch on overlap. `Class` is
-optional, right after `Tier`: a freeform token for the cost tracker's `task_class` field
-(e.g. `feature`, `bugfix`, `refactor`, `spike`); a brief without it tags the session
-`untagged`. `Ceiling` is optional, right after `Class`: a positive integer, the per-task
-cache-read token ceiling summed across every dispatch of the task (impl, review and fix
-rounds alike); it overrides the `budget` subcommand's default ceiling of 25,000,000 for
-that task, and a brief without it uses that default.
+One brief per task at `.freeharness/sdd/<change>/<task>.brief.md`; a task above the
+sizing bounds is split into sub-tasks first, each with its own brief. The brief is the
+single source of requirements for the implementer: exact values, signatures and test
+names live here, never in the dispatch prompt. The implementer reads the brief, the files
+it names and nothing else; never the whole plan, never the session history.
+
+Header lines are `Key: value`, one per line, in this order. `Task` names exactly one id
+(`2.4`, a sub-task `2.4.1`, or `final`); `validate-handoff.mjs briefs` refuses a list, a
+range or a batch. `Spec` is the OpenSpec change id (the implementer runs `openspec status
+--change <id>` and reads the delta specs it needs); never a copied spec, never a path.
+`Write scope` lists every file the implementer may create or modify, one entry per line in
+one of three forms: an exact file path; a directory with a trailing `/`, matching
+everything under it; or a glob, `*` matching within one path segment and `**` matching
+across segments. A path under `.freeharness/` is never charged to a worker, in or out of
+the write scope. A source-file entry may carry a range, `path:120-340`, or a symbol,
+`path#symbolName` (counted as 200 lines), which narrows the reading-set estimate. A
+`path:append` entry names a file the task only appends to: its estimate counts the file's
+last 200 lines; it takes no range or symbol (`path:10-20:append` is refused) and no
+directory or glob; `handoff --brief` fails `append-only <path>` when the file's diff against
+the base removes, changes or inserts a line above the base file's last 5 lines, so
+replacing a closing line and appending entries pass. Briefs
+dispatched together have disjoint scopes, and `scripts/validate-handoff.mjs briefs` refuses
+the batch on overlap. The lead names the new brief files plus every brief file still in
+flight, never the workspace directory: a directory argument skips the set checks, since the
+workspace also holds landed briefs.
+
+`Tier` and `Class` route the dispatch. `docs`, `extraction`, `exploration` and
+`mechanical` (documentation, extraction, exploration, mechanical edits such as matrix
+rows, renames, one-line values and transcription of complete plan text) run on `standard`
+or `strong`; `summary` runs on `fast`, `standard` or `strong`, and `extraction` also on
+`fast`; `security` (a task that changes a security boundary: a guard, a hook verdict, an
+auth or secret path, input validation of untrusted payloads) and `complex` (a parser or
+state machine, concurrency, a cross-file contract, or a task that reached the round cap
+before) run on `strong` with `Effort: high` only; `code` (a code change that is neither
+`security` nor `complex`) runs on `strong`, or on `standard` only with a `Route:` header
+(below); any other class, or none, runs on `strong` only (the implementer's own tier). A
+fix round runs on the tier and effort `validate-handoff.mjs route <brief> --round <n>
+[--p0] [--security]` prints, and any rewrite of a standard `code` brief to `strong` (fix
+round 2, or a fix round carrying a P0 or a security finding) drops the `Route:` line. A `fast` brief keeps
+its reading set under 100,000 tokens at 4 bytes per token; the validator checks the class, never that bound. `validate-handoff.mjs briefs`
+refuses a class the tier does not allow, naming the brief and the allowed classes.
+`Class` is optional, right after `Tier`: the class token also fills the cost tracker's
+`task_class` field; a brief without it tags the session `untagged` and runs on `strong`.
+`Effort` is optional, right after `Class`: `medium` (the default) or `high`; `high` runs
+on `strong` only and is passed as the per-dispatch effort. `Route` comes right after `Effort`, on
+a standard `code` brief only (below). `Split` is optional: `Split: refused - <reason>` waives the size bounds
+when the work cannot be divided, and is the only accepted value. `Read` is optional: a
+comma-separated list of files (with ranges or symbols) the worker reads beyond its write
+scope; its entries count in the reading set. The size bounds are at most 3 write-scope
+files outside test and fixture directories and a reading set under 60,000 tokens at 4
+bytes per token. `Ceiling` is optional, right after `Split` and `Read`: a positive
+integer, the per-task cache-read token ceiling summed across every dispatch of the task
+(impl, review and fix rounds alike), at or below the task's class ceiling: 60,000,000 for
+`security` and `complex`, 50,000,000 for task `final` and 25,000,000 for any other task,
+or the owner's `Ceiling <class>:` value in the change's run authorization (reference/loop.md).
+The header only lowers the class ceiling; `briefs` and `budget` refuse one above it.
+
+`Route: C1-C7 - <reason>` is required on, and allowed only on, a brief with `Tier:
+standard` and `Class: code`; it states that the task meets every standard-code
+criterion: C1 at most 2 write-scope files outside test and fixture directories; C2 no
+parser, state machine, concurrency, guard or hook verdict, auth or secret path, or
+cross-file contract; C3 an existing pattern in the repository the task follows, named in
+the `Read:` header; C4 at least 2 acceptance probes, each stating its expected outcome;
+C5 no manifest, lockfile or generated file in the write scope; C6 no edit of a test
+fixture or helper shared with other tests; C7 the task never came back `partial` or
+`blocked`, and never opened fix round 2, on `standard`. The reason is non-empty and names
+the pattern followed. `validate-handoff.mjs briefs` refuses a standard `code` brief
+without the header, a value not starting with `C1-C7 - ` or with an empty reason, and a
+`Route:` on any other brief; the validator checks C1 to C5; C6 and C7 live in the reason.
+For C1 a directory or glob entry outside test and fixture directories is refused, and a
+`*.test.*` file counts as a test entry. Example: `Route: C1-C7 - adds one retry option following
+src/http/timeout.ts; no shared fixture; first dispatch`. The template carries the line
+as a comment, like `Unaffected:`; a standard `code` brief writes it uncommented.
+
+The implementer type is the pair of `Tier` and `Effort`; there are four:
+
+| Type | Classes |
+|---|---|
+| fast/medium | extraction, summary |
+| standard/medium | docs, extraction, exploration, mechanical, summary, code with `Route:` |
+| strong/medium | every class but security and complex, any other token or none |
+| strong/high | security, complex, and any strong class the lead raises to high |
+
+`Changes` is required, right after `Ceiling`: the identifiers and literal values the task
+changes (a field, a constructor, a flag, a message, a verdict, a declared effort or model),
+comma-separated, or `none - <reason>` when the task changes none. `briefs` searches the
+text of every tracked test file for each term and refuses the brief when a file naming one
+is not covered. A test file is one under a `test`, `tests`, `__tests__` or `fixtures`
+directory, one named `*.test.*`, `*.spec.*`, `*_test.*` or `test_*.py`, or a
+`conftest.py`; a binary file and a file over 4 MiB are skipped. A file is covered when a write-scope entry matches it, an
+`Unaffected:` line names it, or a `## Verify` command names its path directly or relative
+to the command's leading `cd <dir> &&`, as a whole path: never as part of a longer one.
+`Unaffected: <path> - <reason>` is repeatable, one
+line per test file that names a term and stays untouched; the reason is required. The
+failures are `changes-unscoped <term> <path>` (a test names the term and nothing covers
+it), `changes-missing` (no `Changes:` line), `unaffected-reason <path>` (an `Unaffected:`
+line without a reason), `changes-short <term>` (a term under 3 characters) and
+`changes-broad <term> (...)` (more than 40 test files name it; name a narrower term). The
+check covers tests only, so a production file the plan missed is still found by reading
+the design.
+
+`Key-list` is optional, right after `Changes`: `Key-list: <key>[, <key>...]`, one sibling
+key per JSON object the task adds a key to. `briefs` also searches each `Changes` term
+regex-escaped, and fails `changes-unscoped key-list:<key> <path>` for an uncovered test that
+pins an exact key list naming the sibling (`Object.keys(` then a `deepEqual` array quoting it).
+
+`Suite` is required, right after `Changes` and its `Unaffected:` lines: the project's
+full-suite command. The worker never runs it and runs only the `## Verify` commands;
+`briefs` refuses a brief without it (`suite-missing`).
+
+`Tree`, `Setup` and `Resources` come right after `Suite`; reference/trees.md holds the
+tree lifecycle. `Tree: <root>/.worktrees/<change>/<task>` names the task's worktree, the
+absolute path under the main project root; `Tree: none - <reason>`, or no `Tree:` line,
+runs the task in the main tree. A brief may run in the main tree only when it is the one
+implementer in flight: `briefs` fails `tree-required <brief>` when it names more than one
+brief and any of them runs in the main tree, `tree-path <brief>` for a header that differs
+from the derived path, and `tree-absent <brief>` when the path is not a linked worktree
+(run `validate-handoff.mjs tree <brief.md>` first). `Setup: <command> | none - <reason>`
+is required on a tree brief (`setup-missing <brief>`): the command the lead runs in the
+tree before the dispatch, such as an install. `Resources: <name>[, <name>...] | none`
+names the shared ports, databases and GPUs the task uses; two named briefs listing the same
+name, compared case-insensitively, fail `resource-overlap <name> <brief> <brief>`. A write
+scope naming a dependency manifest or lockfile (the C5 set) fails `manifest-parallel
+<path>` when the run names more than one brief. A tree brief's write-scope entry under
+`.freeharness/`, or an untracked one git ignores in the main tree, fails `scope-ignored
+<entry>`, since no tree diff can show a change to it; keep such
+paths in a brief without `Tree:`. The template carries the three lines as comments, like
+`Route:`; a tree brief writes them uncommented.
+
+A line range or a symbol on a write-scope entry bounds the reading-set estimate only: it
+never narrows what the worker may edit, and an edit elsewhere in the same file never
+fails `scope`.
+
+The `## Acceptance probes` section holds 1 to 12 lines `P<n>: <command, input or
+observable> -> <expected verdict or outcome>`, written by the lead from the spec
+scenarios and the design's edge cases before the dispatch. A `security` or `complex`
+brief carries a probe whose expected outcome is an allow or a pass, and a probe that runs
+a corpus, fixture replay or generator command over the changed behavior. A probe of a
+guard or hook verdict runs the hook through node on a payload file (the hook reading the
+payload on stdin), never the probed command typed into Bash, so the session's own
+permission layer never judges the probe: `node <hook>.mjs < payload.json -> <verdict>`. The
+`## Project rules` section holds 1 to 20 lines, since the workers run without CLAUDE.md:
+the project CLAUDE.md invariants and protected boundaries that bear on the write scope,
+plus the artifact rules every worker follows.
 
 ```markdown
 # Brief <task>: <title>
 
 Change: <change-id>
-Task: <task number, or "1.3, 1.4, 1.5 (batch)">
+Task: <one task number, "2.4.1" for a sub-task, or "final" for the final branch review>
 Spec: <change-id>
 Tier: strong | standard | fast
-Class: <optional freeform task-class tag>
-Ceiling: <optional cache-read token ceiling for the task, integer; default 25000000>
+Class: <optional routing class: docs, extraction, exploration, mechanical, summary, code, security, complex, or a freeform token that runs on strong>
+Effort: <optional medium | high; high requires Tier: strong and is passed as the per-dispatch effort>
+<!-- Route: <only for Tier: standard Class: code: C1-C7 - <reason>> -->
+Split: <optional "refused - <reason>" when the work cannot be divided>
+Read: <optional comma-separated files, ranges or symbols read beyond the write scope>
+Ceiling: <optional cache-read ceiling at or below the class ceiling; default the class ceiling>
+Changes: <term>[, <term>...] or none - <reason>
+<!-- Unaffected: <test path that names a term and stays untouched> - <reason> -->
+Suite: <the project's full-suite command; the lead runs it, the worker never does>
+<!-- Tree: <root>/.worktrees/<change-id>/<task> | none - <reason> -->
+<!-- Setup: <command the lead runs in the tree> | none - <reason> -->
+<!-- Resources: <shared port, database or GPU>[, <name>...] | none -->
 Base: <git rev-parse HEAD at dispatch>
 Report: .freeharness/sdd/<change-id>/<task>.review.md
 
@@ -61,31 +194,48 @@ decisions; a stale digest is a defect, not a shortcut.>
 ## Depends
 <task numbers whose output this task needs, or "none">
 
+## Acceptance probes
+P1: <command, input or observable> -> <expected verdict or outcome>
+P2: <command, input or observable> -> <expected verdict or outcome>
+
+## Project rules
+- <invariant or protected boundary from the project CLAUDE.md that bears on the write scope>
+- Artifacts (code, comments, docs, tests, reports) in English; no bold markdown anywhere.
+
 ## Verify
-<the commands whose output proves the task: test target, mypy, lint, eval>
+<the commands whose output proves the task: test target, mypy, lint, eval; a Verify item
+testing a bundled or built file is preceded by its rebuild command, which the worker runs;
+name test files, never a package's `npm test`, which the handoff guard reads as the Suite command>
 
 ## Run rules
-- Build before tests (`npm run build` at the repo root, or `-w freeharness` for the CLI package).
+- Build before tests (`npm run build` at the repo root, or `-w freeharness` for the CLI package; after a canonical/ edit, `npm run bundle:canonical -w freeharness` first); a Verify item testing a bundled or built file is preceded by its rebuild command, which the worker runs.
 - Run tests in the foreground and wait for the exit code; give any run that may exceed two minutes an explicit Bash timeout (up to 600000 ms), since the tool moves a longer foreground command to the background, and never use run_in_background for tests.
 - A command denied by a permission prompt or a guard ends the step: reply blocked with `needs-confirm`; never retry it verbatim and never reach the same effect through another tool.
 - Never pipe test output through `tail` or `head`; keep the full output.
 - One idle notification ends a wait; never wait on a finished background run.
 - Never run the CLI, a hook or a worker against the real HOME; tests use a fake HOME.
 - The reply is the JSON block plus the report path, under 8,000 characters.
+- The reply and the report's first fenced json block follow this skeleton exactly: `{"task":"...","status":"completed|partial|blocked","files_changed":[...],"tests_run":[{"command":"...","result":"pass|fail|unavailable","summary":"..."}],"evidence":[...],"partial_output":null,"blocked_reason":null,"concerns":[]}`; the report file opens with it inside a ```json fence.
+- Cite every acceptance probe id (`P1:` ...) in `evidence` with its observed outcome; the first dispatch runs and cites every probe, and a fix round re-runs the probes its open findings name plus every corpus, fixture replay or generator probe and cites each other probe as `P<n>: carried from round <n-1>`.
+- An environment override (HOME, XDG_*) is set in the same shell command as the program it applies to; a separate export does not persist between tool calls.
+- Edit files only with the Edit and Write tools, never through a Bash heredoc, `sed -i` or an interpreter script.
+- Write a helper or probe script with the Write tool and run it as `node <file>`; a probe that makes a fake HOME write its `.claude/settings.json` or hooks runs from such a script, since the config guard refuses a Bash line naming those paths.
+- The handoff guard measures the comment share of every edited source file and fails one over 30% (grown-only when the file was over at the base); keep comments to the why and the share in line with the surrounding code.
 - Reply and report in English; every comment, docstring, test title and doc passage passes the HEAD-reader test: no task numbers, ruling ids, round or review references (the `commit` field of a PROVENANCE row is the one convention that names the task).
 - Never `git stash`, `git checkout --` or `git reset` in the shared working tree; prove RED by writing the tests first or against a temp copy of the pre-change file.
+- Never write the git index: no `git add`, `git rm`, `git mv`, `git commit`; delete a file with a plain `rm` and claim it in `files_changed`.
+- Never run the `Suite:` command; run only the `## Verify` commands (the lead runs the full suite).
 - A failing test or a regression the task did not expect is handled with the systematic-debugging skill (reproduce, isolate, root fix, verify) before any code change.
+- The report ends with `## Checkpoint` holding six subsections with these exact headings in this order: `### Intent`, `### Files and code`, `### Decisions` (decisions with the approaches tried and rejected), `### Errors and fixes`, `### Open work`, `### Next step`; terse `- ` lines, `(none)` when empty, at most 8,000 characters (target 4,000); on a fix round it is the complete merged state, never an appended delta.
 
 ## Handoff
 Write the review package to the Report path: the JSON handoff block first
-(reference/handoff.md), then the report. Return only the JSON block and the report path
-to the caller. Never dispatch subagents. Other implementers write in the same tree, so
-never `git stash`, `git checkout --` or `git reset` here: prove a failing test by
-writing it first, or against a temp copy of the file. On a stop condition, return
-`blocked` with the reason.
+(reference/handoff.md), then the report body, then the checkpoint. Return only the JSON
+block and the report path to the caller. Never dispatch subagents. Other implementers
+write in the same tree, so never `git stash`, `git checkout --` or `git reset` here: prove
+a failing test by writing it first, or against a temp copy of the file. On a stop
+condition, return `blocked` with the stop token and one line of detail.
 ```
 
-Batching: several tasks that are each the same small edit repeated across files (a
-constant, a one-line fix, a field addition) share one brief whose Task section lists
-every file and its change; the review package covers the batch as one diff. A task that
-needs its own tests, its own judgment or its own review surface gets its own brief.
+Every task gets its own brief, even a small same-shape edit: the review package covers one
+diff, and a task above the sizing bounds is split before any brief is written.

package/canonical/skills/subagent-driven-development/reference/handoff.md

@@ -59,6 +59,49 @@ one; it never widens the scope, never edits outside it, never asks a subagent.
 - Deviations from the brief and the reason.
 - Fix rounds append `## Fix round <n>` sections with the findings addressed, the
   covering tests re-run and their output; the JSON block is rewritten to the new state.
+- The report ends with `## Checkpoint`.
+
+## Checkpoint
+
+The last section of every report is the task's bounded working state, so a fresh fix
+implementer starts from it instead of a transcript. Six subsections with these exact
+headings, in this order, terse `- ` lines, `(none)` when a subsection is empty:
+
+```markdown
+## Checkpoint
+
+### Intent
+- Make `doctor` name the file and line of a gerund fixture failure.
+
+### Files and code
+- src/cli/doctor.ts: `checkFixture()` returns `{file, line}`; test/doctor.test.ts covers it.
+
+### Decisions
+- Report the first failing line only; rejected: collecting every line (output too long).
+
+### Errors and fixes
+- Off-by-one in the line number (counted from 0); fixed in `checkFixture()`.
+
+### Open work
+- (none)
+
+### Next step
+- Re-run the Verify commands and write the handoff.
+```
+
+The checkpoint holds at most 8,000 code points (target 4,000); the validator never
+truncates it. On a fix round it is the complete merged state, stale lines dropped, never an
+appended delta. Two writers turn it into the task state file `<task>.state.md`, replaced and
+never appended: the SDD context hook at SubagentStop when it is installed, and otherwise
+`scripts/validate-handoff.mjs state <report> <task>.state.md`; the lead's fix brief names
+`<task>.state.md`, and the next fix implementer reads it and confirms it against the tree.
+
+`handoff <file> --brief <brief.md>` checks the checkpoint and the probes, and prints
+`FAIL <outcome> <detail>` for:
+- `checkpoint-missing <subsection>`: the report has no `## Checkpoint` (detail `section`), or a
+  subsection is absent, empty or out of order; the detail names it.
+- `checkpoint-oversized <n>`: the checkpoint holds `<n>` code points, more than 8,000.
+- `probe-missing <id>`: a brief probe (`P1`, `P2`, ...) that no `evidence` line cites.
 
 ## Guard commands
 
@@ -86,6 +129,40 @@ reported as `peer-scope`. The `claimed-unchanged` check keeps the whole tree, so
 a path that did not change is still reported. Without the option a guard run while peers are
 writing returns their files as this worker's findings.
 
+A task that runs in its own worktree (a `Tree:` path, reference/trees.md) is guarded with
+`scripts/validate-handoff.mjs handoff <file> --base <sha> --brief <brief.md> --agent
+<agent_id> --tree <Tree>`. Every diff, scope and transcript check then runs against the
+tree, while the brief, the report and the ledger stay under the main root's
+`.freeharness/sdd/<change>/`. A path that is not a linked worktree of the repository under
+`<root>/.worktrees/` fails `tree-path`. Two more outcomes apply:
+- `tree-leak <path>`: the worker wrote the main tree instead of its own. Reported for a
+  write-scope path that differs in the main tree from its HEAD (an untracked file counts;
+  `--lead` paths are excepted), and with `--agent` for an Edit, MultiEdit, Write or
+  NotebookEdit path or a Bash write target under the main root outside the tree and outside
+  `<root>/.freeharness/`, or naming the report's change directory `<root>/.freeharness/sdd/<change>/`
+  itself or a path in it (a Bash removal there included; only a tool write to the report is
+  spared), and for a git command that writes the main tree's index. It returns to the worker
+  as a round.
+- `NOTE tree-cwd <command>`: with `--agent`, a Bash command that ran in a directory
+  outside the tree, typically one missing the `cd <Tree> &&` prefix. A note, not a
+  failure: the lead reads the command and judges whether it touched the main tree.
+
+The change directory holds the ledger, the findings and the round copies the guard trusts,
+so with `--agent` and without `--tree` a write there fails too. Only an Edit, MultiEdit,
+Write or NotebookEdit write to the report is spared, and only while the report is a regular
+file with one link at scan time: a symlink or hard link there would spare the file it shares.
+A Bash write target (the report included), a link created at the report name, a copy or move
+naming the directory itself, or a Bash removal of the directory or a path in it fails as
+`bash-write <path>`, and a tool path as
+- `workspace-write <path>`: an Edit, MultiEdit, Write or NotebookEdit path in the report's
+  change directory other than a spared report. The path prints from the main root; every other
+  `.freeharness/` path, another change's directory included, stays free.
+
+A command behind `env -C`, `env --chdir`, `sudo -D` or `sudo --chdir` is judged from the
+shell's own directory; the option's directory is noted, never resolved, so a relative write
+target behind it also prints `NOTE bash-write-unresolved <target>` and the option can only add
+lines.
+
 `scripts/validate-handoff.mjs recover <transcript.jsonl> <report> [--force]` rebuilds the handoff
 when a dispatch ends without a clean reply. Recovery reads only assistant-authored text:
 the joined `text` blocks of an `assistant` transcript line, and the `input.message` of
@@ -114,5 +191,8 @@ is dispatched the lead appends `## Lead evaluation`: the diff reviewed
 (`git diff <base>..HEAD --stat`), the Verify commands the lead ran itself with their
 summary lines, and the verdict `accepted for review | returned` with the reason. A task
 whose review package carries only the worker's claim is not done. The task reviewer's
-findings, each fix round line (`round <n>/5: <addressed>/<open>`) and, at the cap, the
-`## Controller ruling` (finding, decision, cost if wrong) follow in the same file.
+findings, each fix round's tally line and, at the round cap or the class ceiling, the
+`## Controller ruling` (finding, decision, cost if wrong) follow in the same file. The tally
+is `round <n>/<cap>: <addressed>/<open blocking>`: `<n>` the round, `<cap>` the task's round
+cap (3, or the run authorization's `Rounds:`), `<addressed>` the findings the round fixed and
+`<open blocking>` the blocking findings still open after its re-review.

package/canonical/skills/subagent-driven-development/reference/loop.md

@@ -0,0 +1,57 @@
+# Loop detail
+
+Brief sizing and the budget, dispatch names, the handoff guards, fix rounds, the commit and the final branch review of the subagent-driven-development loop. SKILL.md names this file at the step that needs each part; every line binds like a SKILL.md line.
+
+## Brief
+
+- Sizing, before every brief: a brief covers one behavior (the scenarios of one requirement, or one cohesive part), with at most 3 write-scope files outside test and fixture directories and a reading set (write-scope files plus the `Read:` header's entries) under 60,000 tokens at 4 bytes per token. A file over 1,500 lines is named by range (`path:120-340`) or symbol (`path#symbolName`, counted as 200 lines) in the write scope or `Read:`. A task above a bound is split into sub-tasks `<task>.<n>` (`2.4.1`, `2.4.2`), each with its own brief, dispatch, review and acceptance; the first sub-task's review package carries a `## Split` note naming the sub-tasks and the behavior each owns, and the parent is ticked in `tasks.md` only when every sub-task is accepted. `Split: refused - <reason>` is written only when the work cannot be divided; `validate-handoff.mjs briefs` refuses an oversized brief without it.
+- Pin grep: `briefs` searches each `Changes:` term plain and regex-escaped and, with `Key-list:`, finds exact key-list pins; the lead still greps by hand for a pinned count (a bare number) and puts each hit in the write scope or an `Unaffected:` line; a brief that changes a USAGE line or skill text runs content.test.ts in its Verify.
+- Changed terms: `Changes:` names every identifier and literal value the task changes, and `validate-handoff.mjs briefs` refuses a brief whose write scope, Verify commands or `Unaffected:` lines miss a test that names one. The check covers tests only, so the lead still adds the production files a plan missed by reading the design.
+- Class ceilings: `budget` stops a task at its class ceiling of cache-read tokens: 60,000,000 for a `security` or `complex` task, 50,000,000 for task `final` and 25,000,000 for any other task. The class is `security` or `complex` when a brief declaring the task carries that `Class:` (the higher ceiling when both appear). It trips when the total plus a reserve, the median of the task's dispatches (the lower middle value for an even count), reaches the ceiling, so a typical next dispatch never crosses it. The output names the source of the ceiling: `class <class> default`, `class <class> authorized`, `brief <file>` or `flag`.
+- Run authorization: the owner may set the ceilings and the round cap in one section of the change's `proposal.md` under the exact heading `## Run authorization`, approved with the proposal: `Ceiling <class>: <n>` (`<class>` one of `security`, `complex`, `final`, `other`; `<n>` a positive integer) and `Rounds: <1-9>`, each key at most once. Without it the class defaults and a cap of 3 rounds apply; a malformed section fails `budget`, `briefs` and `round-base` naming proposal.md and the line: `duplicate-section` (a second such heading), `near-miss-heading` (a `## Run authorization` heading in another case or with more words), `unknown-line` (any other non-blank line in the section), `duplicate-key` or `bad-value`. Only the owner edits it; the lead never raises a ceiling or the cap.
+- A brief's `Ceiling:` header only lowers the class ceiling: the highest one among the task's briefs applies at or below it, and one above it fails `budget` and `briefs`. `--ceiling` on `budget` overrides every other source and is the owner's to pass.
+
+## Dispatch names
+
+- Write `_` for `.` because the Agent tool rejects a dot in a name; the ledger stores the dotted id and reads role, task and round through the slug.
+- The lens slug is lowercase letters, digits and hyphens (`review-final-r1-lenses-b`); any other character leaves role and task null in the ledger.
+
+## Guards before the reviewer
+
+- Run `validate-handoff.mjs handoff <report> --base <Base> --brief <brief.md> --agent <agent_id>`, where `<agent_id>` is the id the Agent tool result returns, adding `--in-flight <brief.md>` for every other brief still running so a peer's files are not charged to this worker, and `--lead <path>` for the lead's own paths (the change's `tasks.md`, any review package outside `.freeharness/`) so they are not charged either.
+- A `claimed-unchanged`, `changed-unclaimed`, `scope`, `peer-scope` or `lead-path` failure, a `probe-missing`, or a `checkpoint-missing` or `checkpoint-oversized` failure returns to the worker as findings (a round), never straight to the reviewer; `peer-scope` means the worker claimed a file another dispatch owns, `lead-path` means it claimed one of the lead's own paths, neither ever worth passing on.
+- With `--agent`, the command also scans the worker's transcript and fails `bash-write <path>` (a Bash command wrote a file in the tree) or `bash-write <interpreter>` (an interpreter body wrote in the tree), `workspace-write <path>` (a tool write into the change directory in a shared-tree run), `index-write <command>` (a git command wrote the index or HEAD) and `suite-run` (the worker ran the brief's `Suite:` command). It prints these NOTE lines: `NOTE bash-write-unresolved <target>` (a write target the scan could not resolve), `NOTE transcript-unavailable <no-ledger|no-line|outside-projects|foreign-path|unreadable>` (a ledger path for the agent was not scanned; `foreign-path` names a file other than `agent-<agent_id>.jsonl` in a `subagents` directory, and every accepted path is still scanned), `NOTE transcript-truncated` (only part of the transcript was read), `NOTE transcript-tree-unresolved <error>` (git named no working tree, so the current directory stands in for it) and `NOTE bash-write-budget` (the scan's filesystem or path budget ran out, so later targets were placed by their text alone or left unresolved).
+- Each of these failures returns to the worker as a round, like the other guard failures. The lead may rule a false positive (for example a fixture generator run inside the tree on purpose): it reads the command in the transcript and writes a ruling line in the review package before the reviewer runs, never a silent pass.
+- Threat model: the transcript scan is a visibility layer over the diff guards (`claimed-unchanged`, `changed-unclaimed`, `scope`, `tree-leak`) for the owner's own subagents; tree isolation and the lead's diff read stay the controls. Padding, symlink and quoting or tokenizer shapes against the scan close as wontfix, a follow-up and never a round. The brief, the findings ledger and the review package are written by the lead and are trusted input: a parser that reads only them owes no hostile-input size or timing test; the change ledger and the transcripts stay untrusted.
+- Evidence test: on a `security` or `complex` task a P1 blocks only when it fails a brief probe, a spec scenario, or the corpus probe against the base (a deny the base prints that the task's code no longer prints); a shape the reviewer constructs is `hardening` with its reproducer, recorded as a follow-up.
+- Guard false positive: a worker that returns `blocked` with `needs-confirm` because the config or git guard denied a Verify or probe line that names no guarded path is answered by the lead rerunning that line itself in the task's tree, then re-dispatching the same round only to rerun Verify and write a completed report, with no code change, no new ruling id and no `round-base` call; the denied shape is recorded once as a follow-up. A line that names a guarded path keeps the stop: the owner opens the config-edit window or the task is re-scoped.
+- `transcript-unavailable` with `no-ledger` or `no-line` happens when the dispatch has no ledger line (the other reasons are listed above): the lead dispatches from the repository root so the hooks find the project.
+
+## Fix rounds
+
+- Fix prompt order: the brief path, `Round <n> of <cap>` (`<cap>` the task's round cap), the line "The working tree is the memory and the source of truth: run round-diff and inspect the files before acting; treat the task state in `<task>.state.md` as a bounded handoff and confirm it against the tree", then the ledger path. The lead's fix brief names `<task>.state.md`, the task state the SDD context hook or `validate-handoff.mjs state` wrote from the last checkpoint; the fix checkpoint is the complete updated state, never an appended delta.
+- Round cap: `round-base <brief.md> <n>` refuses `round-cap <n> over <cap>` before copying anything; the cap is 3, or the run authorization's `Rounds:`. The round's tier is what `route` prints (strong from round 3 on, whatever the cap).
+- Controller ruling at the round cap or the class ceiling, one entry per open finding: real and load-bearing gets the smallest unblocking change, carried into the next brief; real and deferred, or contested, is parked with the reason and the cost if wrong. A structural defect that leaves every path a guess stops the run. A ruling carried into the next brief narrows the task's own decisions only; a `[base]`, `hardening` or follow-up finding never becomes a carried ruling.
+- Remove the addition: at the round cap a blocking finding on a mid-task addition (code no brief scenario or design decision asked for, added by the worker or by a digest ruling) is ruled "remove the addition", handled as a sub-task and recorded as a follow-up, without an owner stop; every other round-cap finding keeps the stop.
+
+## Commit by path
+
+- Commit every accepted task with `validate-handoff.mjs commit <report> [<report>...] -F <message-file> [--lead <path>]...`, after the tick of `tasks.md` (pass it as `--lead`), listing every report of the task (each round's review package): the reports must declare the same task, the last one must be `completed`, and the claimed set is the union of their `files_changed`, so an earlier round's path is never dropped. Write the message file yourself; the worker never writes it.
+- The subcommand commits with `--only` over the reports' files plus each `--lead` path. A commit after an explicit `git add` takes the whole index, so a peer's staged deletion rides along in the task commit; `--only` commits the named paths and leaves every other staged entry out.
+- A refusal prints its reason and commits nothing; fix the cause and run the subcommand again. Hooks run; never bypass them. A plain `commit` run from inside a task tree fails `tree-path`, naming `--tree <path> --base <sha>`.
+- A `staged` guard failure names a stray staged entry. Read the entry, attribute it to its dispatch, and unstage it with `git restore --staged <path>` before the commit.
+- Tree landing (`--tree <Tree> --base <sha>`, reference/trees.md) labels a failure by its step: `tree-add-failed`, `tree-commit-failed`, `cherry-pick-failed`, `lead-add-failed`, `main-commit-failed`, and `commit-hook` only for a non-128 exit while a commit hook is installed. Every failure after the tree commit also prints `NOTE tree-commit <sha>` (the tree commit to recover from), `NOTE tree-head-moved <sha>` (the tree's HEAD now sits on it) and one `NOTE main-entry <XY> <path>` per staged or unmerged main-tree entry to clear before a retry.
+- `--tree-only` skips `land-conflict` and `tree-leak`, since it never touches the main tree.
+
+## Test tiers and waves
+
+- A wave is the set of tasks dispatched together before the lead waits.
+- The lead's full-suite run (the briefs' `Suite:` command) happens after the last task of the wave is accepted and committed, and before the next wave's dispatch; the lead runs it alone, one run at a time. Implementers run only their `Verify` commands: the task's tests plus the affected tests the changed-term check found.
+- A suite failure is attributed by running the failing test files at each task commit of the wave; each task is its own commit, so the first commit at which they fail names the task.
+- A regression in a test that names nothing the task changed surfaces at the wave run, never at the worker's.
+
+## Final branch review
+
+- Reviewers: domain reviewers + `pr-reviewer`, each dispatch on the tier `route --review` prints over `final.brief.md`, the spec-compliance pass with `--final-spec`.
+- Probes: a probe of a guard or hook verdict runs the hook through node on a payload file (the hook reading the payload on stdin), never the probed command typed into Bash, so the session's own permission layer never judges the probe.
+- The review runs under the same cap of 3 reviewer dispatches per round unless a user ask for more is recorded in the review package; one fix dispatch for the whole findings list, one scoped re-review, rulings for residuals.

package/canonical/skills/subagent-driven-development/reference/trees.md

@@ -0,0 +1,40 @@
+# Trees for parallel implementers
+
+The worktree lifecycle of the subagent-driven-development loop. SKILL.md names this file at dispatch rule 5, read when more than one implementer is in flight; every line binds like a SKILL.md line.
+
+## When a tree is needed
+
+- One implementer in flight runs in the main tree: its brief carries `Tree: none - <reason>` (or no `Tree:` line) and its task is committed with the plain `commit`.
+- Whenever more than one implementer is in flight, every brief of the set names its own tree, `Tree: <root>/.worktrees/<change>/<task>`, where `<root>` is the main project root and `<task>` the dotted task id. `briefs` fails `tree-required` otherwise.
+- Workers in a tree are plain subagents: no Agent tool isolation, no `name`.
+
+## Band
+
+- The band caps the implementers in flight: small 4 (the default), medium 8, large 12. `briefs --band <small|medium|large>` fails `band <count> over <cap>` when the brief files it names outnumber the cap.
+- Write `Band: <small|medium|large> - <reason>[ - quota <n>%]` in the review package of the first task dispatched under a band other than small.
+- Large needs the user's ask, recorded as `Band: large - <ask> - quota <n>%`, with the newest reading in `~/.claude/freeharness/quota-readings.jsonl` under 50%. The validator never reads the quota and never sees the ask.
+- Medium or large only when the median accepted-task duration in the ledger exceeds four times the lead's service time per task. Record that service time per task as `Service time: <task> <seconds>s`: the tree, the setup, the guards and the landing.
+- At most 16 dispatches of any role in flight: implementers, test-writers and reviewers together. With 12 implementers in flight, 4 slots remain for reviewers.
+- Before a medium or large band, check the free space on the project's volume (`df -h <root>`) against the band times the size of one set-up tree (`du -sh <Tree>`); a filesystem without copy-on-write clones pays the full copy for every tree.
+
+## Lifecycle
+
+1. Create: `validate-handoff.mjs tree <brief.md>` adds the tree detached at the main tree's HEAD and prints `OK tree <path> <sha>` (`OK tree reused <path> <sha>` when it already exists); record the sha as the brief's `Base:`. It refuses, creating nothing, with `tree-path` (the header differs from the derived path), `tree-unignored` (add `.worktrees/` to `.gitignore`), `change-untracked` (commit the change directory first), `tree-exists` (a non-worktree path is in the way) and `tree-stale` (run `git worktree prune`).
+2. Setup: run the brief's `Setup:` command in a subshell, `(cd <Tree> && <Setup>)`, so the lead shell stays at the main root, and record `Setup time: <task> <seconds>s` in the review package.
+3. Check: run `validate-handoff.mjs briefs <new and in-flight brief files> --band <b>`, naming the new briefs plus every brief still in flight as files; a directory argument skips the set checks (`NOTE briefs-dir <count>`). On a refusal, remove the clean trees just created for the refused set with `git worktree remove <Tree>`, fix the briefs and start again.
+4. Dispatch: the prompt carries the tree path and these worker lines: use absolute paths under `<Tree>` for every Read, Edit and Write; start every Bash command with `cd <Tree> &&`. The brief, the report and the ledger stay under the main root's `.freeharness/sdd/<change>/`.
+5. Guards: `validate-handoff.mjs handoff <report> --base <Base> --brief <brief.md> --agent <agent_id> --tree <Tree>`, with the `--in-flight` and `--lead` paths as in the main tree. `tree-leak <path>` (a write in the main tree) and `NOTE tree-cwd <command>` (a command run outside the tree) are listed in `reference/handoff.md`.
+6. Fix rounds run in the same tree on the same base: `round-base <brief.md> <n> --tree <Tree>` and `round-diff <brief.md> <n> --tree <Tree>`. `handoff`, `round-base` and `round-diff` accept only the brief's own tree, `<root>/.worktrees/<change>/<task>` for the brief's change and task; a sibling task's tree, another repository's tree or any other path fails `tree-path`.
+7. Land: `validate-handoff.mjs commit <report> [<report>...] -F <message-file> --tree <Tree> --base <sha> --lead <tasks.md>`, listing every report of the task, lands the task as one commit on the change branch and removes the tree without force. It refuses, writing nothing, with every refusal of the main-tree commit plus `tree-path`, `tree-moved` (the worker committed in the tree), `base-not-ancestor`, `staged`, `tree-leak`, `land-conflict` (the branch changed a claimed path since the base) and `lead-claimed`. A plain `commit` run from inside a task tree is refused with `tree-path`: land a tree task only from the main root with `--tree`. A failure after the tree commit names its step and prints the recovery NOTE lines (reference/loop.md, "Commit by path").
+8. `NOTE tree-kept <path> <reason>`: the task landed, but git refused the removal (an untracked file is left in the tree); the exit status stays 0. Read the leftover, then remove the tree with `git worktree remove <Tree>` once it is clean, or leave it for the user.
+9. `FAIL commit-hook`: a repository hook rejected the main commit; the output lists the staged paths and the tree is kept. Never bypass the hook; the hook's output is a finding for a ruling before the task is committed.
+10. `--tree-only`, for a `land-conflict` or an abandoned tree: `commit <report> -F <message-file> --tree <Tree> --base <sha> --tree-only` commits the claimed paths in the tree alone, prints `OK tree-commit <sha>` and leaves the main tree untouched, so it skips `land-conflict` and `tree-leak`. Record the sha in the review package for the re-brief, then remove the clean tree with `git worktree remove <Tree>`.
+
+Never `git worktree remove --force`: a tree that refuses removal holds work nobody has read.
+
+## Setup, resources and manifests
+
+- `Setup: <command> | none - <reason>` is required on every tree brief; the lead runs it, never the validator (`setup-missing` otherwise). A Node project uses its install command (`npm ci --prefer-offline`).
+- A uv project builds its own environment per tree with `uv sync --frozen`, which links from the uv cache. Never share the main environment of a project installed into it: the editable install points at the main tree's sources, so tests in the tree would import the main tree's code, and a sync from the tree would repoint the install. Sharing is allowed only for a project not installed into its environment, and the `Setup:` reason states it.
+- `Resources:` names the shared ports, databases and GPUs a task uses, comma-separated (`none` when it uses none). Two briefs in flight naming the same resource, compared case-insensitively, fail `resource-overlap`; run them one after the other.
+- A task whose write scope names a dependency manifest or lockfile (`package.json`, `uv.lock`, `Cargo.lock` and the rest of the route rule's C5 set) never runs in parallel: `briefs` fails `manifest-parallel <path>`. Run it alone, in the main tree.

package/canonical/skills/subagent-driven-development/reference/workspace.md

@@ -0,0 +1,31 @@
+# Workspace detail
+
+The run-start step and the validator inventory of the subagent-driven-development loop. SKILL.md names this file at its `<workspace>` step; every line binds like a SKILL.md line.
+
+## Workspace files
+
+- `.freeharness/sdd/<change>/` (gitignored; `init --project` creates it) holds `<task>.brief.md` and `<task>.review.md`, plus `<task>.findings.md` (the findings ledger), `<task>.state.md` (the working state) and `rounds/<task>-r<n>/` (round bases). `handoffs.jsonl` is the append-only record of handoff outcomes, one line per stopped implementer dispatch; the SDD context hook writes it on SubagentStop and `ledger` reads it for the per-task handoff and stop counts.
+
+## Run start
+
+- Before task 1: read `tasks.md` once, list the tasks, note Global Constraints; scan pairs of tasks that share a file or an interface and rule on conflicts (spec is the authority) in a `## Preflight` note of the first review package.
+
+## Validator
+
+The validator `scripts/validate-handoff.mjs` has fourteen subcommands:
+
+- `brief-init <change> <task>`: writes `.freeharness/sdd/<change>/<task>.brief.md` from the task's line and annotation lines in `openspec/changes/<change>/tasks.md` and the template in reference/brief.md, with `Change:`, `Spec:`, `Task:`, `Base:` and `Report:` set, `## Run rules` and `## Handoff` copied, and one `<fill: ...>` line for every other header and section, then prints `OK brief-init <path>`; refuses `task-shape`, `tasks-missing`, `task-unknown`, `template-missing`, `workspace-escape` (the workspace directory resolves outside the project root), `brief-exists` and `brief-unwritable`, and `briefs` fails `placeholder-left <name>` while a placeholder remains.
+- `briefs <dir|file...> [--band small|medium|large]`: headers, one task id, routing class and `Effort:`, size bounds, probes, `## Project rules`, digest budget, write-scope overlap; over the named brief files also the set checks `tree-required`, `tree-path`, `tree-absent`, `setup-missing`, `resource-overlap`, `manifest-parallel` and `band <count> over <cap>` (small when `--band` is absent); a directory argument skips the set checks with `NOTE briefs-dir <count>`.
+- `handoff <file> [--base <sha>] [--brief <brief.md>] [--in-flight <brief.md>]... [--lead <path>]... [--agent <agent_id>] [--tree <path>]`: schema plus the diff guards; `--base` adds `staged` and `base-not-ancestor`; `--lead` excludes the lead's own paths; `--brief` adds `probe-missing`, `checkpoint-missing` and `checkpoint-oversized`; `--agent` scans the worker's transcript for `bash-write`, `workspace-write`, `index-write` and `suite-run`; `--tree` reads the task's tree and adds `tree-leak`.
+- `budget <ledger.jsonl> <task> [--ceiling <n>]`: the total, the median reserve and the class ceiling with its source (reference/loop.md).
+- `ledger <change-dir>`.
+- `recover <transcript.jsonl> <report> [--force]`.
+- `name <dispatch-name>`: checks a dispatch name and prints the corrected form.
+- `gate <findings.md>`.
+- `route <brief.md> [--round <n>] [--p0] [--security]`: prints `Tier: <tier>` and `Effort: <effort>` for the brief's next dispatch: the brief's own (`medium` effort when absent), `strong` for a standard `code` brief from round 2 and for every brief from round 3, `strong` with `--p0`, `strong` and `high` with `--security`, never lower than the brief.
+- `route <brief.md> --review --base <sha> [--round <n>] [--p0] [--final-spec] [--probed]`: prints `Review tier: <tier> - S<n> <reason>` by the first criterion that holds: S1 `strong` (class `security` or `complex`, effort `high`, or a changed guard, hook, auth, secret or parser file, or a file under a `hooks` or `guards` directory), S2 `strong` (round 2 or later, `--p0`, `--final-spec`), S3 `standard` (class `docs`, `mechanical`, `extraction`, `exploration` or `summary`, or at most 200 changed lines in at most 3 files since `<sha>`, untracked files included), S4 `standard` with `--probed`, else S1 `strong`; refuses `route-base` outside a git work tree or for an unknown base.
+- `round-base <brief.md> <n> [--tree <path>] [--p0] [--security]`: refuses `round-cap <n> over <cap>` past the round cap, and `route-climb <tier>/<effort>` when the brief's tier or effort is below what `route --round <n>` with the same flags prints; `--tree` accepts only the brief's own tree.
+- `round-diff <brief.md> <n> [--tree <path>]`: `--tree` accepts only the brief's own tree.
+- `state <report> <state.md>`.
+- `tree <brief.md>`: creates the brief's `Tree:` worktree detached at HEAD and prints `OK tree <path> <sha>`, or `OK tree reused <path> <sha>`; refuses with `tree-path`, `tree-unignored`, `change-untracked`, `tree-exists` or `tree-stale` (reference/trees.md).
+- `commit <report> [<report>...] -F <message-file> [--lead <path>]... [--tree <path> --base <sha> [--tree-only]]`: commits the union of the reports' files (every report of one task, the last `completed`; `handoff-invalid`, `task-mismatch`) plus each `--lead` path by path; run from inside a task tree without `--tree` it fails `tree-path`. With `--tree` it lands the tree task as one commit on the main branch and removes the tree without force (`tree-moved`, `land-conflict`, `lead-claimed`, `tree-leak`, `staged`; `NOTE tree-kept`); a landing failure names its step (`tree-add-failed`, `tree-commit-failed`, `cherry-pick-failed`, `lead-add-failed`, `main-commit-failed`, or `commit-hook` for a non-128 exit with a commit hook installed), and every failure after the tree commit prints the recovery lines `NOTE tree-commit <sha>`, `NOTE tree-head-moved <sha>` and `NOTE main-entry <XY> <path>` (reference/loop.md). `--tree-only` commits in the tree alone and skips `land-conflict` and `tree-leak`.