@ericrisco/rsc 3.7.4 → 4.0.0

package/README.md

@@ -85,7 +85,7 @@ remove the need to check the result.
 1. **Describe the project.** Choose the assistants you use and how technical the conversation should be.
 2. **Review the setup.** See each proposed component and its reason, then accept the plan you want applied.
 3. **Ask for the work.** The agent names the appropriate lane: an answer, a focused change (FTD), or the
-   specification-led chain (SDD) for decisions that affect each other.
+   specification-led chain (ASDD) for decisions that affect each other.
 4. **Keep the result and its evidence.** Project knowledge goes into `02-DOCS/`; implementation stays in
    your code. Future sessions can consult both.
 
@@ -109,7 +109,7 @@ npx @ericrisco/rsc@latest onboard
 
 The first run asks **one** question about conversation (technical, or with analogies), then what the
 project is for, its goal and the assistants to target. Then it presents the complete plan. A small
-website can defer SDD, agents and code guards; an operations harness does not receive them merely
+website can defer ASDD, agents and code guards; an operations harness does not receive them merely
 because it lives in a repository. Deferred components record the evidence that would make rsc
 recommend them later, and `rsc reassess` reports it without installing anything.
 
@@ -186,10 +186,13 @@ Every turn takes exactly one lane, and the agent names it in one line, in your l
 2. **FTD, Fast-Track Development.** The request authorises a change. This is the default for ordinary
    work. One feature document holds intent, scope, a checklist, the evidence and the next step. Tasks
    are checked off against observed proof, never against intention.
-3. **SDD, the ten-phase chain.** For the big or complex: several decisions that affect each other.
-   **The agent enters it on its own**, and you still decide *what* gets built: you approve the spec
-   and answer the clarifying questions, then review each phase or let it run on autopilot. Publishing
-   always asks.
+3. **ASDD, Agent Spec-Driven Development.** For the big or complex: several decisions that affect
+   each other, and work an agent may run for hours. **The agent enters it on its own**, and you still
+   decide *what* gets built: the spec answers four questions (what the user can do, what result they
+   get, what it must respect, how it proves it) and you approve the spec. Then every task is reviewed inside
+   the build, scaled by `rsc risk`; what the agent must not decide alone waits in a decision queue
+   while independent work continues. Low-risk work lands on green CI; auth, billing, CI and migrations
+   wait for you.
 
 Ask for the other lane and it switches.
 
@@ -229,7 +232,7 @@ project. rsc handles four things by default:
 | --- | --- | --- |
 | **You choose how the project works** | The install asks once: straight on `main`, or branches and pull requests? With branches, a commit on `main` is refused and the agent asks before each change: this branch, a new one, or unlock `main`? It never opens a branch on its own. | «unlock main», or `rsc main unlock` |
 | **One workspace per agent** | If another session works in the same folder, new work goes to `.worktrees/<branch>/` at the root you work in (never inside a project folder) and is never committed. A `post-merge` hook retires it once the branch lands. | `rsc isolation off` |
-| **The agent picks the method** | FTD for simple changes, SDD for complex ones. The agent decides and says why. | Ask for the other lane |
+| **The agent picks the method** | FTD for simple changes, ASDD for complex ones. The agent decides and says why. | Ask for the other lane |
 | **Knowledge reaches everyone** | `01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` travel through one exchange branch, `rsc/knowledge`, and reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
 
 **How it knows a project is complex.** A hook counts what anyone can check: a CI setup, a deployment
@@ -318,7 +321,11 @@ git-excluded local path, keeps 30 days, and injects at most 4,096 bytes. `rsc me
 
 ### Review that only brings you what is real
 
-In SDD, `review` sends three adversarial reviewers at the diff (correctness, security, tests). They
+In ASDD, review runs inside every task, as deep as `rsc risk` says: none for docs, one fresh-context
+reviewer for ordinary code, three adversarial reviewers (correctness, security, tests) for auth,
+billing, CI or migrations. `rsc review ledger` caps the fix loop at three rounds and never lets a
+finding be raised twice, and `rsc review escapes` turns every revert into a case for the reviewer. The
+three reviewers
 often report the same defect in different words, and a reviewer hunting for problems can overstate
 one. So `rsc review consolidate` merges the duplicates, and every serious finding left goes to a
 fresh `finding-verifier` agent whose starting position is that the finding is false. It blocks the
@@ -513,7 +520,7 @@ its own when a task matches.
 Two lanes for change: `ftd` for ordinary work, and the ten-phase chain when durable artifacts would
 settle a real ambiguity. `idea-refinement` runs inside `specify`; `decision-challenge` is on demand.
 
-[ftd](skills/ftd/) · [sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/) · [tidy](skills/tidy/)
+[ftd](skills/ftd/) · [asdd](skills/asdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/) · [tidy](skills/tidy/)
 
 ### 💼 Run a business
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.7.4",
+  "version": "4.0.0",
   "counts": {
     "skills": 274,
     "agents": 34,
@@ -260,6 +260,27 @@
       ],
       "profiles": []
     },
+    {
+      "id": "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"
+      ]
+    },
     {
       "id": "astro",
       "description": "Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is `nextjs`).",
@@ -589,7 +610,7 @@
     },
     {
       "id": "clarify",
-      "description": "Use when a spec exists and must be de-risked before planning — hunt its ambiguities, unstated assumptions and edge cases, ask the few build-changing questions, bake the answers back into the spec. The rsc SDD gate between `specify` (writes the spec) and `plan` (designs the build). NOT the cross-artifact consistency check (that is `analyze`).",
+      "description": "Use when a spec exists and must be de-risked before planning — run the gap checklist over its four ASDD questions and out-of-scope, ask only what changes what gets built (one question at a time, recommendation first), record every other call as an assumption, bake the answers back into the spec. The second half of ASDD stage 2 (Spec), between `specify` (writes the spec) and `plan` (designs the build). NOT the cross-artifact consistency check (that is `analyze`).",
       "tags": [
         "sdd",
         "clarify",
@@ -813,7 +834,7 @@
     },
     {
       "id": "connect-tool",
-      "description": "Use when the user names a specific tool to connect to the agent (an ERP, accounting or desktop program, CRM, WhatsApp, a spreadsheet, a database): research its real docs, choose the safest route, build `01-TOOLS/<TOOL>/` with a test that proves it, and guide the user. NOT a full typed API client (that is `api-connector-builder`), NOT a whole-workspace tooling scan (that is `harness`).",
+      "description": "Use when the user names a specific tool to connect to the agent (an ERP, accounting or desktop program, CRM, WhatsApp, a spreadsheet, a database): research its real docs first, and when none exist, diagnose the program with the user and keep going. Picks the safest route, builds `01-TOOLS/<TOOL>/` with a test that proves it. NOT a full typed API client (that is `api-connector-builder`), NOT a whole-workspace tooling scan (that is `harness`).",
       "tags": [
         "connect",
         "integration",
@@ -825,6 +846,8 @@
         "mcp",
         "api",
         "export",
+        "import",
+        "file-exchange",
         "least-privilege",
         "onboarding"
       ],
@@ -842,11 +865,12 @@
     },
     {
       "id": "constitution",
-      "description": "Use when setting or amending a project's non-negotiables — stack canon, quality bars, conventions, security/a11y floors — as numbered, testable rules later phases obey. First rsc-sdd phase; writes 02-DOCS/wiki/sdd/constitution.md. NOT a feature spec (that is `specify`), NOT the technical plan (that is `plan`), NOT the wiki itself (that is `harness`).",
+      "description": "Use when setting or amending a project's non-negotiables — stack canon, quality bars, conventions, security/a11y floors — as numbered, testable rules later phases obey, and drafting the REVIEW.md the reviewer reads. ASDD's base stage; writes 02-DOCS/wiki/sdd/constitution.md and REVIEW.md at the project root. NOT a feature spec (that is `specify`), NOT the technical plan (that is `plan`), NOT the wiki itself (that is `harness`).",
       "tags": [
-        "sdd",
+        "asdd",
         "constitution",
-        "principles"
+        "principles",
+        "review"
       ],
       "recommends": [
         "specify"
@@ -1734,7 +1758,6 @@
         "epistemics"
       ],
       "recommends": [
-        "sdd",
         "verify",
         "debug",
         "review"
@@ -1927,7 +1950,7 @@
     },
     {
       "id": "ftd",
-      "description": "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, and asks whether to branch before the work writes code. NOT the ten-phase chain (that is `sdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing.",
+      "description": "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, asks whether to branch before the work writes code, and runs a minimal risk loop (self-check, `rsc risk`, one reviewer from tier 1). NOT the full method (that is `asdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing.",
       "tags": [
         "ftd",
         "lane",
@@ -2429,14 +2452,16 @@
     },
     {
       "id": "implement",
-      "description": "Use when an approved plan and task list exist and it is time to turn them into working, tested code — the SDD phase after `analyze` and before `verify`. Enforces TDD: a failing test comes before the code that makes it pass, one task at a time, appended to a progress ledger that survives compaction. Delegates test tooling to the stack skill and fans disjoint tasks out via `parallel`. NOT spec writing (that is `specify`), NOT planning (that is `plan`), NOT the final lint/test/audit gate (that is `verify`).",
+      "description": "Use when an approved plan and task list exist and it is time to turn them into working, reviewed code — ASDD stage 4, the per-task loop after `analyze`: TDD build and self-check, `rsc risk` on the diff, review scaled by tier (0/1/3 reviewers), mandatory controls (tests, build, security, traceability), at most 3 fix rounds, then fix-and-record or park in the decision queue. Progress ledger survives compaction; disjoint tasks fan out via `parallel`. NOT spec writing (that is `specify`), NOT planning (that is `plan`), NOT the closing whole-branch gate (stage 5: `verify` + `review`).",
       "tags": [
+        "asdd",
         "sdd",
         "implement",
         "code"
       ],
       "recommends": [
-        "verify"
+        "verify",
+        "review"
       ],
       "profiles": [
         "core",
@@ -4132,11 +4157,12 @@
     },
     {
       "id": "review",
-      "description": "Use when a green diff needs adversarial judgment in the rsc SDD chain, between verify and ship — give a review keyed to the spec/plan/constitution in 02-DOCS/wiki/sdd/, or receive one and verify each comment before agreeing. NOT running lint/type/tests (that is `verify`), NOT the spec-less standalone pass (that is `code-review`), NOT merging (that is `ship`).",
+      "description": "Use when a diff needs adversarial judgment in rsc ASDD — per task inside implement's loop (depth set by `rsc risk`: none, one fresh-context reviewer, or the three-refuter panel) or as the closing review of the whole branch against the spec — keyed to the spec/plan/constitution in 02-DOCS/wiki/sdd/ and the project's REVIEW.md; or receive a review and verify each comment before agreeing. Converges via `rsc review ledger` (max 3 rounds, no repeated finding). NOT running lint/type/tests (that is `verify`), NOT the spec-less standalone pass (that is `code-review`), NOT merging (that is `ship`).",
       "tags": [
-        "sdd",
+        "asdd",
         "review",
-        "code-review"
+        "code-review",
+        "risk"
       ],
       "recommends": [
         "ship"
@@ -4339,28 +4365,9 @@
         "full"
       ]
     },
-    {
-      "id": "sdd",
-      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the user's register from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill.",
-      "tags": [
-        "sdd",
-        "spec",
-        "workflow",
-        "plan"
-      ],
-      "recommends": [
-        "sdd-init",
-        "constitution",
-        "specify"
-      ],
-      "profiles": [
-        "core",
-        "full"
-      ]
-    },
     {
       "id": "sdd-init",
-      "description": "Use when calibrating an existing repo for the rsc SDD chain: detect stack, package manager, test runners and apply/verify commands, refresh the skill registry, and write the runtime config at 02-DOCS/wiki/sdd/config.yaml. NOT the dispatcher that routes SDD phases (that is `sdd`), NOT first-contact user/workspace bootstrap (that is `init`).",
+      "description": "Use when calibrating an existing repo for the rsc SDD chain: detect stack, package manager, test runners and apply/verify commands, refresh the skill registry, and write the runtime config at 02-DOCS/wiki/sdd/config.yaml. NOT the dispatcher that routes SDD phases (that is `asdd`), NOT first-contact user/workspace bootstrap (that is `init`).",
       "tags": [
         "sdd",
         "init",
@@ -4369,7 +4376,6 @@
         "registry"
       ],
       "recommends": [
-        "sdd",
         "specify",
         "implement",
         "verify"
@@ -4437,12 +4443,13 @@
     },
     {
       "id": "ship",
-      "description": "Use when a verified, review-approved branch has to land — the close of the rsc SDD chain: safety checks, then three landing options (merge, PR, park/discard), authorship always Eric and never an AI trailer. NOT running the gates (that is `verify`), NOT reading the diff for defects (that is `review`), NOT shipping to a server (that is `deployment`).",
+      "description": "Use when a verified branch that passed its closing review has to land — the close of rsc ASDD: safety checks, an explainer for the human (what changed, what the checks proved and would not catch), then three landing options (merge, PR with Testing/Risk/How to revert, park/discard). Risk tier 0-1 with CI green may self-merge; tier 2 waits for human approval. Authorship always the human, never an AI trailer. NOT running the gates (that is `verify`), NOT reading the diff for defects (that is `review`), NOT shipping to a server (that is `deployment`).",
       "tags": [
-        "sdd",
+        "asdd",
         "ship",
         "release",
-        "pr"
+        "pr",
+        "risk"
       ],
       "recommends": [],
       "profiles": [
@@ -4689,7 +4696,7 @@
     },
     {
       "id": "specify",
-      "description": "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via frontier-round dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`).",
+      "description": "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of ASDD stage 2 (Spec). Turns a one-line intent into problem, goals, users, out-of-scope, the four ASDD questions (what the user can do, what result they get, what it must respect, how it proves it) and acceptance criteria, via frontier-round dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`).",
       "tags": [
         "sdd",
         "spec",
@@ -4911,8 +4918,9 @@
     },
     {
       "id": "tasks",
-      "description": "Use when an approved plan needs slicing into an ordered task list before any code — the SDD `tasks` phase. Each row carries a literal done-check, dependencies, a parallel-safe marker and a spec trace, appended to the plan artifact. NOT writing the plan (that is `plan`), NOT the consistency gate (that is `analyze`), NOT executing the tasks (that is `implement`).",
+      "description": "Use when an approved plan needs slicing into an ordered task list before any code — the `tasks` step of ASDD stage 3 (Plan). Each row carries the spec criterion it covers, a risk forecast (tier 0/1/2), a literal done-check, dependencies and a parallel-safe marker, appended to the plan artifact. NOT writing the plan (that is `plan`), NOT the consistency gate (that is `analyze`), NOT executing the tasks (that is `implement`).",
       "tags": [
+        "asdd",
         "sdd",
         "tasks",
         "breakdown"
@@ -5409,8 +5417,9 @@
     },
     {
       "id": "verify",
-      "description": "Use when implementation is finished and about to be called done or merged — the rsc-sdd evidence gate: runs the stack's scripts/verify.sh (lint, type, test, audit), walks every task done-check and acceptance criterion, records a dated verdict. NOT judging the diff by eye (that is `review`, spec-less `code-review`), NOT diagnosis (that is `debug`).",
+      "description": "Use when work is about to be called done — the ASDD evidence gate, in two modes: per task inside `implement`'s loop (tests, build, security, traceability) and at closing over the whole branch against main (stack scripts/verify.sh, every done-check and acceptance criterion, rollback plan, dated verdict). A check that did not execute is reported not run, never passed. NOT judging the diff by eye (that is `review`, spec-less `code-review`), NOT diagnosis (that is `debug`).",
       "tags": [
+        "asdd",
         "sdd",
         "verify",
         "test"

package/package.json

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

@@ -5,7 +5,7 @@
 
 export const DOMAINS = [
   { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'unslop', 'author-skill', 'sdd-init'] },
-  { title: 'Spec-Driven Development', ids: ['ftd', 'sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel', 'tidy'] },
+  { title: 'Spec-Driven Development', ids: ['ftd', 'asdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel', 'tidy'] },
   { title: 'Run a business', ids: ['finance-ops', 'invoicing', 'bookkeeping', 'pricing', 'sales-pipeline', 'lead-gen', 'cold-outreach', 'proposals', 'contracts', 'customer-support', 'client-onboarding', 'retention', 'hiring', 'people-ops', 'inventory', 'logistics-ops', 'procurement', 'meeting-notes', 'sop-builder', 'project-ops'] },
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
   { title: 'Legal, privacy & compliance', ids: ['gdpr-privacy', 'terms-conditions', 'compliance', 'data-policy', 'ip-trademark'] },

package/scripts/lib/onboarding-apply.js

@@ -111,7 +111,7 @@ export function renderOnboardingDocuments(plan, planId) {
   const profile = `---\ntechnical_level: ${plan.record.technicalLevel}\nproject_kind: ${plan.record.projectKind}\n---\n\n# User profile\n\nGoal: ${plan.record.goal}\n`;
   const rows = plan.decisions.map((d) => `| ${d.kind} | ${d.id} | ${d.state} | ${d.reason} | ${d.reevaluateWhen.join('; ') || '—'} |`).join('\n');
   const installation = `# Accepted harness plan\n\nPlan id: \`${planId}\`\n\n| Kind | Component | Decision | Reason | Reevaluate when |\n| --- | --- | --- | --- | --- |\n${rows}\n`;
-  const decisions = `# Harness decisions\n\n- Accepted plan \`${planId}\`.\n- Project kind: ${plan.record.projectKind}.\n- SDD: ${plan.decisions.find((d) => d.id === 'sdd')?.state || 'selected through profile'}.\n`;
+  const decisions = `# Harness decisions\n\n- Accepted plan \`${planId}\`.\n- Project kind: ${plan.record.projectKind}.\n- SDD: ${plan.decisions.find((d) => d.id === 'asdd')?.state || 'selected through profile'}.\n`;
   return { profile, installation, decisions };
 }
 

package/scripts/lib/onboarding.js

@@ -276,10 +276,10 @@ export function buildOnboardingPlan(record, evidence) {
   // `sdd` is installed everywhere now, but its DECISION is about practice, not presence — so where
   // the chain is not practised the explicit `deferred` entry below must be the only one, or the
   // generic "installed → selected" mapping would shadow it and `reassess` would see nothing to watch.
-  const decisions = skills.filter((id) => practisesSdd || id !== 'sdd').map((id) => detectedSkills.includes(id)
+  const decisions = skills.filter((id) => practisesSdd || id !== 'asdd').map((id) => detectedSkills.includes(id)
     ? selected(id, 'skill', `Detected ${id} evidence inside the selected project root.`, 'workspace-evidence')
     : selected(id, 'skill', needsSdd
-      ? (id === 'sdd' && complexitySignals.length
+      ? (id === 'asdd' && complexitySignals.length
         ? `Included because the accepted work has ${complexitySignals.join(', ')} complexity.`
         : `Included in the development workflow for ${normalized.softwareScope} software.`)
       : `Included in the lightweight foundation for this ${normalized.projectKind} project.`));
@@ -293,16 +293,16 @@ export function buildOnboardingPlan(record, evidence) {
   // so the chain is always one request away; this decision is what `reassess` watches, and what the
   // floor reads. Collapsing the two would have deleted reassess's reason to exist as a side effect
   // of an installer change, which is not a decision an installer change gets to make.
-  // The reason says both halves, because the plan lists `.claude/skills/sdd` under managed paths
+  // The reason says both halves, because the plan lists `.claude/skills/asdd` under managed paths
   // and a bare "deferred" next to it read as a contradiction (E2E 2026-10-07). Only the wording
-  // changes: the decision stays the one deferred `workflow/sdd` entry that reassess watches.
+  // changes: the decision stays the one deferred `workflow/asdd` entry that reassess watches.
   const whyDeferred = isSoftware
     ? 'the software scope is small, so specification overhead is not justified yet.'
     : 'SDD applies to substantial software work, which is not the declared project purpose.';
-  const sddReason = skills.includes('sdd')
-    ? `The sdd skill is installed, so the chain is one request away; the practice is deferred: ${whyDeferred}`
+  const sddReason = skills.includes('asdd')
+    ? `The asdd skill is installed, so the chain is one request away; the practice is deferred: ${whyDeferred}`
     : whyDeferred.charAt(0).toUpperCase() + whyDeferred.slice(1);
-  if (!practisesSdd) decisions.push(deferred('sdd', 'workflow', sddReason, sddTriggers, softwareTriggers));
+  if (!practisesSdd) decisions.push(deferred('asdd', 'workflow', sddReason, sddTriggers, softwareTriggers));
   if (baseAgents) {
     for (const id of agents) decisions.push(selected(id, 'agent', 'The accepted substantial software workflow requires this implementation or review role.'));
   } else {

package/scripts/lib/retired-skills.js

@@ -14,10 +14,14 @@
 //
 // `ui-engineering` folded into `ux` in 3.4.0: the screen states and form behaviour it owned are
 // `ux`'s state matrix now, and where component state lives is `react`'s.
+//
+// `sdd` became `asdd` in 4.0.0 (spec asdd-v4): the same phases, with the review moved inside each
+// task of `implement` and scaled by `rsc risk`. Artifacts stay under 02-DOCS/wiki/sdd/.
 export const RETIRED_SKILLS = Object.freeze({
   eli5: 'orient', 'show-me': 'orient', bro: 'unslop',
   'design-loop': 'design', 'design-dna': 'design', 'motion-craft': 'design',
   'ui-engineering': 'ux',
+  sdd: 'asdd',
 });
 
 const retiredTo = (id) => (Object.hasOwn(RETIRED_SKILLS, id) ? RETIRED_SKILLS[id] : id);

package/scripts/lib/review-findings.js

@@ -68,6 +68,7 @@ export function normalizeFinding(f) {
     claim: text(f.claim) || text(f.title) || text(f.summary),
     failure_scenario: text(f.failure_scenario) || text(f.repro),
     evidence: text(f.evidence),
+    class: text(f.class) || text(f.bug_class) || text(f.defect_class),
     notes: [],
   };
   if (!out.severity) {
@@ -140,6 +141,8 @@ export function consolidate(rawFindings, { window = DEFAULT_WINDOW } = {}) {
       claims: uniq(members.map((m) => m.claim)),
       failure_scenarios: uniq(members.map((m) => m.failure_scenario)),
       evidence: uniq(members.map((m) => m.evidence)),
+      // Carried through so `review ledger record` can fingerprint by bug class.
+      class: uniq(members.map((m) => m.class))[0] || '',
       notes: uniq(members.flatMap((m) => m.notes)),
       reported: members.length,
       verify: rank(severity) <= rank('should-fix'),

package/scripts/lib/review-ledger.js

@@ -0,0 +1,185 @@
+// The review ledger — the deterministic half of ASDD's fix loop and of the reviewer's learning.
+//
+// Anthropic's reviewer and author once looped more than fifty rounds on one PR, and about 59% of what
+// the reviewer kept flagging was code it had already seen. Three rules stopped that: cap the rounds,
+// never repeat a finding, and record what happened to each finding so noise can be measured. A rule
+// that only lives in a skill's prose is the decorative gate (P2), so the three live here.
+// Spec: 02-DOCS/wiki/sdd/specs/asdd-v4.md.
+//
+// One JSONL file, append-only: `finding`, `outcome` and `round` entries. It sits under .rsc/ and is
+// excluded from the sello's candidate like every other journal the harness writes (targets/sello.mjs).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+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'];
+export const MAX_ROUNDS = 3;
+export const EVALS_DIR = '02-DOCS/wiki/sdd/review-evals';
+
+// Two findings are the same claim when they sit in the same file and share most of their words, or
+// name the same bug class AND still share some. A class alone is not enough: two different
+// null-check bugs in one file are two findings, and suppressing the second hides a real defect.
+// The line is left out on purpose: it moves between rounds, and a repeat must survive the fix
+// that moved it.
+export const SAME_CLAIM = 0.5;
+export const SAME_CLASS_CLAIM = 0.2;
+const STOP = new Set('the and for with not that this its are was from any only one but has have into than then when which will can'.split(' '));
+const words = (s) => new Set(String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP.has(w)));
+function overlap(a, b) {
+  const A = words(a); const B = words(b);
+  let shared = 0;
+  for (const w of A) if (B.has(w)) shared += 1;
+  const union = A.size + B.size - shared;
+  return union ? shared / union : 0;
+}
+
+const text = (v) => (typeof v === 'string' ? v.trim() : '');
+const normFile = (f) => text(f).replace(/\\/g, '/').replace(/^\.\//, '');
+
+// Accepts what the lenses emit and what `review consolidate --json` prints.
+export function normalize(f) {
+  return {
+    file: normFile(f.file),
+    class: text(f.class) || text(f.bug_class) || text(f.defect_class),
+    claim: text(f.claim) || (Array.isArray(f.claims) ? text(f.claims[0]) : '') || text(f.title) || text(f.summary),
+    severity: text(f.severity) || 'question',
+  };
+}
+
+export function sameClaim(a, b) {
+  if (a.file !== b.file) return false;
+  const o = overlap(a.claim, b.claim);
+  if (a.class && b.class && a.class.toLowerCase() === b.class.toLowerCase()) return o >= SAME_CLASS_CLAIM;
+  return o >= SAME_CLAIM;
+}
+
+export function readLedger(root) {
+  const path = join(root, LEDGER_PATH);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
+    try { return [JSON.parse(line)]; } catch { return []; }
+  });
+}
+
+function append(root, entries) {
+  mkdirSync(join(root, '.rsc'), { recursive: true });
+  appendFileSync(join(root, LEDGER_PATH), entries.map((e) => `${JSON.stringify(e)}\n`).join(''));
+}
+
+// → [{id, status: 'new'|'repeat', repeatOf?, ...finding}]. A repeat is recorded too (it is the noise
+// being measured) but points at the original, and the caller must not raise it again.
+export function record(root, rawFindings, { task = '', now = new Date().toISOString() } = {}) {
+  const ledger = readLedger(root);
+  // A finding closed as fixed that shows up again is a regression, not noise: it is raised anew.
+  const fixed = new Set(ledger.filter((e) => e.type === 'outcome' && e.outcome === 'fixed').map((e) => e.id));
+  const seen = ledger.filter((e) => e.type === 'finding' && !e.repeatOf && !fixed.has(e.id));
+  let n = ledger.filter((e) => e.type === 'finding').length;
+  const out = [];
+  for (const raw of rawFindings) {
+    if (!raw || typeof raw !== 'object') continue;
+    const f = normalize(raw);
+    n += 1;
+    const original = seen.find((s) => sameClaim(s, f));
+    const entry = { type: 'finding', id: `L${n}`, task, at: now, ...f, ...(original ? { repeatOf: original.id } : {}) };
+    if (!original) seen.push(entry);
+    out.push(entry);
+  }
+  append(root, out);
+  return out.map((e) => ({ ...e, status: e.repeatOf ? 'repeat' : 'new' }));
+}
+
+export function outcome(root, id, value, { now = new Date().toISOString() } = {}) {
+  if (!OUTCOMES.includes(value)) {
+    return { ok: false, message: `rsc: unknown outcome "${value}". Use one of: ${OUTCOMES.join(', ')}.` };
+  }
+  if (!readLedger(root).some((e) => e.type === 'finding' && e.id === id)) {
+    return { ok: false, message: `rsc: no finding "${id}" in ${LEDGER_PATH}. Run \`npx @ericrisco/rsc review ledger stats\` to see the recorded ids.` };
+  }
+  append(root, [{ type: 'outcome', id, outcome: value, at: now }]);
+  return { ok: true, message: `${id}: ${value}` };
+}
+
+// Counts one more review round for a task. The fourth is refused, with the way out in the message
+// (P6): rethink the approach, or park the task in the decision queue and go on with independent work.
+// The task is qualified by its spec (`<slug>/T001`): every plan numbers its tasks from T001, and a
+// bare id would let one feature inherit another's rounds and park work never reviewed.
+export const QUALIFIED_TASK = /^[^/\s]+\/[^/\s]+$/;
+export function round(root, task, { now = new Date().toISOString() } = {}) {
+  if (!QUALIFIED_TASK.test(task)) {
+    return { ok: false, round: 0, message: `rsc: qualify the task with its spec slug, e.g. \`review ledger round <slug>/${task || 'T001'}\` — task ids repeat across plans.` };
+  }
+  const n = readLedger(root).filter((e) => e.type === 'round' && e.task === task).length + 1;
+  if (n > MAX_ROUNDS) {
+    return {
+      ok: false, round: n,
+      message: `rsc: task "${task}" has had ${MAX_ROUNDS} review rounds and has not converged. Stop fixing line by line: rethink the approach, or park the task in the decision queue (02-DOCS/wiki/sdd/progress/<slug>.md, "## Decision queue") and continue with independent tasks.`,
+    };
+  }
+  append(root, [{ type: 'round', task, n, at: now }]);
+  return { ok: true, round: n, message: `task "${task}": review round ${n} of ${MAX_ROUNDS}` };
+}
+
+export function stats(root) {
+  const ledger = readLedger(root);
+  const findings = ledger.filter((e) => e.type === 'finding');
+  const originals = findings.filter((f) => !f.repeatOf);
+  const last = new Map();
+  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;
+  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);
+  return {
+    findings: originals.length,
+    repeats: findings.length - originals.length,
+    outcomes,
+    falseRate: closed ? outcomes.false / closed : null,
+    tasks: rounds.size,
+    meanRounds: rounds.size ? totalRounds / rounds.size : null,
+    open: originals.filter((f) => !last.has(f.id)).map((f) => f.id),
+  };
+}
+
+export function renderStats(s) {
+  const pct = (x) => (x === null ? 'n/a' : `${Math.round(x * 100)}%`);
+  return [
+    `findings: ${s.findings} unique, ${s.repeats} repeat(s) caught`,
+    `outcomes: ${OUTCOMES.map((k) => `${k} ${s.outcomes[k]}`).join(' · ')} · open ${s.outcomes.open}`,
+    `false rate: ${pct(s.falseRate)} of closed findings`,
+    `rounds: ${s.tasks} task(s), mean ${s.meanRounds === null ? 'n/a' : s.meanRounds.toFixed(2)} round(s) per task`,
+    ...(s.open.length ? [`still open: ${s.open.join(', ')} — close each with \`review ledger outcome <id> <${OUTCOMES.join('|')}>\``] : []),
+  ].join('\n');
+}
+
+// Escapes: reverts that reached the trunk. Each one should become a case the reviewer is scored
+// against (the diff, where the bug was, what the review should have said). Only the conventional
+// shapes are visible — `Revert "…"` from git, and a `revert:` commit type — and the output says so.
+const REVERT = /^(?:\S+\s+)?(?:Revert "|revert(?:\([^)]*\))?!?:)/;
+export function escapes(root, { since = '' } = {}) {
+  const range = since ? [`${since}..HEAD`] : [];
+  const r = spawnSync('git', ['-C', root, 'log', '--format=%H%x00%s', ...range], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) return { ok: false, message: `rsc: cannot read git history${since ? ` since ${since}` : ''} (${(r.stderr || '').trim() || 'not a git repository'}).`, reverts: [] };
+  let cases = [];
+  try { cases = readdirSync(join(root, EVALS_DIR)).filter((f) => f.endsWith('.md')); } catch { cases = []; }
+  const reverts = r.stdout.split('\n').filter(Boolean).map((line) => {
+    const [sha, subject] = line.split('\0');
+    return { sha: sha.slice(0, 7), subject };
+  }).filter((c) => REVERT.test(c.subject)).map((c) => ({ ...c, covered: cases.some((f) => f.startsWith(c.sha)) }));
+  return { ok: true, reverts };
+}
+
+export function renderEscapes(res) {
+  if (!res.reverts.length) return 'No reverts found (only `Revert "…"` subjects and `revert:` commits are recognised).';
+  const pending = res.reverts.filter((c) => !c.covered).length;
+  return [
+    ...res.reverts.map((c) => `${c.covered ? 'case  ' : 'NO CASE'} ${c.sha}  ${c.subject}`),
+    '',
+    pending
+      ? `${pending} revert(s) without a case. Write each as ${EVALS_DIR}/<sha>.md: the diff, where the bug was, what the review should have said.`
+      : 'Every revert has its case.',
+  ].join('\n');
+}