@ericrisco/rsc 4.0.0 → 4.0.1

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0",
+  "version": "4.0.1",
   "counts": {
     "skills": 274,
     "agents": 34,
@@ -4376,8 +4376,9 @@
         "registry"
       ],
       "recommends": [
+        "asdd",
+        "constitution",
         "specify",
-        "implement",
         "verify"
       ],
       "profiles": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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/lib/review-ledger.js

@@ -14,7 +14,8 @@ import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 export const LEDGER_PATH = '.rsc/review-ledger.jsonl';
-export const OUTCOMES = ['fixed', 'false', 'intentional', 'irrelevant'];
+// `parked`: the finding's task went to the decision queue; neither fixed nor dismissed, a human decides.
+export const OUTCOMES = ['fixed', 'false', 'intentional', 'irrelevant', 'parked'];
 export const MAX_ROUNDS = 3;
 export const EVALS_DIR = '02-DOCS/wiki/sdd/review-evals';
 
@@ -129,7 +130,8 @@ export function stats(root) {
   for (const e of ledger) if (e.type === 'outcome') last.set(e.id, e.outcome);
   const outcomes = Object.fromEntries([...OUTCOMES, 'open'].map((k) => [k, 0]));
   for (const f of originals) outcomes[last.get(f.id) || 'open'] += 1;
-  const closed = originals.length - outcomes.open;
+  // Parked is undecided: a human holds it. Counting it as closed would understate the false rate.
+  const closed = originals.length - outcomes.open - outcomes.parked;
   const rounds = new Map();
   for (const e of ledger) if (e.type === 'round') rounds.set(e.task, Math.max(rounds.get(e.task) || 0, e.n));
   const totalRounds = [...rounds.values()].reduce((a, b) => a + b, 0);

package/scripts/lib/risk.js

@@ -6,7 +6,7 @@
 // Spec: 02-DOCS/wiki/sdd/specs/asdd-v4.md.
 
 import { spawnSync } from 'node:child_process';
-import { SELLO_STATE_PATHS, classifyRisk, lensesRequired, readEffectiveConfig, trunkRef } from '../../targets/sello.mjs';
+import { NESTED_WORKTREES, SELLO_STATE_PATHS, classifyRisk, lensesRequired, readEffectiveConfig, trunkRef } from '../../targets/sello.mjs';
 
 function git(root, args) {
   const r = spawnSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
@@ -24,7 +24,11 @@ export function changedPaths(root, base = null) {
   const mb = head ? (git(root, ['merge-base', 'HEAD', ref]) || '').trim() : '';
   if (!mb) return { ok: false, message: `rsc: cannot find a common ancestor with ${ref}. Pass --base <ref> or the paths themselves: npx @ericrisco/rsc risk <path…>` };
   // --no-renames: a rename reports both paths, so moving a file OUT of a tier-2 place still counts.
-  const diff = (from) => new Set([...nul(git(root, ['diff', '--name-only', '--no-renames', '-z', from])), ...nul(git(root, ['ls-files', '--others', '--exclude-standard', '-z']))]);
+  // Nested worktrees are skipped only while UNTRACKED (another checkout sitting in the tree). Once
+  // committed, a path under them is part of the change and keeps its tier.
+  const untracked = () => nul(git(root, ['ls-files', '--others', '--exclude-standard', '-z'])).filter((n) => !NESTED_WORKTREES.test(n));
+  const diff = (from) => new Set([...nul(git(root, ['diff', '--name-only', '--no-renames', '-z', from])), ...untracked()]
+    .filter((n) => !SELLO_STATE_PATHS.includes(n)));
   let names = diff(mb);
   let shown = ref;
   // Working straight on the trunk (FTD on an open main), the merge-base IS HEAD, and a change
@@ -34,7 +38,6 @@ export function changedPaths(root, base = null) {
     names = diff('HEAD~1');
     shown = 'HEAD~1 (on the trunk: the last commit)';
   }
-  for (const p of SELLO_STATE_PATHS) names.delete(p);
   return { ok: true, base: shown, paths: [...names].sort() };
 }
 

package/scripts/rsc.js

@@ -46,7 +46,7 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
   process.exit(0);
 }
 const GENERAL_HELP = [
-  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | agent-model <target> <model|inherit|status> | agents [status|reset <name|--all>] | memory <on|off|status|save|resume|learn|metrics> | risk [--base <ref>] [paths…] | review consolidate|ledger|escapes | ingest <file...> | copy check <file> | copy rules | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
+  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | agent-model <target> <model|inherit|status> | agents [status|reset <name|--all>] | memory <on|off|status|save|resume|learn|metrics> | risk [--base <ref>] [paths…] | spec gate [specs…] | review consolidate|ledger|escapes | ingest <file...> | copy check <file> | copy rules | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
   'Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)',
   '   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.',
 ].join('\n');
@@ -77,7 +77,7 @@ const PURGE_HELP = [
 const GLOBAL_VALUE_FLAGS = new Set([
   '--topic', '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--workflow', '--accept-plan',
 ]);
-const COMMANDS = new Set(['ingest', 'copy', 'onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'agent-model', 'agents', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'review', 'risk', 'sello', 'repair', 'uninstall', 'purge']);
+const COMMANDS = new Set(['ingest', 'copy', 'onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'agent-model', 'agents', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'review', 'risk', 'spec', 'sello', 'repair', 'uninstall', 'purge']);
 function positionalTokens(input) {
   const out = [];
   for (let i = 0; i < input.length; i++) {
@@ -1232,6 +1232,19 @@ async function main() {
       if (hits.length) process.exitCode = 1;
       return;
     }
+    case 'spec': {
+      // `spec gate` — the specify phase's exit gate, reachable from a user project. It was only an npm
+      // script inside this package, so the one check ASDD's spec depends on could not run where specs live.
+      const USE = 'Use: npx @ericrisco/rsc spec gate [spec.md ...]\n  Without paths it checks 02-DOCS/wiki/sdd/specs/ of this project. Exits 1 when a spec fails.';
+      if (argv[1] !== 'gate') { say(USE); if (argv[1]) process.exitCode = 1; return; }
+      const { spawnSync } = await import('node:child_process');
+      const { fileURLToPath: toPath } = await import('node:url');
+      const rest = argv.slice(2);
+      const specs = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--target');
+      const r = spawnSync(process.execPath, [toPath(new URL('./spec-gate.js', import.meta.url)), ...specs], { stdio: 'inherit', windowsHide: true });
+      process.exitCode = r.status ?? 1;
+      return;
+    }
     case 'risk': {
       // How much review and whose approval a change needs, by WHAT it touches (ASDD, P1/P7). The
       // agent never picks its own tier: this does, from the sello's path table, sello on or off.
@@ -1266,7 +1279,7 @@ async function main() {
       const USE = [
         'Use: npx @ericrisco/rsc review consolidate [report.md|findings.json ...] [--json] [--window <lines>]',
         '  Without files it reads stdin. Each lens report carries its findings in ```json findings blocks.',
-        '     npx @ericrisco/rsc review ledger record <findings.json> [--task <id>] | outcome <id> <fixed|false|intentional|irrelevant> | round <slug>/<task> | stats [--json]',
+        '     npx @ericrisco/rsc review ledger record <findings.json> [--task <id>] | outcome <id> <fixed|false|intentional|irrelevant|parked> | round <slug>/<task> | stats [--json]',
         '     npx @ericrisco/rsc review escapes [--since <ref>] [--json]',
       ].join('\n');
       if (argv[1] === 'ledger' || argv[1] === 'escapes') {

package/scripts/spec-gate.js

@@ -6,14 +6,24 @@
 // the phase's own instrument, and the author's.
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, basename, resolve, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { specCompleteness, statusClaims, checkClaims } from './lib/spec-gate.js';
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
-const DEFAULT_DIR = join(ROOT, '02-DOCS', 'wiki', 'sdd', 'specs');
+// The corpus of the project the gate is run FROM — not of the package that ships the script. Run as
+// `npx @ericrisco/rsc spec gate` in a user project, a package-relative default found nothing.
+function projectRoot() {
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    if (top) return top;
+  } catch { /* not a git project: look upward for 02-DOCS instead */ }
+  for (let dir = process.cwd(); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, '02-DOCS'))) return dir;
+    if (dirname(dir) === dir) return process.cwd();
+  }
+}
 
 function defaultTargets() {
+  const DEFAULT_DIR = join(projectRoot(), '02-DOCS', 'wiki', 'sdd', 'specs');
   try {
     return readdirSync(DEFAULT_DIR)
       .filter((f) => f.endsWith('.md') && !f.endsWith('.plan.md'))

package/skills/asdd/SKILL.md

@@ -28,7 +28,7 @@ This skill does **not** do a phase. It names the method, reads the register, pla
                  d verify findings      e mandatory controls
                  f fix (max 3 rounds)   g fix & record  ─or─  park ─► DECISION QUEUE ◄── HUMAN
  5. CLOSE ────► verify against main + rollback plan · closing review (whole branch vs spec) · explainer
-    SHIP ─────► tier 0-1: self-merge on green CI + empty queue  │  tier 2: ◄── HUMAN APPROVES
+    SHIP ─────► remote: PR (self-merge only tier 0-1 + green CI + no blocking entry)  │  no remote: park  ◄── HUMAN
     LEARN ────► finding outcomes · reverts → reviewer cases · repeated finding → rule
 ```
 
@@ -36,13 +36,15 @@ This skill does **not** do a phase. It names the method, reads the register, pla
 | --- | --- | --- |
 | **1 Base** | `../constitution/SKILL.md` (also drafts `REVIEW.md`), `../sdd-init/SKILL.md` | `constitution.md`, `REVIEW.md`, `config.yaml` |
 | **2 Spec** | `../specify/SKILL.md` → `../clarify/SKILL.md` | `specs/<slug>.md` |
-| **3 Plan** | `../plan/SKILL.md` → `../tasks/SKILL.md` → `../analyze/SKILL.md` | `plans/<slug>.md` |
+| **3 Plan** | `../plan/SKILL.md` → `../tasks/SKILL.md` → `../analyze/SKILL.md` | `plans/<slug>.md`, `analysis/<slug>.md` |
 | **4 Loop** | `../implement/SKILL.md`, calling `../verify/SKILL.md` and `../review/SKILL.md` per task | `progress/<slug>.md` (with `## Decision queue`), `decisions.md` |
-| **5 Close** | `../verify/SKILL.md` (closing mode), then `../review/SKILL.md` (closing review, on what will ship), `../ship/SKILL.md` | `verifications/<slug>-<date>.md`, the PR |
+| **5 Close** | `../verify/SKILL.md` (closing mode), then `../review/SKILL.md` (closing review, on what will ship), `../ship/SKILL.md` | `verifications/<slug>-<date>.md`, `reviews/<slug>.md`, the PR or parked branch |
 | on demand | `../debug/SKILL.md` · `../worktrees/SKILL.md` · `../parallel/SKILL.md` | — |
 
 **Where the human enters — three places only:** approving the spec, answering the decision queue, approving a tier-2 merge. Everything else runs.
 
+No ASDD phase edits the root `CLAUDE.md`: every artifact is indexed in `02-DOCS/wiki/index.md` (the Knowledge map). The root `CLAUDE.md` is owned by `harness` and is tier 2 in `rsc risk`.
+
 ### The spec proves itself
 
 Every spec answers four questions, and `spec:gate` refuses one dated 2026-11-03 or later without them: **what the user can do**, **what result they get** (against a reference the human approved — a screenshot, a sketch, an expected API response), **what it must respect** (prior decisions, specs and behaviour; read from the brain when the project has one, else `decisions.md`), **how it proves it** (how the check runs, what evidence remains — "yes, I tested it" is not evidence). Plus an explicit **out of scope**: what the agent might add "just in case".
@@ -57,14 +59,24 @@ Every spec answers four questions, and `spec:gate` refuses one dated 2026-11-03
 
 ### Park, don't block
 
-Tier 2, a contradiction with a recorded decision, a gap clarify could not close, or no convergence in 3 rounds: the task goes to the **decision queue** (`## Decision queue` in `progress/<slug>.md`) with its evidence, and the agent **continues with the independent tasks**. The run never waits at 2 a.m. for an answer.
+Tier 2, a contradiction with a recorded decision, a gap that would make the build unsafe, or no convergence in 3 rounds: the task goes to the **decision queue** (`## Decision queue` in `progress/<slug>.md`) with its evidence, and the agent **continues with the independent tasks**. The run never waits at 2 a.m. for an answer.
+
+Every entry carries a kind, one line each:
+
+```markdown
+- [blocking] Q3 — <what must be decided>, <evidence>, <task>
+- [review-after] Q4 — <assumption taken>, <where it is recorded>, <task>
+```
+
+- **`blocking`** — tier 2, a contradiction with a recorded decision, no convergence in 3 rounds, a hard failure. It stops a self-merge.
+- **`review-after`** — clarify's recorded assumptions, a spec reference the agent had to write itself, a provisional constitution ratification. It never stops a merge; it is listed in the PR body (or the parked summary) for the human.
 
 ## The invoke rule — route to the phase that fits
 
 > **The new-feature gate (hard).** The moment the user is thinking about a new feature or change — "add…", "build…", "it should also…", "quiero añadir…" — and the decisor chose this lane, it goes to `specify` first, *even if a stack skill also fired*. **No feature code is written — by any skill — until a spec AND a plan exist and are approved.** Small authorised changes go to `../ftd/SKILL.md`, which escalates here when `rsc risk` says tier 2 or the change contradicts a recorded decision.
 
-1. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`.
-2. **No constitution, or `status: draft`?** → `constitution` once (it also drafts `REVIEW.md`).
+1. **Empty repo (nothing to detect)?** → `constitution` first (it decides the stack), then `sdd-init`.
+2. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`. **No constitution, or `status: draft`?** → `constitution` once (it also drafts `REVIEW.md`).
 3. **Ambiguous / architectural / risky before a spec?** → optional proposal via `specify`.
 4. **Fuzzy idea, no spec?** → `specify`. **Spec with gaps?** → `clarify`.
 5. **Approved spec, no plan?** → `plan`, then `tasks`, then `analyze`.
@@ -78,9 +90,19 @@ Skip honestly: `constitution` runs once per project; `clarify` and `analyze` are
 
 ## Autopilot — one up-front yes
 
-The user says "take it all the way" once (or `sdd.autopilot: true` in `config.yaml`) and the chain runs end to end **without asking to continue between phases**, still writing every artifact. The up-front yes satisfies the new-feature gate.
+The user says "take it all the way" once (or `execution_mode: automatic` under `sdd:` in `config.yaml`, set by `sdd-init`) and the chain runs end to end **without asking to continue between phases**, still writing every artifact. The up-front yes satisfies the new-feature gate.
+
+Autopilot does not stop the run for questions — it **parks**: real ambiguity, tier 2, a contradiction with a recorded decision or a non-converging task go to the decision queue while independent work continues. It **stops** only for a hard failure nothing else can proceed past, and for destructive or irreversible actions.
+
+**In autopilot, per phase:**
+
+- `constitution` ratifies provisionally → `review-after` entry.
+- `specify` uses a checkable reference it wrote itself (expected output, sample response) → `review-after` entry.
+- `clarify` records its assumptions (`suposición tomada`) → `review-after` entries.
+- `implement` parks `blocking` items and continues with the independent tasks.
+- `ship` lands by the rule below.
 
-Autopilot does not stop the run for questions — it **parks**: real ambiguity, tier 2, a contradiction with a recorded decision or a non-converging task go to the decision queue while independent work continues. It **stops** only for a hard failure nothing else can proceed past, and for destructive or irreversible actions. Landing follows the risk: tier 0-1 with green CI and an empty queue may self-merge; tier 2 waits for the human.
+**Landing — there is always a legal path.** A remote exists → open a PR; self-merge only when `rsc risk` says tier 0-1, CI is green and no `blocking` entry is open; `review-after` entries go into the PR body. No remote → **park**: leave the branch committed, write the explainer, the open entries and the exact merge command for the human into `progress/<slug>.md`, and stop. Never merge locally around the branch guard: when `rsc main status` says `closed: true`, the guard denies it.
 
 Narrate in the `orient` voice: name each stage as it passes and show its artifact, one line each.
 
@@ -101,8 +123,10 @@ Each phase declares a tier — `heavy` (constitution, plan, analyze, review, deb
 ├── proposals/<slug>.md      ← optional pre-execution briefing
 ├── specs/<slug>.md          ← one spec per feature (four questions + out of scope)
 ├── plans/<slug>.md          ← plan + tasks
+├── analysis/<slug>.md       ← analyze's cross-artifact report
 ├── progress/<slug>.md       ← append-only loop ledger + ## Decision queue
 ├── verifications/<slug>-YYYY-MM-DD.md
+├── reviews/<slug>.md        ← closing review record
 ├── review-evals/<sha>.md    ← one case per revert that escaped review (`rsc review escapes`)
 ├── archive/<slug>/
 ├── sessions/<date>-<slug>.md
@@ -111,7 +135,7 @@ REVIEW.md                    ← project root: how this repo is judged
 .rsc/review-ledger.jsonl     ← findings, outcomes, rounds (tool-written)
 ```
 
-The directory keeps its `sdd/` name: existing projects keep working. Index it in `02-DOCS/wiki/index.md` under the `sdd/` topic; the harness keeps it honest.
+The directory keeps its `sdd/` name: existing projects keep working. Index it in `02-DOCS/wiki/index.md` under the `sdd/` topic — never in the root `CLAUDE.md`; the harness keeps it honest.
 
 ## Stack handoff and skill registry
 
@@ -126,7 +150,7 @@ Every phase ends with this block so the dispatcher can chain without interpretin
   "status": "complete|blocked|failed",
   "executive_summary": "one short paragraph",
   "artifact": "path/to/artifact-or-none",
-  "next_recommended": "sdd-init|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
+  "next_recommended": "sdd-init|constitution|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
   "risk": "low|medium|high",
   "model": { "tier": "heavy|balanced|light", "resolved": "model-id", "routing": "on|off" },
   "skill_resolution": { "used": [], "missing": [], "fallback": [], "compact_rules": [] },
@@ -152,7 +176,7 @@ A run stopped mid-flight writes `02-DOCS/wiki/sdd/sessions/<date>-<slug>.md` ins
 
 ## Start here
 
-- **New project** → `sdd-init`, `constitution`, then `specify`.
+- **New project** → `sdd-init`, `constitution`, then `specify`. **Empty repo** → `constitution` first (it decides the stack), then `sdd-init`.
 - **Existing project, new feature** → `specify` (proposal first if risky or architectural).
 - **Small authorised change** → `../ftd/SKILL.md`.
 

package/skills/asdd/evals/cases.yaml

@@ -69,7 +69,7 @@ capability:
       - "Includes sdd-init as step zero when 02-DOCS/wiki/sdd/config.yaml is missing, and explains that it detects test commands, strict TDD and .rsc/skill-registry.json"
       - "Applies the invoke rule: a fuzzy idea with no spec on disk routes to specify (and notes constitution runs once per project if not yet present)"
       - "Does NOT itself write the spec or start coding — it hands off to the specify phase skill (../specify/SKILL.md)"
-      - "Notes that artifacts will be written under 02-DOCS/wiki/sdd/ (specs/, plans/, decisions.md) and indexed in the root CLAUDE.md Knowledge map"
+      - "Notes that artifacts will be written under 02-DOCS/wiki/sdd/ (specs/, plans/, decisions.md) and indexed in 02-DOCS/wiki/index.md (never the root CLAUDE.md)"
       - "Mentions standard result envelopes with status, artifact, next_recommended, risk, skill_resolution and evidence"
       - "Defers concrete stack tooling (test runner, build, framework idioms) to the relevant stack skill rather than prescribing it here"
 

package/skills/clarify/SKILL.md

@@ -86,6 +86,17 @@ Run in order. The discipline is: find many candidate gaps, keep only the ones th
 
    Then re-read the spec once more: did resolving one gap open a new one? If so, one more short loop. Otherwise, hand it to the human for approval.
 
+## In autopilot — nobody to ask
+
+Under an up-front autopilot yes there is no one to answer, so step 4 changes: **every question that
+would have been asked is recorded instead** as a **suposición tomada** in the spec (your recommended
+answer, its basis, the spec line it came from) and mirrored as a `review-after` entry in the
+**decision queue** (`## Decision queue` in `02-DOCS/wiki/sdd/progress/<slug>.md`; create it if
+absent). The run continues; the human reviews these afterwards and nothing waits on them. Only a gap
+that would make the build **unsafe**, or whose answer would **contradict a recorded decision**, is a
+`blocking` entry — and only `blocking` stops the branch from merging itself. Never ask and wait in
+autopilot; never stay silent about what you assumed.
+
 ## Late gaps — found during implementation
 
 A gap nobody saw until `implement` is running does not stop the run. It goes to the **decision queue** of `implement`'s per-task loop (`../implement/SKILL.md`): the task that needs the answer is parked, independent tasks continue, and when the human answers, the answer is written back into this spec (and its `## Clarifications` log) so the spec stays the contract.
@@ -121,7 +132,7 @@ After baking back, the spec line becomes a bounded, testable behaviour ("rejects
 
 ## Exit gate
 
-The gate is passed when the spec, constitution, prior decisions and profile were all read (settled questions cited, not re-asked); **every typed point in the handoff has its declared outcome** (asked / validated / left deferred / graduated), with nothing silently dropped; every gap checklist row was walked; only questions that change what gets built were asked, one at a time with a recommendation; every other call is a **suposición tomada** in the spec; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under out of scope; and the final re-read opened no new gap.
+The gate is passed when the spec, constitution, prior decisions and profile were all read (settled questions cited, not re-asked); **every typed point in the handoff has its declared outcome** (asked / validated / left deferred / graduated), with nothing silently dropped; every gap checklist row was walked; only questions that change what gets built were asked, one at a time with a recommendation (in autopilot: recorded as assumptions with their `review-after` / `blocking` queue entries); every other call is a **suposición tomada** in the spec; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under out of scope; and the final re-read opened no new gap.
 
 ## Result envelope
 

package/skills/constitution/SKILL.md

@@ -31,7 +31,7 @@ Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and use its
 
 The harness may already hold real conventions under `02-DOCS/wiki/stack/*` (e.g. `nextjs.md`, `fastapi.md`, `postgresdb.md`). The constitution does not copy them — it **ratifies the principle and links the detail**. Run this reconciliation pass first:
 
-1. **Read the Knowledge map** — the full index lives in `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it). List every `02-DOCS/wiki/stack/*` article that exists.
+1. **Read the Knowledge map** — `02-DOCS/wiki/index.md`. List every `02-DOCS/wiki/stack/*` article that exists.
 2. **Read each stack article.** Pull out anything already phrased as a rule (a version pin, a lint config, a test threshold, a naming convention).
 3. **For each existing rule, decide:** is it a *project-wide non-negotiable* (→ ratify it as a principle, linking the stack article for detail) or a *local mechanic* (→ leave it in the stack wiki, do not lift it into the constitution)?
 4. **Contradictions are findings, not fixes.** If two stack articles disagree, or a stack article contradicts what the user states now, surface it and let the user resolve — never silently pick a winner.
@@ -72,7 +72,7 @@ For any significant either/or (e.g. "strict types or gradual?", "squash or merge
 
 Two principles are inherited from the rsc ecosystem and appear in every constitution unless the user explicitly overrides them:
 
-- **Git authorship is the human's.** Commits and PRs are authored by the human (Eric, or whoever owns the repo). No `Co-Authored-By` an AI, no "generated with" footer. Enforced at the `ship` phase.
+- **Git authorship is the human's.** Commits and PRs are authored by the responsible person — the configured git user. No `Co-Authored-By` an AI, no "generated with" footer. Enforced at the `ship` phase.
 - **Decisions are logged.** Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (or the harness `decisions.md`) with date, options considered, and the why. The constitution itself is the highest-order decision record.
 
 ## Drafting the constitution
@@ -107,6 +107,7 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
 - **Semantic-ish versioning.** MAJOR when a principle is removed or reversed (breaks existing work); MINOR when a principle is added or materially tightened; PATCH for wording/clarity with no behavior change.
 - **Amendments are append-only in the log.** Never silently edit a ratified principle — strike it (mark superseded) and add the new one, bump the version, and record date + why in the amendment log.
 - **Ratification.** A new or amended constitution is shown to the user and ratified explicitly before it takes effect. "Ratify" is an explicit yes on the shown draft; walk each change only if the user asks.
+- **In autopilot** (`execution_mode: automatic`, or an up-front "take it all the way"), there is no one to ask: ratify **provisionally** (`status: provisional` in the frontmatter), log it in `decisions.md`, and add a `review-after` entry to the decision queue (`../asdd/SKILL.md`) so the human confirms it later. It does not block the run or a self-merge.
 - **Downstream notice.** When a principle changes mid-project, flag that existing specs/plans may now be inconsistent — `analyze` will catch the drift on the next run.
 
 ## Anti-patterns
@@ -120,7 +121,7 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
 | "I'll rewrite the existing constitution to match what they said today." | Amend, don't overwrite. Strike + add + bump version + log the why. |
 | "No profile yet, I'll assume they're technical." | Use analogies; ask once "technical or with analogies?" or send them to `init`. |
 | "I'll add a Co-Authored-By so the commit credits the assist." | No. Git authorship is the human's — it's a fixed principle, enforced at `ship`. |
-| "I'll ratify it myself since it's obvious." | The user ratifies. Show the draft, get the explicit yes, then it takes effect. |
+| "I'll ratify it myself since it's obvious." | The user ratifies. Show the draft, get the explicit yes, then it takes effect. Only autopilot ratifies provisionally, as a `review-after` queue entry. |
 
 ## Checklist before handing off
 
@@ -131,18 +132,18 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
 - [ ] Fixed principles included: human git authorship + decisions logged.
 - [ ] `02-DOCS/wiki/sdd/constitution.md` written with version + ratified date + amendment log.
 - [ ] `REVIEW.md` drafted at the project root; always-human paths mirrored into `.rsc/sello-config.json` `risk.raise` (or the user told why they are not).
-- [ ] Root `CLAUDE.md` `## Knowledge map` pointer has the read-first row for the constitution.
-- [ ] The constitution was shown to the user and explicitly ratified.
+- [ ] The constitution is indexed in `02-DOCS/wiki/index.md` (the Knowledge map) under the `sdd/` topic.
+- [ ] The constitution was shown to the user and explicitly ratified — or, in autopilot, ratified provisionally with a `review-after` queue entry.
 
-## Project grounding (02-DOCS + CLAUDE.md)
+## Project grounding (02-DOCS)
 
-This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`. It is a **read-first** pointer entry, so its row stays in the short `## Knowledge map` pointer in the root `CLAUDE.md` (create `CLAUDE.md` if absent, additive only — never delete existing sections) — unlike other sdd artifacts, which are indexed in `02-DOCS/wiki/index.md` (the full Knowledge map that root `CLAUDE.md` points to). Add this row to the root pointer if it is not already present:
+This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map) like every other sdd artifact:
 
 ```markdown
 | Project constitution (SDD non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
 ```
 
-Every later rsc-sdd phase reads this file before it works. The harness maintains and improves the article over the life of the project; this skill is the place that ratifies and amends it.
+Never edit the root `CLAUDE.md` from here: it is owned by `harness` and is tier 2 in `rsc risk`. Every later ASDD phase reads the constitution before it works. The harness maintains and improves the article over the life of the project; this skill is the place that ratifies and amends it.
 
 ## Result envelope
 

package/skills/constitution/evals/cases.yaml

@@ -68,5 +68,5 @@ capability:
       - "Every principle is numbered, imperative, and testable (a number, command, or named artifact), not an aspiration like 'write clean code'."
       - "Includes the two fixed principles: git authorship is the human's (no Co-Authored-By AI / generated-with footer, enforced at ship) and significant decisions are logged."
       - "Produces a Definition of Done checklist (the merge bar verify runs against) covering format/lint, types, tests/coverage, conventions, branch+PR+authorship, security, and decisions logged."
-      - "Writes 02-DOCS/wiki/sdd/constitution.md with a version (v1.0.0), ratified date, and an append-only amendment log; adds the Knowledge-map row to root CLAUDE.md additively (never deleting sections)."
+      - "Writes 02-DOCS/wiki/sdd/constitution.md with a version (v1.0.0), ratified date, and an append-only amendment log; indexes it in 02-DOCS/wiki/index.md and never edits the root CLAUDE.md."
       - "Shows the draft and gets explicit ratification from the user before it takes effect, and ends by pointing to the specify phase as next in the chain."

package/skills/debug/SKILL.md

@@ -124,8 +124,8 @@ first — isolate which side actually fails before you open either stack's debug
 
 When the cause is non-obvious — a race, an order dependency, an environment-only failure, a
 regression a reviewer would otherwise have to rediscover — append a short entry to
-`02-DOCS/wiki/sdd/decisions.md` (append-only; create it if absent and add a row to the root
-`CLAUDE.md` `## Knowledge map` under the `sdd/` topic). One entry:
+`02-DOCS/wiki/sdd/decisions.md` (append-only; create it if absent and index it in
+`02-DOCS/wiki/index.md` under the `sdd/` topic — never the root `CLAUDE.md`). One entry:
 
 ```text
 ## YYYY-MM-DD — bug: <symptom in five words>  (feature: <slug>)

package/skills/implement/SKILL.md

@@ -72,6 +72,10 @@ COMMIT   → commit this task as one logical unit (authorship = Eric; see ship f
 The order is load-bearing. **Red before green** is not a suggestion — a test you write *after* the
 code tells you nothing about whether it can fail. **Refactor only on green** keeps every cleanup
 reversible against a passing bar. Self-check means evidence: the test output you saw, not "I tested it".
+**ESM (and any language where a missing module fails at load):** a test importing a module that
+does not exist dies on the import, not on the assertion — that red proves nothing. Create the module
+first with a stub export (`export function total() { return 0 }`), then the red must fail on the
+assertion.
 
 ### Four things you may never do to reach green
 
@@ -104,6 +108,9 @@ task's risk forecast. **The agent never picks or argues down its own tier.**
 
 ### c) Review scaled by tier — fresh context
 
+Tier 1 or 2: first call `npx @ericrisco/rsc review ledger round <slug>/<task>` — before **every**
+review of the task, this first one included. Round 1 is the task's first review, not its first fix.
+
 | Tier | Review |
 | --- | --- |
 | 0 | none — the controls (e) still run |
@@ -120,10 +127,13 @@ finding.
 ### d) Consolidate, verify, record
 
 Exactly as `../review/SKILL.md` → *Consolidate, then verify*: `npx @ericrisco/rsc review consolidate
-<reports…>`, then `finding-verifier` on every finding it marks `verify` (tier 1: on every blocker).
-Then `npx @ericrisco/rsc review ledger record <findings.json>`. A finding the ledger already holds
-comes back `repeat`: **never raise it again**. When a finding closes, record its outcome:
-`review ledger outcome <id> fixed|false|intentional|irrelevant`.
+<reports…>` (tier 1 too: it applies the downgrade), then `finding-verifier` on every finding it
+marks `verify` — every blocker and should-fix. Findings use the JSON shape in
+`references/per-task-review.md`. Then `npx @ericrisco/rsc review ledger record <findings.json>`. A
+finding the ledger already holds comes back `repeat`: **never raise it again**. When a finding
+closes, record its outcome: `review ledger outcome <id> fixed|false|intentional|irrelevant|parked`
+(`parked` = its task went to the decision queue). The ledger is local (`.rsc/`, not committed);
+what lasts is the review-evals cases and rules `review` writes from it.
 
 ### e) Mandatory controls — every tier
 
@@ -140,8 +150,8 @@ A control that did not run is reported as **not run**, never as passed — and t
 
 ### f) Fix loop — at most 3 rounds
 
-Each round opens with `npx @ericrisco/rsc review ledger round <slug>/<task>`. It exits non-zero on the 4th
-round with the action to take; obey it (step g).
+Each re-review opens with another `review ledger round <slug>/<task>` (step c). It exits non-zero
+on the 4th round with the action to take; obey it (step g).
 
 - **From round 2, re-review only the new diff** (BASE = the previous round's head).
 - **Fix the bug class, not the line**: name the class and fix every instance in the task's scope.
@@ -153,12 +163,15 @@ round with the action to take; obey it (step g).
 | Situation | Action |
 | --- | --- |
 | Trivial, or no business weight | Fix it and record it in `decisions.md` with the task id |
-| Tier 2, contradicts a decision in `decisions.md`, or no convergence in 3 rounds | Park the task in the **decision queue** and continue with independent tasks |
+| Tier 2, contradicts a decision in `decisions.md`, or no convergence in 3 rounds | Park the task in the **decision queue** (`blocking`) and continue with independent tasks |
 
 The **decision queue** is a `## Decision queue` section in `02-DOCS/wiki/sdd/progress/<slug>.md`, one
-entry per parked task: task id, tier, the question, the options, your recommendation, the evidence
-path. Tasks that depend on a parked task wait; the rest continue. Only a human empties the queue — an
-agent's approval never counts as human.
+entry per item: its kind, task id, tier, the question, the options, your recommendation, the
+evidence path. **Kind is `blocking` or `review-after`.** Tier 2, a contradiction with a recorded
+decision and no convergence are `blocking`: the task is parked, its dependents wait, and the branch
+cannot merge itself. An assumption you took so work could continue is `review-after`: nothing waits
+and it does not stop a self-merge — the human reads it afterwards. Only a human closes an entry —
+an agent's approval never counts as human.
 
 Then append the progress entry and show the checkpoint (below).
 
@@ -167,18 +180,10 @@ Then append the progress entry and show the checkpoint (below).
 
 ## Delegating the test tooling (do not reinvent it)
 
-Write the *intent* of the test here; get the *mechanics* from the stack skill. The discipline is
-yours; the fixtures, runners and idioms are theirs.
-
-| Stack | Where the test mechanics live | What you delegate |
-| --- | --- | --- |
-| FastAPI / async Python | `../fastapi/references/testing.md` | `ASGITransport` in-process client, `dependency_overrides`, transactional rollback fixture, `pytest-asyncio` |
-| Go services | `../go/references/testing.md` | table-driven subtests, `httptest`, interface fakes, golden files, `errors.Is` checks |
-| Next.js / React | `../nextjs/references/testing.md` | Vitest + Testing Library for units, Playwright for flows, server-action / RSC testing |
-| Flutter | `../flutter/references/testing.md` | `flutter test` widget tests, `pump`/`pumpAndSettle`, golden tests, mocked repositories |
-
-If the feature spans two stacks (a Next.js front-end calling a FastAPI back-end), each task names its
-stack and pulls that stack's testing reference — you do not mix idioms inside one task.
+Write the *intent* of the test here; get the *mechanics* (fixtures, runners, idioms) from the stack
+skill's testing reference: `../fastapi/references/testing.md`, `../go/references/testing.md`,
+`../nextjs/references/testing.md`, `../flutter/references/testing.md`. A feature spanning two stacks
+names the stack per task and never mixes idioms inside one task.
 
 ## Skill digestion and resolution
 
@@ -252,9 +257,13 @@ each dispatch self-sufficient and make its return machine-checkable:
 
 - **Carry the task, not your context.** Hand the worker its task brief, its **Interfaces** block
   (`Consumes`/`Produces`, exact signatures — from `tasks`), and the plan's **§0 Global Constraints**.
-  Anything not in those three is invisible to it. Prefer **file paths over pasted text** (use
-  `scripts/task-brief` and `scripts/review-package`, below) — pasted briefs and diffs stay resident
-  in your context and get re-read every turn.
+  Anything not in those three is invisible to it. Prefer **file paths over pasted text** —
+  `scripts/task-brief <plan> <N>` (N as `1`, `001` or `T001`; reads the `tasks` table row plus any
+  `### T1` detail block) and `scripts/review-package` — pasted briefs and diffs stay resident in
+  your context and get re-read every turn.
+- **Native isolation leaves worktrees behind.** A subagent dispatched with worktree isolation
+  works in `.claude/worktrees/`. `rsc risk` ignores that folder, but after you cherry-pick the
+  worker's commits, remove it (`git worktree remove <path>`).
 - **Model is REQUIRED on every dispatch.** Always set the subagent's model explicitly (the
   `developer` agent already pins balanced). An omitted model silently inherits the session's model —
   usually the most expensive one — which is the quiet way fan-out cost explodes.
@@ -271,10 +280,8 @@ each dispatch self-sufficient and make its return machine-checkable:
 
 ## Model tier — `balanced` (opt-in routing)
 
-Default tier **`balanced`** — the bulk of TDD execution. Routing is **off** unless `models.enabled:
-true` in `02-DOCS/wiki/sdd/config.yaml`; when on, resolve and apply it per
-`../asdd/references/model-routing.md` (fan-out on `balanced`, a hard sub-problem escalated to
-`heavy`). Routing off → honor the session model silently.
+Default **`balanced`**. Routing is **off** unless `models.enabled: true` in `config.yaml`; when on,
+apply `../asdd/references/model-routing.md` (hard sub-problem → `heavy`); off → session model.
 
 ## Checkpoints — what to say
 
@@ -327,13 +334,12 @@ outranks the plan, and the plan outranks your in-the-moment preference.
 
 ## Red flags — stop and re-route
 
-- **No plan or no task list** → you cannot implement intent you haven't planned. Route to `plan` /
-  `tasks`.
+- **No plan or no task list** → you cannot implement intent you haven't planned: `plan` / `tasks`.
 - **Unresolved `analyze` findings** (contradiction between constitution ↔ spec ↔ plan ↔ tasks) →
   resolve them before any code; they will only get more expensive after the diff exists.
 - **A task forces a constitution violation** → surface it, stop, kick it back to `analyze`/`plan`.
 - **You're on the default branch** → stop before the first commit and ask: branch or default branch (`worktrees`).
-- **A test won't go red** (wrong reason — import error, syntax) → fix the test before trusting it.
+- **A test won't go red** for the right reason (import error, syntax) → stub the module, fix the test.
 - **The combined suite is red after a parallel merge** → do not checkpoint as done; debug with
   `debug` before continuing.
 - **You're tempted to disable/skip a failing test to "make progress"** → that's the bug talking.
@@ -344,11 +350,11 @@ outranks the plan, and the plan outranks your in-the-moment preference.
 ```text
 - [ ] a) RED for the right reason → GREEN → REFACTOR; committed as one unit (authorship = Eric)
 - [ ] b) `rsc risk` on the task diff; tier recorded
-- [ ] c) review by tier, fresh context, spec + diff + surrounding code, no pre-judging
-- [ ] d) `review consolidate` + `finding-verifier`; `review ledger record`
+- [ ] c) `review ledger round <slug>/<task>` before each review (≤ 3); by tier, fresh context, no pre-judging
+- [ ] d) `review consolidate` + `finding-verifier`; `review ledger record`; outcomes closed
 - [ ] e) tests, build, security, traceability — each passed or **not run**
-- [ ] f) `review ledger round <slug>/<task>` each round; ≤ 3; class fixed, no repeats
-- [ ] g) fixed + logged in decisions.md, or parked in the decision queue
+- [ ] f) re-review only the new diff; class fixed, no repeats
+- [ ] g) fixed + logged in decisions.md, or in the decision queue (`blocking` / `review-after`)
 - [ ] Progress entry appended; skill resolution recorded; checkpoint shown
 ```
 
@@ -375,12 +381,9 @@ End every implementation checkpoint or completed batch with:
 
 ## What this skill is NOT
 
-- **Not the closing gate.** The per-task controls prove each task; the whole branch against main,
-  the rollback plan and the human explanation are stage 5 (`verify` closing mode, `review`, `ship`).
-- **Not spec or plan writing.** If you find the plan is wrong mid-build, stop and amend it via
-  `plan`; don't silently re-architect inside a commit.
-- **Not the deep-debug protocol.** When a test fails for a reason you don't understand, switch to
-  `debug` (reproduce → isolate → hypothesize → fix → verify) instead of guessing.
+- **Not the closing gate** — whole branch, rollback plan and explanation are stage 5 (`verify`, `review`, `ship`).
+- **Not plan writing** — a plan found wrong mid-build is amended via `plan`, never inside a commit.
+- **Not deep debugging** — a failure you don't understand goes to `debug`, not to guessing.
 
 ## Where you are in ASDD
 
@@ -393,4 +396,3 @@ branch. Parked tasks travel in the decision queue for the human.
 ## Orientación (siempre)
 
 Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
-

package/skills/implement/references/per-task-review.md

@@ -26,8 +26,17 @@ words at dispatch; keep the contract identical.
 Every finding uses `review`'s format and severities (`blocker` / `should-fix` / `nit`, with
 `file:line`, why, repro, fix) and names its **bug class**, so the fix covers every instance. The
 report ends with a ` ```json findings ` block — the input to `review consolidate` and
-`review ledger record` — and one line: `VERDICT: pass` or `VERDICT: changes-needed (<counts>)`.
-Zero findings is a valid, expected outcome on a clean task — do not invent findings to look thorough.
+`review ledger record` — holding an array of objects in exactly this shape:
+
+```json
+{"severity":"blocker|should-fix|nit|question","file":"path","line":N,"claim":"…","failure_scenario":"concrete input → wrong result","evidence":"quoted code","class":"bug class"}
+```
+
+A `blocker` or `should-fix` without `file`+`line` or without `failure_scenario` is downgraded to
+`question` by `review consolidate`; then every remaining blocker and should-fix goes to
+`finding-verifier`. Close the report with one line: `VERDICT: pass` or
+`VERDICT: changes-needed (<counts>)`. Zero findings is a valid, expected outcome on a clean task —
+do not invent findings to look thorough (an empty array is fine).
 
 ## Anti-pre-judging (the reviewer is told this too)