@ericrisco/rsc 4.0.2 → 4.0.3

package/manifest.json

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

package/package.json

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

@@ -48,6 +48,8 @@ export function assess(paths, cfg = null) {
     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,
     ...(configError ? { configError } : {}),
   };
@@ -61,6 +63,7 @@ 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}`] : []),
     ...top.slice(0, 20).map(([p, c]) => `  ${c.padEnd(10)} ${p}`),
     ...(top.length > 20 ? [`  … ${top.length - 20} more`] : []),

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/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/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,89 @@
+// 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 }];
+  });
+}
+
+/**
+ * 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.classifyRisk(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);
+  if (specs.some((s) => s.ok)) return null;
+  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/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,
+  };
+}
+