@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/skills/companion/land/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: land
+description: Get an already-decided change into the repo on the right surface — which of the three routes it takes, and the ratifying turn it needs first. Use when a change has been agreed and has to become a commit here, a tracker ticket, or a proposal to the owner, or when the question is which surface it belongs on and what the commit must carry. It decides nothing about whether the change is correct — that argument belongs earlier, not here.
+---
+
+# Landing a change
+
+This file **is** the doctrine: the routes and the authority they run under
+were decided with the owner. If the doctrine changes, it changes here.
+
+## The gate before any route: the ratifying turn
+
+Nothing below fires until this passes. It is not a formality — **the entire
+authority to commit rests on it**, because the boundary that used to stop you is
+now prose plus this turn and nothing else.
+
+- **Commit only after the owner approves THAT change, in this session, in words.**
+  Not inferred from them reading your verdict. Not from "they asked me to look at
+  the feedback". Not from a standing instruction to improve the reviewer. Not
+  from their silence.
+- **The approval is per batch.** One "yes, all three" covers the three changes
+  just discussed and nothing else. A fourth change you noticed while committing
+  the third is not covered — ask.
+- **It is void at session end.** After a compaction, a day rollover, or a
+  restart, a previous yes is history, not permission. Ask again. If you cannot
+  point at their approving words *in the conversation you are currently in*, you
+  do not have one.
+- **Ambiguous is not approved.** "Sounds right" about an argument is not
+  approval of a diff. If you are constructing an argument for why it counts, it
+  does not.
+
+**The load-bearing sentence, and the first thing to check if this ever goes
+wrong:** *if a change ever lands without a ratifying turn — implicitly, by
+inference, or from a prior session — the widening is void, not merely
+violated.*
+
+## Which route: three surfaces, three answers
+
+Decide the surface first. It is almost always obvious, and picking wrong is the
+one way to turn a good change into a bad one.
+
+### 1. Review-side — how the reviewer judges (`prompts/`, `agents/`)
+
+Round templates, lens bodies, the addendum registry's effect on what a pass
+says. **This is yours now**, through the conversation, under the ratifying turn.
+The old producer — the EOD curator writing `state/rubric/<slug>/` on the VM —
+is **retired**: the curator flags candidates in the digest and
+authors nothing, and never ask the overseer to draft one. The proposal
+*surface* lives on, and **you are its producer now**: when a review-side
+change needs the owner's ratification rather than a ratifying turn, you author
+a proposal directory and their accept click in the TUI ratifies it.
+
+#### Authoring a rubric proposal (the TUI-accept route)
+
+- **Where**: `state/rubric/<lens>-<topic>-<YYYY-MM-DD>/` under `/workspace` —
+  the LOCAL repo's state dir, the same tree the TUI's `[7] feedback` tab
+  reads (`src/tui/proposals.ts` lists it from the repo root; there is no VM
+  path in this loop). Slug charset `[A-Za-z0-9._-]`, no leading dot, or the
+  TUI never lists it.
+- **What it contains**, exactly two files:
+  - `PROPOSAL.md` — the pitch: rationale, evidence PRs, expected effect on
+    false-positive/miss rates. First three non-blank lines are the card the
+    TUI shows; make them carry the argument.
+  - `changes.patch` — ONE unified diff against the current `agents/` /
+    `prompts/` files, paths repo-relative with `a/` `b/` prefixes
+    (`git diff` output is the right shape).
+- **Targets: `agents/` and `prompts/` only.** The TUI refuses anything else —
+  both diff sides plus rename/copy headers are checked, so a deletion or
+  rename cannot smuggle a path in. It equally refuses a patch that touches
+  lines inside a `<!-- RATIFIED … -->` fence or adds a fence marker of its
+  own: a proposal can argue against a ratified passage, never carry one in.
+- **You NEVER apply the patch yourself.** the owner's accept click in the TUI
+  IS the ratification (accept = apply + auto-ratify + local commit; the
+  divergence fixture and seed manifest are re-pinned by that path, not by
+  you). Reject removes the dir and records a `#rejected-proposal` memory
+  entry — never re-propose one of those. Until they click, the directory is
+  inert prose; writing it needs no ratifying turn, precisely because it
+  changes nothing.
+
+Two things travel with a review-side commit:
+
+- **`tests/seed-integrity.test.ts` is the map of what is frozen.** Seeded content
+  (`pass-common.md`, `conversation-system.md`, `eod-sweep.md`,
+  the seeded `agents/pass-*.md`) is frozen (`docs/ownership.md`) —
+  a reseed is the owner's ratification, not yours. Ours to edit: the round
+  templates, `companion.md`, `companion-day-open.md`, the Slack appendix. The
+  test's own `NON_SEEDED` list is the authority; check it, do not remember it.
+- **Pass behaviour changes go through `PASS_ADDENDA` in `src/include.ts`**,
+  composed onto BUILT bodies — never through a seed edit. That is a system-side
+  commit that happens to change review behaviour, and it is the sanctioned path.
+- If a ratified reseed *is* what the owner asked for, the ratification is recorded
+  the way the machinery already does it: `recordRatification()` in
+  `src/tui/proposals.ts` appends to `tests/fixtures/ratified-divergence.json`
+  and re-pins `tests/fixtures/seed-manifest.json`. Same commit as the edit, or
+  the suite is red. Do not hand-edit either fixture around it.
+
+### 2. System-side — daemon behaviour (`src/`, `tests/`, `scripts/`, `docs/`)
+
+Severity mapping, dispatch, webhook routing, the TUI, yourself. **One rule for
+all of it**: after a ratifying turn, you edit it and commit it. There is
+deliberately **no carve-out** — not for the mutation gate, not for the posting
+guards, not for "anything structural". The owner rejected both carve-outs
+explicitly, and the recorded consequence is that the safety story for a gate
+edit is the ratifying turn plus a one-key revert, with no second structural
+barrier. Weigh that when you ask.
+
+What does *not* move: the gate's shape. Every GitHub mutation still goes through
+the one `MutationGate`; you may edit the gate, you may never add a path around
+it, and `dry_run` is the owner's alone in either direction.
+
+### 3. Author-side — how the code gets written in the first place
+
+The highest-yield surface in the corpus, and the one you touch least directly.
+**It becomes a tracker ticket, and the owner acts on it.** Nothing reaches
+the reviewed repo until they move.
+
+- Write the ticket on the issue tracker at `/tracker`, as actor `companion`,
+  under the concurrency protocol (`/tracker-docs/issue-tracker.md`).
+- Carry the argument: the episode, the verdict, the counter-case, and what a
+  change to the team's practice would be.
+- The daemon's improvement-PR machinery (caps ≤50 lines / ≤3 files, 1/day,
+  3/week, enforced in daemon code) remains the **only** path to a bot-filed PR
+  and is untouched — you do not feed it, and you never file one yourself. This
+  is a deliberate narrowing: changes from feedback are never automatic, and a
+  human step is the accepted price.
+
+## Ratified invariants: propose only, never edit
+
+Some passages are the owner's, wherever they live. In the files we own they are
+**fenced**:
+
+```
+<!-- RATIFIED ci-gate — do not edit; owner only -->
+…the ratified text, byte for byte…
+<!-- /RATIFIED ci-gate -->
+```
+
+Edit freely *around* a fence; never *inside* one. `tests/invariant-fences.test.ts`
+hashes each fence's contents and fails just as loudly when a marker goes missing
+— deleting the fence is not a way around the pin. The same holds for the
+invariants living in `src/` that have no fence yet (the CI gate in
+`cigate.ts`, reachability in `severity.ts`, the one-way transition in
+`recheck.ts`, `validatorTier` in `dispatch.ts`, the migration COMMENT rule):
+**their being unfenced is a gap, not permission.**
+
+Arguing for a change to one is allowed and welcome. Making it is not. A verdict
+that requires changing a ratified invariant lands as an argument in the column
+and, where the invariant lives in a prompt or lens, as a rubric proposal
+directory (route 1 above — PROPOSAL.md making the case, and a patch the TUI
+will accept only for the *unfenced* text around it; the fence itself stays
+theirs) — never as a commit you write first and mention after.
+
+## The commit
+
+- **One purpose per commit.** Touch only what this change justified. If you
+  notice something else while you are in the file, note it and leave it.
+- **`master` in the real checkout, never a worktree.** That is
+  yours alone and it is deliberate: the owner is watching the TUI you are editing,
+  and the hot reload watches the main checkout's `dist/`. The tree is shared
+  with worktree agents who are under orders never to stash your work — so commit
+  coherent work promptly rather than sitting on a wide diff.
+- **Green before committing, always**: `timeout 900 npm test` with zero
+  failures, then `npm run build` clean. Never commit with a red suite. The build
+  is also how the change reaches the running TUI — say what you are about to
+  rebuild before you do it, so a screen blink is never a surprise.
+- **Message**: `[companion]` prefix and a plain body that says what changed
+  and why. No trailers (no `Feedback-PR:`, `Adjudication:` or
+  `Ratified-in-session:` line), no quote of the owner's words, no session or
+  ticket id: the history is public, and the approval lives in the session.
+- **Tell them what you changed, in one line**, naming the surface.
+
+## Did it actually reach the reviewer?
+
+A committed review-side or system-side change is not live until the VM has it,
+and **you may never deploy** — `deploy.sh` in any mode is outside the boundary,
+in every direction, permanently.
+
+The answer is already on the owner's screen: the deploy tab shows the VM's
+`BUILD_SHA`, local `HEAD`, the pending commit list with diffstat, and
+`deploy.sh --dry-run`'s plan verbatim. So the honest report is: *"committed; it
+shows as pending on the deploy tab; it reaches the reviewer when you deploy."*
+Never say a change is live because you committed it, and never press the deploy
+tab's button on your own judgment — that verb is their finger, not yours.
+
+## Never
+
+- Never commit without a ratifying turn in the current session, for that
+  specific change.
+- Never treat a prior session's approval, a general instruction, or your own
+  confidence as one.
+- Never edit inside a `RATIFIED` fence, or delete a fence marker.
+- Never touch a frozen seed without a ratification recorded in the same commit.
+- Never batch two purposes into one commit, and never commit with a red suite.
+- Never call GitHub — no `gh`, no API, no token, no branch, no PR, no issue.
+  Author-side is a tracker ticket, and that is the whole of it.
+- Never run `deploy.sh`, never write to the VM, never hold a VM credential.
+- Never push anything anywhere: the sandbox has no remote, and the reviewed repo
+  is mounted `:ro`.
+- Never land a change you have not argued for. Deciding is `adjudicate`;
+  understanding is `evidence`; trying it against the past is `replay`.

package/skills/companion/replay/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: replay
+description: "Re-run a past episode offline against the committed regression case set — real human findings on closed PRs — to see how a proposed change to the reviewer would have behaved. Use when asked whether a tweak would still catch what humans caught, to calibrate against the pre-bot corpus, or to try a change before it lands. Strictly offline: it never labels a PR, never wakes a session, and never posts anything."
+---
+
+# Replaying a past episode
+
+This file **is** the doctrine; the case set was decided with the owner. The
+instrument itself is `src/regression.ts`, and where this file
+and that module disagree, **the module wins** — its assertions run, this prose
+does not.
+
+## The safety point, first, because it is the one that can do damage
+
+**A replay must never become a posting path.**
+
+There is an obvious way to "re-run a review": put the trigger label on the PR
+and let the live daemon dispatch a round. That is how the old cutover comparison
+harness worked, and **it is forbidden here** — a live round posts a real review
+to a real author on a real PR. The same applies to every disguised version of
+it:
+
+- Never label, re-label, or ask anyone to label a PR.
+- Never write an overseer inject asking for a re-review, a rerun, or a fresh
+  round on any PR. Your one lever is not a replay mechanism.
+- Never touch `dry_run`. It is the owner's alone in both directions (`docs/ownership.md`),
+  and a replay that needs it flipped is a replay you must not run.
+- Never replay an **open** PR at all, whatever the mechanism.
+
+`src/regression.ts` enforces the same thing in code rather than in prose, and it
+is worth knowing exactly what it checks, because those checks are your floor and
+not your ceiling. `assertReplaySafe(cases, gate)` refuses to start unless:
+
+1. the gate it was **handed** reports dry-run — read from the object, never from
+   `config.toml`, never inherited, never a printed sentence (see
+   `src/compare.ts`'s `attestDryRun` for what that mistake looked like);
+2. no case is a still-open PR;
+3. no case is at or after the contamination cutoff (`2026-03-01`) — rows from
+   then on are the old `/auto-review` loop's own output or suspected
+   AI-assisted, so scoring against them scores the reviewer against itself.
+
+`runRegression` calls it regardless of whether you did. And the `replay` seam in
+`RegressionDeps` carries the rule in its own doc comment: it **must build its
+own round in a scratch root against `case.headSha`**, and it **must not** label
+a PR and let the live daemon dispatch. Nothing in that module imports the
+daemon, `wire.ts`, or a GitHub adapter — if you find yourself adding such an
+import to make a replay work, stop: that is the boundary, and you have just
+reached it.
+
+## What the set is, and what it deliberately is not
+
+The cases are real findings by human reviewers on **closed** PRs
+(`tests/fixtures/regression-cases.json`, built by
+`scripts/build-regression-set.mjs` from the corpus export — by hand,
+never by a test and never by the daemon).
+
+Three properties decide how you read a run:
+
+1. **Selection is by SUBSTANCE, not by verdict.** `selectCases` never reads the
+   GitHub verdict — blocking measures the reviewer, not the finding, and 82% of
+   blocking findings carry no correctness vocabulary at all. A finding is
+   admitted only if it states a reason or proposes a concrete alternative
+   (rung ≥ L3), is in English, is not bot-authored, and does not rest on
+   evidence off the PR. Do not "improve" a run by widening that bar.
+2. **A failure is an INVESTIGATION, not a veto and not a bug.** Every finding
+   carries an expectation label — `expected-catch` (the reviewer should reach
+   it), `out-of-remit` (ratified design puts it outside the reviewer, so a miss
+   is *correct*), `expected-divergence` (the human was argued down; either
+   answer is defensible). Two of the three make a divergence the expected
+   outcome. `runRegression` never returns a blocking verdict and its `exitCode`
+   is always `0`.
+3. **There is deliberately no score to maximize.** A set that could be optimized
+   would ratchet the reviewer toward imitating one person's habits, and one
+   reviewer is 43% of the corpus. If you catch yourself tuning a change until
+   the numbers go up, you are doing the thing the set exists to prevent.
+
+## Running one
+
+1. **Name the change under test** — pass it as `changeUnderTest`. A run whose
+   header cannot say what was tried is a run nobody can act on later.
+2. **Load and parse the set** with `parseCaseSet`. It refuses an empty or
+   half-parsed set on purpose: a clean score out of nothing is the one result
+   this whole module exists to make impossible.
+3. **Supply a `replay` implementation that satisfies the rule above**, plus the
+   real gate object. If no offline replay implementation exists yet, **say so
+   and stop.** "I could not run it offline" is a correct and complete answer;
+   reaching for the live daemon to fill the gap is not. There is no
+   almost-offline route.
+4. **Run it serially.** You have no subagents — cases run one after another, and
+   `runRegression` already loops that way. Do not fake parallelism and never
+   claim a run you did not do.
+5. **Read `renderInvestigation`'s output as written.** It opens by saying what
+   it is not, because the one way this set can do harm is by being read as a
+   pass/fail gate the reviewer is then tuned to satisfy.
+
+## Reading the result honestly
+
+- **`not-reached`** is the only column worth investigating, and the question it
+  asks is not "is this a regression?" but "is this in the reviewer's remit at
+  all — and if it is, was it ever reached before this change?" A finding
+  unreached both before and after is not evidence about the change.
+- **`vacuous` cases** — the replay produced nothing at all for a case that has
+  findings. **Suspect the harness before the reviewer.** A vacuous PASS from an
+  extractor that matched nothing was the old comparison harness's failure mode; when
+  half the cases are vacuous, `runRegression` says `ask-owner` and it means
+  it.
+- **Reviewer skew above 40%** means the run is partly measuring one person's
+  habits. Widen the set before acting on a pattern in it.
+- **`sandbox-only` findings are not failures.** The reviewer reads things humans
+  skipped, and that is what it is for.
+- **A label may be wrong.** If the honest answer is that we do not want a
+  finding raised, re-label the case `out-of-remit` with a note — but that is a
+  change to the instrument, so it lands like any other change: through the
+  ratifying turn, via `land`.
+
+## After the run
+
+Report the recommendation (`no-action`, `look-at-these`, `ask-owner`), the
+headline, and the unreached findings — in the column, in the owner's own terms. A
+run **never** decides whether the change lands. It is one input to the argument
+that happens before `land` is ever loaded, and it does not replace it.
+
+Do not write a memory entry for a run. The investigation markdown is the
+artefact; a run is a measurement, not a conclusion.
+
+## Never
+
+- Never label a PR, ask for a round, or nudge a session to produce a replay.
+- Never replay an open PR, or a case at or after the contamination cutoff.
+- Never run against a gate that is not dry-run, and never change `dry_run`.
+- Never treat a run as a gate, a score, or permission to land — it has no
+  blocking verdict by design.
+- Never widen the substance bar, drop the per-reviewer cap, or re-label a case
+  to make a run come out better.
+- Never report a run you did not complete, and never present a vacuous run as a
+  clean one.
+- Never call GitHub, the mutation gate, `deploy.sh`, or the VM. The corpus, the
+  case set and the reviewed code are all local files.

package/skills/companion/setup/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: setup
+description: Set up the reviewed repo so the reviewer knows its codebase — facts and unit cut, review history themes, the setup survey, the portrait, then an interview on goals, merge-blocking concerns, risk areas, style and tests whose answers become the repo profile, plus memory pins proposed to the owner. Use when the owner runs qcr setup or presses I, asks to set up or tune the reviewer for this repo, re-tune its profile, or when setup_profile says setup is owed.
+---
+
+# Setting up a repo
+
+This file **is** the doctrine, decided with the owner. The instruments
+are the `setup_*` tools and `src/setup/` behind them, and where this file and
+that code disagree, **the code wins** — its refusals run, this prose does not.
+
+## What setup is, and what it is not
+
+Setup teaches the reviewer one repo: what it is, what it already holds itself
+to, and what its owner cares about. It ends in three things — the **repo
+profile** (the per-lens tuning), the **repo portrait**, and **seeded memory**.
+It hunts no bugs: that is the scan, which comes after setup, on a set-up repo.
+
+**You judge; the tools act.** You read the repo, condense, ask and propose.
+Every write goes through a tool that validates it — you never hand-write a
+file the tools own, and you never write `config.toml` (it is mounted
+read-only, on purpose).
+
+## Always start with `setup_profile`
+
+It says where setup stands: which profile the live config names, whether it
+loads, whether setup is **owed**, what the interview has answered so far and
+what became of each commit. Setup is resumable: pick up at the first step
+not yet done, and say which one that is.
+
+**The nudge.** When `setup_profile` says setup is owed and the owner did not
+ask for it, mention it **once** in a conversation — one sentence, what it
+buys, `qcr setup` or `I` on the board — and drop it. Never start setup on
+your own initiative.
+
+## The order
+
+1. **Facts and the unit cut.** `setup_repo_facts`, then propose a cut
+   (`setup_unit_cut_propose`), let the owner correct it
+   (`setup_unit_cut_adjust`), and save it only when they agree. A saved cut is
+   reused: re-cut only when they ask.
+2. **Review history.** `setup_review_history`. If there is no digest, ask them
+   to run `qcr history pull` — you cannot fetch it. Condense it into themes
+   (`setup_review_history_themes`): your words, never a quote, never a name.
+   An empty history is normal for a repo new to the reviewer.
+3. **The survey.** `setup_survey_preview`; tell them the price; start it with
+   the preview's key only when they agree. It runs in the background — keep
+   going with them; check `setup_survey_status` when it matters.
+4. **The portrait.** `setup_portrait_assemble`, then write them your reading
+   of it (`setup_portrait_narrative`): what kind of repo this is, what it
+   already enforces, what reviewers keep asking for, and what the facts leave
+   open — those open questions are where the interview starts.
+5. **The interview** (below).
+6. **The profile** — previewed, shown, written (below).
+7. **The replay** — optional, offered once, cost first (below).
+8. **Pins** — proposed, never pinned (below).
+9. **What it takes to go live** (below).
+
+## The interview
+
+`setup_interview` shows its fixed frame: four points, a list of concerns, and
+the table that turns a priority into lens settings. Read it first.
+
+- **Adaptive, from the portrait.** Ask about what THIS repo makes
+  interesting. A backend with no frontend gets one line on `frontend`, not a
+  conversation. A payments service gets a real one on `money`.
+- **Four points, always:** the project's **goals**, what must **block a
+  merge**, the **risk areas** (security, data, money, compliance), and
+  **style & tests**. The profile cannot be written until every concern has a
+  priority and the goals are recorded — the tool refuses, and names what is
+  missing.
+- **A priority per concern:** `critical`, `important`, `normal`, `ignore`.
+  Offer yours with the evidence behind it ("reviews here keep asking about
+  migrations — I'd say data is critical"), and take their answer. `normal` is
+  the reviewer as shipped; say so, so they know what they are choosing against.
+  `ignore` switches the concern's lenses off — say what they stop paying for,
+  and what they stop getting.
+- **The goals in their words.** Short. They are recorded as `goals`, and what
+  a lens should watch for because of them becomes that lens's `emphasis`.
+- **One question at a time**, plainly worded. This is a conversation, not a
+  form; the tool, not the owner, keeps track of what is left.
+
+## The profile: preview, show, write
+
+- **`setup_profile_apply` without `write` previews**: the diff and what the
+  table decided, with the concern behind each lens. Show them the diff — not
+  a summary of it. Nothing is written.
+- **Emphasis**: a few sentences per lens they care about, only where there is
+  something to say. Your words, from their goals and the portrait; never a raw
+  review comment, never a colleague's name.
+- **A style guide**: only when style matters to them (`important` or
+  `critical`) AND the repo writes none of its own — no style guide, no style
+  section in its agent-directive files (the facts say which). Draft it from
+  the conventions the survey observed and their answers, as rules a reviewer
+  can cite, and pass it as `style_guide`. A guide the repo writes always
+  wins over yours; if it has one, draft nothing.
+- **`write: true` only after they agreed to the diff.** The write is validated
+  with the daemon's own loaders first — a profile that would not boot is
+  refused and nothing changes. When it lands, a commit is asked for; their
+  machine carries it out if the config home is a git repo. `setup_profile`
+  shows what became of it.
+- **Direct edits are their right.** If they edit the profile themselves, check it
+  with `setup_profile_validate` (they can run `qcr setup validate`), and say
+  plainly whether the daemon would boot with it.
+
+## The replay: old against new, cost first
+
+Once a write has landed, offer ONCE to replay one or two recent PRs with the
+profile as it was before the write and as it is now — the tuning's effect,
+seen before it goes live. It is optional: if they decline, move on.
+
+- Pick PRs the change should show on — ones touching the lenses the
+  interview moved — and say why.
+- `setup_replay_preview` shows both sides' plans and the price. **Tell them
+  the cost and the hard cap first**; start (`setup_replay_start`, the
+  preview's key) only when they agree.
+- It runs in the background; keep going with them. `setup_replay_status`
+  shows the two reviews side by side when it is done. Read it FOR them: what
+  the new profile catches that the old missed, what it no longer raises,
+  what moved in severity, what it cost — and whether that is what their goals
+  asked for. One or two PRs are a sample: say so, and never re-tune on one
+  finding alone.
+- A difference they do not want is a reason to re-tune (the same interview,
+  shorter), then replay again only if they ask.
+
+## Pins: propose, they decide
+
+Pinned memory heads every PR round, and the head is small. Propose a
+handful of the survey's and history's most important entries with
+`setup_pin_propose`, each with one line of why — conventions a round must
+never miss, not trivia. **You do not pin.** They appear marked ☆ on the
+TUI's memory tab; they pin with `p`. The tool prices the pinned head: if the
+proposals would push it past its budget, propose fewer.
+
+## What it takes to go live
+
+Tell them, plainly, what is still theirs:
+
+- **Name the profile.** If the live config does not name it, PR rounds do
+  not use it: they set `[review] profile = "<name>"` in their `config.toml`.
+- **Deploy.** Nothing reaches PR reviews until they deploy; the deploy tab
+  says "profile changed, not deployed" until then. You never deploy.
+
+## Re-tuning later
+
+The same interview, shorter: `setup_profile` shows the recorded answers;
+ask only about what changed, and write only the difference — a write keeps
+every answer it was not given. Moving a concern back to `normal` clears what
+the table wrote for it. The same preview-then-write discipline applies.
+
+**After a scan** the re-tune is yours: `setup_retune`, not the
+interview. Change only what the scan gives grounds for, give every change
+its reason from what it found, preview, write, then report to them what
+changed and why. Refresh the portrait (`setup_portrait_assemble`, then your
+narrative) so the next re-tune reads this scan. It reaches PR reviews only
+on their deploy — the deploy tab shows the re-tune pending until then.
+
+## Never
+
+- Never write `config.toml`, and never a file the setup tools own by hand.
+- Never pin — propose, and let them pin.
+- Never start a survey, a re-survey or a replay they did not agree to, and
+  never spend before they have seen the cost.
+- Never quote a raw review comment or name its author anywhere outside the
+  state home.
+- Never call `deploy.sh`, the mutation gate, or the VM, and never write to
+  GitHub: a profile reaches PR reviews only when they deploy it.

package/skills/companion/survey/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: survey
+description: Sweep the standing candidate list for reviews that departed from the good path, and report them grouped by family, worst first — repeat blocks, dead rounds, repeat approvals, dismissals, disagreements, explicit [feedback]. Use when asked whether there is anything worth looking at, what is on the backlog, or where to start today, and when an honest "nothing found, here is what I checked" is the likely answer. It only surveys — it settles nothing.
+---
+
+# Surveying for candidates
+
+This file **is** the doctrine, decided with the owner. If the doctrine
+changes, it changes here. The instrument is `src/tui/candidates.ts`, and where this file and that
+module disagree, **the module wins** — its code runs, this prose does not.
+
+## What this is, and what it is not
+
+You are answering *"anything worth looking at?"* — and answering it honestly
+when the answer is no.
+
+**You survey; you do not judge.** Nothing here decides whether a review was
+right, attributes a fault, or writes a verdict. The moment the question turns
+into *"was the reviewer wrong on that one?"*, you are done here: hand the item
+to **`adjudicate`**, which will pull the evidence and reach a verdict under its
+own doctrine. Presenting a candidate as a defect is the one way this skill can
+do damage, because a candidate is a **shape**, not a fault: 27 of 29 live
+reviews departed from the good path, and most of those departures are fine.
+
+## The one good path, and what counts as leaving it
+
+Perfect is: **triggered → APPROVE in one round → merged.** Everything else is a
+departure, and departures are the *space* the survey works in, not a filter that
+narrows it — measured on the live corpus, exactly 2 of 29 PRs took the perfect
+path.
+
+**One carve-out, and it is the owner's, stated in their own terms: a block the
+author accepted and fixed is the review WORKING.** Block → fix → approve is not
+a candidate and must never be offered as one. It becomes one only if the block
+turned out to be wrong, or was withdrawn. `REPEAT_BLOCK_ROUNDS = 3` in the
+module is that carve-out in code: one fix cycle is the review doing its job,
+three blocks in a row is a treadmill.
+
+## The seven families
+
+Groups come out in this order — **highest-signal and rarest first** — and
+worst-first inside each group. The ordering is the whole usability of the list:
+with ~93% of reviews departing, a flat worst-first list buries a rare
+disagreement under a pile of long re-blocks, and the rare ones are the
+informative ones.
+
+1. **Explicit `[feedback]`** — a human said so, in words, on the PR. The
+   highest-confidence family and still the emptiest: zero comments in 1,125
+   deliveries at last count.
+2. **Human/bot disagreement, in BOTH directions** — a human approving where the
+   bot blocked, *and* a human requesting changes where the bot approved. The
+   second is the false-negative direction nothing else in the system measures.
+3. **The review was dismissed** — the author threw it away rather than
+   answering it.
+4. **Rounds that produced no verdict** — overdue, malformed, orphaned,
+   cancelled. Silent failures; nothing consumed these before.
+5. **Blocked round after round** — the shape: ten rounds, all
+   REQUEST_CHANGES, nine of them `staleness` re-runs.
+6. **Repeat approvals** — approved, then approved again. Already diagnosed:
+   the recheck forbids re-approval, so this family should shrink to
+   nothing once it deploys. Detected precisely so we can watch it die — if it
+   is still growing after a deploy, that is the finding.
+7. **Sheer length** — ten rounds or more, whatever the pattern.
+
+## Where the list lives
+
+**`/evidence/candidates.json`** — read-only, written by the TUI on its poll.
+Read it; do not recompute it, and do not build your own list beside it.
+
+- `candidates[]` — every candidate ever seen, with `family`, `severity`,
+  `headline`, `detail`, `first_seen`, `last_seen`, `signature`, and `judged`.
+- `families[]` — **every family, on every sweep**, with what it scanned, what it
+  found, and a named `gap` when its source is not reachable. This is what you
+  read out when there is nothing to report.
+- `coverage` — PRs scanned, and how many rounds have a local record against how
+  many the daemon says exist.
+
+**The list does not expire, and that is deliberate.** The event feed's horizon
+is about a day; the reviews worth adjudicating are usually older. A candidate
+not worked today is still there next week, with its original `first_seen`. Do
+not treat an old `first_seen` as staleness — an item that has sat for three
+weeks is an item nobody has answered, which is a reason to raise it, not to drop
+it.
+
+If the file is absent, say so: the TUI has not swept yet, or the mount is
+missing. Never substitute `/feed/events.jsonl` for it — that is the horizon this
+list exists to outlive.
+
+## Judged items return only if the PR moved
+
+An item leaves the open list when an `#adjudication` memory entry for its PR is
+observed — the entry `adjudicate` Step 7 already writes. Nothing else marks
+anything judged, and **you never edit the list**: `/evidence` is `:ro`, and the
+one-directional flow (adjudicate writes memory → the sweep observes it → the row
+goes quiet) is the design, not an inconvenience.
+
+A row comes back marked **`returned: true`** when the PR's signature has changed
+since it was judged — new rounds, a new head, a new verdict. Say so when you
+offer it: *"#1234 is back — you judged it on the 22nd and it has taken four
+rounds since"* is a different offer from a fresh candidate, and the owner should
+be able to tell them apart.
+
+## Reporting
+
+Short, grouped, worst-first. One line per candidate; the detail lines only for
+the ones you are actually recommending.
+
+- Lead with the count and the shape: *"Nine open, mostly long re-blocks — but
+  there is one disagreement, and it is the interesting one."*
+- **Name the rare family out loud** even when its severity is low. That is what
+  the grouping is for.
+- **Recommend one**, and say why it is the one. A list of nine with no
+  recommendation makes the owner do the sorting the survey was supposed to do.
+- Never editorialise on whether the review was wrong. *"Ten blocking rounds"* is
+  a fact; *"the reviewer was too harsh here"* is a verdict you have not earned.
+
+## The empty answer
+
+**Report what you checked. Never silence, never a consolation candidate.**
+
+> Nothing worth adjudicating. Checked all seven families across 14 PRs: no
+> `[feedback]` comments, no dismissals, no rounds without a verdict, longest
+> blocking run 2 (one fix cycle — the review working), no repeat approvals,
+> nothing at ten rounds. Two families are dark: disagreement and dismissal both
+> need the `feedback_signals` ledger, which has no local copy.
+
+The owner's reasoning, recorded: they have to be able to tell it actually looked. An
+empty survey that says "nothing" is indistinguishable from a survey that failed,
+and inventing a marginal candidate to have something to say is worse than both.
+
+**Read the `gap` fields and pass them on.** A family with a gap was not checked
+clean — it could not be checked at all, and saying "no explicit feedback" when
+the comment transport does not exist is a false negative you authored.
+
+## Handing off
+
+- The item needs judging → **`adjudicate`**.
+- You need the record of what actually happened first → **`evidence`**.
+- Something has already been decided and has to move → **`land`**.
+- The question is whether a proposed change would have behaved better →
+  **`replay`**.
+
+You have **no `Skill` tool** — invoke one by name, or read
+`/workspace/skills/companion/<name>/SKILL.md` directly. You have **no
+subagents**: survey one family at a time, yourself, and never pretend a
+fan-out ran.
+
+## Never
+
+- Never judge here. A candidate is a shape; the verdict is `adjudicate`'s.
+- Never offer a block the author accepted and fixed as a candidate.
+- Never answer an empty survey with silence, and never invent a candidate so
+  there is something to say.
+- Never drop an old candidate for being old, and never add a TTL, a rolling
+  window or a top-N cut to the list — the durability is the feature.
+- Never report a family as clean when its `gap` says it has no source.
+- Never write to `/evidence` — it is `:ro`, and judged-ness flows back through
+  memory, never through a second write path.
+- Never call GitHub, the mutation gate, `deploy.sh`, or the VM. The list, the
+  manifests and the feed are all local files.