@ericrisco/rsc 3.7.5 → 4.0.1

package/scripts/lib/risk.js

@@ -0,0 +1,68 @@
+// `rsc risk` — how much review and whose approval a change needs, decided by WHAT it touches.
+//
+// ASDD reviews inside every task, so the depth of that review cannot be the agent's own call: the
+// change sets the tier, never the author (Anthropic, "How the Claude Code team does code review").
+// The table is the sello's (targets/sello.mjs), reused as is, and it works with the sello off.
+// Spec: 02-DOCS/wiki/sdd/specs/asdd-v4.md.
+
+import { spawnSync } from 'node:child_process';
+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 });
+  return r.status === 0 ? r.stdout : null;
+}
+const nul = (out) => (out || '').split('\0').filter(Boolean);
+
+// Every path that differs from the base (committed, staged, unstaged or untracked). The base is the
+// merge-base with `--base`, or with the trunk when none is given.
+export function changedPaths(root, base = null) {
+  const cfg = readEffectiveConfig(root);
+  const ref = base || trunkRef(root, cfg);
+  if (!ref) return { ok: false, message: 'rsc: no base to compare against. Pass --base <ref> or the paths themselves: npx @ericrisco/rsc risk <path…>' };
+  const head = git(root, ['rev-parse', 'HEAD']);
+  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.
+  // 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
+  // already committed would read as no change at all: tier 0, no reviewer, no escalation. With
+  // nothing uncommitted, the last commit is the change being asked about.
+  if (!base && mb === head.trim() && !names.size && git(root, ['rev-parse', '--verify', '--quiet', 'HEAD~1']) !== null) {
+    names = diff('HEAD~1');
+    shown = 'HEAD~1 (on the trunk: the last commit)';
+  }
+  return { ok: true, base: shown, paths: [...names].sort() };
+}
+
+export function assess(paths, cfg = null) {
+  const { tier, classes, configError } = classifyRisk(paths, cfg);
+  return {
+    tier,
+    classes: [...new Set(Object.values(classes))].sort(),
+    reviewers: lensesRequired(tier, cfg),
+    humanApproval: tier >= 2,
+    paths: classes,
+    ...(configError ? { configError } : {}),
+  };
+}
+
+export function render(r) {
+  const top = Object.entries(r.paths).filter(([, c]) => r.tier === 0 || c !== 'docs');
+  return [
+    `tier ${r.tier}`,
+    `classes: ${r.classes.join(', ') || 'none'}`,
+    `reviewers: ${r.reviewers}`,
+    `human approval: ${r.humanApproval ? 'required' : 'not required'}`,
+    ...(r.base ? [`base: ${r.base}`] : []),
+    ...(r.configError ? [`config ignored: ${r.configError}`] : []),
+    ...top.slice(0, 20).map(([p, c]) => `  ${c.padEnd(10)} ${p}`),
+    ...(top.length > 20 ? [`  … ${top.length - 20} more`] : []),
+  ].join('\n');
+}

package/scripts/lib/spec-gate.js

@@ -18,6 +18,10 @@ import { parseFrontmatter } from './frontmatter.js';
 // would be exactly the parallel accounting P3 forbids.
 export const NEW_FAMILIES_SINCE = '2026-09-06';
 
+// ASDD (4.0) makes a spec prove itself: four questions a long autonomous run is checked against.
+// Same date rule as above, for the same reason — the corpus before it cannot answer them honestly.
+export const ASDD_FAMILIES_SINCE = '2026-11-03';
+
 // The four states a point can be in. Order is the table's order in the skill body.
 export const OPEN_POINT_TYPES = [
   'pregunta abierta', // formulable now, unanswered → clarify asks it
@@ -32,7 +36,7 @@ export const OPEN_POINT_TYPES = [
 const FAMILIES = {
   problem: { prefixes: ['problema & por que', 'problema y por que', 'problem & why'] },
   goals: { prefixes: ['objetivos', 'goals'] },
-  nongoals: { prefixes: ['no-objetivos', 'no objetivos', 'non-goals'] },
+  nongoals: { prefixes: ['no-objetivos', 'no objetivos', 'non-goals', 'fuera de alcance', 'out of scope'] },
   users: { prefixes: ['usuarios & contexto', 'usuarios y contexto', 'users & context'] },
   behaviour: { prefixes: ['comportamiento', 'behaviour', 'behavior'] },
   acceptance: { prefixes: ['criterios de aceptacion', 'acceptance criteria'] },
@@ -53,6 +57,10 @@ const FAMILIES = {
     prefixes: ['la alternativa mas barata', 'alternativa mas barata', 'cheapest alternative', 'the cheapest alternative'],
     since: NEW_FAMILIES_SINCE,
   },
+  can: { prefixes: ['que podra hacer el usuario', 'what the user can do'], since: ASDD_FAMILIES_SINCE },
+  result: { prefixes: ['que resultado obtiene', 'what result they get'], since: ASDD_FAMILIES_SINCE },
+  respect: { prefixes: ['que debe respetar', 'what it must respect'], since: ASDD_FAMILIES_SINCE },
+  proof: { prefixes: ['como lo demuestra', 'how it proves it'], since: ASDD_FAMILIES_SINCE },
 };
 
 const UNCHECKED = [
@@ -66,6 +74,7 @@ const UNCHECKED = [
   // Sin esta línea, el verde sería más estrecho que la regla que aparenta imponer — que es la
   // definición de puerta decorativa, sólo que por omisión en vez de por ausencia.
   `las specs anteriores a ${NEW_FAMILIES_SINCE} — quedan exentas de "qué pasa si no lo construimos" y de "la alternativa más barata", que no pueden rellenarse a posteriori`,
+  `las specs anteriores a ${ASDD_FAMILIES_SINCE} — quedan exentas de las cuatro preguntas de ASDD (qué podrá hacer el usuario, qué resultado obtiene, qué debe respetar, cómo lo demuestra)`,
 ];
 
 function fold(s) {

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> | review consolidate [reports…] | 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', '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++) {
@@ -509,7 +509,7 @@ async function selectAgents() {
 // the assistant (with the user present), never blindly from this CLI.
 function printNextSteps(targets, ids) {
   const hasHarness = ids.includes('harness');
-  const hasSdd = ids.includes('sdd') || ids.includes('sdd-init');
+  const hasSdd = ids.includes('asdd') || ids.includes('sdd-init');
   const label = (id) => TARGETS.find((t) => t.id === id)?.label || id;
   const openLine = `Open this project in: ${targets.map((t) => `**${label(t)}**`).join(' · ')}`;
 
@@ -667,7 +667,7 @@ async function wizard(flagTargets, declaredTargets = []) {
       // First, because it is what someone who already has a harness came here for nine times in ten.
       ...(declared ? [{ key: 'update', label: `Update this project — keeps its ${declared.skills.length} skills, refreshes hooks and content` }] : []),
       { key: 'base', label: `Base install — the essentials (${baseIds.length} skills)` },
-      { key: 'sdd', label: 'Base + Spec-Driven Development — the specify → plan → implement → ship flow' },
+      { key: 'asdd', label: 'Base + Agent Spec-Driven Development (ASDD) — spec → plan → review-in-the-loop → ship' },
       { key: 'manual', label: 'Pick skills by hand, by area' },
     ]);
     if (choice === null) { say('\nOK — nothing installed. Anytime: npx @ericrisco/rsc'); return; }
@@ -675,7 +675,7 @@ async function wizard(flagTargets, declaredTargets = []) {
 
     let ids;
     if (choice === 'base') ids = baseIds;
-    else if (choice === 'sdd') ids = skillsForProfile(m, 'core');
+    else if (choice === 'asdd') ids = skillsForProfile(m, 'core');
     else if (choice === 'manual') {
       const picked = await manualSelect();
       if (picked === null) continue;          // backed out → re-show this menu
@@ -1232,11 +1232,109 @@ 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.
+      const K = await import('./lib/risk.js');
+      const S = await import('../targets/sello.mjs');
+      const root = S.resolveRoot(process.cwd());
+      const base = flag('base');
+      if (base === true) { say('Use: npx @ericrisco/rsc risk [--base <ref>] [paths…] [--json]'); process.exitCode = 1; return; }
+      const rest = argv.slice(1);
+      // Values of value-taking flags are not paths (`--target` is global). Paths given from a
+      // subdirectory are resolved against the repository root, or the table would never match them.
+      const VALUED = new Set(['--base', '--target']);
+      const { resolve: res, relative: rel } = await import('node:path');
+      const given = rest.filter((a, i) => !a.startsWith('--') && !VALUED.has(rest[i - 1]))
+        .map((p) => rel(root, res(process.cwd(), p)).split('\\').join('/'));
+      let paths = given;
+      let against = null;
+      if (!given.length) {
+        const c = K.changedPaths(root, base || null);
+        if (!c.ok) { say(c.message); process.exitCode = 1; return; }
+        paths = c.paths;
+        against = c.base;
+      }
+      const r = { ...K.assess(paths, S.readEffectiveConfig(root)), ...(against ? { base: against } : {}) };
+      say(argv.includes('--json') ? JSON.stringify(r, null, 2) : K.render(r));
+      return;
+    }
     case 'review': {
       // `review consolidate` — the deterministic half of the refuter panel (P1): the three lenses
       // often report one defect three ways, so grouping happens here, by location and evidence, and
       // only the unique serious findings go on to `finding-verifier`, which is judgement.
-      const USE = 'Use: npx @ericrisco/rsc review consolidate [report.md|findings.json ...] [--json] [--window <lines>]\n  Without files it reads stdin. Each lens report carries its findings in ```json findings blocks.';
+      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|parked> | round <slug>/<task> | stats [--json]',
+        '     npx @ericrisco/rsc review escapes [--since <ref>] [--json]',
+      ].join('\n');
+      if (argv[1] === 'ledger' || argv[1] === 'escapes') {
+        // ASDD's fix loop and the reviewer's learning, token-free (P1): rounds capped, repeats caught,
+        // outcomes counted, reverts listed as the cases the reviewer should be scored against.
+        const L = await import('./lib/review-ledger.js');
+        const { resolveRoot } = await import('../targets/sello.mjs');
+        const root = resolveRoot(process.cwd());
+        const str = (name) => { const v = flag(name); return typeof v === 'string' ? v : undefined; };
+        const json = argv.includes('--json');
+        const fail = (msg) => { say(msg); process.exitCode = 1; };
+        if (argv[1] === 'escapes') {
+          const res = L.escapes(root, { since: str('since') || '' });
+          if (!res.ok) return fail(res.message);
+          say(json ? JSON.stringify(res, null, 2) : L.renderEscapes(res));
+          return;
+        }
+        const [, , sub, a, b] = argv;
+        if (sub === 'record') {
+          const { readFileSync } = await import('node:fs');
+          const R = await import('./lib/review-findings.js');
+          const args = argv.slice(3);
+          const file = args.find((x, i) => !x.startsWith('--') && args[i - 1] !== '--task');
+          let raw;
+          try { raw = file ? readFileSync(file, 'utf8') : readFileSync(0, 'utf8'); }
+          catch (e) { return fail(`rsc: cannot read ${e.path || 'stdin'} (${e.code || e.message}).\n${USE}`); }
+          let list;
+          try { const v = JSON.parse(raw); list = Array.isArray(v) ? v : (Array.isArray(v?.findings) ? v.findings : [v]); }
+          catch { const p = R.parseFindings(raw, file || 'stdin'); if (p.errors.length) return fail(p.errors.join('\n')); list = p.findings; }
+          const out = L.record(root, list, { task: str('task') || '' });
+          if (json) say(JSON.stringify(out, null, 2));
+          else say(out.map((f) => `${f.id}  ${f.status === 'repeat' ? `repeat of ${f.repeatOf} — do not raise it again` : 'new'}  ${f.file || '(no file)'}  ${f.claim}`).join('\n') || 'nothing to record');
+          return;
+        }
+        if (sub === 'outcome') {
+          if (!a || !b) return fail(USE);
+          const r = L.outcome(root, a, b);
+          if (!r.ok) return fail(r.message);
+          say(r.message);
+          return;
+        }
+        if (sub === 'round') {
+          if (!a) return fail(USE);
+          const r = L.round(root, a);
+          say(r.message);
+          if (!r.ok) process.exitCode = 1;
+          return;
+        }
+        if (sub === 'stats') {
+          const s = L.stats(root);
+          say(json ? JSON.stringify(s, null, 2) : L.renderStats(s));
+          return;
+        }
+        return fail(USE);
+      }
       if (argv[1] !== 'consolidate') { say(USE); if (argv[1]) process.exitCode = 1; return; }
       const { readFileSync } = await import('node:fs');
       const R = await import('./lib/review-findings.js');

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/analyze/SKILL.md

@@ -11,11 +11,11 @@ origin: risco
 
 You have a **constitution**, a **spec**, a **plan** and a **task list**. Four artifacts written at four different moments, by a mind that drifted a little each time. `analyze` reads all four *against each other* and surfaces where they disagree. It is the cheapest place in the whole chain to catch a problem — a contradiction found here costs a sentence; the same contradiction found mid-implement costs a rewrite.
 
-Sixth phase of the rsc-sdd chain (`constitution → specify → clarify → plan → tasks → analyze → implement`); the method itself lives in `../sdd/SKILL.md`. It is a **gate, not a worker**: it produces a report and stops. The user reads the findings and decides what to fix, and which phase to send each fix back to.
+Sixth phase of the rsc-sdd chain (`constitution → specify → clarify → plan → tasks → analyze → implement`); the method itself lives in `../asdd/SKILL.md`. It is a **gate, not a worker**: it produces a report and stops. The user reads the findings and decides what to fix, and which phase to send each fix back to.
 
 **Report only. Resolve nothing.** Never edit the constitution, spec, plan or tasks; never open a code file to "just fix it"; never silently reconcile a contradiction by picking a side. This one is absolute because a gate that quietly fixes things stops being a gate: the user never learns the spec was wrong, the plan built on the old assumption stays stale, and the "consistency check" has manufactured a new inconsistency. Name the conflict, show both sides with locations, propose where it should be resolved, hand the decision back.
 
-**Model tier: `heavy`** (adversarial cross-reading). Resolve and apply it per `../sdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`.
+**Model tier: `heavy`** (adversarial cross-reading). Resolve and apply it per `../asdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`.
 
 **Register.** Read `technical_level` in `02-DOCS/wiki/harness/user-profile.md` before reporting; with no profile, use analogies and say the harness has not set the register yet. The register changes how the report reads, never what gets checked; the six analyses always run in full.
 
@@ -99,7 +99,7 @@ Render it in the orient voice, in the user's register. Do not log a decision to
 ## Result envelope
 
 End with the parseable block every SDD phase shares, so the dispatcher can chain without
-interpreting prose (contract: `../sdd/SKILL.md`):
+interpreting prose (contract: `../asdd/SKILL.md`):
 
 ```json result-envelope
 {

package/skills/asdd/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: asdd
+description: "Use when a feature or substantial change should go from idea to shipped, verified software and an agent may run it for hours on its own — the ASDD (Agent Spec-Driven Development) dispatcher and front door, in any language. A spec that must prove itself, review inside every task scaled by `rsc risk`, a decision queue for what the agent must not decide alone. Routes constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement (verify + review per task) -> closing -> ship. Successor of `sdd`. NOT a single phase (it dispatches), NOT small authorised changes (that is `ftd`), NOT the workspace harness (that is `harness`)."
+tags: [sdd, asdd, spec, workflow, plan, review]
+recommends: [sdd-init, constitution, specify]
+profiles: [core, full]
+origin: risco
+---
+
+# asdd — Agent Spec-Driven Development
+
+*The front door for letting an agent build for hours without coming back with a Frankenstein: intent in, shipped-and-verified software out, every decision recorded in `02-DOCS/wiki/sdd/`.*
+
+**Why it exists.** Classic SDD reviewed at the end. On paper it checked the spec; in a long autonomous run, the only thing that bit for hours was the test — and tests prove the code works, not that it does what was asked (a real run: 8 hours, 4,500 green tests, and a dropped token plus a QR nobody requested). ASDD keeps the phases and changes two things: **the spec must prove itself**, and **the review moves inside every task**, scaled by risk. The human stops reviewing everything and only takes the decisions the agent must not take alone.
+
+This skill does **not** do a phase. It names the method, reads the register, places the request on the map and hands off. Each phase skill points at the next one.
+
+## The five stages
+
+```text
+  request ─► decisor (answer · ftd · asdd)
+                         │ asdd
+ 1. BASE ─────► constitution + REVIEW.md                 (once per project)
+ 2. SPEC ─────► specify (4 questions + out of scope) ─► clarify (gap checklist)   ◄── HUMAN APPROVES
+ 3. PLAN ─────► plan ─► tasks (criterion · risk forecast · check) ─► analyze
+ 4. LOOP ─────► per task, in implement:
+                 a build + self-check   b rsc risk        c review by tier
+                 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 ─────► 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
+```
+
+| Stage | Phase skills | Writes |
+| --- | --- | --- |
+| **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`, `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`, `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".
+
+### The risk decides, never the agent
+
+`npx @ericrisco/rsc risk [--base <ref>] [paths…]` classifies a change by **what it touches** (the sello's path table; works with the sello off): tier 0 docs/copy → no reviewer; tier 1 ordinary code → one fresh-context reviewer; tier 2 auth, billing, CI workflows, migrations, secrets, harness config → the three-refuter panel **and human approval**. An agent's approval never counts as a human's.
+
+### The loop converges
+
+`npx @ericrisco/rsc review ledger` holds it to the rules that stopped Anthropic's 50-round reviews: `round <slug>/<task>` refuses a 4th round (rethink the approach or park the task), `record` marks a finding already raised as a `repeat` that is never raised again, `outcome` closes each finding as `fixed|false|intentional|irrelevant`, `stats` measures the noise. Flag the bug class, not the line; from round 2 re-review only the new diff.
+
+### Park, don't block
+
+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. **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`.
+6. **Green light?** → `implement` (the per-task loop; `parallel` / `worktrees` when useful).
+7. **All tasks done or parked?** → closing: `verify` (closing mode, main merged in), then `review` (closing review of that exact state), then `ship`.
+8. **Broken mid-flight?** → `debug`, then resume.
+
+Cannot tell the phase? Ask one question: *"Do we have a written spec for this yet?"*
+
+Skip honestly: `constitution` runs once per project; `clarify` and `analyze` are gates, not paperwork — pass through only when the change is genuinely tiny, and say so.
+
+## Autopilot — one up-front yes
+
+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.
+
+**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.
+
+## Read the register first
+
+Read `technical_level` in `02-DOCS/wiki/harness/user-profile.md`. It picks the words (technical, or plain with analogies), never whether the gates exist. No profile → analogies, ask once "technical or with analogies?", persist it (that is `init`'s job; `asdd` honors it). At gates, ask only what changes what gets built, one question at a time, recommendation first.
+
+## Per-phase model routing (opt-in)
+
+Each phase declares a tier — `heavy` (constitution, plan, analyze, review, debug), `balanced` (specify, clarify, tasks, implement, verify), `light` (ship, worktrees, sdd-init) — resolved to a model in `config.yaml` under `models`. Off by default (`models.enabled: false`). Never switch unasked, never claim a switch a tool can't make; the dispatcher itself stays on the session model. Protocol: `references/model-routing.md`.
+
+## Where the artifacts live
+
+```text
+02-DOCS/wiki/sdd/
+├── config.yaml              ← runtime calibration (sdd-init)
+├── constitution.md          ← non-negotiables (once)
+├── 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
+└── decisions.md             ← append-only: every decision, and the task it was taken in
+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 — never in the root `CLAUDE.md`; the harness keeps it honest.
+
+## Stack handoff and skill registry
+
+ASDD is process, not stack: `plan` defers stack specifics, `implement` borrows the stack skill's testing approach, `verify` runs its checks (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`; UI → `../design/SKILL.md`). Choose skills through `.rsc/skill-registry.json`, digest them into 4-5 compact rules per subagent brief, never load the catalog.
+
+## Standard result envelope
+
+Every phase ends with this block so the dispatcher can chain without interpreting prose:
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "one short paragraph",
+  "artifact": "path/to/artifact-or-none",
+  "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": [] },
+  "evidence": []
+}
+```
+
+A run stopped mid-flight writes `02-DOCS/wiki/sdd/sessions/<date>-<slug>.md` instead: stage, artifacts, last verdict, done and parked tasks, the decision queue, next steps.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "Tests are green, the feature is done." | Green proves it runs. Traceability to the spec proves it is what was asked; untraced behaviour is a finding. |
+| "I'll review everything at the end." | That is how 40 correct tasks become a Frankenstein. Review inside each task, then once more at closing. |
+| "This change is obviously low risk." | `rsc risk` decides, from the paths. The agent never picks or argues down its own tier. |
+| "One more round and it converges." | Round 4 is refused. Rethink the approach or park the task. |
+| "I'll wait for the user's answer." | Park the task in the decision queue and continue with independent work. |
+| "The reviewer agent approved it, merge." | An agent's approval never counts as a human's. Tier 2 waits. |
+| "The screenshots look alike." | Compare against a reference the human approved, or a deterministic diff. |
+| "`asdd` should write the spec itself." | It dispatches. `specify` owns the spec. |
+| "Ship with Co-Authored-By: Claude." | Authorship is the responsible person. No AI trailer, no generated-with footer. |
+
+## Start here
+
+- **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`.
+
+Then follow the arrows: each phase ends by pointing at the next, all the way to `ship`.

package/skills/{sdd → asdd}/evals/README.md

@@ -1,6 +1,6 @@
-# Eval harness — `sdd`
+# Eval harness — `asdd`
 
-Evaluates the `sdd` dispatcher (the rsc-sdd front door) on two axes: **triggering**
+Evaluates the `asdd` dispatcher (the rsc-sdd front door) on two axes: **triggering**
 (does it fire when a feature should run the spec-driven flow, and stay quiet when a
 single phase or a different skill owns the request) and **capability** (does loading it
 measurably improve how the agent opens and routes the work). Cases live in `cases.yaml`.
@@ -9,7 +9,7 @@ feeds prompts to Claude Code and judges the result against the rubrics.
 
 ## What's in `cases.yaml`
 
-- `should_trigger` (7) — prompts that MUST invoke `sdd`, including non-obvious phrasings
+- `should_trigger` (7) — prompts that MUST invoke `asdd`, including non-obvious phrasings
   ("which step am I on", "decide what and why, write it down, then build") with no SDD
   jargon.
 - `should_not_trigger` (6) — near-misses that must route elsewhere. Each carries a
@@ -19,12 +19,12 @@ feeds prompts to Claude Code and judges the result against the rubrics.
 
 ## A. Triggering eval
 
-1. Load **only** `sdd` into the agent (no other rsc skills available, so routing is honest).
+1. Load **only** `asdd` into the agent (no other rsc skills available, so routing is honest).
 2. For each `should_trigger` prompt: open a fresh session, paste the prompt verbatim, and
-   record whether `sdd` activates — a pass means it names the method, places the request on
+   record whether `asdd` activates — a pass means it names the method, places the request on
    the phase map, and routes to a phase (it should NOT start writing the spec or coding
    itself). Run **3–5 trials** per prompt.
-3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `sdd` does NOT
+3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `asdd` does NOT
    fire. Where a `route_to` sibling is named, sanity-check the prompt genuinely belongs there
    (e.g. "write the spec" → `specify`, "open the PR and merge" → `ship`).
 4. Score: a prompt passes if the **majority of its trials** go the expected way.
@@ -35,7 +35,7 @@ prompts (at most 1 of the 13 may misbehave).
 ## B. Capability eval
 
 1. **Without the skill:** fresh session, skill NOT loaded, give the `scenario` prompt. Save output A.
-2. **With the skill:** fresh session, `sdd` loaded, same prompt. Save output B.
+2. **With the skill:** fresh session, `asdd` loaded, same prompt. Save output B.
 3. Grade each output against that scenario's `must_include` points — count points clearly covered.
 4. Repeat across **3 trials** per scenario per condition and average the coverage.
 
@@ -47,14 +47,14 @@ the skill — or these rubrics — needs work.
 
 - This is **LLM-as-judge / human-in-the-loop**, not deterministic. Use a consistent grader
   (same model + rubric) across A/B to keep the comparison fair.
-- The headline differentiators for `sdd`: it **dispatches, it does not perform a phase**; it
+- The headline differentiators for `asdd`: it **dispatches, it does not perform a phase**; it
   states the method ("the artifact is the contract"), reads the **register** (`technical_level`)
   and speaks in the orient voice (never skipping gates), presents the **chained phase map**, applies the **invoke
   rule** and the **skip rules** honestly, and writes artifacts under `02-DOCS/wiki/sdd/`.
-- Key confusables to watch: "write the spec" is `specify`, not `sdd`; "set the principles" is
+- Key confusables to watch: "write the spec" is `specify`, not `asdd`; "set the principles" is
   `constitution`; "open the PR" is `ship`; "build 01-TOOLS/02-DOCS" is `harness`. If the agent
   does the phase work itself instead of routing, that's a fail even if the output looks good.
-- Because `sdd` is the front door, some phase siblings may not yet be installed. A correct
+- Because `asdd` is the front door, some phase siblings may not yet be installed. A correct
   response still routes by name and does the phase inline if the sibling is absent — it must
   never invent a phase that isn't in the chain.
 - Run after any edit to `SKILL.md` or its `description`, since both axes are sensitive to wording.

package/skills/{sdd → asdd}/evals/cases.yaml

@@ -1,7 +1,7 @@
-skill: sdd
+skill: asdd
 
-# Cases for the rsc-sdd "sdd" dispatcher / front door.
-# sdd states the SDD method, reads the user's register (technical_level) from
+# Cases for the "asdd" dispatcher / front door (ASDD, successor of sdd in 4.0).
+# asdd states the SDD method, reads the user's register (technical_level) from
 # 02-DOCS/wiki/harness/user-profile.md, and ROUTES to the right phase skill in
 # the chain constitution -> specify -> clarify -> plan -> tasks -> analyze ->
 # implement -> verify -> review -> ship (debug/worktrees/parallel on demand).
@@ -17,7 +17,7 @@ should_trigger:
   - prompt: "I'm somewhere in the middle of building a feature and I've lost track of which step I'm on. Can you orient me?"
     why: "Non-obvious: no SDD jargon, but 'which step am I on' is precisely the dispatcher's 'which phase are you in' job — it asks the one orienting question (is there a written spec?) and routes."
 
-  - prompt: "Run the full sdd flow on this new authentication requirement."
+  - prompt: "Run the full asdd flow on this new authentication requirement."
     why: "Direct request to run the chained flow — the dispatcher owns the flow and routes the first phase; it should not try to do every phase inline itself."
 
   - prompt: "I have a one-paragraph idea for a notifications feature. Take it all the way to a PR the disciplined way."
@@ -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/{sdd → asdd}/references/model-routing.md

@@ -6,7 +6,7 @@ that lets each phase run on the model its work deserves — cheaper where it's s
 where it matters — without surprising anyone and without faking a switch a tool can't make.*
 
 This file is the **single source of truth** for the behavior. `sdd-init` writes the profile,
-`sdd` summarizes it, and every phase skill points here for the procedure. If the three ever
+`asdd` summarizes it, and every phase skill points here for the procedure. If the three ever
 disagree, this file wins.
 
 ## Why this exists
@@ -64,7 +64,7 @@ session model, never announce a switch, never nag. Everything below applies only
 
 **Two phases are deliberately absent from `phases`:**
 
-- `sdd` (the dispatcher) — routing decisions are cheap; it stays on the session model.
+- `asdd` (the dispatcher) — routing decisions are cheap; it stays on the session model.
 - `parallel` — it has no fixed tier. Each fanned-out subagent inherits the tier of the *kind
   of work* its unit does (an implement-type unit → `balanced`; a scan/research unit → `light`;
   a deep-reasoning unit → `heavy`).

package/skills/building-agents/SKILL.md

@@ -14,7 +14,7 @@ A thin provider adapter, a disciplined agent loop, schema-validated tools, provi
 
 > Program against a **capability interface**, never a vendor SDK. Vendor specifics (model id, tool-schema shape, JSON mode, caching, token limits) live behind one adapter resolved from config. Model names and prices rot — if one appears in business logic it's a bug, and re-verify the dated tables before quoting a number.
 
-**Hand off instead when:** a new non-trivial feature has no approved spec + plan under `02-DOCS/wiki/sdd/` → stop and run [`specify`](../specify/SKILL.md) first (method: [`sdd`](../sdd/SKILL.md)), which routes back here once the plan is approved; one-line/low-risk changes go straight through. Anthropic-SDK internals (caching, thinking, batch) in a file that *only* imports `anthropic` → `claude-api` if your environment has it, since this skill stays multi-provider. Workspace scaffolding → [`harness`](../harness/SKILL.md). Choosing *which* coding agent to use → agent-eval territory. Pure prompt-wording tuning with no architecture change → prompt engineering, not this. A one-shot throwaway prompt, or no retrieval/tools/loop/evals at all → you don't need an agent; call the SDK directly and say so.
+**Hand off instead when:** a new non-trivial feature has no approved spec + plan under `02-DOCS/wiki/sdd/` → stop and run [`specify`](../specify/SKILL.md) first (method: [`asdd`](../asdd/SKILL.md)), which routes back here once the plan is approved; one-line/low-risk changes go straight through. Anthropic-SDK internals (caching, thinking, batch) in a file that *only* imports `anthropic` → `claude-api` if your environment has it, since this skill stays multi-provider. Workspace scaffolding → [`harness`](../harness/SKILL.md). Choosing *which* coding agent to use → agent-eval territory. Pure prompt-wording tuning with no architecture change → prompt engineering, not this. A one-shot throwaway prompt, or no retrieval/tools/loop/evals at all → you don't need an agent; call the SDK directly and say so.
 
 ## Decision rules (read before writing code)