@ericrisco/rsc 3.0.9 → 3.0.11

package/README.md

@@ -98,8 +98,8 @@ rsc 3.0 fixes all four, by default, with no new commands to learn:
 
 **Commit, push and pull request without a prompt each time.** A harness installed from scratch lets
 the agent run `git commit`, `git push` and `gh pr create` without asking, because those are the steps
-that close every lane. A force-push still asks. The guards still decide: a commit on a closed `main` is
-refused whatever the permission says. It is a project decision, saved as `gitPermissions` in
+that close every lane. A force-push still asks. In Claude Code, rsc's guards still decide: a commit on a
+closed `main` is refused whatever the permission says. No other assistant runs those guards. It is a project decision, saved as `gitPermissions` in
 `.rsc.json`. A clone gets the same setting. A project adopted before this is left as it was until
 someone runs `rsc git-permissions on`.
 
@@ -108,16 +108,32 @@ someone runs `rsc git-permissions on`.
 | Claude Code | `.claude/settings.json` → `permissions.allow` (force-push under `ask`). Claude Code applies it once the folder is trusted. |
 | Codex | `.codex/rules/rsc-git.rules` (`prefix_rule`; force-push → `prompt`). Loaded when the project is trusted. |
 | Gemini | `.gemini/settings.json` → `tools.allowed` |
-| OpenCode | `opencode.json` → `permission.bash` (force-push → `ask`) |
+| OpenCode | `opencode.json`. With OpenCode 2 installed: the top-level `permissions` list (`shell` rules; force-push → `ask`). rsc's rules go before yours, so any rule of yours that matches later still wins; only a leading `"*"` allow/ask default stays in front. With OpenCode 1.x, or when `opencode --version` cannot be read: `permission.bash`, which both versions read. Moving to 2 moves rsc's entries over. An `opencode.jsonc` is read but never rewritten (its comments would be lost): rsc prints the rules to paste. |
 | Cursor | Not covered: its CLI matches only the first word, so allowing a push would allow every git command. |
 | DeepSeek Harness | Not covered: dsh has no per-command allow list. Its own Permissions selector (`/permission`) sets approval for every command at once. |
 
 ```bash
-rsc git-permissions status   # decided or not, and wired per assistant
-rsc git-permissions off      # ask again for commit, push and PR (saved in .rsc.json)
+rsc git-permissions status   # per assistant: wired or not, and in which format (--json for scripts)
+rsc git-permissions off      # remove rsc's rules (saved in .rsc.json)
 rsc git-permissions on       # turn it on, also for a project adopted before
 ```
 
+**What `off` turns off.** Only rsc's allow rules. Each command says, per assistant, what rsc controls
+there, what stops when it is off, and what is left to the assistant. `off` does not hand rsc's
+protections to the assistant. Claude Code keeps rsc's guards (branch-guard, danger-guard), because
+they do not depend on this switch. OpenCode, Codex and Gemini run no rsc guard. There, your own
+settings decide. With no rule matching, OpenCode 2 asks and OpenCode 1.x runs the command. To refuse a
+force-push in OpenCode 2, add this at the end of `permissions` (use `"ask"` to get a human approval):
+
+```json
+{ "action": "shell", "resource": "git push --force*", "effect": "deny" },
+{ "action": "shell", "resource": "git push -f*", "effect": "deny" },
+{ "action": "shell", "resource": "git push * --force*", "effect": "deny" },
+{ "action": "shell", "resource": "git push * -f*", "effect": "deny" }
+```
+
+In OpenCode 1.x the same patterns go at the end of `permission.bash` (`"git push --force*": "deny"`, …).
+
 **How does it know a project is "complex or in production"?** There are two layers. A hook counts
 what anyone can check: a CI setup, a deployment file (`Dockerfile`, `vercel.json`, `fly.toml`…) or
 at least two people in the last 50 commits. If any of those is there, a commit on the default branch
@@ -216,6 +232,14 @@ Every turn takes exactly one lane, and your agent names the one it took in a lin
 
 The agent says which lane it took and why, in one line. Ask for the other one and it switches.
 
+**The review only brings you what is real.** In SDD, `review` sends three adversarial reviewers at
+the diff (correctness, security, tests). They often find the same defect in different words, and a
+reviewer hunting for problems can overstate one. So before anything reaches you,
+`rsc review consolidate` merges the duplicates (same place, or the same quoted line), and every
+serious finding left goes to a fresh `finding-verifier` agent whose starting position is that the
+finding is false. It blocks the merge only if the verifier reproduces it or traces it. You get
+"11 reported → 4 unique → 2 confirmed", and the refuted ones are listed with the reason.
+
 **Isolation cleans itself up.** When a lane opens a branch or a worktree, you no longer have to
 remember to retire it: a `post-merge` hook does it the moment the work lands on the trunk, on both
 landing paths — a local merge and the pull after a forge merge. It removes only what is provably
@@ -403,6 +427,11 @@ rsc memory resume                    # print this branch/worktree continuation
 rsc memory learn --text "…" --evidence "…" --confidence 0.8 --approve
 rsc memory off                       # disable hooks, commands and injection project-wide
 rsc sync --target claude,codex       # refresh managed skills/hooks from the current package version
+rsc agent-model opencode openai/gpt-5   # pin the model the generated agents carry (saved in .rsc.json)
+rsc agent-model opencode inherit     # back to the session's model (OpenCode's default)
+rsc agents status                    # installed agents, and which ones you edited
+rsc agents reset developer           # take rsc's version of an agent you edited (yours is backed up first)
+rsc review consolidate c.md s.md t.md  # merge the review lenses' findings; serious ones go to finding-verifier
 rsc backups                          # list project-local snapshots
 rsc restore latest --dry-run         # preview restoring the newest snapshot
 rsc restore <snapshot-id>            # restore a project-local snapshot
@@ -410,6 +439,29 @@ rsc upgrade --dry-run                # show npm upgrade + sync commands
 rsc uninstall postgresdb --dry-run   # preview a removal
 ```
 
+### `rsc doctor`: harness health vs onboarding readiness
+
+`doctor` answers two different questions, and prints both first, on separate lines:
+
+```text
+Harness health: healthy
+Onboarding readiness: pending
+Pending: 02-DOCS/wiki/sdd/constitution.md (draft)
+Next: Complete 02-DOCS/wiki/sdd/constitution.md with the `constitution` phase …
+```
+
+- **Harness health** (`healthy` in `--json`) says whether what is installed works: skills, agents,
+  commands and hook scripts are on disk. It is the only thing the exit code follows (1 when
+  unhealthy), so CI and editor extensions can rely on it.
+- **Onboarding readiness** (`onboarding` in `--json`: `status`, `missing`, `pending`, `action`) says
+  whether onboarding is finished. It checks the accepted plan's floor, the same check that prints
+  `RSC_ONBOARDING_READY`, plus drafts. The status is `ready`; `pending` when a draft such as the
+  onboarding constitution still has to be completed; `incomplete` when part of the floor is missing,
+  for example a deleted constitution in an SDD plan, with the exact phase or command that fixes it;
+  or `not onboarded` when there is no onboarding record, as in a manual `rsc add` install. Readiness
+  never changes `healthy` or the exit code. `Missing:` and `Pending:` appear only when they have
+  entries.
+
 ---
 
 
@@ -841,11 +893,20 @@ The richer surfaces are intentionally narrower than skill support:
 | Windsurf, Cline, Roo | unsupported | yes | unsupported |
 | Antigravity, Zed, Continue, Amp, Jules, Aider | unsupported | unsupported | unsupported |
 
-`manifest.json` is the generated public inventory: 33 agents (4 base + 29
+`manifest.json` is the generated public inventory: 34 agents (5 base + 29
 selective specialists) and 53 command entries (20 fixed + 33 stack aliases).
 Unsupported means rsc writes nothing for that surface; it does not emulate a
 provider feature with an unverified file.
 
+**Generated agents follow your project, not rsc's defaults.** OpenCode agents carry no `model:`, so
+they use whatever model the session runs (a local one, OpenAI, Anthropic). To pin one for the whole
+team, run `rsc agent-model opencode <model>`: it is saved as `agentModels` in `.rsc.json` and works
+for any target with agents (`inherit` drops the pin). OpenCode agents never grant a tool either: a
+read-only reviewer only gets `edit`, `write`, `patch` and `bash` set to `false`, and an agent that may
+edit or run commands gets no `tools` block, so your project's permission policy decides. If you edit
+a generated agent, `rsc sync` keeps your file and says so. `rsc agents reset <name>` (or `--all`)
+takes rsc's version back after a backup in `.rsc/backups/`.
+
 ---
 
 ## Skill format

package/manifest.json

@@ -1,8 +1,8 @@
 {
-  "version": "3.0.9",
+  "version": "3.0.11",
   "counts": {
     "skills": 270,
-    "agents": 33,
+    "agents": 34,
     "commands": 53,
     "fixedCommands": 20
   },
@@ -5715,6 +5715,14 @@
         "fastapi"
       ]
     },
+    {
+      "id": "finding-verifier",
+      "description": "Adversarial verifier of review findings: takes ONE consolidated finding and tries to prove it false against the code. Default stance: the finding is false; only a reproduced or traced failure is CONFIRMED. Fresh context, edits nothing.",
+      "role": "refuter",
+      "tier": "balanced",
+      "tools": null,
+      "skills": []
+    },
     {
       "id": "flutter-build-resolver",
       "description": "Flutter build resolver: reproduces a failing build and applies the minimum verified repair. NOT widget review or package modernization.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.0.9",
+  "version": "3.0.11",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -17,10 +17,11 @@ import { countGaps, listSkills, listAgents } from './lib/capabilities.js';
 import { resolveCommands, commandPath, targetHasCommands } from '../targets/commands.js';
 import { inspectMemoryWiring } from '../targets/memory.js';
 import { metricsSummary } from '../targets/session-memory-core.mjs';
-import { agentPath } from '../targets/agents.js';
+import { agentPath, targetHasAgents, effectiveAgentModel } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
 import { versionReport } from './lib/versions.js';
 import { CONSTITUTION_PATH, constitutionIsDraft } from './lib/constitution-draft.js';
+import { onboardingReadiness } from './lib/onboarding-apply.js';
 
 // Gates the committed manifest says the team disarmed, still armed here. Read through the same
 // partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
@@ -298,6 +299,11 @@ export function doctor({ target, home, cwd }) {
     memory,
     missingAgents,
     agentCollisions: state.agentCollisions || [],
+    // #298 — generated agents the user edited and sync kept as they are. Not unhealthy: theirs on
+    // purpose. Named with the way back, so a stale edit is one command from rsc's version.
+    agentsEditedByYou: (state.agentsKept || []).map((k) => ({ ...k, action: `\`npx @ericrisco/rsc agents reset ${k.name}\` takes rsc's version (yours is backed up first).` })),
+    // Which model the agents carry: the session's (inherit) or a project pin (`rsc agent-model`).
+    agentModel: targetHasAgents(target) ? (effectiveAgentModel(target, root) || 'inherit') : null,
     missingCommands,
     commandOrphans,
     commandCollisions: state.commandCollisions || [],
@@ -316,6 +322,14 @@ export function doctor({ target, home, cwd }) {
   report.pending = constitutionIsDraft(root)
     ? [{ id: 'constitution-draft', path: CONSTITUTION_PATH, action: 'Complete it with the `constitution` phase before the first SDD feature; ratifying removes `status: draft`.' }]
     : [];
+  // #298 — onboarding readiness is a SEPARATE question from health: is the accepted plan's floor
+  // on disk (the same check that prints RSC_ONBOARDING_READY), and is anything still a draft. It is
+  // reported, never folded into `healthy`: `healthy` and the exit code keep meaning "the installed
+  // harness works", which is what CI and editor extensions built on #277 read. Wrapped because a
+  // report must never fail for asking an extra question.
+  try { report.onboarding = onboardingReadiness(root); } catch (error) {
+    report.onboarding = { status: 'incomplete', missing: ['<onboarding readiness could not be read>'], pending: [], action: String(error?.message || error).slice(0, 200) };
+  }
   report.healthy = report.hookWired && !report.missing.length && !missingAgents.length && !missingCommands.length
     && !report.opencodePluginsOutdated.length;
   return report;

package/scripts/install-apply.js

@@ -7,7 +7,7 @@ import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import { shadowTarget } from '../targets/agents-md-shadow.js';
 import {
-  targetHasAgents, reconcileAgents, agentPath, agentNames,
+  targetHasAgents, reconcileAgents, agentPath, agentNames, writeAgentsDetailed,
   resolveAgentNames, agentByName, allAgentNames, readDeveloperTier, writeDeveloperTier,
 } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
@@ -223,6 +223,7 @@ export function recordInManifest({ cwd, target, skillIds, agentIds = [], catalog
     optOuts: optOuts ?? projectOptOuts(prev.optOuts),
     memory: prev.memory,
     gitPermissions: gitPermissions ?? prev.gitPermissions,
+    agentModels: prev.agentModels,
     onboarding: onboarding ?? prev.onboarding,
   });
 }
@@ -306,13 +307,19 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
       ? explicit
       : resolveAgentNames(Object.keys(state.skills || {}), explicit);
   const previousAgents = state.agents || [];
+  let keptAgents = [];
   if (targetHasAgents(target)) {
     const agentResult = reconcileAgents(target, cwd, readDeveloperTier(cwd), previousAgents, desiredAgents);
     state.agents = agentResult.names;
     state.agentCollisions = agentResult.collisions;
+    // #298 — agents the user edited and rsc left alone. Recorded so `doctor` can say it on any run,
+    // and returned so the command that just ran says it now.
+    keptAgents = agentResult.kept;
+    state.agentsKept = keptAgents.map(({ name, path }) => ({ name, path }));
   } else {
     state.agents = [];
     state.agentCollisions = [];
+    state.agentsKept = [];
   }
   state.explicitAgents = explicit;
   const memoryResult = policy?.memory === false
@@ -381,7 +388,7 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     if (existsSync(join(cwd, '.git'))) mergeHook = installMergeHook(cwd);
   } catch (err) { mergeHook = { installed: false, state: 'skipped', reason: err.message }; }
   ignoreLocalState(cwd, target);
-  return { ...state, backup, mergeHook };
+  return { ...state, backup, mergeHook, keptAgents };
 }
 
 // `.rsc/` holds local machine state — hook scripts, install markers, the sello's
@@ -551,9 +558,16 @@ export async function uninstall({ skillIds = [], agentIds = [], target, home, cw
     delete state.skills[id];
   }
   const agentResult = reconcileAgents(target, cwd, readDeveloperTier(cwd), state.agents || [], desiredAgents);
-  state.agents = agentResult.names;
+  // An edited agent no longer wanted stays on disk (#298) and stays recorded as rsc-managed, so a
+  // later reset or uninstall can still find it.
+  state.agents = [...new Set([...agentResult.names, ...agentResult.kept.map((k) => k.name)])];
   state.agentCollisions = agentResult.collisions;
+  state.agentsKept = agentResult.kept.map(({ name, path }) => ({ name, path }));
   state.explicitAgents = nextExplicit;
+  for (const k of agentResult.kept) {
+    const i = removed.indexOf(k.path);
+    if (i >= 0) removed.splice(i, 1);
+  }
   const desiredCommands = resolveCommands({
     target,
     skills: remainingSkillIds,
@@ -712,7 +726,30 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   // question sat untracked, one `git add -A` from the team repo (team simulation D13). Sync is what a
   // clone runs, so it writes the same exclude. Lazy import: onboarding-apply imports this module.
   try { (await import('./lib/onboarding-apply.js')).excludePersonalProfile(cwd); } catch { /* not a repo → nothing */ }
-  return { synced: declared, syncedAgents: declaredAgents, backup: nextState.backup };
+  return { synced: declared, syncedAgents: declaredAgents, backup: nextState.backup, keptAgents: nextState.keptAgents || [] };
+}
+
+/**
+ * #298 — `rsc agents reset <name|--all>`: take rsc's version of agents the user edited. The user's
+ * file is snapshotted first (a backup under .rsc/backups/), and the answer says where, so taking rsc's
+ * version is never the loss the protection exists to prevent.
+ */
+export function resetAgents({ target, home, cwd = process.cwd(), names = [], all = false }) {
+  if (!targetHasAgents(target)) return { reset: [], backup: null, kept: [] };
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const installed = state.agents || [];
+  const chosen = all ? installed : names;
+  const unknown = chosen.filter((name) => !installed.includes(name));
+  if (unknown.length) throw new Error(`${unknown.join(', ')}: not an agent rsc installed for ${target} (installed: ${installed.join(', ') || 'none'})`);
+  if (!chosen.length) return { reset: [], backup: null, kept: [] };
+  const files = chosen.map((name) => agentPath(target, cwd, name));
+  const backup = createBackup({ cwd, operation: 'agents-reset', target, paths: files.filter((f) => existsSync(f)), cliVersion: CLI_VERSION });
+  const { written } = writeAgentsDetailed(target, cwd, readDeveloperTier(cwd), chosen, { force: true });
+  state.agentsKept = (state.agentsKept || []).filter((k) => !chosen.includes(k.name));
+  writeState(paths.stateFile, state);
+  const rel = (p) => relative(cwd, p).split(sep).join('/');
+  return { reset: chosen, written, backup: backup ? rel(join(cwd, '.rsc', 'backups', backup.id)) : null };
 }
 
 // Remove EVERYTHING rsc put in this project: installed skills across all targets,

package/scripts/lib/manifest-file.js

@@ -15,7 +15,7 @@ import { join } from 'node:path';
 export const MANIFEST = '.rsc.json';
 export const manifestPath = (cwd = process.cwd()) => join(cwd, MANIFEST);
 
-const KEYS = ['version', 'targets', 'skills', 'agents', 'ownSkills', 'catalogVersion', 'tier', 'optOuts', 'memory', 'gitPermissions', 'onboarding'];
+const KEYS = ['version', 'targets', 'skills', 'agents', 'ownSkills', 'catalogVersion', 'tier', 'optOuts', 'memory', 'gitPermissions', 'agentModels', 'onboarding'];
 
 export function readManifest(cwd = process.cwd()) {
   const file = manifestPath(cwd);
@@ -40,10 +40,19 @@ export function readManifest(cwd = process.cwd()) {
     memory: raw.memory ?? undefined,
     // true on a project installed from scratch since 3.0.3; absent on older ones; false once turned off.
     gitPermissions: typeof raw.gitPermissions === 'boolean' ? raw.gitPermissions : undefined,
+    // #298 — per-target agent model: { opencode: 'openai/gpt-5' | 'inherit' }. Only plain objects of
+    // strings survive the read; what each value may contain is checked where it is rendered.
+    agentModels: agentModelsFrom(raw.agentModels),
     onboarding: raw.onboarding ?? undefined,
   };
 }
 
+function agentModelsFrom(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value).filter(([, v]) => typeof v === 'string').sort(([a], [b]) => a.localeCompare(b));
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
 // Stable output: fixed key order, arrays one entry per line, order as given. Rewriting an
 // unchanged manifest must produce identical bytes, or every install shows up as a diff.
 export function writeManifest(cwd, manifest) {

package/scripts/lib/onboarding-apply.js

@@ -10,7 +10,7 @@ import { readManifest, writeManifest } from './manifest-file.js';
 import { encodeGoal, identifyPlan } from './onboarding.js';
 import { createBackup, restoreBackup } from './backups.js';
 import { RETIRED_SKILLS, replaceRetired } from './retired-skills.js';
-import { CONSTITUTION_PATH } from './constitution-draft.js';
+import { CONSTITUTION_PATH, constitutionIsDraft } from './constitution-draft.js';
 import { LAYER_IGNORE, TEMPLATE_SOURCE, targetName, templateAssets } from './tools-skeleton.js';
 
 const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
@@ -445,7 +445,10 @@ function floorSatisfied(cwd, path) {
 // conflictos de merge, y que un repo clonado puede traer preparado. Así que se valida la forma antes
 // de mirar el disco: un `..` daba el suelo por satisfecho MIRANDO FUERA de la raíz, y un `null` o una
 // cadena en lugar de un array tumbaban `rsc install` después de haber instalado.
-export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
+//
+// Devuelve los CAMINOS que faltan (como se muestran). `missingHarnessFloor` los redacta para el
+// instalador y `onboardingReadiness` los entrega tal cual a `doctor`: una comprobación, dos lectores.
+export function harnessFloorGaps(cwd = process.cwd(), plan = {}) {
   const declared = Array.isArray(plan?.floorPaths) ? plan.floorPaths : [];
   const missing = [];
   for (const path of declared) {
@@ -453,15 +456,19 @@ export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
     const usable = segments.length > 0 && !segments.includes('..') && !String(path).startsWith('/');
     // Un camino que no se puede usar se reporta como NO satisfecho, nunca como satisfecho, y sin
     // repetir su contenido: es dato ajeno y va a un canal que lee un agente.
-    if (!usable) { missing.push('missing harness floor <invalid declaration>'); continue; }
+    if (!usable) { missing.push('<invalid declaration>'); continue; }
     // La barra sólo si el camino declarado la traía: el suelo condicional es un FICHERO, y decir
     // `constitution.md/` invita a buscar un directorio que no existe.
     const shown = String(path).endsWith('/') ? `${floorKey(path)}/` : floorKey(path);
-    if (!floorSatisfied(cwd, path)) missing.push(`missing harness floor ${shown}`);
+    if (!floorSatisfied(cwd, path)) missing.push(shown);
   }
   return missing;
 }
 
+export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
+  return harnessFloorGaps(cwd, plan).map((shown) => `missing harness floor ${shown}`);
+}
+
 /**
  * Lo que el instalador puede afirmar honestamente, y qué hacer si no.
  *
@@ -479,3 +486,50 @@ export function harnessReadiness(cwd = process.cwd(), plan = {}) {
       : '',
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Preparación del onboarding, como pregunta PROPIA (#298 punto 5).
+//
+// `doctor` respondía sólo «¿el arnés instalado funciona?» (`healthy`, y el exit code con él) y un
+// usuario leía ese `true` como «el onboarding está terminado» con la constitución sin escribir. Son
+// dos preguntas: ésta se calcula con el MISMO suelo que decide RSC_ONBOARDING_READY/INCOMPLETE
+// (`harnessFloorGaps`) más los borradores, y nunca toca `healthy`.
+//
+//   ready          suelo completo, nada en borrador
+//   pending        suelo completo, pero algo es un borrador que el usuario debe completar
+//   incomplete     falta parte del suelo del plan aceptado (o el recibo no cuadra con su id)
+//   not-onboarded  no hay recibo: instalación manual (`rsc add`) o anterior al onboarding
+//
+// Un recibo de una versión que no declaraba suelo queda exento por construcción (P3), igual que en
+// el instalador: aquí no se inventa un suelo que el plan aceptado no traía.
+const ONBOARD_ACTION = 'Run `npx @ericrisco/rsc@latest onboard` to record a plan for this harness (optional: what is installed keeps working).';
+const draftAction = (path) => `Complete ${path} with the \`constitution\` phase (tell your agent "constitution") before the first SDD feature; ratifying removes \`status: draft\`.`;
+
+export function onboardingReadiness(cwd = process.cwd(), manifest = readManifest(cwd)) {
+  const pending = constitutionIsDraft(cwd) ? [CONSTITUTION_PATH] : [];
+  const receipt = manifest?.onboarding;
+  if (!receipt?.plan) {
+    return { status: 'not-onboarded', missing: [], pending, action: ONBOARD_ACTION };
+  }
+  let identical = false;
+  try { identical = identifyPlan(receipt.plan) === receipt.acceptedPlanId; } catch { /* ilegible: no cuadra */ }
+  if (!identical) {
+    return {
+      status: 'incomplete', missing: ['<onboarding receipt does not match its accepted plan id>'], pending,
+      action: 'Do not trust the receipt. Re-run `npx @ericrisco/rsc@latest onboard` and accept a fresh plan.',
+    };
+  }
+  const missing = harnessFloorGaps(cwd, receipt.plan);
+  if (missing.length) {
+    const actions = [];
+    if (missing.includes(CONSTITUTION_PATH)) {
+      actions.push(`Write ${CONSTITUTION_PATH} with the \`constitution\` phase (tell your agent "constitution"); the SDD plan you accepted requires it.`);
+    }
+    if (missing.some((path) => path !== CONSTITUTION_PATH)) {
+      actions.push('Invoke the `harness` skill to scaffold 01-TOOLS/ + 02-DOCS/.');
+    }
+    return { status: 'incomplete', missing, pending, action: actions.join(' ') };
+  }
+  if (pending.length) return { status: 'pending', missing, pending, action: draftAction(CONSTITUTION_PATH) };
+  return { status: 'ready', missing, pending, action: '' };
+}

package/scripts/lib/review-findings.js

@@ -0,0 +1,175 @@
+// Consolidation of the refuter panel's findings — the deterministic half of `review`.
+//
+// Three fresh-context lenses attack the same diff, so they often report the SAME defect in three
+// different sentences, and the author spends triage time discovering that eleven findings are four.
+// Grouping them is an algorithm, not a judgement (P1), so it lives here and not in the skill's prose.
+// What survives grouping and is serious enough to block goes to `finding-verifier` — that half IS
+// judgement, and stays in the agent.
+//
+// Input: what the lenses emit — fenced ```json findings blocks inside their reports, or plain JSON.
+// Output: unique findings, highest severity first, each with the lenses that reported it and a
+// `verify` flag on the ones the verifier must try to refute before they may block.
+
+export const SEVERITIES = ['blocker', 'should-fix', 'nit', 'question'];
+const ALIASES = {
+  critical: 'blocker', high: 'blocker', blocking: 'blocker',
+  medium: 'should-fix', shouldfix: 'should-fix', 'should_fix': 'should-fix', major: 'should-fix',
+  low: 'nit', info: 'nit', minor: 'nit',
+};
+const rank = (s) => SEVERITIES.indexOf(s);
+export const DEFAULT_WINDOW = 3;
+
+export function normalizeSeverity(raw) {
+  const s = String(raw || '').trim().toLowerCase();
+  if (SEVERITIES.includes(s)) return s;
+  return ALIASES[s] || ALIASES[s.replace(/[-\s]/g, '')] || null;
+}
+
+const text = (v) => (typeof v === 'string' ? v.trim() : '');
+const normFile = (f) => text(f).replace(/\\/g, '/').replace(/^\.\//, '');
+const normEvidence = (e) => text(e).replace(/\s+/g, ' ').toLowerCase();
+
+// Pull every finding out of one source. A source is a lens report (markdown with fenced blocks) or a
+// JSON file. Anything unparseable is reported, never silently dropped: a lost finding is the one
+// failure a consolidation step must not add.
+export function parseFindings(raw, source = 'stdin') {
+  const findings = [];
+  const errors = [];
+  const take = (value, where) => {
+    const list = Array.isArray(value) ? value : (Array.isArray(value?.findings) ? value.findings : [value]);
+    for (const item of list) {
+      if (!item || typeof item !== 'object') { errors.push(`${where}: a finding must be an object`); continue; }
+      findings.push({ ...item, source });
+    }
+  };
+  const blocks = [...String(raw).matchAll(/```json[ \t]+findings[^\n]*\n([\s\S]*?)```/g)];
+  if (blocks.length) {
+    blocks.forEach((m, i) => {
+      try { take(JSON.parse(m[1]), `${source} block ${i + 1}`); }
+      catch (e) { errors.push(`${source} block ${i + 1}: not valid JSON (${e.message})`); }
+    });
+    return { findings, errors };
+  }
+  const trimmed = String(raw).trim();
+  if (!trimmed) return { findings, errors };
+  try { take(JSON.parse(trimmed), source); }
+  catch { errors.push(`${source}: no \`\`\`json findings block and not plain JSON`); }
+  return { findings, errors };
+}
+
+// The pre-report gate, checked instead of trusted: a blocker or should-fix with no location or no
+// concrete failure scenario is a suspicion, and a suspicion is a question. The downgrade is visible.
+export function normalizeFinding(f) {
+  const out = {
+    lens: text(f.lens) || text(f.source) || 'unknown',
+    severity: normalizeSeverity(f.severity),
+    file: normFile(f.file),
+    line: Number.isInteger(Number(f.line)) && Number(f.line) > 0 ? Number(f.line) : null,
+    claim: text(f.claim) || text(f.title) || text(f.summary),
+    failure_scenario: text(f.failure_scenario) || text(f.repro),
+    evidence: text(f.evidence),
+    notes: [],
+  };
+  if (!out.severity) {
+    out.notes.push(`severity "${f.severity ?? ''}" unknown → question`);
+    out.severity = 'question';
+  }
+  if (rank(out.severity) <= rank('should-fix')) {
+    const missing = [];
+    if (!out.file || !out.line) missing.push('file:line');
+    if (!out.failure_scenario) missing.push('failure_scenario');
+    if (missing.length) {
+      out.notes.push(`${out.severity} without ${missing.join(' and ')} → question`);
+      out.severity = 'question';
+    }
+  }
+  return out;
+}
+
+// Two findings are the same defect when they quote the same evidence, or when they point at the same
+// place (same file, lines within the window) AND say the same thing. Place alone is not enough: the
+// first real panel run put two different defects on adjacent lines (a discount applied to one unit,
+// and a missing 0..100 check), and merging them buried the second one where no verifier looked.
+// A missed merge costs one extra verification; a wrong merge hides a defect — so the bar is
+// conservative. "Say the same thing" is word overlap (Jaccard) of claim, or claim + failure scenario.
+const STOP = new Set('the and for with not that this its are was from any only one but has have into than then when which will can its'.split(' '));
+const words = (s) => new Set(String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP.has(w)));
+function overlap(a, b) {
+  const A = words(a); const B = words(b);
+  let shared = 0;
+  for (const w of A) if (B.has(w)) shared += 1;
+  const union = A.size + B.size - shared;
+  return union ? shared / union : 0;
+}
+export const SAME_CLAIM = 0.2;
+export function similarity(a, b) {
+  return Math.max(overlap(a.claim, b.claim),
+    overlap(`${a.claim} ${a.failure_scenario}`, `${b.claim} ${b.failure_scenario}`));
+}
+function sameDefect(a, b, window) {
+  const ea = normEvidence(a.evidence);
+  if (ea.length >= 12 && ea === normEvidence(b.evidence)) return true;
+  const near = a.file && a.file === b.file && a.line && b.line && Math.abs(a.line - b.line) <= window;
+  return Boolean(near) && similarity(a, b) >= SAME_CLAIM;
+}
+
+export function consolidate(rawFindings, { window = DEFAULT_WINDOW } = {}) {
+  const items = rawFindings.map(normalizeFinding);
+  const parent = items.map((_, i) => i);
+  const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+  for (let i = 0; i < items.length; i += 1) {
+    for (let j = i + 1; j < items.length; j += 1) {
+      if (sameDefect(items[i], items[j], window)) parent[find(j)] = find(i);
+    }
+  }
+  const groups = new Map();
+  items.forEach((it, i) => {
+    const root = find(i);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(it);
+  });
+  const uniq = (xs) => [...new Set(xs.filter(Boolean))];
+  const merged = [...groups.values()].map((members) => {
+    const severity = SEVERITIES[Math.min(...members.map((m) => rank(m.severity)))];
+    const lines = members.map((m) => m.line).filter(Boolean);
+    return {
+      severity,
+      file: uniq(members.map((m) => m.file))[0] || '',
+      lines: lines.length ? [Math.min(...lines), Math.max(...lines)] : [],
+      lenses: uniq(members.map((m) => m.lens)).sort(),
+      claims: uniq(members.map((m) => m.claim)),
+      failure_scenarios: uniq(members.map((m) => m.failure_scenario)),
+      evidence: uniq(members.map((m) => m.evidence)),
+      notes: uniq(members.flatMap((m) => m.notes)),
+      reported: members.length,
+      verify: rank(severity) <= rank('should-fix'),
+    };
+  });
+  merged.sort((a, b) => rank(a.severity) - rank(b.severity)
+    || a.file.localeCompare(b.file) || (a.lines[0] || 0) - (b.lines[0] || 0));
+  merged.forEach((m, i) => { m.id = `F${i + 1}`; });
+  return {
+    reported: items.length,
+    unique: merged.length,
+    toVerify: merged.filter((m) => m.verify).length,
+    findings: merged,
+  };
+}
+
+const where = (f) => (f.file ? `${f.file}${f.lines.length ? `:${f.lines[0]}${f.lines[1] !== f.lines[0] ? `-${f.lines[1]}` : ''}` : ''}` : '(no location)');
+
+export function renderConsolidation(result, errors = []) {
+  const out = [
+    `${result.reported} finding(s) reported → ${result.unique} unique · ${result.toVerify} go to finding-verifier`,
+  ];
+  for (const f of result.findings) {
+    out.push('', `${f.id} [${f.severity}] ${where(f)} — ${f.claims[0] || '(no claim)'}`);
+    out.push(`   lenses: ${f.lenses.join(', ')}${f.reported > 1 ? ` (${f.reported} reports merged)` : ''}`);
+    for (const c of f.claims.slice(1)) out.push(`   also: ${c}`);
+    for (const s of f.failure_scenarios) out.push(`   failure: ${s}`);
+    for (const n of f.notes) out.push(`   note: ${n}`);
+    if (f.verify) out.push('   → verify: dispatch finding-verifier; it blocks only if CONFIRMED');
+  }
+  for (const e of errors) out.push('', `⚠️  ${e}`);
+  return out.join('\n');
+}