git:20261021.24cf1e2 to git:20261022.4dd1799

This directory owns one markdown file per agent registered in `viber/.claude-plugin/plugin.json` `agents[]`: each a single-purpose worker taking labelled lines and returning fixed lines. The dispatching side (what a skill sends, when, at what tier) belongs to the skills node; the reference files the agents read belong to the references node.

## Terms

- Labelled input: every agent's `## Input` names the `label: value` lines its dispatch carries and what each one means; a multi-line value (`input:`, `question:`, `summary:`, `brief:`) runs to the end of the prompt. The dispatching skill sends exactly those lines and nothing else.

- `refs:`: the plugin reference directory (`${CLAUDE_PLUGIN_ROOT}/references`), from which an agent reads the reference files its body names.

- Auditor agents: the four `code-auditor` agents (`mapper`, `scout`, `hunter`, `critic`). They take another form: a `# <Name> - <role>` heading, `## Inputs you are given`, `## Hard rules`, no tools paragraph, no `DENIED` line.

- Coder notes: `<run>/work/<task id>-coder.md`, the at-most-8-line notes `task-coder` writes, read as `*-coder.md` by `task-reviewer`, `final-reviewer`, `closeout`, `memory-writer`, `rules-writer` and `qa-writer`.

- Review set: `planner-spec-review` (the specification half and its coverage), `planner-graph-review` (dependencies and ordering, reading from `## Tasks` on) and `planner-task-review` (one slice of at most 8 consecutive tasks) review a planner plan past 12 tasks, each reading only its own `plan-rules.md` sections and its part of the plan; `planner-review` reviews every other plan.

## Relationships

- Reference reads: `node-doctrine.md` (`memory-writer`, `memory-auditor`, `memory-node-writer`), `rule-admission.md` (`rules-auditor`, `rules-writer`), `qa-format.md` (`qa-writer`, `e2e-writer`), `plan-rules.md` (`planner-review` whole; of the review set, `planner-spec-review` its `## Spec` and `## Contracts` sections, `planner-graph-review` `## Graph`, `planner-task-review` `## Task`), `adr-admission.md` (`adr-screener`), `test-strategy.md` (`task-coder`, `task-reviewer`), `tdd.md` (`task-coder` on a `TDD: required` task), `integration-tests.md` (`planner-review`, `planner-task-review`, `task-coder`, `task-reviewer`), `ui-tells.md` (`task-coder`, `task-reviewer`, on a task whose `Files` render or style an interface). `hunter` writes to the schema of `skills/code-auditor/references/synthesis.md`; `hunter` and `critic` get a clean checkout only for a lens reading `Worktree: required`, through `skills/code-auditor/scripts/worktree.sh` and, on the diff scope, `diff-overlay.sh`. `mapper`, `scout`, `hunter` and `critic` read the run file and one lens file of `skills/code-auditor/references/lenses/`; `mapper` also reads that lens's `<lens>.signals.md`.

- Skill calls from agents: `prototype-writer` invokes `impeccable`, else `viber:pro-designer`, when either is in its skill listing.

## Contracts

- Strength: `task-coder` and `task-reviewer` get the task's tier as `model`, `final-reviewer` `sonnet` clamped into the tiers range, `scout` `sonnet` on the security lens; every other dispatch passes no `model`, so the frontmatter `model:` and `effort:` decide. `mapper`, `hunter` and `critic` carry `model: inherit` and run at the session's model; `scout` is pinned to `haiku`.

- Every non-auditor agent carries the tools paragraph ("Your tools are ..., every one of them loaded ...") naming exactly its `tools:` list; an agent holding `Bash` adds the sentence that `No such tool available` on `Glob` or `Grep` means using `find` and `grep` through `Bash`, and `mapper`, `hunter` and `critic` state that fallback under `## Hard rules`. The same paragraph, and their hard rules for those three, add that a refusal whose reason opens with `viber guard:` is a correction to apply, never a denial.

- Agents sharing the working tree (`task-coder`, `task-reviewer`, `final-reviewer`) keep git read-only (`status`, `diff`, `log`, `show`), never `stash`, `checkout`, `restore` or `clean`: one stash stack serves every coder. `task-coder`'s only writes to the index are `git rm -r -q --` and `git update-index --chmod=+x --`. Each guarded rule is one line in the agent, enforced by `hooks/scripts/shell-guard.sh` (the coder: no chained command, no `rm`, no file write or inline or `.temp/` interpreter code through `Bash`, the four git subcommands; both reviewers: the git subcommands only), whose header holds the rationale.

- Baseline report: `test-runner` writes `status: pass | skip | fail | build-failed` then `<test name> | <file> | <assertion or error>` lines; `task-coder` and `task-reviewer` treat a failure as pre-existing only when its test name and file match such a line.

- Red evidence: on a PASS of a `TDD: required` task with a task file, `task-coder` adds `RED: <n> failing | <out>/red.log` or `RED: missing <symbol> | <out>/red.log` (`<out>` its `.temp/viber/<id>/`), from a `Verification` run redirected into `red.log` before the first production edit, or, on an attempt starting with the production code in the tree, into the next free `red-<n>.log` with the behaviour temporarily reverted; a PASS whose own text admits skipping a required step is returned as `VERDICT: FAIL`. `task-reviewer` gets `red: <path>` and, when red-check ran, `red-check: <line>`, and checks that the failing tests are the task's new ones; on `UNRUNNABLE` a new test that would pass on HEAD is a Blocking finding.

- Extras: `task-coder` appends each path of its `EXTRA:` line to its `extras` file (`<id>-extra.md`) and `task-reviewer` to its own (`<id>-extra-review.md`), one repo-relative path per line; `task-reviewer` gets the coder's paths and the rechecks by running its `scope` command (`plan-index.sh --extra`), and the task commit stages both files' paths.

- Stall path: `task-coder` writes its `DECIDE:` line whole to its `decide-file` (`<id>-options.md`); its options become `arbiter`'s `options:` for case `decide`; a ruling comes back to coders, reviewers and `closeout` as a `decision: <task-id>: <text>` line of `status.md`, which wins over the task file. Every `DECIDE:` option is work a later coder attempt does or a ruling the build records; `arbiter`'s `## Actors` states what the orchestrator (writes and deletes no file, runs viber's scripts only) and a coder can do.

- Scratch: `task-coder` keeps scratch output under its `out` directory and names a file it must leave in the tree outside `.temp/` on `SCRATCH:`, never also on `FILES:` or `EXTRA:`; `implementor` passes it to `commit-task.sh --drop`, and `task-reviewer` blocks an untracked leftover with that line as the fix, never `rm`.

- Memory: with `memory` `true`, `final-reviewer` reports nothing living in a `CLAUDE.md`, a notes line about one included, and the final-review fix coder, handed `memory:` on its `review` dispatch, edits no `CLAUDE.md`.

- Repair pass: a `repair: <problem>` dispatch line makes `task-coder` fix that one problem on top of the task's earlier work, reading its notes and every `review-<id>-*.md` first, and `task-reviewer` gate that problem plus the task's whole `DoD`; `arbiter`'s case `cap` is reached only after a failed repair pass. `closeout` returns `LEFT: <n>` (or `none`) after `PATH:` on `VERDICT: ARCHIVED`, counting the `left uncommitted` lines of `outcome.md`.

- Join keys: `scout` echoes `unit` (the `U<n>` id) byte-identical to the unit line it was given; `critic` is handed only the `.claim.md` sidecar (`LOCATION`, `CLASS`, `## Reproduce`), never the hunter's report.

## Commands

- `node --test tests/viber/code-auditor.unit.test.ts` after an auditor agent is added, removed or renamed: it holds every `viber:<name>` the `code-auditor` skill dispatches to `plugin.json` `agents[]`.

## Change together

- The "Stop what you started" block is verbatim in `task-coder`, `task-reviewer`, `final-reviewer`, `test-runner`, `e2e-writer` and `skills/extension/templates/extension.md`.

- The tools paragraph and the `DENIED` / `REASON: <refused tool name>: <the exact refused command, or the path for a file tool>` output wording are verbatim across every non-auditor agent (`prover` and `researcher` add the URL or query for a web tool).

- Memory audit vocabulary (`STALE`, `GONE`, `UNVERIFIABLE`, `MISS`, `SHAPE`, `OK`) and the `<out><slug>-audit.md` name (`/` -> `--`): `memory-auditor`, `memory-node-writer` and `skills/memory/SKILL.md`. The rules counterpart (adding `DROP` and `MOVE:`): `rules-auditor`, `rules-writer` and `skills/rules/SKILL.md`.

- The clean-checkout steps (`worktree.sh add`, `diff-overlay.sh`, replay, `worktree.sh remove`, and `WORKTREE_FAILED` / `OVERLAY_FAILED` ending in `NO FINDING` for `hunter` and `INCONCLUSIVE` for `critic`): `hunter.md` and `critic.md`.

- An agent added, removed or renamed: `plugin.json` `agents[]`, every `viber:<name>` dispatch in `skills/`, and for `planner-review`, the three review-set agents and `plain-plan-review` `hooks/scripts/plan-gate.sh`.

- `planner-review`'s input labels (`refs:`, `memory:`, `input:`, whose `Answered:` lines `planner/SKILL.md` writes and the Faithful rule reads): `planner-review.md`, `skills/planner/SKILL.md` and the dispatch text `hooks/scripts/plan-gate.sh` prints in its deny message. The review set's labels (`planner-task-review`'s `tasks: T<a>-T<b>`, `planner-graph-review`'s `memory:`, `planner-spec-review`'s `input:`) are written by the same two.

- The tools paragraph, `## Calibration`, its re-review sentence and `## Output` are verbatim across `planner-review`, `planner-spec-review`, `planner-graph-review` and `planner-task-review`; each carries `effort: high`, and the three set agents take no `scope:` line.

- The guarded one-line rules of `task-coder`, `task-reviewer` and `final-reviewer`, and `hooks/scripts/shell-guard.sh` (rules R1-R5 and their rationale): a rule added or dropped changes both.

- The `viber guard:` marker sentence: the tools paragraph above, `mapper`, `hunter` and `critic` hard rules, `skills/extension/templates/extension.md`, and the marker `kill-guard.sh` and `shell-guard.sh` open their reasons with.

## Traps

- The harness rejects a subagent's `Write` of any `.md` whose name starts with `report`, `summary`, `findings` or `analysis`; `hooks/register.tsx` writes such a file in its place for a viber agent inside the project root, yet every file an agent is told to write is named otherwise (`outcome.md`, `review-*.md`, `*-audit.md`, `final-review-<n>.md`).

- A file an agent writes that something parses (`hunter`'s sidecar, `mapper`'s `map.md`) can end on a leaked `</content>` line: those two agents read the tail back and delete it, and a new parsed output needs the same guard.

- `scout`, `mapper` and `hunter` return no `VERDICT:` line (JSON lines, `map written: <path>`, the paths written): a caller parsing them never looks for one, and for `hunter` reads the files in `reports/`, never its final message.