@ericrisco/rsc 4.0.2 → 4.0.4

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.2",
+  "version": "4.0.4",
   "counts": {
     "skills": 274,
     "agents": 34,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "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/install-apply.js

@@ -103,7 +103,8 @@ export function generatedHookFiles({ target, cwd, policy }) {
     join(cwd, '.rsc', 'ship-guard.mjs'),
     join(cwd, '.rsc', 'branch-guard.mjs'),
     join(cwd, '.rsc', 'gitmoji-guard.mjs'), join(cwd, '.rsc', 'userprompt-gate.mjs'),
-    join(cwd, '.rsc', 'sello.mjs'), ...(laneGate ? [join(cwd, '.rsc', 'ftd-nudge.mjs')] : [])];
+    join(cwd, '.rsc', 'sello.mjs'), join(cwd, '.rsc', 'asdd-gate.mjs'), join(cwd, '.rsc', 'spec-completeness.mjs'),
+    ...(laneGate ? [join(cwd, '.rsc', 'ftd-nudge.mjs')] : [])];
 }
 
 export function managedPathsForInstall({ skillIds, agentIds = [], target, home, cwd, policy }) {

package/scripts/lib/review-ledger.js

@@ -122,6 +122,22 @@ export function round(root, task, { now = new Date().toISOString() } = {}) {
   return { ok: true, round: n, message: `task "${task}": review round ${n} of ${MAX_ROUNDS}` };
 }
 
+// Records that a review panel ran on a task: which lenses, distinct. Self-attested, like the sello's
+// approve — it binds the claim to a task, it does not prove the review was good. The ship guard reads
+// it: a tier-2 branch does not leave the machine without a panel of the required size on its spec.
+export function panel(root, task, lenses, { now = new Date().toISOString() } = {}) {
+  if (!QUALIFIED_TASK.test(task)) {
+    return { ok: false, message: `rsc: qualify the task with its spec slug, e.g. \`review ledger panel <slug>/closing --lenses correctness,security,tests\`.` };
+  }
+  const list = [...new Set(String(lenses || '').split(',').map((l) => l.trim().toLowerCase()).filter(Boolean))];
+  if (!list.length) return { ok: false, message: 'rsc: name the lenses that ran: --lenses correctness,security,tests' };
+  // Bound to the commit reviewed: code committed after it is code no panel has seen.
+  const r = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', windowsHide: true });
+  const sha = r.status === 0 ? r.stdout.trim() : null;
+  append(root, [{ type: 'panel', task, lenses: list, sha, at: now }]);
+  return { ok: true, message: `task "${task}": panel of ${list.length} recorded (${list.join(', ')})${sha ? ` on ${sha.slice(0, 7)}` : ''}` };
+}
+
 export function stats(root) {
   const ledger = readLedger(root);
   const findings = ledger.filter((e) => e.type === 'finding');

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 { NESTED_WORKTREES, SELLO_STATE_PATHS, classifyRisk, lensesRequired, readEffectiveConfig, trunkRef } from '../../targets/sello.mjs';
+import { NESTED_WORKTREES, SELLO_STATE_PATHS, classifyChange, 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 });
@@ -31,24 +31,31 @@ export function changedPaths(root, base = null) {
     .filter((n) => !SELLO_STATE_PATHS.includes(n)));
   let names = diff(mb);
   let shown = ref;
+  let from = mb;
   // 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)';
+    from = 'HEAD~1';
   }
-  return { ok: true, base: shown, paths: [...names].sort() };
+  return { ok: true, base: shown, from, paths: [...names].sort() };
 }
 
-export function assess(paths, cfg = null) {
-  const { tier, classes, configError } = classifyRisk(paths, cfg);
+// `texts` is what the change adds per path (sello.changeText): content signals raise a path that its
+// name alone would leave at tier 1 — auth code in `src/app.js`.
+export function assess(paths, cfg = null, texts = {}) {
+  const { tier, classes, configError, content } = classifyChange(paths, texts, cfg);
   return {
     tier,
     classes: [...new Set(Object.values(classes))].sort(),
     reviewers: lensesRequired(tier, cfg),
     humanApproval: tier >= 2,
+    // Tier 2 is ASDD work, whatever lane it started in: the ship guard refuses to push it without a spec.
+    escalate: tier >= 2 ? 'asdd' : null,
     paths: classes,
+    content,
     ...(configError ? { configError } : {}),
   };
 }
@@ -61,7 +68,9 @@ export function render(r) {
     `reviewers: ${r.reviewers}`,
     `human approval: ${r.humanApproval ? 'required' : 'not required'}`,
     ...(r.base ? [`base: ${r.base}`] : []),
+    ...(r.escalate ? ['escalate: asdd — tier 2 needs a spec linked to this branch (`branch: <name>` in its frontmatter) that passes `npx @ericrisco/rsc spec gate`; push and PR are refused until it exists. Write it now, before more code.'] : []),
     ...(r.configError ? [`config ignored: ${r.configError}`] : []),
+    ...(r.content || []).slice(0, 10).map((h) => `  content: ${h.class} in ${h.path} ("${h.match}")`),
     ...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

@@ -9,210 +9,9 @@
 // the problem `specify` exists to solve, not something a parser can do, and a gate that implies
 // otherwise is worse than one that admits its edge.
 
-import { parseFrontmatter } from './frontmatter.js';
 
-// The two families below are NOT retroactive. The corpus is 34 specs written before this rule
-// existed, and none of them can answer "what if we don't build it" honestly after the fact; a gate
-// that turns 34 files red gets switched off within a week. So the requirement starts on a date, and
-// the date is derived from the file's own `timestamp:` — not from a list of exempted specs, which
-// would be exactly the parallel accounting P3 forbids.
-export const NEW_FAMILIES_SINCE = '2026-09-06';
+export { NEW_FAMILIES_SINCE, ASDD_FAMILIES_SINCE, OPEN_POINT_TYPES, specCompleteness } from '../../targets/spec-completeness.mjs';
 
-// 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
-  'suposición tomada', // we decided, with the basis written → clarify validates it
-  'decisión diferida', // sharp, out of this cycle on purpose → clarify leaves it
-  'área no formulable', // known to be coming, not yet sharp → clarify notes it
-];
-
-// The corpus is Spanish, the template is English, and both carry drifting parentheticals
-// ("Objetivos (resultado)", "Criterios de aceptación (binarios)"). Matching literal strings would
-// be useless, so each family is a set of normalised prefixes.
-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', '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'] },
-  open: {
-    prefixes: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
-  },
-  // A spec that cannot say what happens if nobody builds it has not been interrogated, only
-  // de-risked. `since` is what keeps that demand off the specs written before it existed.
-  inaction: {
-    prefixes: [
-      'que pasa si no lo construimos', '¿que pasa si no lo construimos',
-      'coste de no construirlo', 'el coste de no construirlo',
-      'cost of not building', 'the cost of not building',
-    ],
-    since: NEW_FAMILIES_SINCE,
-  },
-  cheapest: {
-    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 = [
-  'que ninguna sección contenga una suposición sin marcar (no es detectable por máquina; es el juicio que la fase existe para ejercer)',
-  'que el contenido de cada sección sea correcto, y no sólo presente',
-  'que los criterios de aceptación sean de verdad binarios',
-  // Added with the status check below, for the same reason the three above exist: a green that is
-  // narrower than the rule it appears to enforce is the decorative gate all over again.
-  'si una spec dice "implementada" sin nombrar commit, PR ni versión (no hay nada que ir a mirar)',
-  'si el trabajo de una spec que se declara sin aterrizar llegó por otra vía (git no lo distingue)',
-  // 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) {
-  return s
-    .normalize('NFD')
-    .replace(/[̀-ͯ]/g, '')
-    .toLowerCase()
-    .trim();
-}
-
-function familyOf(heading) {
-  const h = fold(heading);
-  for (const [family, { prefixes }] of Object.entries(FAMILIES)) {
-    if (prefixes.some((p) => h.startsWith(p))) return family;
-  }
-  return null;
-}
-
-// A heading with nothing under it is not a filled section. Neither is one holding only the
-// template's own italic/angle-bracket guidance, which is what a hurried pass leaves behind.
-function isSubstantive(line) {
-  const t = line.trim();
-  if (!t) return false;
-  if (/^<.*>$/.test(t)) return false; // <guidance from the template>
-  if (/^\*[^*].*\*$/.test(t) && t.length < 200) return false; // *italic guidance*
-  if (/^(-|\*)\s*$/.test(t)) return false; // an empty bullet
-  return true;
-}
-
-// The template's guidance does not fit on one line, and a section still holding it is a section
-// nobody filled in. The single-line check above never saw those: `<What concretely happens if` does
-// not end in `>`, so it read as content and an untouched template passed the gate green.
-//
-// Only a block that actually CLOSES counts as guidance. A stray `<` that never finds its `>` — a
-// latency budget written `<400ms`, a generic in a code sample — stays content, because guessing
-// wrong in that direction hides real prose.
-function guidanceLines(lines) {
-  const skip = new Set();
-  for (let i = 0; i < lines.length; i += 1) {
-    const t = lines[i].trim();
-    if (!t.startsWith('<') || t.endsWith('>')) continue;
-    for (let j = i + 1; j < lines.length; j += 1) {
-      const u = lines[j].trim();
-      if (u === '' || u.startsWith('#')) break; // the block ended without closing: not guidance
-      if (u.endsWith('>')) {
-        for (let k = i; k <= j; k += 1) skip.add(k);
-        i = j;
-        break;
-      }
-    }
-  }
-  return skip;
-}
-
-function hasSubstance(lines) {
-  const guidance = guidanceLines(lines);
-  return lines.some((line, i) => !guidance.has(i) && isSubstantive(line));
-}
-
-// The day this spec was written, as YYYY-MM-DD, or null when there is nothing trustworthy to read.
-// Null always means EXEMPT: a spec we cannot date is not a spec we get to fail. Three ways to land
-// there, and all three are safe — the CLI itself calls specCompleteness('') to print `unchecked`,
-// and parseFrontmatter throws on that.
-function specDay(markdown) {
-  try {
-    const raw = parseFrontmatter(markdown).timestamp;
-    if (typeof raw !== 'string') return null;
-    const day = raw.slice(0, 10); // ISO order is lexicographic order; no timezone maths needed
-    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : null;
-  } catch {
-    return null;
-  }
-}
-
-function requiredFamilies(markdown) {
-  const day = specDay(markdown);
-  return Object.entries(FAMILIES)
-    .filter(([, { since }]) => !since || (day !== null && day >= since))
-    .map(([family]) => family);
-}
-
-function parseOpenPoints(lines) {
-  const points = [];
-  for (const line of lines) {
-    const m = line.match(/^\s*[-*]\s+(?:\[[ x]\]\s*)?(.*)$/);
-    if (!m || !m[1].trim()) continue;
-    const body = m[1];
-    const declared = OPEN_POINT_TYPES.find((t) => {
-      const re = new RegExp(`^\\*\\*\\s*${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\*\\*`, 'i');
-      return re.test(fold(body)) || re.test(body);
-    });
-    points.push({
-      type: declared || OPEN_POINT_TYPES[0], // the costliest default: treat it as a real question
-      typed: Boolean(declared),
-      text: body.trim(),
-    });
-  }
-  return points;
-}
-
-/**
- * @param {string} markdown a written spec file
- * @returns {{ok: boolean, missing: string[], empty: string[],
- *            openPoints: Array<{type: string, typed: boolean, text: string}>,
- *            untyped: string[], unchecked: string[]}}
- */
-export function specCompleteness(markdown) {
-  const lines = String(markdown ?? '').split('\n');
-  const sections = new Map(); // family -> body lines
-
-  let current = null;
-  for (const line of lines) {
-    const h = line.match(/^##\s+(.*)$/);
-    if (h) {
-      const fam = familyOf(h[1]);
-      current = fam;
-      if (fam && !sections.has(fam)) sections.set(fam, []);
-      continue;
-    }
-    if (current && sections.has(current)) sections.get(current).push(line);
-  }
-
-  const families = requiredFamilies(markdown);
-  const missing = families.filter((f) => !sections.has(f));
-  const empty = families.filter((f) => sections.has(f) && !hasSubstance(sections.get(f)));
-
-  const openPoints = sections.has('open') ? parseOpenPoints(sections.get('open')) : [];
-  const untyped = openPoints.filter((p) => !p.typed).map((p) => p.text);
-
-  return {
-    ok: missing.length === 0 && empty.length === 0,
-    missing,
-    empty,
-    openPoints,
-    untyped,
-    unchecked: UNCHECKED,
-  };
-}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Does the status still match the repository?

package/scripts/rsc.js

@@ -1262,13 +1262,17 @@ async function main() {
         .map((p) => rel(root, res(process.cwd(), p)).split('\\').join('/'));
       let paths = given;
       let against = null;
+      let from = 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;
+        from = c.from;
       }
-      const r = { ...K.assess(paths, S.readEffectiveConfig(root)), ...(against ? { base: against } : {}) };
+      // Given paths are read whole (a forecast or a single file); a diff contributes its added lines.
+      const texts = S.changeText(root, from, paths);
+      const r = { ...K.assess(paths, S.readEffectiveConfig(root), texts), ...(against ? { base: against } : {}) };
       say(argv.includes('--json') ? JSON.stringify(r, null, 2) : K.render(r));
       return;
     }
@@ -1279,7 +1283,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|parked> | 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> | panel <slug>/<task> --lenses a,b,c | stats [--json]',
         '     npx @ericrisco/rsc review escapes [--since <ref>] [--json]',
       ].join('\n');
       if (argv[1] === 'ledger' || argv[1] === 'escapes') {
@@ -1328,6 +1332,13 @@ async function main() {
           if (!r.ok) process.exitCode = 1;
           return;
         }
+        if (sub === 'panel') {
+          if (!a || a.startsWith('--')) return fail(USE);
+          const r = L.panel(root, a, str('lenses'));
+          if (!r.ok) return fail(r.message);
+          say(r.message);
+          return;
+        }
         if (sub === 'stats') {
           const s = L.stats(root);
           say(json ? JSON.stringify(s, null, 2) : L.renderStats(s));
@@ -1532,7 +1543,7 @@ async function main() {
           if (!candidate) { say(S.MESSAGES.noTrunk()); process.exitCode = 1; return; }
           const paths2 = Object.keys(candidate.files);
           if (!paths2.length) { say('sello: nothing to freeze — the working tree matches the trunk base.'); return; }
-          const risk = S.classifyRisk(paths2, cfg);
+          const risk = S.classifyCandidate(root, candidate, cfg);
           if (risk.configError) say(`⚠️  ${risk.configError}\n   (using the default risk table until it is fixed)`);
           const required = S.lensesRequired(risk.tier, cfg);
           S.writeSello(root, { status: 'frozen', ...candidate, risk, required, lenses: [], createdAt: new Date().toISOString() });

package/skills/asdd/SKILL.md

@@ -51,7 +51,7 @@ Every spec answers four questions, and `spec:gate` refuses one dated 2026-11-03
 
 ### 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.
+`npx @ericrisco/rsc risk [--base <ref>] [paths…]` classifies a change by **what it touches and what it adds** (the sello's path table plus fixed content patterns — password hashing, session cookies, payments, schema changes, secrets — so auth code in `src/app.js` is still auth; 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. **Enforced at push:** a tier-2 branch leaves the machine only with a spec linked to it that passes `rsc spec gate` **and** a panel recorded with `rsc review ledger panel <slug>/<task> --lenses correctness,security,tests`.
 
 ### The loop converges
 

package/skills/ftd/SKILL.md

@@ -74,6 +74,8 @@ The lane inherits ASDD's per-task loop, cut to its floor:
 **Escalate to `asdd`** when `rsc risk` says **tier 2**, or when the change contradicts a decision
 already recorded in `decisions.md`: the feature document becomes its spec input, as below.
 
+**This escalation is enforced, not advised.** A tier-2 branch cannot be pushed or opened as a PR until a spec linked to it (`branch: <name>` in its frontmatter) passes `npx @ericrisco/rsc spec gate`. Time pressure does not change the lane: escalate the moment `rsc risk` says tier 2, before writing more code.
+
 ## Isolation
 
 Where the work runs follows the project's decision (asked at install: «main» or «ramas y PR»; rsc

package/skills/implement/SKILL.md

@@ -115,7 +115,7 @@ review of the task, this first one included. Round 1 is the task's first review,
 | --- | --- |
 | 0 | none — the controls (e) still run |
 | 1 | one fresh-context reviewer; frozen brief in `references/per-task-review.md` |
-| 2 | the three refuters (`refuter-correctness` · `refuter-security` · `refuter-tests`) in parallel, as `../review/SKILL.md` runs them |
+| 2 | the three refuters (`refuter-correctness` · `refuter-security` · `refuter-tests`) in parallel, as `../review/SKILL.md` runs them; then `review ledger panel <slug>/<task> --lenses correctness,security,tests` — the push gate checks it |
 
 Every reviewer gets the **spec**, the **diff as a file** (`scripts/review-package <BASE> <HEAD>`, BASE
 = the task's *recorded* base sha, never `HEAD~1`), the **surrounding code** at that sha (not just the

package/skills/review/SKILL.md

@@ -11,7 +11,7 @@ origin: risco
 
 Tests prove the code works, not that it does what was asked. Review answers that other question: **is the diff correct, well-scoped and faithful to the spec — or did it pass for the wrong reasons?** In ASDD (`../asdd/SKILL.md`) it runs in two modes:
 
-- **Per task** — called from `implement`'s loop after each task's self-check. Depth comes from `npx @ericrisco/rsc risk [--base <ref>] [paths…]` (same path table as the sello, works with the sello off): **tier 0** → no review; **tier 1** → one fresh-context reviewer (a subagent that never saw the implementation conversation); **tier 2** → the three-refuter panel below, and the branch will wait for human approval at ship.
+- **Per task** — called from `implement`'s loop after each task's self-check. Depth comes from `npx @ericrisco/rsc risk [--base <ref>] [paths…]` (same path table as the sello, works with the sello off): **tier 0** → no review; **tier 1** → one fresh-context reviewer (a subagent that never saw the implementation conversation); **tier 2** → the three-refuter panel below, recorded after it runs with `npx @ericrisco/rsc review ledger panel <slug>/<task> --lenses correctness,security,tests` (the ship guard refuses to push a tier-2 branch without it — one reviewer is not a panel), and the branch will wait for human approval at ship. The tier reads the diff's content too: auth code in a generic file is tier 2.
 - **Closing review** — once, before `ship`: the whole branch against the spec. Forty individually-correct tasks can still fail to be the feature together: a criterion nobody owned, two tasks that each assumed the other handled an edge, scope that crept in a slice at a time. Read the spec's acceptance criteria and "must respect" list against `git diff <base>...HEAD`, not the task reviews. Its record — tier, counts, verdict, each finding with its outcome — goes to `02-DOCS/wiki/sdd/reviews/<slug>.md`.
 
 This skill owns **two roles that share one discipline**:

package/skills/ship/SKILL.md

@@ -246,6 +246,7 @@ In the `orient` voice: the explainer, the checklist result in one line, the thre
 | "I'll add `Co-Authored-By: Claude` / a 'Generated with Claude Code' footer to be transparent" | It forges the record. The work is the responsible person's — no AI trailer, ever. Strip it. |
 | "Review didn't formally approve but it's obviously fine" | No verdict = not ready. Ship runs on APPROVE only. Route back to review. |
 | "Tier 2, but the three refuters approved — I'll self-merge" | An agent's approval never counts as a human's. Tier 2 waits for human approval. |
+| "Tier 2, one reviewer was enough here" | The push gate wants the panel recorded (`review ledger panel … --lenses correctness,security,tests`). Run the three, record them, then push. |
 | "The tree has a couple of stray edits, they're harmless" | A dirty tree means the merge is not the reviewed diff. Clean it or stash it first. |
 | "`main` is protected but I'll just force-merge, I'm sure" | Protected means PR. Don't bypass the gate the repo deliberately set. |
 | "No remote and the guard denies the merge — I'll merge another way" | The denial is the answer. Park the branch with the merge command for the human. |

package/skills/specify/SKILL.md

@@ -199,6 +199,8 @@ empty sections by name, exits non-zero on any `FAIL`, and prints what it does **
 unmarked assumption is yours to catch, because no parser can. A red gate means the spec is not
 closed: name the section that failed and fix it before step 9.
 
+When the work already lives on a branch, put `branch: <name>` in the spec's frontmatter: for a tier-2 change (`rsc risk`) the ship guard refuses push and PR until a spec linked to the branch passes the gate.
+
 ### Fresh-eyes spec review (step 8, scaled to the stakes)
 
 The author's own context is blind to its own gaps — the same mind that wrote the spec self-reviews it

package/targets/asdd-gate.mjs

@@ -0,0 +1,134 @@
+// ASDD escalation gate — the deterministic half of "tier 2 in FTD means ASDD".
+//
+// A real 4.0.2 run took a login (auth → tier 2) down the small-change lane: `rsc risk` said tier 2,
+// the ftd skill said "escalate to asdd", and the agent decided not to — with no spec, so the user
+// registration it added was never recorded as an assumption anyone would review. A rule that bends
+// under time pressure is prose (P2). This makes it a mechanism at the one moment that matters: before
+// a tier-2 branch leaves the machine (`git push`, `gh pr create|merge`), a spec linked to the branch
+// must exist and pass the spec gate.
+//
+// A spec is linked to the branch when its frontmatter says `branch: <branch>`, or when its file name
+// (the slug) IS the branch's last segment (`feat/login` ↔ `specs/login.md`; `_` and `-` alike). Exact,
+// never a substring: `api.md` must not vouch for `feat/rapid-login`.
+// A branch whose tier-2 paths are all harness configuration (an rsc install or upgrade, CLAUDE.md) is
+// not feature work and needs no spec — it still needs a human, as every tier 2 does.
+// Fail-open on any environment problem; opt out per project with `.rsc/.no-asdd-gate`.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { expand } from './shell-unwrap.mjs';
+
+// Options that take a value must swallow it, or `gh -R owner/repo pr create` reads `owner/repo` as
+// the subcommand and slips past.
+const OPTS = String.raw`(?:(?:-[CcR]\s+\S+|--(?:repo|git-dir|work-tree)\s+\S+|--?\S+)\s+)*`;
+const PUSH_OR_PR = new RegExp(String.raw`\bgit\s+${OPTS}push(?![\w-])|\bgh\s+${OPTS}pr\s+${OPTS}(?:create|merge)(?![\w-])`);
+export const SPECS_DIR = join('02-DOCS', 'wiki', 'sdd', 'specs');
+
+// Quoted text is blanked so a mention is not a push; and the segments a shell really runs
+// (`bash -c "git push"`, `eval …`) are judged too — the same unwrapping the sello uses.
+export function isPushOrPr(command) {
+  if (typeof command !== 'string' || !command) return false;
+  const runs = (c) => PUSH_OR_PR.test(c.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""'));
+  return runs(command) || expand(command).some(runs);
+}
+
+function git(root, ...args) {
+  const r = spawnSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], { windowsHide: true, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return r.status === 0 ? (r.stdout || '') : null;
+}
+
+const branchOf = (text) => (/^---\r?\n[\s\S]*?^branch:[ \t]*["']?([^"'\r\n]+?)["']?[ \t]*$[\s\S]*?^---/m.exec(text) || [])[1] || null;
+
+/** The specs linked to `branch`: `{ path, ok, missing, empty }` each. */
+export function linkedSpecs(root, branch, specCompleteness) {
+  let files = [];
+  try { files = readdirSync(join(root, SPECS_DIR)).filter((f) => f.endsWith('.md') && !f.endsWith('.plan.md')); } catch { return []; }
+  const norm = (x) => x.toLowerCase().replace(/_/g, '-');
+  const last = norm(branch.split('/').pop());
+  return files.flatMap((f) => {
+    const text = readFileSync(join(root, SPECS_DIR, f), 'utf8');
+    if (branchOf(text) !== branch && norm(f.slice(0, -3)) !== last) return [];
+    const r = specCompleteness(text);
+    return [{ path: join(SPECS_DIR, f).split('\\').join('/'), ok: r.ok, missing: r.missing, empty: r.empty }];
+  });
+}
+
+// A panel still covers HEAD when its commit is an ancestor of HEAD and this branch's own commits since
+// changed no code. Not code, by the same rules the gate applies above: documentation, the harness's
+// own state (.rsc/ journals, nested worktrees) and harness configuration. Commits that came from the
+// trunk (a merge of main into the branch) are not this branch's work and are not counted.
+function reviewedStill(root, sha, trunk, sello, cfg) {
+  if (!sha) return false;
+  if (spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', sha, 'HEAD'], { windowsHide: true }).status !== 0) return false;
+  const since = [...new Set((git(root, 'log', '--no-merges', '--no-renames', '--format=', '--name-only', `${sha}..HEAD`, `^${trunk}`) || '')
+    .split('\n').map((l) => l.trim()).filter(Boolean))]
+    .filter((n) => !sello.SELLO_STATE_PATHS.includes(n) && !sello.NESTED_WORKTREES.test(n));
+  const { classes } = sello.classifyRisk(since, cfg);
+  return Object.values(classes).every((c) => c === 'docs' || c === 'harness');
+}
+
+// Largest panel recorded in the review ledger for a task of any of these specs (`<slug>/<task>`) that
+// still covers HEAD.
+function panelSize(root, slugs, stillValid = () => true) {
+  let text = '';
+  try { text = readFileSync(join(root, '.rsc', 'review-ledger.jsonl'), 'utf8'); } catch { return 0; }
+  let best = 0;
+  for (const line of text.split('\n')) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e?.type !== 'panel' || typeof e.task !== 'string' || !Array.isArray(e.lenses)) continue;
+    if (!slugs.some((s) => e.task.toLowerCase().replace(/_/g, '-').startsWith(`${s.toLowerCase().replace(/_/g, '-')}/`))) continue;
+    if (!stillValid(e.sha)) continue;
+    best = Math.max(best, new Set(e.lenses.map((l) => String(l).toLowerCase())).size);
+  }
+  return best;
+}
+
+/**
+ * null when the command may go ahead; the denial text (with its way out, P6) when it may not.
+ * `lib` carries the sibling modules so tests and the hook load them the same way.
+ */
+export function asddGate(root, command, { sello, specCompleteness }) {
+  if (!isPushOrPr(command)) return null;
+  if (existsSync(join(root, '.rsc', '.no-asdd-gate'))) return null;
+  const branch = (git(root, 'rev-parse', '--abbrev-ref', 'HEAD') || '').trim();
+  if (!branch || branch === 'HEAD' || branch === 'main' || branch === 'master') return null;
+  const cfg = sello.readEffectiveConfig(root);
+  const trunk = sello.trunkRef(root, cfg);
+  if (!trunk) return null;
+  const base = (git(root, 'merge-base', 'HEAD', trunk) || '').trim();
+  if (!base) return null;
+  const paths = [...new Set([
+    ...(git(root, 'diff', '--name-only', '--no-renames', '-z', base) || '').split('\0'),
+    ...(git(root, 'ls-files', '--others', '--exclude-standard', '-z') || '').split('\0').filter((n) => !sello.NESTED_WORKTREES.test(n)),
+  ].filter(Boolean))].filter((n) => !sello.SELLO_STATE_PATHS.includes(n));
+  const { tier, classes } = sello.classifyChange(paths, sello.changeText(root, base, paths), cfg);
+  if (tier < 2) return null;
+  const tierTwo = [...new Set(Object.values(classes))].filter((c) => c !== 'default' && c !== 'docs');
+  if (tierTwo.length && tierTwo.every((c) => c === 'harness')) return null;
+  const specs = linkedSpecs(root, branch, specCompleteness);
+  const passing = specs.filter((s) => s.ok);
+  if (passing.length) {
+    // The spec exists; now the review it requires. A tier-2 change gets the full panel (three lenses
+    // by default), recorded against one of its linked specs in the review ledger.
+    const required = sello.lensesRequired(2, cfg);
+    const slugs = passing.map((s) => s.path.split('/').pop().slice(0, -3));
+    const best = panelSize(root, slugs, (sha) => reviewedStill(root, sha, trunk, sello, cfg));
+    if (best >= required) return null;
+    return `Branch "${branch}" is risk tier 2 and its spec passes, but no review panel of ${required} lens(es) is recorded for it` +
+      `${best ? ` (largest still valid: ${best})` : ''}. Tier 2 is reviewed by the full panel, not by one reviewer, and a panel covers ` +
+      'the commit it was recorded on: code committed after it needs the panel again (the record is self-attested, like the sello). ' +
+      `Recover: run the ${required} fresh-context refuters (correctness, security, tests) on the branch, then record it — ` +
+      `\`npx @ericrisco/rsc review ledger panel ${slugs[0]}/closing --lenses correctness,security,tests\` — and push again. ` +
+      'To turn this gate off for the project: create `.rsc/.no-asdd-gate`.';
+  }
+  const why = [...new Set(Object.values(classes).filter((c) => c !== 'default' && c !== 'docs'))].join(', ');
+  const found = specs.length
+    ? `The linked spec does not pass the gate: ${specs.map((s) => `${s.path} (missing: ${[...s.missing, ...s.empty].join(', ') || '—'})`).join('; ')}. `
+    : `No spec in ${SPECS_DIR.split('\\').join('/')}/ is linked to "${branch}". `;
+  return `Branch "${branch}" is risk tier 2 (${why || 'tier 2'}): tier 2 is ASDD work, and it does not leave this machine without an approved spec. ` +
+    found +
+    'Recover: write the spec with the `specify` skill (the four questions: what the user can do, what result they get, what it must respect, how it proves it; ' +
+    `plus out of scope), put \`branch: ${branch}\` in its frontmatter, check it with \`npx @ericrisco/rsc spec gate <spec>\`, and push again. ` +
+    'Anything decided without the person goes to the decision queue as review-after. To turn this gate off for the project: create `.rsc/.no-asdd-gate`.';
+}

package/targets/claude.js

@@ -187,6 +187,9 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sello.mjs is ship-guard's sibling import (hooks are materialized file-by-file,
   // so the deterministic sello core must land next to the guard that loads it).
   copyFileSync(join(HERE, 'sello.mjs'), join(paths.projectRoot, '.rsc', 'sello.mjs'));
+  // The ASDD escalation gate and the spec section check it runs — siblings of the guard, same reason.
+  copyFileSync(join(HERE, 'asdd-gate.mjs'), join(paths.projectRoot, '.rsc', 'asdd-gate.mjs'));
+  copyFileSync(join(HERE, 'spec-completeness.mjs'), join(paths.projectRoot, '.rsc', 'spec-completeness.mjs'));
   const sgCmd = viaBootstrap('guard', at('.rsc', 'ship-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
@@ -240,7 +243,8 @@ export function wireHook(paths, sourceMd, policy = {}) {
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),
   );
   settings.hooks.UserPromptSubmit.push({ hooks: [{ type: 'command', command: fgCmd }] });
-  written.push(sgDest, gmDest, fgDest, bgDest, join(paths.projectRoot, '.rsc', 'sello.mjs'), join(paths.projectRoot, '.rsc', 'trunk-policy.mjs'));
+  written.push(sgDest, gmDest, fgDest, bgDest, join(paths.projectRoot, '.rsc', 'sello.mjs'), join(paths.projectRoot, '.rsc', 'trunk-policy.mjs'),
+    join(paths.projectRoot, '.rsc', 'asdd-gate.mjs'), join(paths.projectRoot, '.rsc', 'spec-completeness.mjs'));
   } else {
     for (const event of ['PreToolUse', 'UserPromptSubmit']) {
       if (!settings.hooks[event]) continue;
@@ -251,7 +255,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
       });
       if (!settings.hooks[event].length) delete settings.hooks[event];
     }
-    const gone = ['ship-guard.mjs', 'branch-guard.mjs', 'gitmoji-guard.mjs', 'sello.mjs', ...(laneGate ? [] : ['trunk-policy.mjs', 'userprompt-gate.mjs'])];
+    const gone = ['ship-guard.mjs', 'branch-guard.mjs', 'gitmoji-guard.mjs', 'sello.mjs', 'asdd-gate.mjs', 'spec-completeness.mjs', ...(laneGate ? [] : ['trunk-policy.mjs', 'userprompt-gate.mjs'])];
     for (const name of gone) rmSync(join(paths.projectRoot, '.rsc', name), { force: true });
     if (laneGate) {
       // Same per-turn gate as a governed project: the lane, and where code changes go here.

package/targets/clone-bootstrap.mjs

@@ -43,7 +43,7 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
  * nothing checks is just drift with a head start.
  */
 export const PROJECT_OPT_OUTS = [
-  'audit', 'auto-update', 'claudemd-check', 'copy-guard', 'danger-guard', 'feature-gate', 'ftd-close', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
+  'asdd-gate', 'audit', 'auto-update', 'claudemd-check', 'copy-guard', 'danger-guard', 'feature-gate', 'ftd-close', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
 ];
 
 /**

package/targets/opt-outs.js

@@ -17,6 +17,7 @@
 
 /** Decisions of the project: they belong in `.rsc.json` and are rebuilt in a clone. */
 export const PROJECT_OPT_OUTS = [
+  'asdd-gate',        // a tier-2 branch cannot be pushed without a spec linked to it (ship guard)
   'audit',            // cadence of this project's skill audit
   'auto-update',      // installing new rsc releases alone: one machine ahead moves the team's catalogVersion
   'claudemd-check',   // the root CLAUDE.md context budget

package/targets/sello.mjs

@@ -202,6 +202,97 @@ export function classifyRisk(paths, cfg = null) {
   return { tier, classes, lowered, configError };
 }
 
+// ---------------------------------------------------------------- content signals
+// A path table only sees code that lives where its name says. A real 4.0.3 run put a whole login —
+// password hashing, session cookies — into `src/app.js`: tier 1 by path, so no gate and no panel would
+// have fired had the spec not happened to be called `login.md`. These rows read WHAT the change adds:
+// code that hashes passwords, sets session cookies, moves money, alters a schema or carries a secret
+// is high risk wherever it lives. Still deterministic (P1): fixed patterns over the added lines, never
+// a judgement. Documentation is not scanned — a spec that talks about passwords is not auth code.
+export const CONTENT_RISK = [
+  // Operations, not words: hashing or verifying a password, issuing a session or token. A login form's
+  // `type="password"` or an i18n string is not auth code (closing review, 4.0.4).
+  { class: 'auth', scope: 'code', pattern: String.raw`\b(?:bcrypt(?:js)?|argon2(?:id|i|d)?)\.(?:hash|compare|verify)(?:Sync)?\s*\(|\b(?:scrypt|scryptSync|pbkdf2|pbkdf2Sync|timingSafeEqual|createHmac)\s*\(|\bjwt\.(?:sign|verify)\s*\(|\b(?:password_hash|password_verify)\s*\(|\bpassport\.(?:use|authenticate)\s*\(|\b(?:getServerSession|verifyIdToken|signInWith[A-Z]\w*)\s*\(|\bres\.cookie\s*\(\s*(?:['"\x60](?:sid|session|token|auth)|[A-Z_]*(?:SESSION|SID|TOKEN|AUTH))|\bpromisify\s*\(\s*(?:crypto\.)?(?:scrypt|pbkdf2)\b|\b(?:jwtVerify|SignJWT)\b|\breq\.session\.(?:\w+\s*=[^=]|regenerate\s*\()|\bcreateSession\s*\(|set-cookie['"\x60]?\s*[,:]\s*['"\x60]?\s*\x60?(?:sid|session|token|auth)\w*=` },
+  { class: 'billing', scope: 'code', pattern: String.raw`\b(?:paymentIntents|charges|refunds|subscriptions|checkout\.sessions|invoices)\.(?:create|update|confirm|capture)\s*\(|\bprocess\.env\.(?:STRIPE|PAYPAL|BRAINTREE|ADYEN)_\w+` },
+  { class: 'migrations', scope: 'code', pattern: String.raw`\b(?:ALTER\s+TABLE|DROP\s+(?:TABLE|COLUMN)|CREATE\s+TABLE|ADD\s+COLUMN|RENAME\s+COLUMN)\b` },
+  // A secret is a leak wherever it is added — tests, config and docs included.
+  { class: 'secrets', scope: 'all', pattern: String.raw`-----BEGIN [A-Z ]*PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\b[sr]k_live_[0-9a-zA-Z]{16,}|\bgh[pousr]_[0-9A-Za-z]{30,}` },
+];
+// What `code` rows never read: tests and fixtures, lockfiles, minified bundles, docs, and comment lines.
+const NOT_CODE = /(?:^|\/)(?:tests?|__tests__|spec|fixtures?|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|poetry\.lock|Gemfile\.lock|composer\.lock|go\.sum)$|\.min\.(?:js|css)$/;
+const COMMENT_LINE = /^\s*(?:\/\/|#|\*|\/\*|<!--|--\s)/;
+const CONTENT_MAX_BYTES = 1024 * 1024;
+
+// The text a change ADDS, per path: added lines of the diff against `base` for tracked files, the
+// whole file for untracked ones (or for every path when there is no base — an explicit `rsc risk
+// <paths>`). One whole-tree diff, filtered after: a pathspec per file overflows the argument list on a
+// large change, and a large change must not get LESS scrutiny than a small one. Unreadable or huge
+// files are skipped: the path row still scores them.
+export function changeText(rawRoot, base, paths) {
+  const root = resolveRoot(rawRoot);
+  const out = {};
+  const wanted = new Set(paths);
+  const readWhole = (p) => {
+    try {
+      const st = lstatSync(join(root, p));
+      if (st.isFile() && st.size <= CONTENT_MAX_BYTES) out[p] = readFileSync(join(root, p), 'utf8');
+    } catch { /* gone or unreadable */ }
+  };
+  if (!base) { paths.forEach(readWhole); return out; }
+  const tracked = new Set(nulList(git(root, 'ls-files', '-z')));
+  const diff = git(root, 'diff', '-U0', '--no-renames', '--no-color', base) || '';
+  let cur = null;
+  let header = false;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('diff --git ')) { header = true; cur = null; continue; }
+    if (header) {
+      // git quotes a path with a tab, newline or quote even under core.quotePath=false: "b/tab\tx.js".
+      const q = /^\+\+\+ "b\/((?:[^"\\]|\\.)*)"$/.exec(line);
+      const m = q ? [null, q[1].replace(/\\([tn"\\])/g, (_, c) => ({ t: '\t', n: '\n', '"': '"', '\\': '\\' })[c])]
+        : /^\+\+\+ b\/(.+?)\t?$/.exec(line);
+      if (m && wanted.has(m[1])) { cur = m[1]; out[cur] ||= ''; }
+      if (line.startsWith('@@')) header = false;
+      continue;
+    }
+    if (line.startsWith('@@')) continue;
+    if (cur && line.startsWith('+')) out[cur] += `${line.slice(1)}\n`;
+  }
+  paths.filter((p) => !tracked.has(p)).forEach(readWhole);
+  return out;
+}
+
+// Path rows and content rows together. A path scores the higher of the two; `content` lists each
+// content hit (path, class, the matched text) so the reader can see why. Lowered classes apply to
+// content rows too; floor classes stay at tier 2.
+export function classifyChange(paths, texts = {}, cfg = null) {
+  const byPath = classifyRisk(paths, cfg);
+  const lowered = byPath.lowered || [];
+  const content = [];
+  let { tier } = byPath;
+  const classes = { ...byPath.classes };
+  const rowTier = (cls) => (lowered.includes(cls) && !FLOOR_CLASSES.includes(cls) ? 1 : 2);
+  const docs = new RegExp(RISK_TABLE.find((r) => r.class === 'docs').pattern);
+  for (const [p, text] of Object.entries(texts)) {
+    if (!text) continue;
+    const codeText = docs.test(p) || NOT_CODE.test(p) ? '' : text.split('\n').filter((l) => !COMMENT_LINE.test(l)).join('\n');
+    for (const row of CONTENT_RISK) {
+      const m = new RegExp(row.pattern, row.scope === 'all' ? '' : 'i').exec(row.scope === 'all' ? text : codeText);
+      if (!m) continue;
+      const t = rowTier(row.class);
+      content.push({ path: p, class: row.class, match: m[0].slice(0, 60) });
+      if (t > classifyRisk([p], cfg).tier) classes[p] = row.class;
+      if (t > tier) tier = t;
+      break;
+    }
+  }
+  return { ...byPath, tier, classes, content };
+}
+
+export function classifyCandidate(rawRoot, candidate, cfg = null) {
+  const paths = Object.keys(candidate.files);
+  return classifyChange(paths, changeText(rawRoot, candidate.base, paths), cfg);
+}
+
 // How many lenses a tier requires (capped by an explicit config knob, floor 1).
 export function lensesRequired(tier, cfg = null) {
   const base = tier === 0 ? 0 : tier === 1 ? 1 : 3;
@@ -418,7 +509,7 @@ export function checkSello(rawRoot) {
   const paths = Object.keys(candidate.files);
   if (paths.length === 0) return { ok: true, code: 'clean' };
 
-  const risk = classifyRisk(paths, cfg);
+  const risk = classifyCandidate(root, candidate, cfg);
   // P7 first, before any sello state is consulted: a docs-only change must never
   // be blocked by a leftover sello from some other change.
   if (risk.tier === 0) return { ok: true, code: 'risk0' };

package/targets/ship-guard.mjs

@@ -61,6 +61,17 @@ try {
   }
 } catch { /* sello lib missing/unloadable → nothing to enforce, fail open */ }
 
+// ---- ASDD escalation gate ---------------------------------------------------
+// A tier-2 branch does not leave the machine (push, PR) without a spec linked to it that passes the
+// spec gate. Its own opt-out (.rsc/.no-asdd-gate); fail-open if a sibling is missing.
+try {
+  const sello = await import(new URL('./sello.mjs', import.meta.url));
+  const { specCompleteness } = await import(new URL('./spec-completeness.mjs', import.meta.url));
+  const { asddGate } = await import(new URL('./asdd-gate.mjs', import.meta.url));
+  const verdict = asddGate(root, command, { sello, specCompleteness });
+  if (verdict) deny(verdict);
+} catch { /* sibling missing/unloadable → nothing to enforce, fail open */ }
+
 // Ship-guard's own opt-out (branch hygiene only — the sello above already ran).
 if (existsSync(join(root, '.rsc', '.no-ship-guard'))) allow();
 

package/targets/spec-completeness.mjs

@@ -0,0 +1,216 @@
+// The spec exit gate's section check, as a self-contained module. It lives in targets/ because it is
+// installed next to the hooks (`.rsc/`) — the ship guard needs it in a user project, where scripts/lib
+// does not exist — and scripts/lib/spec-gate.js re-exports it, so there is one implementation.
+
+// `timestamp:` from the leading frontmatter block, quotes stripped. Anything else → null (exempt),
+// which is what the full frontmatter parser yielded for these specs.
+function frontmatterTimestamp(markdown) {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(markdown ?? ''));
+  if (!fm) return null;
+  const m = /^timestamp:[ \t]*(.+?)[ \t]*$/m.exec(fm[1]);
+  return m ? m[1].replace(/^(['"])(.*)\1$/, '$2') : null;
+}
+
+// The two families below are NOT retroactive. The corpus is 34 specs written before this rule
+// existed, and none of them can answer "what if we don't build it" honestly after the fact; a gate
+// that turns 34 files red gets switched off within a week. So the requirement starts on a date, and
+// the date is derived from the file's own `timestamp:` — not from a list of exempted specs, which
+// 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
+  'suposición tomada', // we decided, with the basis written → clarify validates it
+  'decisión diferida', // sharp, out of this cycle on purpose → clarify leaves it
+  'área no formulable', // known to be coming, not yet sharp → clarify notes it
+];
+
+// The corpus is Spanish, the template is English, and both carry drifting parentheticals
+// ("Objetivos (resultado)", "Criterios de aceptación (binarios)"). Matching literal strings would
+// be useless, so each family is a set of normalised prefixes.
+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', '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'] },
+  open: {
+    prefixes: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
+  },
+  // A spec that cannot say what happens if nobody builds it has not been interrogated, only
+  // de-risked. `since` is what keeps that demand off the specs written before it existed.
+  inaction: {
+    prefixes: [
+      'que pasa si no lo construimos', '¿que pasa si no lo construimos',
+      'coste de no construirlo', 'el coste de no construirlo',
+      'cost of not building', 'the cost of not building',
+    ],
+    since: NEW_FAMILIES_SINCE,
+  },
+  cheapest: {
+    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 = [
+  'que ninguna sección contenga una suposición sin marcar (no es detectable por máquina; es el juicio que la fase existe para ejercer)',
+  'que el contenido de cada sección sea correcto, y no sólo presente',
+  'que los criterios de aceptación sean de verdad binarios',
+  // Added with the status check below, for the same reason the three above exist: a green that is
+  // narrower than the rule it appears to enforce is the decorative gate all over again.
+  'si una spec dice "implementada" sin nombrar commit, PR ni versión (no hay nada que ir a mirar)',
+  'si el trabajo de una spec que se declara sin aterrizar llegó por otra vía (git no lo distingue)',
+  // 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) {
+  return s
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .trim();
+}
+
+function familyOf(heading) {
+  const h = fold(heading);
+  for (const [family, { prefixes }] of Object.entries(FAMILIES)) {
+    if (prefixes.some((p) => h.startsWith(p))) return family;
+  }
+  return null;
+}
+
+// A heading with nothing under it is not a filled section. Neither is one holding only the
+// template's own italic/angle-bracket guidance, which is what a hurried pass leaves behind.
+function isSubstantive(line) {
+  const t = line.trim();
+  if (!t) return false;
+  if (/^<.*>$/.test(t)) return false; // <guidance from the template>
+  if (/^\*[^*].*\*$/.test(t) && t.length < 200) return false; // *italic guidance*
+  if (/^(-|\*)\s*$/.test(t)) return false; // an empty bullet
+  return true;
+}
+
+// The template's guidance does not fit on one line, and a section still holding it is a section
+// nobody filled in. The single-line check above never saw those: `<What concretely happens if` does
+// not end in `>`, so it read as content and an untouched template passed the gate green.
+//
+// Only a block that actually CLOSES counts as guidance. A stray `<` that never finds its `>` — a
+// latency budget written `<400ms`, a generic in a code sample — stays content, because guessing
+// wrong in that direction hides real prose.
+function guidanceLines(lines) {
+  const skip = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    const t = lines[i].trim();
+    if (!t.startsWith('<') || t.endsWith('>')) continue;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const u = lines[j].trim();
+      if (u === '' || u.startsWith('#')) break; // the block ended without closing: not guidance
+      if (u.endsWith('>')) {
+        for (let k = i; k <= j; k += 1) skip.add(k);
+        i = j;
+        break;
+      }
+    }
+  }
+  return skip;
+}
+
+function hasSubstance(lines) {
+  const guidance = guidanceLines(lines);
+  return lines.some((line, i) => !guidance.has(i) && isSubstantive(line));
+}
+
+// The day this spec was written, as YYYY-MM-DD, or null when there is nothing trustworthy to read.
+// Null always means EXEMPT: a spec we cannot date is not a spec we get to fail. Three ways to land
+// there, and all three are safe — the CLI itself calls specCompleteness('') to print `unchecked`,
+// and parseFrontmatter throws on that.
+function specDay(markdown) {
+  try {
+    const raw = frontmatterTimestamp(markdown);
+    if (typeof raw !== 'string') return null;
+    const day = raw.slice(0, 10); // ISO order is lexicographic order; no timezone maths needed
+    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : null;
+  } catch {
+    return null;
+  }
+}
+
+function requiredFamilies(markdown) {
+  const day = specDay(markdown);
+  return Object.entries(FAMILIES)
+    .filter(([, { since }]) => !since || (day !== null && day >= since))
+    .map(([family]) => family);
+}
+
+function parseOpenPoints(lines) {
+  const points = [];
+  for (const line of lines) {
+    const m = line.match(/^\s*[-*]\s+(?:\[[ x]\]\s*)?(.*)$/);
+    if (!m || !m[1].trim()) continue;
+    const body = m[1];
+    const declared = OPEN_POINT_TYPES.find((t) => {
+      const re = new RegExp(`^\\*\\*\\s*${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\*\\*`, 'i');
+      return re.test(fold(body)) || re.test(body);
+    });
+    points.push({
+      type: declared || OPEN_POINT_TYPES[0], // the costliest default: treat it as a real question
+      typed: Boolean(declared),
+      text: body.trim(),
+    });
+  }
+  return points;
+}
+
+/**
+ * @param {string} markdown a written spec file
+ * @returns {{ok: boolean, missing: string[], empty: string[],
+ *            openPoints: Array<{type: string, typed: boolean, text: string}>,
+ *            untyped: string[], unchecked: string[]}}
+ */
+export function specCompleteness(markdown) {
+  const lines = String(markdown ?? '').split('\n');
+  const sections = new Map(); // family -> body lines
+
+  let current = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h) {
+      const fam = familyOf(h[1]);
+      current = fam;
+      if (fam && !sections.has(fam)) sections.set(fam, []);
+      continue;
+    }
+    if (current && sections.has(current)) sections.get(current).push(line);
+  }
+
+  const families = requiredFamilies(markdown);
+  const missing = families.filter((f) => !sections.has(f));
+  const empty = families.filter((f) => sections.has(f) && !hasSubstance(sections.get(f)));
+
+  const openPoints = sections.has('open') ? parseOpenPoints(sections.get('open')) : [];
+  const untyped = openPoints.filter((p) => !p.typed).map((p) => p.text);
+
+  return {
+    ok: missing.length === 0 && empty.length === 0,
+    missing,
+    empty,
+    openPoints,
+    untyped,
+    unchecked: UNCHECKED,
+  };
+}
+