@ericrisco/rsc 1.2.1 → 1.2.3

package/README.md

@@ -403,6 +403,8 @@ Take a fuzzy intent to a shipped, verified change — phase by phase. `npx @eric
 
 [sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/)
 
+> Two of those are not phases the chain walks on its own. `idea-refinement` **is** invoked — `specify` runs its FRAME block before the first question round. `decision-challenge` is **on-demand**: it exists, it is good, and no phase calls it yet. Listed so you can reach for it, not because the chain will. And the limit of what FRAME buys you, stated rather than implied: a second reading by the same model breaks correlation of **framing**, not of model — it shares the priors it is checking.
+
 ### 💼 Run a business
 
 [finance-ops](skills/finance-ops/) · [invoicing](skills/invoicing/) · [bookkeeping](skills/bookkeeping/) · [pricing](skills/pricing/) · [sales-pipeline](skills/sales-pipeline/) · [lead-gen](skills/lead-gen/) · [cold-outreach](skills/cold-outreach/) · [proposals](skills/proposals/) · [contracts](skills/contracts/) · [customer-support](skills/customer-support/) · [client-onboarding](skills/client-onboarding/) · [retention](skills/retention/) · [hiring](skills/hiring/) · [people-ops](skills/people-ops/) · [inventory](skills/inventory/) · [logistics-ops](skills/logistics-ops/) · [procurement](skills/procurement/) · [meeting-notes](skills/meeting-notes/) · [sop-builder](skills/sop-builder/) · [project-ops](skills/project-ops/)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "1.2.3",
   "counts": {
     "skills": 272,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/lib/spec-gate.js

@@ -9,6 +9,15 @@
 // 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';
+
 // 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
@@ -21,13 +30,29 @@ export const OPEN_POINT_TYPES = [
 // ("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'],
+  problem: { prefixes: ['problema & por que', 'problema y por que', 'problem & why'] },
+  goals: { prefixes: ['objetivos', 'goals'] },
+  nongoals: { prefixes: ['no-objetivos', 'no objetivos', 'non-goals'] },
+  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,
+  },
 };
 
 const UNCHECKED = [
@@ -38,6 +63,9 @@ const UNCHECKED = [
   // 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`,
 ];
 
 function fold(s) {
@@ -50,7 +78,7 @@ function fold(s) {
 
 function familyOf(heading) {
   const h = fold(heading);
-  for (const [family, prefixes] of Object.entries(FAMILIES)) {
+  for (const [family, { prefixes }] of Object.entries(FAMILIES)) {
     if (prefixes.some((p) => h.startsWith(p))) return family;
   }
   return null;
@@ -67,6 +95,58 @@ function isSubstantive(line) {
   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) {
@@ -108,9 +188,9 @@ export function specCompleteness(markdown) {
     if (current && sections.has(current)) sections.get(current).push(line);
   }
 
-  const families = Object.keys(FAMILIES);
+  const families = requiredFamilies(markdown);
   const missing = families.filter((f) => !sections.has(f));
-  const empty = families.filter((f) => sections.has(f) && !sections.get(f).some(isSubstantive));
+  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);

package/scripts/spec-gate.js

@@ -4,8 +4,8 @@
 // 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 { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, basename, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { specCompleteness, statusClaims, checkClaims } from './lib/spec-gate.js';
@@ -25,11 +25,19 @@ function defaultTargets() {
 
 // The repository, asked instead of assumed. Returns null when there is nothing to ask — a
 // report-only instrument that crashes where it cannot look is worse than one that says so.
+function spawnSyncGit(cwd, args) {
+  try { return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch { return ''; }
+}
+
 function gitProbe(root) {
   const git = (args) => execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
   let main;
+  let top;
   try {
     git(['rev-parse', '--git-dir']);
+    // The repository, not the directory we happened to be handed: `children()` looks for sibling
+    // repos under this one, and asking a specs/ subdirectory for its children finds nothing.
+    top = git(['rev-parse', '--show-toplevel']) || root;
     // Prefer the remote tip — a stale local `main` reports merged work as missing. But CI checks out
     // detached with no `origin/main` and no local `main`, and falling through to "no repository to
     // ask" there means the check silently stops checking exactly where it runs unattended. HEAD is
@@ -44,12 +52,118 @@ function gitProbe(root) {
   return {
     hasCommit: (sha) => { try { git(['cat-file', '-e', `${sha}^{commit}`]); return true; } catch { return false; } },
     isAncestor: (sha) => { try { git(['merge-base', '--is-ancestor', sha, main]); return true; } catch { return false; } },
-    // The squash-merge subject carries `(#N)`; --fixed-strings so the parens are not a regex.
-    hasPr: (n) => { try { return git(['log', main, '--grep', `(#${n})`, '--fixed-strings', '-1', '--format=%H']) !== ''; } catch { return false; } },
+    // Two ways a pull request lands, and only one of them was recognised. The squash subject carries
+    // `(#N)`; a plain merge writes `Merge pull request #N from …` and matched nothing, so half the
+    // ways of landing were invisible even when the right repository was being asked.
+    // Two literal searches rather than one regex: `--fixed-strings` is what keeps the parens from
+    // being read as a group, and swapping it for an alternation would put that back.
+    hasPr: (n) => {
+      for (const needle of [`(#${n})`, `Merge pull request #${n} `]) {
+        try {
+          if (git(['log', main, '--grep', needle, '--fixed-strings', '-1', '--format=%H']) !== '') return true;
+        } catch { /* try the other form */ }
+      }
+      return false;
+    },
     hasTag: (v) => { try { return git(['tag', '-l', `v${v}`]) !== ''; } catch { return false; } },
+    root: top,
   };
 }
 
+const commonDir = (dir) => {
+  const r = spawnSyncGit(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return r || dir;
+};
+const sameRepo = (a, b) => commonDir(a) === commonDir(b);
+
+const isRepo = (dir) => { try { return statSync(join(dir, '.git')).isDirectory() || statSync(join(dir, '.git')).isFile(); } catch { return false; } };
+
+/**
+ * Which repository is this spec's `status:` talking about?
+ *
+ * It used to be "the one holding the file", which is right only when docs and code live together.
+ * Where they deliberately do not — this workspace's own CLAUDE.md requires the children's working
+ * docs to live in the container — every true claim came back false, and a gate that flags everything
+ * distinguishes nothing.
+ *
+ * The subject is pinned ONCE per spec and every claim is then judged against it. Letting each claim
+ * find whichever repository happens to confirm it would read better and destroy the function: an
+ * unconfirmed claim would simply find no confirmer, and nothing would ever be reported stale again.
+ */
+function resolveSubject(specPath, claims) {
+  const answers = (root) => {
+    const p = gitProbe(root);
+    if (!p) return null;
+    return claims.some((c) => (c.kind === 'sha' && p.hasCommit(c.value))
+      || (c.kind === 'version' && p.hasTag(c.value))
+      || (c.kind === 'pr' && p.hasPr(c.value))) ? p : null;
+  };
+
+  // The declaration is AUTHORITATIVE. Softening it to "wins when it can answer" fixed a wrong config
+  // and opened something worse: with sibling repos, a claim that is false where the spec belongs and
+  // true next door is handed to the neighbour, confirmed, and printed nowhere. A silent false negative
+  // is worse than the noisy false positive it replaced, and choosing the judge by who agrees with the
+  // claim is not a way to find out whether the claim is true. A wrong `project.root` is a wrong datum;
+  // fix the datum.
+  const declared = declaredRoot(specPath);
+  if (declared && isRepo(declared)) return { probe: gitProbe(declared), from: 'config' };
+
+  const here = gitProbe(dirname(specPath));
+  const home = here && here.root;
+
+  if (home) {
+    const kids = children(home).map((dir) => ({ dir, probe: answers(dir) })).filter((k) => k.probe);
+    // Two histories cannot both be the subject. Saying so is an answer; picking the first one that
+    // sorted alphabetically is a coin toss wearing a verdict's clothes.
+    if (kids.length > 1) {
+      return { probe: null, note: `several repositories here could answer it (${kids.map((k) => basename(k.dir)).join(', ')}) — say which one in project.root` };
+    }
+    if (kids.length === 1) return { probe: kids[0].probe, from: 'derived' };
+    // Nobody answered. Fall through to the floor rather than guessing: with no declaration and no
+    // recogniser, the spec's own repository is the only honest default.
+  }
+  // The floor is the old behaviour: a spec that lives beside its own code must keep the detection it
+  // already had, or fixing the split layout would downgrade every caught lie to "could not check".
+  const floor = declared && isRepo(declared) ? gitProbe(declared) : here;
+  return { probe: floor, from: declared ? 'config' : 'spec repo' };
+}
+
+/** `project.root` from the nearest SDD config, resolved against the directory that holds 02-DOCS. */
+function declaredRoot(specPath) {
+  let dir = resolve(dirname(specPath));
+  for (let i = 0; i < 24; i += 1) {
+    const cfg = join(dir, '02-DOCS', 'wiki', 'sdd', 'config.yaml');
+    if (existsSync(cfg)) {
+      try {
+        const block = /^project:[ \t]*\r?\n((?:[ \t]+.*\r?\n?)*)/m.exec(readFileSync(cfg, 'utf8'));
+        const m = block && /^[ \t]+root:[ \t]*(.+?)[ \t]*$/m.exec(block[1]);
+        // Relative to the directory that owns 02-DOCS, not to the config file and not to the cwd:
+        // the only reading where `.` keeps meaning what it means today and the answer does not change
+        // with where the gate was invoked from.
+        if (m) return resolve(dir, m[1].replace(/^['"]|['"]$/g, ''));
+      } catch { /* unreadable config → derive instead */ }
+      return null;
+    }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/** Git repositories directly inside `root` — far enough to find a child, near enough to still be this project. */
+function children(root) {
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+      .map((e) => join(root, e.name))
+      .filter(isRepo)
+      // A linked worktree has a `.git` file and the same history, so without this a repo and its own
+      // worktree look like two candidates that both answer — an ambiguity invented out of one repo.
+      .filter((dir, i, all) => all.findIndex((d) => sameRepo(d, dir)) === i);
+  } catch { return []; }
+}
+
 const statusOf = (text) => (/^status:[ \t]*(.*)$/m.exec(text) || [, ''])[1];
 
 function main() {
@@ -66,11 +180,17 @@ function main() {
   // the project the spec belongs to — checking them against wherever this script happens to live
   // gives the right answer only by coincidence, and the wrong one the moment the gate is pointed at
   // another checkout.
-  const probes = new Map();
-  const probeFor = (path) => {
+  const subjects = new Map();
+  const announced = new Set();
+  const subjectFor = (path, claims) => {
     const dir = dirname(path);
-    if (!probes.has(dir)) probes.set(dir, gitProbe(dir));
-    return probes.get(dir);
+    // Keyed by directory alone. It used to include the claims, which meant a fresh resolution per
+    // spec — the opposite of what its own comment claimed, and measured at 0.8s → 10.3s over a
+    // 36-spec corpus, because every miss re-walks the children and re-runs git. A corpus shares a
+    // subject; that is the whole premise.
+    const key = dir;
+    if (!subjects.has(key)) subjects.set(key, resolveSubject(path, claims));
+    return subjects.get(key);
   };
   let anyProbe = false;
   for (const path of targets) {
@@ -92,12 +212,24 @@ function main() {
     }
     // A status that still matches the repository prints nothing: the report grows only where there
     // is something to act on (P5).
-    const probe = probeFor(path);
+    const claims = statusClaims(statusOf(text));
+    const subject = claims.length ? subjectFor(path, claims) : { probe: null };
+    // A subject nobody declared was inferred from the claims themselves, which is a guess. Say it
+    // once per run: silent inference is how a coincidence passes for a verdict.
+    if (subject.from === 'derived' && subject.probe && !announced.has(subject.probe.root)) {
+      announced.add(subject.probe.root);
+      console.log(`      note: subject derived (not declared) — asking ${subject.probe.root}; set project.root to settle it`);
+    }
+    const probe = subject.probe;
     anyProbe = anyProbe || Boolean(probe);
-    for (const v of checkClaims(statusClaims(statusOf(text)), probe)) {
+    for (const v of checkClaims(claims, probe)) {
       if (v.verdict === 'holds') continue;
       if (v.verdict === 'stale') drifted += 1;
-      console.log(`      status ${v.verdict.toUpperCase()}: ${v.raw} — ${v.reason}`);
+      // Every non-green line names where it looked, so the reader can go and check by hand (P6).
+      const rel = probe ? relative(process.cwd(), probe.root) : '';
+      const where = probe ? ` [asked ${!rel || rel.startsWith('..') ? probe.root : rel}]` : '';
+      const reason = !probe && subject.note ? subject.note : v.reason;
+      console.log(`      status ${v.verdict.toUpperCase()}: ${v.raw} — ${reason}${where}`);
     }
   }
 

package/skills/specify/SKILL.md

@@ -22,6 +22,21 @@ Fire on the **faintest** sign the user is thinking about a new feature or change
 
 You are not slowing them down; you make the intent reviewable *before* code exists, which is far cheaper than discovering the misunderstanding in a PR. End every spec by handing to `clarify`/`plan` — never to `implement`.
 
+### Your first sentence is not a verdict on the idea
+
+Catching the intent eagerly, above, is right. What comes *after* catching it is where this phase has been failing: the opening line validates. "Great idea", "makes sense", "that would be really useful" — or, since half this catalog's work happens in Spanish, "buena idea", "qué gran idea", "me encanta", "tiene todo el sentido" — is a verdict you do not have the evidence for, delivered at the cheapest possible moment to be wrong, to someone who still believes you. The ban is on the **judgement**, in any language, not on any particular wording: the list above is what it looks like, not what it is limited to. A spec built on a validated premise is coherent, plannable, testable and pointed at the wrong thing; nothing downstream can catch that, because every later gate compares artifacts to each other and they all agree.
+
+So the first response to an intent carries exactly two things:
+
+1. **A restatement** of what you understood, in one sentence, so a misread surfaces now.
+2. **The strongest objection you can actually articulate** from what you already know or can cheaply check — why this might not be worth building, or might be the wrong shape.
+
+Never a judgement of the idea's quality, in either direction. And go look before you object: an objection sourced from the repo, the wiki or a prior spec is worth ten sourced from your priors.
+
+If, having looked, there is no real objection, **say so in one line and move on — silence is a valid result**. Manufacturing an objection to look rigorous is the same failure wearing the opposite coat, and a doubt that fires on every idea measures you, not the idea. A typo fix does not get a restatement and an objection; it gets fixed.
+
+**And the objection never blocks.** It is a divergence, not a veto: the user often holds context you do not — a business reason, a conversation elsewhere, a constraint nobody wrote down. If they choose to proceed anyway, do not re-argue. **Write the reason into the spec** and continue. That is what keeps this from being decorative without giving it power it should not have: it cannot stop the decision, it can only stop the decision from being tacit. If the thing later goes wrong, the record says the doubt was raised and overridden — not that nobody looked.
+
 **Offer autopilot once, right here.** At this boundary, propose how to run the rest of the chain:
 > *"¿Quieres que lo lleve hasta el final yo solo — spec → plan → código → verify, parando solo si algo es ambiguo — o prefieres que pare a que apruebes en cada fase?"*
 
@@ -50,6 +65,22 @@ Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the tech
 
 If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
 
+## FRAME before you ask anything — from `idea-refinement`
+
+Before the frontier round, write five lines. They are the FRAME block of `../idea-refinement/SKILL.md`, a skill this catalog ships and the README advertises, and that until now no phase invoked:
+
+- **Actor** — who is struggling, and in what situation?
+- **Current workaround** — what do they do today, *including doing nothing*?
+- **Desired progress** — what observable change would make this useful?
+- **Constraints** — time, money, trust, regulation, the product that already exists.
+- **Known vs assumed** — separate what you have actually seen from what merely sounds plausible.
+
+Then name the directions worth considering, and **"don't build it" is one of them** — enumerated, with its consequence, not offered as a courtesy. A direction you can dismiss in one line still had to be written down first; the ones that never get written are the ones that never get weighed.
+
+If the idea arrives phrased as a feature ("an AI dashboard"), FRAME is where it turns back into a problem and an outcome ("operators need to spot failed jobs before customers report them"). The original phrasing stays as one candidate, not as the conclusion.
+
+Ceremony scales with the stakes here as everywhere: FRAME earns its five lines on anything with real scope, and on a small change it collapses to the one line that matters.
+
 ## Questioning discipline — ask the frontier, never cross a dependency
 
 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**.
@@ -70,6 +101,8 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Section | Holds | Watch for |
 | --- | --- | --- |
 | Problem & why | The pain, the cost of not solving it, the trigger | A "solution" disguised as a problem |
+| Cost of not building it | What concretely happens if nobody does this, and what it costs | Softening a genuinely small cost — "not much" IS the finding |
+| The cheapest alternative | What would solve most of it without building this, and why that is not enough | "Nothing" — there is always a manual workaround or a smaller version |
 | Goals | What success delivers, in outcome terms | A "goal" that's actually a HOW |
 | Non-goals / out of scope | What is explicitly NOT done now — adjacent work, deferred features | Silence — unsaid scope becomes assumed scope |
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
@@ -89,6 +122,8 @@ 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*.
 
+**Two of those sections are enforced, not suggested.** For a spec dated 2026-09-06 or later, `spec:gate` refuses the file if *Cost of not building it* or *The cheapest alternative* is missing or still holding the template's guidance. Specs written before that date are exempt — they cannot answer honestly after the fact. The two exist because every other gate in the chain compares artifacts to each other, so a spec that is wrong-but-coherent passes all of them; these are the only two lines that ask whether the thing should exist at all.
+
 ### Points to clarify carry a type
 
 *Points to clarify* is the handoff to `clarify`, and it holds four different objects that need four
@@ -124,7 +159,10 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 1. EXPLORE context        → profile + sdd config + constitution + existing specs + wiki + recent git
 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
+3. RESTATE + OBJECT     → one sentence of what you understood, plus the strongest objection you can
+                            actually make. No verdict on the idea. No objection to make? Say so, one line
+3b. FRAME (idea-refinement)→ actor · current workaround incl. doing nothing · desired progress ·
+                            constraints · known vs assumed; "don't build it" enumerated as a direction
 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
@@ -216,6 +254,14 @@ ask → user answers → fold it in → say what changed → show the revised sp
 Password resets are the #1 support ticket and a sign-up drop-off point.
 A passwordless email link removes the password entirely.
 
+## Cost of not building it
+Password resets stay the top support ticket — roughly N a week — and the
+sign-up funnel keeps leaking at the password step.
+
+## The cheapest alternative
+A better password-reset email. It removes some of the tickets and none of the
+drop-off, because the friction is the password itself, not the reset.
+
 ## Goals
 - A user can sign in with only their email, via a one-time link.
 - No password is ever stored or required.

package/skills/specify/evals/cases.yaml

@@ -65,7 +65,7 @@ capability:
     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 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."
+      - "Produces the spec sections: Problem & why, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
       - "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 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."
@@ -80,3 +80,14 @@ capability:
       - "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."
+
+  - scenario: "A user opens with pure enthusiasm and no problem statement: 'Tengo una idea buenísima — quiero montar un dashboard con IA que resuma toda la actividad del equipo cada mañana.' Nothing exists yet. Show the FIRST response, verbatim. Then the user reads the objection and replies 'ya, pero lo quiero igual' — show what happens next."
+    must_include:
+      - "The first response opens with a one-sentence RESTATEMENT of the intent and the STRONGEST OBJECTION the assistant can actually articulate — never a verdict on the idea's quality ('great idea', 'makes sense', 'that would be really useful') in any language."
+      - "The objection is sourced from something checked — the repo, the wiki, prior specs, or a named fact about the situation — not from generic priors; and if after looking there is genuinely no objection, it says so in ONE line and moves on rather than manufacturing one to look rigorous."
+      - "Runs the FRAME block from idea-refinement before any question round: actor, current workaround INCLUDING doing nothing, desired progress, constraints, and known-vs-assumed separated."
+      - "Names at least one concrete thing it went and LOOKED AT before objecting — the repo, the wiki, an existing spec, a prior decision — or says plainly that it could not check anything and that the objection is therefore weaker."
+      - "Enumerates 'don't build it' as one of the directions, with its concrete consequence — not mentioned as a courtesy and not silently dropped."
+      - "Does not turn the objection into a refusal or a question round: it states the doubt and keeps going in the same turn, so the user gets both the reservation and the progress."
+      - "The spec it goes on to write carries 'Cost of not building it' and 'The cheapest alternative' with real content, and the assistant notes that spec:gate will refuse the spec if either is left empty."
+      - "On 'ya, pero lo quiero igual': does NOT re-argue and does NOT block — it accepts the decision, and says that the reason for proceeding against the objection gets written into the spec so the record shows the doubt was seen and overridden rather than never raised."

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

@@ -26,6 +26,16 @@ status: draft
 <The pain, who feels it, and the cost of leaving it unsolved. One short
 paragraph. State the problem, not a pre-chosen solution.>
 
+## Cost of not building it
+<What concretely happens if nobody does this, and what it costs. If the honest
+answer is "not much", that IS the finding — write it down rather than softening
+it. Required for specs dated 2026-09-06 or later.>
+
+## The cheapest alternative
+<What would solve most of this WITHOUT building it, and why that is not enough.
+"Nothing" is not an answer; there is always a manual workaround, a smaller
+version, or doing nothing. Required for specs dated 2026-09-06 or later.>
+
 ## Goals
 - <What success delivers, in outcome terms. One bullet per goal.>
 
@@ -71,6 +81,12 @@ costliest of the four.>
 - **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).
+- **The two doubt sections are dated, not retroactive.** `Cost of not building
+  it` and `The cheapest alternative` are required only for specs whose
+  frontmatter `timestamp` is `2026-09-06` or later. Specs written before that
+  are exempt — they cannot answer honestly after the fact, and a gate that turns
+  the whole corpus red is a gate that gets switched off. A spec with no readable
+  `timestamp` falls on the exempt side too.
 - **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.

package/targets/session-memory-adapter.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { capture, resume } from './session-memory-core.mjs';
 
 const LOCAL_TARGETS = new Set(['claude', 'codex', 'cursor', 'gemini', 'opencode']);
@@ -15,6 +15,20 @@ function projectSettings(cwd) {
   }
 }
 
+// The project is the nearest ancestor holding `.rsc.json` — the file that IS the harness's decision.
+// The hook payload's `cwd` is only where the tool call happened to run; inside a container of child
+// repos that is routinely a subdirectory with no harness of its own, and anchoring there scatters
+// one session's journal across children. With no harness anywhere above, the cwd stays the project.
+function nearestHarness(dir) {
+  let current = dir;
+  for (;;) {
+    if (existsSync(join(current, '.rsc.json'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return dir;
+    current = parent;
+  }
+}
+
 function sessionId(native, target) {
   return native?.session_id || native?.sessionId || native?.sessionID || native?.conversation_id
     || native?.thread_id || `${target}-${process.ppid}`;
@@ -63,7 +77,7 @@ export function handleLifecycle({ target, event, native = {}, cwd, settings } =
   try {
     if (!LOCAL_TARGETS.has(target)) throw new Error(`unsupported memory target: ${target}`);
     if (isRemote(target, native)) return { output: {}, capture: null, remote: true, degraded: false };
-    const project = resolve(cwd || native.cwd || process.env.RSC_PROJECT_CWD || process.cwd());
+    const project = nearestHarness(resolve(cwd || native.cwd || process.env.RSC_PROJECT_CWD || process.cwd()));
     if (!existsSync(project)) throw new Error('project directory unavailable');
     const config = settings || projectSettings(project);
     if (config.enabled === false) return { output: {}, capture: null, remote: false, degraded: false };