@ericrisco/rsc 1.0.26 → 1.0.27

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.26",
+  "version": "1.0.27",
   "counts": {
     "skills": 264
   },
@@ -4557,7 +4557,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 one-question-at-a-time 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 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`).",
       "tags": [
         "sdd",
         "spec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "drift:check": "node scripts/drift-check.js",
     "drift:knowledge": "node scripts/drift-check.js --knowledge",
     "knowledge:doctor": "node scripts/knowledge-doctor.js",
+    "spec:gate": "node scripts/spec-gate.js",
     "routing:audit": "node scripts/routing-audit.js",
     "test": "node --test",
     "coverage": "c8 --reporter=text node --test",

package/scripts/build-manifest.js

@@ -3,14 +3,15 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv';
 import { parseFrontmatter } from './lib/frontmatter.js';
+import { fenceBalance } from './lib/skill-lint.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const SKILLS = join(ROOT, 'skills');
 
-function skillDirs() {
-  return readdirSync(SKILLS).filter((d) => {
+function skillDirs(base = SKILLS) {
+  return readdirSync(base).filter((d) => {
     try {
-      return statSync(join(SKILLS, d)).isDirectory() && statSync(join(SKILLS, d, 'SKILL.md')).isFile();
+      return statSync(join(base, d)).isDirectory() && statSync(join(base, d, 'SKILL.md')).isFile();
     } catch {
       return false;
     }
@@ -47,6 +48,20 @@ export function validateFrontmatter() {
   return errors;
 }
 
+// A skill body whose code-block delimiters do not pair renders half its content as one code block,
+// and every other gate stays green while it happens. Deterministic defect, deterministic check —
+// and it lives here so `prepublishOnly` can never ship one.
+export function validateBodies(base = SKILLS) {
+  const errors = [];
+  for (const id of skillDirs(base)) {
+    const r = fenceBalance(readFileSync(join(base, id, 'SKILL.md'), 'utf8'));
+    if (!r.balanced) {
+      errors.push(`${id}: unbalanced code-block delimiter opened at line ${r.opened} (${r.fences} found)`);
+    }
+  }
+  return errors;
+}
+
 // A skill's `description` is in context on every turn it is installed, invoked or not, so the
 // catalog's total description weight is the one number that scales with the catalog itself.
 // The hard failure stays at the schema limit; this reports the soft ceiling the rubric asks for,
@@ -67,9 +82,10 @@ function main() {
   const arg = process.argv[2];
   const out = join(ROOT, 'manifest.json');
   if (arg === '--validate') {
-    const errs = validateFrontmatter();
+    const errs = [...validateFrontmatter(), ...validateBodies()];
     if (errs.length) { console.error(errs.join('\n')); process.exit(1); }
     console.log('frontmatter OK');
+    console.log('skill bodies OK (code-block delimiters balanced)');
     const w = descriptionWeight();
     console.log(
       `description weight: ${(w.total / 1024).toFixed(1)} KB across ${w.count} skills `

package/scripts/lib/skill-lint.js

@@ -0,0 +1,29 @@
+// Structural lint of a skill body. Pure: give it the text, get a verdict.
+//
+// Scope is deliberately one defect class. A stray closing delimiter inverts every block boundary
+// after it, so a skill can render half its body as one code block while every other gate stays
+// green: the frontmatter validates, the description fits, the prose reads fine in the source. It is
+// a purely deterministic defect, so it belongs to a binary, not to a reader's attention.
+
+const FENCE = /^(?:```|~~~)/;
+
+/**
+ * @param {string} body raw skill markdown
+ * @returns {{balanced: boolean, fences: number, opened: number|null}}
+ *   `fences` counts column-0 delimiters; `opened` is the 1-indexed line of the unpaired one.
+ */
+export function fenceBalance(body) {
+  const lines = String(body ?? '').split('\n');
+  let open = null; // line number of the delimiter that opened the current block
+  let fences = 0;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    // Only a column-0 delimiter is a block boundary. Indented ones are content: a fenced sample
+    // inside a fenced block. Counting those would flag correct documents.
+    if (!FENCE.test(lines[i])) continue;
+    fences += 1;
+    open = open === null ? i + 1 : null;
+  }
+
+  return { balanced: open === null, fences, opened: open };
+}

package/scripts/lib/spec-gate.js

@@ -0,0 +1,122 @@
+// The exit gate of the `specify` phase, as a binary instead of a feeling.
+//
+// "Stop when the WHAT and WHY are complete enough to plan against" cannot tell done from not-done,
+// so the phase closed whenever the agent felt closed — with the write/review/approve steps visible
+// the whole time, pulling attention toward being finished. This checks the artifact instead: every
+// template section carries content or an explicit open point.
+//
+// What it does NOT check is returned in `unchecked`, on purpose. Detecting an unmarked assumption is
+// 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.
+
+// 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: ['problema & por que', 'problema y por que', 'problem & why'],
+  goals: ['objetivos', 'goals'],
+  nongoals: ['no-objetivos', 'no objetivos', 'non-goals'],
+  users: ['usuarios & contexto', 'usuarios y contexto', 'users & context'],
+  behaviour: ['comportamiento', 'behaviour', 'behavior'],
+  acceptance: ['criterios de aceptacion', 'acceptance criteria'],
+  open: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
+};
+
+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',
+];
+
+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;
+}
+
+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 = Object.keys(FAMILIES);
+  const missing = families.filter((f) => !sections.has(f));
+  const empty = families.filter((f) => sections.has(f) && !sections.get(f).some(isSubstantive));
+
+  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,
+  };
+}

package/scripts/spec-gate.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Runs the `specify` exit gate over written specs. Report-only: it never edits a spec.
+//
+// Not wired into `prepublishOnly`, and that is deliberate: specs live under 02-DOCS, which is never
+// tracked (principle 9), so a publish gate depending on them would fail in any clean clone. This is
+// the phase's own instrument, and the author's.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { specCompleteness } from './lib/spec-gate.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_DIR = join(ROOT, '02-DOCS', 'wiki', 'sdd', 'specs');
+
+function defaultTargets() {
+  try {
+    return readdirSync(DEFAULT_DIR)
+      .filter((f) => f.endsWith('.md') && !f.endsWith('.plan.md'))
+      .map((f) => join(DEFAULT_DIR, f));
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const targets = args.length ? args : defaultTargets();
+  if (!targets.length) {
+    console.log('no specs found — pass a path, or write one to 02-DOCS/wiki/sdd/specs/');
+    return;
+  }
+
+  let failed = 0;
+  for (const path of targets) {
+    const r = specCompleteness(readFileSync(path, 'utf8'));
+    const name = basename(path);
+    if (r.ok) {
+      const typed = r.openPoints.length - r.untyped.length;
+      console.log(`PASS  ${name} — ${r.openPoints.length} open point(s), ${typed} typed`);
+      if (r.untyped.length) {
+        console.log(`      untyped (treated as open questions): ${r.untyped.length}`);
+      }
+    } else {
+      failed += 1;
+      console.log(`FAIL  ${name}`);
+      if (r.missing.length) console.log(`      missing section(s): ${r.missing.join(', ')}`);
+      if (r.empty.length) console.log(`      section(s) with no content: ${r.empty.join(', ')}`);
+    }
+  }
+
+  // A green here is narrower than the rule it enforces, so it says so every run rather than
+  // letting the reader assume the gate covered more than it did.
+  console.log(`\n${targets.length - failed}/${targets.length} pass. Not checked by this gate:`);
+  for (const u of specCompleteness('').unchecked) console.log(`  - ${u}`);
+  if (failed) process.exit(1);
+}
+
+main();

package/skills/clarify/SKILL.md

@@ -28,12 +28,36 @@ This is the fourth phase of the rsc SDD chain (`constitution` → `specify` →
 
 Clarify never works blind. Before asking a single question, load three things:
 
-1. **The spec.** Read the target spec under `02-DOCS/wiki/sdd/specs/<slug>.md` end to end. If the path wasn't given, find the most recently touched spec or ask which one.
+1. **The spec.** Read the target spec under `02-DOCS/wiki/sdd/specs/<slug>.md` end to end. If the path wasn't given, find the most recently touched spec or ask which one. Its *Points to clarify* is a **typed** handoff, not a question list — read the types before you plan a single question (below).
 2. **The constitution.** Read `02-DOCS/wiki/sdd/constitution.md` if it exists. Its principles (stack canon, quality bars, conventions) resolve a surprising number of "ambiguities" without bothering the user — if the constitution already fixes the auth method or the data region, that's answered, not open.
 3. **The harness profile.** `02-DOCS/wiki/harness/user-profile.md`, for the dial above.
 
 Citing what you read ("checked the constitution — auth is already fixed to OAuth, so that's not an open question") shows your work and prevents re-litigating settled decisions.
 
+## The typed handoff — what `specify` already decided
+
+*Points to clarify* holds four different objects, and each one gets a different action from you.
+Treating all four as questions is how clarify re-asks what was already decided and disturbs what was
+deliberately deferred:
+
+| Type in the spec | What it means | Your action |
+| --- | --- | --- |
+| **pregunta abierta** | Formulable, unanswered | Ask it — this is your queue |
+| **suposición tomada** | `specify` decided it; the basis is written | **Validate**, don't re-ask: state the assumption and its basis back, and ask only whether it still holds |
+| **decisión diferida** | Sharp, out of this cycle on purpose | Leave it. Do not reopen scope the author closed |
+| **área no formulable** | Known to be coming, not yet phrasable | Note it. If your pass sharpens it into a real question, it graduates — say that it did |
+
+**Declare what you did with each entry.** Close the pass with one line per point: asked, validated
+(held / broke), left deferred, or graduated. An entry you silently dropped is the gap that comes back
+at implementation time.
+
+**An untyped entry** (an older spec, or a hurried one) is read as **pregunta abierta** — the
+costliest reading, so nothing gets skipped by accident. Type it as you go, so the spec improves on
+the way through.
+
+Sharpness, not difficulty, is what separates a question from an unformulable area: *can you state it
+precisely now?* Not *can you answer it?*
+
 ## The ambiguity taxonomy — where specs hide their gaps
 
 Scan the spec against these categories. Most real gaps fall into one of them; walking the list is how you find the ones the author didn't think to write down.
@@ -111,7 +135,7 @@ After baking back, the spec line becomes a bounded, testable behavior with accep
 
 ## Exit gate
 
-The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as dial-sized decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap.
+The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); **every typed point in the handoff has its declared outcome** (asked / validated / left deferred / graduated), with nothing silently dropped; all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as dial-sized decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap.
 
 ## Result envelope
 

package/skills/specify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 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 one-question-at-a-time 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 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`)."
 tags: [sdd, spec, requirements]
 recommends: [clarify, plan]
 profiles: [core, full]
@@ -29,9 +29,11 @@ A **yes engages autopilot** (`../sdd/SKILL.md`): you still write the spec and ev
 
 ## The one rule that defines this skill
 
-**No implementation leaks.** The moment the spec names a framework, a table schema, a library, an endpoint shape, a file path, or an algorithm, it has stopped being a spec. Those decisions belong to `plan` and the stack skills. Specify describes the *observable behaviour and the reason for it*; the system that delivers it is deliberately left open.
+A spec is a **contract**: what the system will observably do, and why that matters. Every line either belongs in the contract or belongs to how the contract gets honoured — and the second kind is `plan`'s, not yours. Framework, table schema, library, endpoint shape, file path, algorithm: all of them are how, so the moment one appears the document has stopped being a contract.
 
-If you cannot describe a requirement without naming the technology, you have found a real question — record it as a point to clarify, do not guess the answer.
+One question settles every judgement call in this skill: **is this a clause of the contract, or a detail of how it gets met?**
+
+If you cannot state a requirement without naming the technology, that is a real open question — record it as a typed point to clarify, do not guess the answer.
 
 ## Model tier — `balanced` (opt-in routing)
 
@@ -41,23 +43,25 @@ This phase's default model tier is **`balanced`** — it drafts the what/why spe
 
 Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment level, and adapt:
 
-- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the spec's scope. Draft, show, move on.
+- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the contract. Draft, show, move on.
 - **L1 "breve"** — one line of *why* per question; ask the few that genuinely matter.
 - **L2 "explica decisiones"** — justify each requirement as you record it; surface the trade-offs you inferred.
-- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one question at a time), confirm each answer before recording it. Ideal for non-technical users.
+- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one round per frontier, never crossing a dependency), confirm each answer before recording it. Ideal for non-technical users.
 
 If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
 
-## Questioning discipline — one at a time, only where you can't infer
+## Questioning discipline — ask the frontier, never cross a dependency
 
-The failure mode of specs is the wall of twenty questions. Avoid it:
+The failure mode of specs is the wall of twenty questions. The cure is not one question per turn: that spends a turn of the user's time per question even when the questions do not touch each other. The cure is the **frontier**.
 
 1. **Infer first.** Read the `constitution` (`02-DOCS/wiki/sdd/constitution.md`), the existing wiki, and sibling specs. Fill every section you reasonably can from what already exists.
-2. **Ask only the gaps that change the spec.** A question earns its place only if a different answer would change scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become *points to clarify*, not questions.
-3. **One focused question per turn.** Ask, wait, record, then ask the next. Never batch. Phrase in the user's technical register.
-4. **When inference and asking both fail, mark it.** Anything you cannot resolve in this pass becomes an explicit entry in *Points to clarify* — that list is the handoff contract to the `clarify` phase, not a defect.
+2. **Ask only the gaps that change the contract.** A gap earns a question only if a different answer would move scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become typed *points to clarify*, not questions.
+3. **Ask the whole frontier in one round.** The frontier is every remaining gap whose prerequisites are already settled — the questions you can ask *now* without guessing at answers you have not heard yet. Number them, give each your recommended answer, then wait. Where the harness offers a native question selector, use it; where it does not, emit the same round as numbered text.
+4. **Never cross a dependency.** A gap whose answer depends on another question open in *this* round belongs to a later round. Recompute the frontier after every set of answers: settled decisions push it outward and unblock what waited on them. If an answer redefines a question you already emitted in the same round, discard that question out loud and re-ask it next round rather than using an answer given under a premise that just moved.
+5. **Facts are your job; decisions are the user's.** When a frontier question needs a fact from the environment, go find it — and do not block on it. A running search is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now.
+6. **When inference and asking both fail, type it.** Anything unresolved becomes a typed entry in *Points to clarify* — the handoff contract to `clarify`, not a defect.
 
-Stop asking when the WHAT and WHY are complete enough to plan against. Remaining unknowns live in *Points to clarify*; you do not need every answer before writing the file.
+A frontier of one is one question, and needs no apology. A frontier of zero is no question at all: never invent one to look diligent.
 
 ## What a good spec contains
 
@@ -71,7 +75,7 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
 | Behaviour | What the system does, in observable terms, incl. main + edge + error paths | A verb that's actually a HOW ("queries", "caches") |
 | Acceptance criteria | Testable, binary checks that say "done" | Vague critera ("works well", "is fast") |
-| Points to clarify | Open questions, assumptions made, decisions deferred | Pretending there are none |
+| Points to clarify | The typed handoff to `clarify` — see the four types below | An untyped list, or pretending there are none |
 
 ### Acceptance criteria carry the weight
 
@@ -85,6 +89,33 @@ Then they see an empty-cart message and the "pay" button is disabled
 
 A criterion that needs a human to "decide if it's good enough" is not done yet — sharpen it or move the soft part to *Points to clarify*.
 
+### Points to clarify carry a type
+
+*Points to clarify* is the handoff to `clarify`, and it holds four different objects that need four
+different actions. An untyped list makes `clarify` treat all of them as questions, so it re-asks what
+you already decided and touches what you deliberately deferred. Type every entry:
+
+| Type | What it is | What `clarify` does with it |
+| --- | --- | --- |
+| **pregunta abierta** | Formulable with precision right now, unanswered | Asks it |
+| **suposición tomada** | You decided it; the basis is written down | Validates it — does it still hold? |
+| **decisión diferida** | Sharp, out of this cycle on purpose | Leaves it alone |
+| **área no formulable** | Known to be coming, not yet sharp enough to phrase | Notes it; it graduates when it sharpens |
+
+The test that separates the last two from a question is **sharpness, not difficulty**: *can you state
+the question precisely now?* — not *can you answer it?* Sharp → **pregunta abierta**. Not sharp →
+**área no formulable**. Beyond what this change is for → `Non-goals`, where it never graduates.
+
+Write the type in bold at the head of the entry, and give a `suposición tomada` its basis:
+
+```text
+- **suposición tomada** — el enlace caduca en minutos, no en horas. *Base:* el patrón de los
+  proveedores que ya usamos. *Riesgo:* si el soporte pide horas, el criterio de aceptación cambia.
+```
+
+An entry with no type is read as **pregunta abierta**, the costliest of the four. The default never
+saves you work.
+
 ## The pass, end to end
 
 Run these in order. It is a collaborative dialogue, not a form you fill in silence — and **you do not skip to a design dump.** Track the steps with a todo list so none is dropped.
@@ -94,23 +125,40 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 2. SCOPE check            → if the request is several independent subsystems, DECOMPOSE into sub-specs first,
                             then brainstorm the FIRST one; each gets its own spec → plan → build cycle
 3. RESTATE in one sentence→ confirm you understood the intent before anything else
-4. ASK, one at a time     → only the gaps that change scope; multiple-choice when you can; wait, record, repeat
+4. ASK the frontier       → only gaps that change the contract; whole frontier per round, numbered, each
+                            with your recommendation; never cross a dependency; wait, record, recompute
 5. PROPOSE 2-3 approaches → distinct directions with honest trade-offs; lead with your recommendation and why
 6. PRESENT the design     → section by section (problem, users, behaviour, acceptance), scaled to complexity;
                             after EACH section ask "does this look right?" and adjust before moving on
 7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in 02-DOCS/wiki/index.md
                             (the Knowledge map; root CLAUDE.md keeps only a short pointer), commit if a repo
-8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline.
-                            On L2/L3 or a high-risk spec, also dispatch a FRESH-EYES review (below)
+8. SELF-REVIEW            → run the EXIT GATE (below) until green; scan for contradictions, ambiguity,
+                            scope creep; fix inline. On L2/L3 or high risk, add a FRESH-EYES review
 9. USER APPROVES          → ask them to read the written spec and confirm; loop on changes until they approve
 10. HAND OFF              → only now, result envelope → clarify/plan. NEVER to implement.
 ```
 
-**The gate is steps 5-9, and it is the point of this skill.** Implementation does not begin — not `plan`-to-code, not a stack skill, not "just a quick version" — until the user has approved the design at step 9. This holds for **every** feature, including ones that feel too small to design; "too simple to spec" is exactly where unexamined assumptions cost the most. The only thing that skips the loop is a literal one-line, zero-risk change (a typo, a copy tweak) — name it as such and do it.
-```
+**Steps 5-9 are the gate**, stated once under *Detect the moment* above and not restated here: approval at step 9 is what unlocks implementation.
 
 `<slug>` is a short kebab-case name derived from the feature (e.g. `bulk-csv-import`, `magic-link-login`). If a spec with that slug exists, read it and update rather than overwrite.
 
+### Exit gate — checked, not felt
+
+"Complete enough to plan against" cannot tell done from not-done, and the write/review/approve steps
+are visible while you are still asking, pulling attention toward being finished. So the bound is a
+property of the **file**, not of your confidence:
+
+> Every template section carries content or an explicit typed open point, and no section holds an
+> unmarked assumption.
+
+Run `npm run spec:gate <path>` on the spec you just wrote (no path: the whole corpus). It reports the
+missing and the empty sections by name, and it prints what it does **not** check — the 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.
+
+A gate that has never been seen fail is not known to work, so this one ships with the test that
+watches it fail and pass (`tests/spec-gate.test.js`).
+
 ### Fresh-eyes spec review (step 8, scaled to the dial)
 
 The author's own context is blind to its own gaps — the same mind that wrote the spec self-reviews it
@@ -191,8 +239,12 @@ A returning user on a new device who does not remember a password.
   link can be requested.
 
 ## Points to clarify
-- Link validity window? (assumed: short, exact value deferred to clarify)
-- Rate-limit on requests per email? (deferred)
+- **pregunta abierta** — ¿cuánto vale la ventana de validez del enlace?
+- **suposición tomada** — la ventana es corta, en minutos. *Base:* el patrón de los proveedores que
+  ya usamos. *Riesgo:* si soporte pide horas, cambia el criterio de aceptación.
+- **decisión diferida** — límite de peticiones por email; fuera de este ciclo.
+- **área no formulable** — qué pasa con las cuentas compartidas; sospecho que hay una pregunta y
+  todavía no sé enunciarla.
 ```
 
 Note what is *absent*: no token format, no table, no email provider, no framework. Those are `plan`'s job.
@@ -226,17 +278,16 @@ The proposal is allowed to mention options and tradeoffs; the spec that follows
 
 ## Anti-patterns → STOP
 
+Only failures with no positive statement elsewhere in this skill. The rules about the frontier, the
+constitution, the 2-3 approaches, the gate, and answer-is-not-approval are stated positively above
+(§Questioning discipline, §Detect the moment, the pass, §Approval is its own exchange) and are not
+repeated here as prohibitions: naming a behaviour makes it more available, not less.
+
 | If you're about to… | Reality / Fix |
 | --- | --- |
 | Name a framework, table, endpoint, or library | That's HOW. Strip it; describe the behaviour instead, or log the open question. |
-| Dump 12 questions in one message | One focused question per turn. Infer the rest from the constitution and wiki. |
-| Ask a question you could answer from the constitution | Read it first. Only ask what genuinely changes the spec. |
 | Write "it should work well / be fast / be intuitive" | Not testable. Make it a binary Given/When/Then or move it to Points to clarify. |
-| Skip the whole loop because "this is too simple to design" | That's the rationalization that wastes the most work. Every feature gets the loop; only a literal one-line, zero-risk change skips. |
-| Present one approach as the answer | Offer 2-3 distinct directions with trade-offs and a recommendation; let the user choose before you write the spec. |
 | Hand to `plan`/`implement` before the user approved the written spec | The approval at step 9 is the gate. No design approved → nothing gets built. |
-| Treat the answer to your question as the approval of the spec | They answered the question, and the answer *changed* the spec. Fold it in, say what changed, show it, ask again. |
-| Write `status: aprobada` after a blanket "just run it" | That is autopilot. Record it as such — the record must not overstate the strongest gate in the chain. |
 | Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
 | Resolve every ambiguity yourself to look finished | Inventing answers is worse than naming gaps. List them in Points to clarify. |
 | Start designing the solution because it's clearer | Stay on WHAT/WHY. The plan is a later, separate phase. |
@@ -287,7 +338,7 @@ If `clarify` surfaces answers, they get baked back into this same spec file. Onl
 - `../plan/SKILL.md` — turns the de-risked spec into a technical implementation plan (the HOW).
 - `../harness/SKILL.md` — the 02-DOCS wiki + accompaniment dial + decisions log this skill honors.
 - `references/spec-template.md` — the exact section template written to `02-DOCS/wiki/sdd/specs/<slug>.md`.
-- `references/eliciting-requirements.md` — inference checklist + the one-question-at-a-time elicitation patterns.
+- `references/eliciting-requirements.md` — inference checklist + the frontier-round elicitation pattern.
 
 ## Orientación (siempre)
 

package/skills/specify/evals/cases.yaml

@@ -63,20 +63,20 @@ should_not_trigger:
 capability:
   - scenario: "A user says: 'I want to add magic-link (passwordless) login.' There is a constitution at 02-DOCS/wiki/sdd/constitution.md but no spec yet. Produce the spec."
     must_include:
-      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only scope-changing questions ONE at a time (not a batch of ten)."
+      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
       - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
       - "Produces the spec sections: Problem & why, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify."
       - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
       - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in the root CLAUDE.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
-      - "Lists honest Points to clarify (e.g. link validity window, rate-limiting) as the handoff rather than inventing those values."
+      - "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
       - "Ends by pointing to the clarify phase as the next step in the SDD chain."
 
   - scenario: "A user pastes a rough one-liner: 'Let users export all their data as a download.' Show how you'd elicit and capture this without over-asking."
     must_include:
       - "Recovers the underlying problem/why rather than treating the feature request as the problem, and inherits any relevant constraints from the constitution."
-      - "Applies the 'would a different answer change the spec?' test and asks only the genuinely scope-changing question(s), one at a time, in the user's register."
+      - "Applies the 'would a different answer change the contract?' test, then splits what is left by dependency: independent gaps go out together in one round with recommendations, and any gap whose answer hinges on another still-open one is held for the next round rather than asked blind."
       - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
-      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to Points to clarify instead of fabricating decisions."
+      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to typed Points to clarify instead of fabricating decisions, and checks the written file against the phase's exit gate before calling it done."
       - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
       - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
       - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."

package/skills/specify/references/eliciting-requirements.md

@@ -31,13 +31,49 @@ and the intent itself. Only what survives as unknown becomes a question or a
 What you genuinely cannot resolve here is exactly what `clarify` exists for.
 Naming it is the correct outcome, not a failure.
 
-## The one-question-at-a-time pattern
+## The frontier pattern
 
-A question earns a turn only if a *different answer would change the spec*.
+A gap earns a question only if a *different answer would change the contract*.
 Apply this test before asking:
 
 > "If they answer A vs B, does a goal, a user, the scope, or an acceptance
-> criterion change?" — No → don't ask; infer or defer. Yes → ask, alone.
+> criterion change?" — No → don't ask; infer or type it as a point to clarify.
+> Yes → it is a question.
+
+Then decide *when* to ask it. Model the gaps as a tree: every decision branches
+into the decisions hanging off it. The **frontier** is every gap whose
+prerequisites are already settled — what you can ask now without guessing at
+answers you have not heard. Ask the whole frontier in one round; ask nothing
+that depends on an answer still pending in that same round.
+
+```text
+Round 1 (frontier: 3 independent gaps)
+❓ **Q1 — <title>**: <body, options if you have them>
+➡️ <your recommended answer>
+---
+❓ **Q2 — <title>**: …
+➡️ …
+---
+❓ **Q3 — <title>**: …
+➡️ …
+
+→ user answers → fold in → recompute the frontier → Round 2
+```
+
+Where the harness offers a native question selector, emit the round through it;
+otherwise emit the numbered text above. Same content either way.
+
+**Facts are yours, decisions are theirs.** A gap that needs a fact from the
+environment (a file, a config, a version) is legwork, not a question: go find
+it. Don't block the round on it — a running search is an unsettled prerequisite,
+so only its dependents wait. Ask the rest of the frontier now.
+
+**A frontier of one** is one question, and needs no apology. **A frontier of
+zero** is silence: never invent a question to look diligent.
+
+**If an answer redefines a question you already emitted this round**, say so and
+drop it. Re-ask it next round. An answer given under a premise that has since
+moved is worse than no answer, because it looks settled.
 
 Phrase by register:
 
@@ -48,8 +84,10 @@ Phrase by register:
 - **Technical / L0-L1** — terse, decision-shaped:
   > "Expired-link recovery in scope, or defer?"
 
-Always: ask → wait → record the answer in the relevant section → confirm at L2/L3
-→ ask the next. Never present a numbered list of ten questions.
+Always: emit the round → wait → record each answer in its section → confirm at
+L2/L3 → recompute the frontier. The thing to avoid was never two questions in
+one message; it was ten questions whose answers depend on each other, which is
+what crossing a dependency produces.
 
 ## Turning answers into testable criteria
 
@@ -64,14 +102,16 @@ link" action that issues a fresh one.
 ```
 
 If the answer is fuzzy ("it should feel fast"), do not invent a number — push
-once for a concrete figure; if none is available, file it under *Points to
-clarify* with the assumption you're carrying meanwhile.
+once for a concrete figure; if none is available, file it as a
+**suposición tomada** with its basis and its risk, which is what makes it
+something `clarify` can validate instead of re-ask.
 
 ## When to stop
 
-Stop eliciting when the WHAT and WHY are complete enough that `plan` could start
-without guessing at scope. Lingering unknowns are fine — they belong in *Points
-to clarify*. Over-asking to feel thorough is itself an anti-pattern: it burns the
+Stop when the frontier is empty: every branch visited, nothing left silently
+assumed. Then run the exit gate (`npm run spec:gate <path>`) on the written
+file — the bound is a property of the artifact, not of your confidence.
+Lingering unknowns are fine, and belong in *Points to clarify*, typed. Over-asking to feel thorough is itself an anti-pattern: it burns the
 user's patience and pushes them to rubber-stamp answers they haven't thought
 through. A short spec with three honest open points beats a long spec with three
 fabricated ones.

package/skills/specify/references/spec-template.md

@@ -50,16 +50,30 @@ checkable by `verify` and convertible to a `tasks` done-check.>
 - Given <state>, When <action>, Then <observable outcome>.
 
 ## Points to clarify
-<The handoff to the `clarify` phase. Open questions, assumptions you made and
-on what basis, decisions deferred. This list being non-empty is normal.>
-- [ ] <Open question> — (assumption made: <…>, basis: <…>)
-- [ ] <Deferred decision>
+<The typed handoff to `clarify`. Every entry declares which of the four it is,
+because each one gets a different action from the next phase. Non-empty is
+normal; untyped is not — an untyped entry is read as `pregunta abierta`, the
+costliest of the four.>
+- **pregunta abierta** — <formulable now, unanswered. clarify asks it.>
+- **suposición tomada** — <what you decided.> *Base:* <why.> *Riesgo:* <what
+  changes if it turns out wrong.> clarify validates it rather than re-asking.
+- **decisión diferida** — <sharp, out of this cycle on purpose. clarify leaves
+  it.>
+- **área no formulable** — <you can tell something is coming and cannot phrase
+  the question yet. clarify notes it; it graduates when it sharpens.>
 ```
 
 ## Field notes
 
 - **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
-  (once `plan` exists). Don't invent other states.
+  (once `plan` exists). Don't invent other states. An approval obtained as a
+  blanket "just run it" is recorded as **approved in autopilot**, not flat.
+- **Before you call it written**, run `npm run spec:gate <path>`. It checks that
+  every section here carries content or an explicit open point, and prints the
+  clauses it cannot check (the unmarked assumption is yours).
+- **Sharpness, not difficulty**, sorts the last two types from the first: *can
+  you state the question precisely now?* Not *can you answer it?* Anything past
+  what this change is for goes to **Non-goals**, where it never graduates.
 - **Behaviour** is where HOW leaks in most. Audit every verb: "queries",
   "caches", "calls", "stores in" are implementation. Replace with the observable
   effect ("shows", "lets the user", "prevents", "remembers across visits").