@ericrisco/rsc 0.1.42 → 0.1.43

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.42",
+  "version": "0.1.43",
   "counts": {
     "skills": 257
   },
@@ -4120,7 +4120,7 @@
     },
     {
       "id": "sdd",
-      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'munta aquesta feature bé', 'de la idea a producción', 'de la idea a producció', 'fem un SDD per X', 'quina fase soc', 'per-phase model routing', 'use a cheaper model for implementation', 'qué modelo por fase'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill.",
+      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the accompaniment dial from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill.",
       "tags": [
         "sdd",
         "spec",
@@ -4425,7 +4425,7 @@
     },
     {
       "id": "specify",
-      "description": "Use when a feature, change, or product idea is still fuzzy and needs brainstorming into an APPROVED spec BEFORE any planning or code — the brainstorming front door of SDD. Turns a one-line intent into a WHAT/WHY spec (problem, goals, users, scope, behaviour, acceptance) with zero implementation detail, via one-question-at-a-time dialogue, 2-3 proposed approaches with a recommendation, and a design the user approves before anything gets built. Triggers: 'write a spec for…', 'spec this out', 'brainstorm this feature', 'especifica esta feature', 'm'agradaria afegir/posar X', 'voldria…', 'vull afegir/fer X', 'es podria afegir…', 'estaria bé que…', 'i si…?', 'I want to add X', 'tengo una idea', 'se me ha ocurrido', '¿y si…?', 'wouldn't it be nice if…', 'let's think this through', 'what should this feature do', 'draft a PRD', or any moment someone jumps to HOW before WHAT is agreed. NOT the technical plan (that's `plan`), NOT the de-risking ambiguity sweep (that's `clarify`), NOT project-wide principles (that's `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 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`).",
       "tags": [
         "sdd",
         "spec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {
@@ -32,7 +32,9 @@
     "targets",
     "schema",
     "skills",
-    "manifest.json"
+    "manifest.json",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
   ],
   "keywords": [
     "agent-skills",

package/schema/frontmatter.schema.json

@@ -4,7 +4,7 @@
   "required": ["name", "description", "tags"],
   "properties": {
     "name": { "type": "string", "pattern": "^[a-z0-9-]+$" },
-    "description": { "type": "string", "minLength": 10 },
+    "description": { "type": "string", "minLength": 10, "maxLength": 1024 },
     "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
     "recommends": { "type": "array", "items": { "type": "string" } },
     "profiles": { "type": "array", "items": { "enum": ["minimal", "core", "full"] } }

package/scripts/build-manifest.js

@@ -47,6 +47,22 @@ export function validateFrontmatter() {
   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,
+// because turning 257 skills red the day the rubric changed would help nobody.
+export const DESCRIPTION_CEILING_CHARS = 350;
+
+export function descriptionWeight() {
+  const rows = skillDirs().map((id) => {
+    const fm = parseFrontmatter(readFileSync(join(SKILLS, id, 'SKILL.md'), 'utf8'));
+    return { id, chars: (fm.description || '').length };
+  });
+  const total = rows.reduce((s, r) => s + r.chars, 0);
+  const over = rows.filter((r) => r.chars > DESCRIPTION_CEILING_CHARS).sort((a, b) => b.chars - a.chars);
+  return { total, count: rows.length, mean: Math.round(total / (rows.length || 1)), over };
+}
+
 function main() {
   const arg = process.argv[2];
   const out = join(ROOT, 'manifest.json');
@@ -54,6 +70,14 @@ function main() {
     const errs = validateFrontmatter();
     if (errs.length) { console.error(errs.join('\n')); process.exit(1); }
     console.log('frontmatter OK');
+    const w = descriptionWeight();
+    console.log(
+      `description weight: ${(w.total / 1024).toFixed(1)} KB across ${w.count} skills `
+      + `(mean ${w.mean} chars) · ${w.over.length} over the ${DESCRIPTION_CEILING_CHARS}-char ceiling`,
+    );
+    if (w.over.length) {
+      console.log(`  heaviest: ${w.over.slice(0, 5).map((r) => `${r.id} (${r.chars})`).join(', ')}`);
+    }
     return;
   }
   const manifest = buildManifest();

package/scripts/doctor.js

@@ -1,9 +1,11 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { targetPaths } from '../targets/index.js';
+import { homedir } from 'node:os';
+import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
 import { loadManifest } from './lib/manifest.js';
 import { listBackups } from './lib/backups.js';
+import { SDD_GATE_TEXT } from '../targets/hook-once.mjs';
 
 export function doctor({ target, home, cwd }) {
   const root = cwd || process.cwd();
@@ -22,9 +24,139 @@ export function doctor({ target, home, cwd }) {
       count: backups.length,
       latest: backups[0]?.id || null,
     },
+    contextBudget: contextBudget({ target, home, cwd }),
   };
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);
   }
   return report;
 }
+
+// ---------------------------------------------------------------------------------------
+// Context budget — what the harness costs in tokens before the user has typed anything.
+//
+// Until this existed, the only way to learn that a harness was injecting the same 11KB block
+// twice per session was to read the hook wiring by hand. `audit` judges bloat by NUMBER of
+// installed skills, which is orthogonal: five heavy skills cost more than twenty light ones.
+// This measures weight, names the biggest contributors, and never writes anything.
+// ---------------------------------------------------------------------------------------
+
+// Targets whose "always-on" surface is a markdown file the assistant reads on its own terms
+// (the AGENTS.md family, cursor rules). There is no per-session or per-turn injection to
+// measure, and reporting 0 would read as "this costs you nothing" — a different, wrong claim.
+const HOOKLESS_TARGETS = new Set(TARGET_IDS.filter((t) => t !== 'claude'));
+
+const bytesOf = (p) => { try { return statSync(p).size; } catch { return 0; } };
+
+// The always-on body a wired scope injects: the hook command embeds the exact SKILL.md path,
+// so read it from there rather than guessing the layout.
+function alwaysOnBytesFor(scopeRoot, settingsRaw) {
+  const fromCommand = /"([^"]*suggest[^"]*SKILL\.md)"/.exec(settingsRaw || '');
+  if (fromCommand && bytesOf(fromCommand[1])) return bytesOf(fromCommand[1]);
+  return bytesOf(join(scopeRoot, '.rsc', 'skills', 'suggest', 'SKILL.md'));
+}
+
+function readScope(scopeRoot, label) {
+  const settingsPath = join(scopeRoot, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) {
+    return { label, root: scopeRoot, wired: false, status: 'ok', alwaysOnBytes: 0, perTurnBytes: 0, version: null };
+  }
+  let raw;
+  try {
+    raw = readFileSync(settingsPath, 'utf8');
+    JSON.parse(raw); // a scope we cannot parse is reported, not guessed at
+  } catch {
+    return { label, root: scopeRoot, wired: true, status: 'unknown', alwaysOnBytes: 0, perTurnBytes: 0, version: null };
+  }
+  const wired = raw.includes('.rsc/') || raw.includes('.rsc\\\\');
+  let version = null;
+  try { version = readFileSync(join(scopeRoot, '.rsc', '.version'), 'utf8').trim() || null; } catch { /* unknown */ }
+  return {
+    label,
+    root: scopeRoot,
+    wired,
+    status: 'ok',
+    version,
+    alwaysOnBytes: wired ? alwaysOnBytesFor(scopeRoot, raw) : 0,
+    perTurnBytes: wired && raw.includes('userprompt-gate') ? Buffer.byteLength(SDD_GATE_TEXT) : 0,
+  };
+}
+
+// Frontmatter `description` of an installed skill — the part of a skill that is ALWAYS in
+// context, whether or not the skill is ever invoked. Cheap to parse, and the figure that
+// matters most as the catalog grows.
+function descriptionBytes(skillDir) {
+  try {
+    const text = readFileSync(join(skillDir, 'SKILL.md'), 'utf8');
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (!fm) return 0;
+    const d = /description:\s*([\s\S]*?)(?=\n[a-z_]+:|$)/.exec(fm[1]);
+    return d ? Buffer.byteLength(d[1].trim()) : 0;
+  } catch { return 0; }
+}
+
+export function contextBudget({ target, home = homedir(), cwd = process.cwd() } = {}) {
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const installed = Object.keys(state.skills || {});
+  const hookless = HOOKLESS_TARGETS.has(target);
+
+  // Both scopes rsc can be wired in. They are independent installs: this is exactly the pair
+  // that silently doubles every injected block.
+  const scopes = hookless ? [] : [
+    readScope(cwd, 'project'),
+    ...(join(home) === join(cwd) ? [] : [readScope(home, 'user')]),
+  ];
+  const wired = scopes.filter((s) => s.wired);
+
+  const perSkill = installed.map((id) => {
+    const base = state.skills[id]?.base || paths.skillDir(id);
+    return { id, bytes: bytesOf(join(base, 'SKILL.md')), descriptionBytes: descriptionBytes(base) };
+  });
+  const descriptionsBytes = perSkill.reduce((s, k) => s + k.descriptionBytes, 0);
+
+  const findings = [];
+  if (wired.length > 1) {
+    const doubled = wired.reduce((s, k) => s + k.alwaysOnBytes + k.perTurnBytes, 0)
+      - (wired[0].alwaysOnBytes + wired[0].perTurnBytes);
+    findings.push({
+      id: 'duplicate-wiring',
+      severity: 'high',
+      summary: `rsc is wired in ${wired.length} scopes (${wired.map((s) => s.label).join(' + ')}), so every `
+        + `injected block lands ${wired.length} times — about ${doubled} wasted bytes per session.`,
+      action: 'Keep ONE scope. Remove the other with `npx @ericrisco/rsc uninstall --all` run from that '
+        + 'root, or update both to a version that de-duplicates at runtime.',
+    });
+  }
+  for (const s of scopes) {
+    if (s.status === 'unknown') {
+      findings.push({
+        id: 'unreadable-scope',
+        severity: 'low',
+        summary: `The ${s.label} scope at ${s.root} has a settings.json that cannot be parsed, so its weight is unknown.`,
+        action: 'Fix or remove that settings.json, then re-run `rsc doctor`.',
+      });
+    }
+  }
+
+  const byBytes = (a, b) => b.bytes - a.bytes;
+  return {
+    scopes,
+    notApplicable: hookless ? ['sessionStart', 'perTurn'] : [],
+    sessionStartBytes: wired.reduce((s, k) => s + k.alwaysOnBytes, 0),
+    perTurnBytes: wired.reduce((s, k) => s + k.perTurnBytes, 0),
+    descriptionsBytes,
+    installedSkills: installed.length,
+    topContributors: {
+      bodies: [...perSkill].sort(byBytes).slice(0, 5).map(({ id, bytes }) => ({ id, bytes })),
+      descriptions: [...perSkill]
+        .sort((a, b) => b.descriptionBytes - a.descriptionBytes)
+        .slice(0, 5)
+        .map(({ id, descriptionBytes: bytes }) => ({ id, bytes })),
+    },
+    findings,
+    note: hookless
+      ? 'This target has no hook injection; only skill weight applies.'
+      : 'sessionStart counts the always-on body per wired scope; conditional banners are excluded.',
+  };
+}

package/scripts/install-apply.js

@@ -49,6 +49,10 @@ function ensureBase(id, cwd, baseVersions) {
   return dest;
 }
 
+// Every file wireHook() materializes, so they are covered by the pre-write backup and
+// reported by a --dry-run. Keep in sync with targets/claude.js wireHook(): a file it
+// writes but this omits is silently absent from the snapshot, so `rsc restore` cannot
+// bring it back.
 function generatedHookFiles({ target, cwd }) {
   if (target !== 'claude') return [];
   return [
@@ -56,6 +60,8 @@ function generatedHookFiles({ target, cwd }) {
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     join(cwd, '.rsc', 'ship-guard.mjs'),
     join(cwd, '.rsc', 'danger-guard.mjs'),
+    join(cwd, '.rsc', 'userprompt-gate.mjs'),
+    join(cwd, '.rsc', 'hook-once.mjs'),
   ];
 }
 

package/scripts/rsc.js

@@ -122,6 +122,35 @@ function printAgentHandoff() {
   say('════════════════════════════════════════════════');
 }
 
+// What the harness costs in context before the user types anything. Printed ahead of the raw
+// health JSON because it is the part a human acts on: the figures say whether the harness is
+// paying its way, and the findings say what to do about it.
+const kb = (n) => `${(n / 1024).toFixed(1)} KB`;
+
+function printContextBudget(b) {
+  if (!b) return;
+  say('\n════════════════ CONTEXT BUDGET ════════════════');
+  if (b.notApplicable.length) {
+    say(`  ${b.note}`);
+  } else {
+    say(`  Per session start : ${kb(b.sessionStartBytes)}   (always-on body, per wired scope)`);
+    say(`  Per user turn     : ${kb(b.perTurnBytes)}`);
+  }
+  say(`  Skill descriptions: ${kb(b.descriptionsBytes)}   (${b.installedSkills} installed, always in context)`);
+  if (b.topContributors.bodies.length) {
+    const top = b.topContributors.bodies.map((t) => `${t.id} ${kb(t.bytes)}`).join(' · ');
+    say(`  Heaviest bodies   : ${top}`);
+  }
+  for (const s of b.scopes.filter((x) => x.wired)) {
+    say(`  Scope ${s.label.padEnd(8)}: ${s.root}${s.version ? ` (${s.version})` : ''}${s.status === 'unknown' ? ' — UNREADABLE' : ''}`);
+  }
+  for (const f of b.findings) {
+    say(`\n  [${f.severity.toUpperCase()}] ${f.summary}`);
+    say(`  → ${f.action}`);
+  }
+  say('════════════════════════════════════════════════\n');
+}
+
 async function wizard() {
   const m = loadManifest();
   await banner();
@@ -241,8 +270,12 @@ async function main() {
     }
     case 'list':
       return void say(listInstalled({ target }).join('\n') || '(nothing installed)');
-    case 'doctor':
-      return void say(JSON.stringify(doctor({ target }), null, 2));
+    case 'doctor': {
+      const report = doctor({ target });
+      if (argv.includes('--json')) return void say(JSON.stringify(report, null, 2));
+      printContextBudget(report.contextBudget);
+      return void say(JSON.stringify({ ...report, contextBudget: undefined }, null, 2));
+    }
     case 'sync': {
       const dry = argv.includes('--dry-run');
       for (const t of targets) {

package/scripts/skill-rubric.md

@@ -11,9 +11,9 @@ dishonest 9.
 
 | # | Dimension | Weight | What a 10 looks like |
 |---|---|---|---|
-| 1 | **Triggering & description** | 0.15 | Third-person, `Use when …` lead, concrete `Triggers:` incl. ≥1 non-obvious phrasing and ≥1 Spanish/Catalan phrasing, explicit `NOT … (that is <sibling>)` boundary, ≤1024 chars, parses as single-line quoted YAML. |
+| 1 | **Triggering & description** | 0.15 | Third-person, `Use when …` lead, an explicit `NOT … (that is <sibling>)` boundary, and nothing else it can do without. Judged on **discriminative power, not coverage**: could a reader pick this skill over its nearest sibling from the description alone? Aim ≤350 chars; ≤1024 is the hard limit. Parses as single-line quoted YAML. |
 | 2 | **Scope & boundary** | 0.10 | One job. Body never drifts into a sibling's territory; it delegates by name. Near-miss prompts route to the correct existing sibling. |
-| 3 | **Body craft & progressive disclosure** | 0.15 | 120–400 lines, references pointed to inline (not orphaned), rsc voice, every fence language-tagged, a checklist/decision table only where the flow branches, an anti-patterns table present. |
+| 3 | **Body craft & progressive disclosure** | 0.15 | **The smallest body that routes correctly** — ≤400 lines is a ceiling, not a target, and there is no minimum: a skill that does its job in 60 lines scores higher than the same skill padded to 200. Every `references/` file is pointed to inline from this body (an unlinked reference is never loaded, so it is dead weight). rsc voice, every fence language-tagged, a checklist/decision table only where the flow branches, an anti-patterns table present. |
 | 4 | **Correctness, grounding & freshness** | **0.25** | Every load-bearing claim is accurate and **current (2025–2026)**: real library/API versions, no hallucinated flags/endpoints. The spec cites **authoritative sources with dates**; nothing rests on stale or invented facts. This is the heaviest dimension by design. |
 | 5 | **Actionability** | 0.15 | Concrete and runnable: real numbers, paths, commands, decision rules — not adjectives. A practitioner could act from it without leaving the skill. |
 | 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that names a **real** sibling, ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
@@ -34,6 +34,7 @@ dishonest 9.
 ## How the reviewer must work (anti-cheat)
 
 - **Independent pass.** Review the artifact as written; do not assume the author's intent filled a gap.
-- **Evidence, not vibes.** For dimension 1 quote the char count; for 3 quote the SKILL.md line count; for 4 quote at least two source titles **with their dates** from the spec and name any claim you could not verify; for 6 count the entries.
+- **Evidence, not vibes.** For dimension 1 quote the char count **and name the sibling the description distinguishes this skill from**; for 3 quote the SKILL.md line count **and name anything that could be cut without losing routing**; for 4 quote at least two source titles **with their dates** from the spec and name any claim you could not verify; for 6 count the entries.
+- **Length is a cost, never a credit.** Do not reward a longer description or body for being thorough. Every line is paid for in context on every turn the skill is installed, whether or not it is invoked. If two versions route the same, the shorter one scores higher.
 - **Freshness is mandatory.** If the skill names a version, API, or pricing that is plausibly out of date, dimension 4 is capped at 6 until a current source is cited. "Looks right" is not a source.
 - **Fix loop.** Below 8.5, return a concrete `mustFix` list; the author applies it and re-scores. Up to two fix rounds. If still < 8.5, **record the real score and flag it** — never round up to pass.

package/skills/harness/SKILL.md

@@ -102,6 +102,7 @@ harness/
 │   ├── audit-report-template.md      ← exact format of the audit report shown to user
 │   ├── wiki-protocol.md              ← embedded wiki protocol + Inbox/Worklog Sweep + Continuous Improvement
 │   ├── ingest-formats.md             ← multiformat Fetch (PDF, image, CSV, JSON, html…)
+│   ├── ingest-ignore-defaults.md     ← what the sweep skips by default (the .rscignore baseline)
 │   ├── inbox-readme-template.md      ← the inbox/README.md drop-zone contract
 │   ├── wiki-raw-template.md          ← format for raw/<topic>/*.md
 │   ├── wiki-worklog-template.md      ← format for raw/worklog/*.md (work-driven capture)

package/skills/orient/SKILL.md

@@ -52,3 +52,9 @@ When the user says "explícame más / menos", "no me expliques tanto", or "ensé
 - Ask before deciding at any real fork; do not decide alone when the user can choose.
 - Never invent project state — situate the user from what is actually built (read the Knowledge map / repo if unsure).
 - Defer the "install a missing skill?" prompt to `suggest`.
+
+## See Also
+
+- `references/orientation-contract.md` — the full brújula contract: block anatomy, what each of the
+  four beats must contain, and how the dial changes their depth. Read it when a turn ends ambiguously
+  or when calibrating a new dial level.

package/skills/sdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdd
-description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'munta aquesta feature bé', 'de la idea a producción', 'de la idea a producció', 'fem un SDD per X', 'quina fase soc', 'per-phase model routing', 'use a cheaper model for implementation', 'qué modelo por fase'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill."
+description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the accompaniment dial from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill."
 tags: [sdd, spec, workflow, plan]
 recommends: [sdd-init, constitution, specify]
 profiles: [core, full]

package/skills/specify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specify
-description: "Use when a feature, change, or product idea is still fuzzy and needs brainstorming into an APPROVED spec BEFORE any planning or code — the brainstorming front door of SDD. Turns a one-line intent into a WHAT/WHY spec (problem, goals, users, scope, behaviour, acceptance) with zero implementation detail, via one-question-at-a-time dialogue, 2-3 proposed approaches with a recommendation, and a design the user approves before anything gets built. Triggers: 'write a spec for…', 'spec this out', 'brainstorm this feature', 'especifica esta feature', 'm'agradaria afegir/posar X', 'voldria…', 'vull afegir/fer X', 'es podria afegir…', 'estaria bé que…', 'i si…?', 'I want to add X', 'tengo una idea', 'se me ha ocurrido', '¿y si…?', 'wouldn't it be nice if…', 'let's think this through', 'what should this feature do', 'draft a PRD', or any moment someone jumps to HOW before WHAT is agreed. NOT the technical plan (that's `plan`), NOT the de-risking ambiguity sweep (that's `clarify`), NOT project-wide principles (that's `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 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`)."
 tags: [sdd, spec, requirements]
 recommends: [clarify, plan]
 profiles: [core, full]

package/skills/suggest/SKILL.md

@@ -6,112 +6,86 @@ recommends: []
 profiles: [minimal, core, full]
 ---
 
-# rsc-suggest — detect & install the skill the task needs
+# rsc-suggest — the always-on layer
 
-You are always loaded — your body is injected into context at the start of **every** session, and again after every compaction, so you are the one piece guaranteed to be present *before any other skill is matched*. That makes you the **always-on layer**. You do two jobs, in this order:
+Your body is injected at the start of **every** session and again after every compaction, so you
+are the one piece guaranteed to be present before any other skill is matched. Two jobs, in order:
 
-1. **Route new-feature intent into SDD before any code is written** — the new-feature gate below. This is your first duty; it runs before everything else.
-2. **Keep the session equipped** — detect when the task needs an rsc skill that is **not installed**, name it, and install it on confirm.
+1. **Route feature intent into SDD** before any code is written.
+2. **Keep the session equipped** — spot the skill the task needs but the user does not have.
+
+Everything below is what only this layer can do. The method behind each rule lives in the skill that
+owns it; this is the pointer, not the manual.
 
 ---
 
-## The new-feature gate (always-on — runs before any other skill)
+## 1. Routing: feature intent goes through SDD first
 
-This is the **highest-precedence rule in the session.** It fires on **every** user turn, in **any language**, and runs **before you plan, answer, or invoke ANY other skill — no matter how many skills are installed or how strongly one of them matches the request.** That covers the stack skills (`nextjs`, `react`, `fastapi`, `flutter`, `go`, `postgresdb`, `building-agents`, `design`) **and any other skill that would build, create, scaffold, generate, or produce the feature** (e.g. `chatbot`, `course-builder`, `marketing`, automation/connector skills). A skill matching the request does **not** override this gate — it runs *inside* the SDD chain, after the plan is approved. There is no skill with priority over this check.
+The moment someone wants something to **exist or behave differently** — build, add, change,
+integrate, "it should also…", "¿y si…?", in any language — route the turn to `specify` before any
+code is written. No skill outranks this. The stack and builder skills that match the same request
+(`nextjs`, `react`, `fastapi`, `flutter`, `go`, `postgresdb`, `building-agents`, `design`,
+`chatbot`, `course-builder`, `marketing`…) run **inside** the chain, after the plan is approved —
+matching strongly is not a reason to skip ahead.
 
-**The rule (non-negotiable).** The moment the user wants to **build, add, or change a feature**, you MUST route it into SDD via `specify` **first**. **No feature code is written — by ANY skill — until a spec AND a plan exist and the user has approved them.** A stack skill that matched the same request does **not** get to skip this: it builds only *after* the plan is approved. (Exception: if the user engaged **SDD autopilot**, that single up-front consent IS the approval for the whole run — auto-advance through the phases without re-asking; see `../sdd/SKILL.md`.)
+Two exceptions, and say out loud when you take one:
 
-**Where does this turn go? When unsure, choose `specify` — the safe default.**
+- a genuinely one-line, low-risk change (typo, copy tweak, config bump, non-breaking bump) — just do it;
+- a bug fix restoring intended behaviour — that is `debug`, then resume.
 
-| The turn is… | Route to |
-| --- | --- |
-| A new feature / capability / integration / UI, a behaviour change, a data-model or architecture change, "it should also…", anything non-trivial | **`specify`** → `clarify` → `plan` → `tasks` → `implement` (which fans work out to subagents via `parallel`) |
-| A genuinely one-line / low-risk change: typo, copy tweak, config bump, rename, non-breaking dependency bump | Just do it inline, then verify — and **say out loud** you are skipping the chain |
-| A bug fix that restores intended behaviour | **`debug`**, then resume |
-| Ambiguous / in-between / you cannot tell | **`specify`** — a skipped spec is where drift hides |
+When you cannot tell, choose `specify`. A skipped spec is where drift hides.
 
-**Triggers — detect the *intent*, never a fixed phrase, in ANY language.** What fires the gate is the **meaning**, not the words: the user wants something to exist or behave differently than it does now — build, add, create, change, replace, integrate, "it should also…", "wouldn't it be nice if…". This is judged **semantically**, so it holds in **any language** — Catalan, Spanish, English, Portuguese, French, Italian, German, Basque, Galician, or anything else, including a language with no example below. The lists that follow are **illustrative examples, NOT a checklist**: never wait for one of these phrases to appear before firing. If the meaning is feature-shaped, the gate fires — full stop.
-- **CA:** "m'agradaria afegir/posar…", "vull fer/posar…", "es podria…", "i si…".
-- **ES:** "quiero añadir/montar…", "me gustaría…", "se me ha ocurrido", "¿y si…?".
-- **EN:** "I want to add…", "let's build…", "it should also…".
-- A **URL plus a description of desired behaviour** ("on this page I'd like…") **is** a feature request — in any language.
+Judge the **meaning**, not the wording: the trigger is semantic, so it holds in any language,
+including ones with no example here. A URL plus a description of desired behaviour is a feature
+request. If the user engaged **SDD autopilot**, that one consent covers the whole run — advance
+through the phases without re-asking.
 
-**Stop rationalizing — every one of these is wrong:**
-- *"I understand the feature, I'll just build it."* → That is the exact failure SDD prevents. Spec first; the artifact is the contract.
-- *"A more specific skill matched (a stack skill, `chatbot`, `course-builder`, marketing…), so it takes precedence."* → **No skill outranks this gate.** Any builder skill **defers** to `specify` for new features and runs *inside* the chain, after the plan is approved. Route first.
-- *"The user gave lots of detail / a URL, so they want code now."* → Detail feeds the spec, not the editor.
-- *"The dial is L0, so I'll skip the gate to stay terse."* → L0 changes how many words and questions, **never** whether the gate fires.
-- *"It's phrased in a language I have no example for, so maybe it isn't a feature request."* → The trigger lists are examples, not a closed set. Judge the **meaning**, not the keywords; any language with build/add/change intent fires the gate identically.
+If `specify` / `sdd` are not installed, offer to add them (§2) before routing.
 
-If `specify` / `sdd` are **not installed**, fall through to the install detector below and offer to add them *before* routing. The gate decides **where the turn goes**; the detector below only handles **missing** skills. Full method and phase map: `../sdd/SKILL.md`.
+Method, phase map and full decision table: `../sdd/SKILL.md`. On Claude Code this rule also arrives
+as a per-turn hook; the brevity here is deduplication, not relaxation.
 
 ---
 
-When the current task would clearly benefit from an rsc skill that is **not installed**:
-
-1. Name it in plain language: "Para esto va bien `<id>`, que aún no tienes."
-2. Ask one short confirm: "¿La instalo? (sí/no)".
-3. On yes, run `npx @ericrisco/rsc add <id>` (Bash). Then continue the task.
-
-Rules:
-
-- Installing changes the user's environment — always confirm first.
-- To know what exists, run `npx @ericrisco/rsc catalog --available` (every NOT-installed skill as `id  available  short description`) and **pick the best fit yourself, by meaning** — see the detector below. Don't guess from memory.
-- `npx @ericrisco/rsc consult "<task>"` is only a cheap **lexical** hint: it keyword-matches and silently returns nothing for natural-language or non-English/Catalan intent (e.g. it finds no email skill for "mandar emails"). Never let it be the decider; if it's empty, scan `catalog` and judge semantically.
-- Never recommend something already installed (`npx @ericrisco/rsc list`).
-- One suggestion at a time. Don't interrupt the flow for nice-to-haves.
+## 2. Keeping the session equipped
 
-## Mid-task capability intent detector
+When the task needs a capability the user has **not installed** — building, creating, automating,
+analyzing, connecting, shipping, securing, selling, teaching, governing or documenting something —
+name it and offer it. This runs mid-conversation, not only at project start.
 
-This runs **inside the agent conversation**, not only in the `rsc` CLI. At the start of
-each user turn, before planning, coding, writing, researching, or answering in depth,
-check whether the user is asking to create, build, fix, connect, automate, analyze,
-publish, sell, teach, govern, secure, deploy, or document something that maps to a
-known rsc capability.
+1. `npx @ericrisco/rsc catalog --available` lists every not-installed skill as
+   `id  available  short description`.
+2. Pick the single best fit **by meaning**, the way you would match a request to a teammate's
+   expertise — "mandar emails de bienvenida" → an email/outreach skill, though not one keyword
+   overlaps; "login con Google" → an auth skill, not `flutter`. If nothing genuinely fits, say so
+   and move on: a tangential suggestion is worse than none.
+3. Ask once, plainly: "Para esto instalaría `<id>`, que aún no tienes. ¿La instalo? (sí/no)".
+4. On yes, run `npx @ericrisco/rsc add <id>`, then continue the original task.
 
-This is broader than "start a project". It includes mid-conversation requests such as:
+Installing changes the user's environment, so it is always their call. One suggestion at a time,
+and never to interrupt a flow with a nice-to-have. Never recommend something already installed
+(`npx @ericrisco/rsc list`).
 
-- Technology: "quiero montar una pagina web", "necesito una API", "build me a mobile app", "conecta Stripe", "automatiza este flujo", "deploy this", "review security".
-- Creation: "haz una landing que convierta", "write a cold email sequence", "crea un pitch deck", "monta un curso", "edita shorts", "make social posts".
-- Data and AI: "analiza estos datos", "build a dashboard", "quiero un agente de IA", "haz RAG sobre mis documentos", "extrae datos de PDFs".
-- Business and ops: "organiza mi empresa", "prepara facturas", "monta CRM/pipeline", "haz contratos", "reduce churn", "gestiona soporte".
-- Knowledge and research: "documenta cómo funciona esto", "crea una wiki", "procesa este inbox", "research competitors", "turn this into SOPs".
-- Other languages: any equivalent phrasing. Match the user's intent, not exact words.
+`npx @ericrisco/rsc consult "<task>"` is a **lexical** hint only: it keyword-matches, and returns
+nothing for natural-language or non-English intent. Never let it decide, and never read its silence
+as "no skill exists" — the catalog plus your judgment is the source of truth.
 
-When a capability intent appears, **you** make the match semantically — do not delegate the decision to a keyword ranker:
-
-1. Run `npx @ericrisco/rsc catalog --available` to get every NOT-installed skill as
-   `id  available  short description`. (It already excludes what's installed.)
-2. **Read the catalog and pick the single best-fit skill by MEANING** — match the user's
-   intent to a skill's *purpose*, semantically, in any language (CA/ES/EN/…), the way you'd
-   match a request to a teammate's expertise. Judge meaning, not shared keywords:
-   "mandar emails de bienvenida" → `email-connector` even though no words overlap its tags;
-   "login con Google" → an auth/security skill, not `flutter`; "transcripció de veu" → a
-   speech/audio skill *if one exists*.
-3. If nothing in the catalog genuinely fits, **say so and move on** — don't force a weak
-   match, and don't propose a tangential skill just to have an answer. (`npx @ericrisco/rsc
-   consult "<intent>"` is available as a lexical hint, but it misses natural-language and
-   Catalan intent and is silent for many real needs — never read its silence as "no skill
-   exists." The catalog + your judgment is the source of truth.)
-4. Ask before installing: "Para esto instalaría `<id>`, que aún no tienes. ¿La instalo? (sí/no)".
-5. On yes, run `npx @ericrisco/rsc add <id>` and continue the original request. One at a time.
-
-Example: "quiero montar una pagina web para vender cursos online" → scan the catalog and
-pick the web stack skill (usually `nextjs`) by meaning; don't start building before offering it.
-Example: "hazme una secuencia de cold emails para vender mi SaaS" → pick the email/outreach
-skill (`cold-outreach` / `email-connector`) because it *means* email outreach — not because
-the keywords happen to match (they often won't).
-
-## Onboarding gate (first contact)
+---
 
-Before handling the first request of the session, check the workspace state:
+## 3. First contact
 
-- If `02-DOCS/wiki/harness/user-profile.md` is **missing** AND `.rsc/.no-harness` is **missing**, the harness has never been set up here — your FIRST action is to invoke `init` (auto-onboarding), which opens with the two gauging questions (technical level + accompaniment dial). Don't wait to be asked; don't start the user's task until first contact is done.
-- If the user declines or says they don't want a harness here ("sin harness", "solo código", "no quiero esto") — create an empty `.rsc/.no-harness` and never auto-start `init` in this repo again. Confirm in one line.
-- Once `02-DOCS/wiki/harness/user-profile.md` exists, this gate is inert — never re-onboard.
+Before handling the first request of a session, check the workspace:
 
-This is the universal layer every assistant reads. On Claude Code a SessionStart hook also prints this reminder deterministically, but the rule above is what makes it fire everywhere.
+- No `02-DOCS/wiki/harness/user-profile.md` **and** no `.rsc/.no-harness` → the harness has never
+  been set up here. Invoke `init` first; it opens with the two gauging questions (technical level +
+  accompaniment dial). Do not start the user's task before first contact is done.
+- The user declines a harness here ("sin harness", "solo código") → create an empty
+  `.rsc/.no-harness`, confirm in one line, and never auto-start `init` in this repo again.
+- Once the profile exists, this gate is inert. Never re-onboard.
 
 ## Orientación (siempre)
 
-Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente,
+terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. Nunca termines
+en seco. Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`.
+(Defiere a este mismo cuerpo, §2, el "¿instalo la skill que falta?".)

package/targets/claude.js

@@ -48,6 +48,9 @@ export function unwireHook(paths) {
 export function wireHook(paths) {
   const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
+  // Shared by session-start + userprompt-gate. Hooks are materialized file by file, so a module
+  // they import must be copied as their SIBLING — a subdirectory import would break once copied.
+  copyFileSync(join(HERE, 'hook-once.mjs'), join(paths.projectRoot, '.rsc', 'hook-once.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
   const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;

package/targets/hook-once.mjs

@@ -0,0 +1,120 @@
+// hook-once.mjs — cross-scope single-shot guard for rsc hooks.
+//
+// rsc can be wired in more than one scope at once (user-level ~/.claude/settings.json AND
+// project-level .claude/settings.json). Each scope runs its OWN copy of the hook scripts, so
+// the same always-on body and the same SDD gate get injected twice — once per scope. wireHook()
+// is idempotent within a settings file but blind to the other one, so the duplication cannot be
+// solved at install time; it has to be solved at injection time.
+//
+// The marker therefore CANNOT live in `.rsc/` — each scope has its own root, which is the whole
+// problem. It lives in a per-user directory under the OS temp dir, which both scopes can see.
+//
+// Claude Code gives every hook the same `session_id` for both scopes, and the same `prompt_id`
+// within one turn (docs: code.claude.com/docs/en/hooks). That is the dedup key.
+//
+// Fail-open is the rule throughout: if anything about this mechanism misbehaves, the hook prints.
+// A duplicated block costs context; a swallowed always-on layer costs the session its behaviour.
+import { mkdirSync, writeFileSync, statSync, readdirSync, unlinkSync, utimesSync, readFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+
+const PRUNE_AFTER_MS = 24 * 3600 * 1000;
+
+// Per-user so two accounts on one machine never share (or suppress) each other's markers.
+// RSC_HOOK_MARKER_DIR overrides it so tests get an isolated directory per case.
+export function markerDir() {
+  if (process.env.RSC_HOOK_MARKER_DIR) {
+    const dir = process.env.RSC_HOOK_MARKER_DIR;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  }
+  let uid = 'anon';
+  try { uid = String(userInfo().uid ?? userInfo().username ?? 'anon'); } catch { /* keep anon */ }
+  const dir = join(tmpdir(), `rsc-hooks-${uid}`);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+// Keys are built from hook payload values, so they can contain anything. Flatten to a safe
+// filename — a key must never be able to point outside the marker directory.
+function safeName(key) {
+  return String(key).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 200);
+}
+
+// Drop markers from previous days so the directory cannot grow without bound. Best-effort.
+function prune(dir, now) {
+  try {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      try {
+        if (now - statSync(p).mtimeMs > PRUNE_AFTER_MS) unlinkSync(p);
+      } catch { /* raced with another hook — fine */ }
+    }
+  } catch { /* unreadable dir — fine */ }
+}
+
+/**
+ * Claim the right to emit `key` once.
+ *
+ * @returns true if this process should print, false if another scope already did.
+ *
+ * `windowMs` bounds how long a claim lasts. Two scopes fire within milliseconds of each other,
+ * while two genuine repeats of the same event (two compactions in one session, which reuse
+ * session_id AND source) are minutes apart — so an expired marker means "new event", not
+ * "duplicate". This window is the one heuristic in the design, and only SessionStart needs it:
+ * UserPromptSubmit keys on prompt_id, which is already unique per turn.
+ */
+export function claimOnce(key, { dir = markerDir(), windowMs = 30_000, now = Date.now() } = {}) {
+  try {
+    const file = join(dir, safeName(key));
+    try {
+      // Atomic create: whichever scope gets here first is the one that prints.
+      writeFileSync(file, String(now), { flag: 'wx' });
+      prune(dir, now);
+      return true;
+    } catch {
+      // Marker exists. Fresh → someone else already emitted this exact event.
+      const age = now - statSync(file).mtimeMs;
+      if (age <= windowMs) return false;
+      // Stale → this is a new occurrence of the same key. Re-arm and print.
+      const stamp = new Date(now);
+      utimesSync(file, stamp, stamp);
+      return true;
+    }
+  } catch {
+    return true; // fail-open
+  }
+}
+
+// The SDD gate text lives here, not inline in userprompt-gate.mjs, so it has exactly one
+// definition: the hook emits it and `rsc doctor` measures it from the same constant. Anything
+// that reports a byte count for text it does not own drifts the moment the text changes.
+export const SDD_GATE_TEXT = `===== rsc SDD new-feature gate (highest precedence) =====
+Before acting on this turn: if the user wants to BUILD, ADD, or CHANGE a feature — in
+ANY language, judged by intent, not by keywords — you MUST route it through SDD via
+\`specify\` FIRST. No feature code is written by ANY skill (stack skills included —
+nextjs/react/fastapi/flutter/go/postgresdb/building-agents/design — and any builder skill
+such as chatbot/course-builder/marketing) until a spec AND a plan exist and the user has
+approved them. No skill outranks this gate.
+- Unclear / in-between? -> \`specify\` (the safe default; a skipped spec is where drift hides).
+- One-line / low-risk change, or a bug fix restoring intended behaviour? -> skip the chain,
+  do it, and say so out loud.
+Full gate + decision table live in the always-on \`suggest\` body; method in \`sdd\`.
+=========================================================
+`;
+
+/**
+ * Parse the hook payload Claude Code writes to stdin.
+ * Pass `raw` explicitly in tests; in a hook, call with no argument to read fd 0.
+ * Any problem (no stdin, closed fd, malformed JSON) degrades to {} — callers then fail open.
+ */
+export function readHookInput(raw) {
+  try {
+    const text = raw === undefined ? readFileSync(0, 'utf8') : raw;
+    if (!text || !text.trim()) return {};
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}

package/targets/session-start.mjs

@@ -5,14 +5,26 @@
 // Always emits suggest's always-on body; appends an onboarding banner when the
 // workspace has no harness profile yet, and an auto-ingest nudge when there is
 // un-ingested material waiting in the inbox.
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { claimOnce, readHookInput } from './hook-once.mjs';
 
 const STALE_AUDIT_DAYS = 14; // periodic skill-audit cadence (kept in sync with scripts/audit.js)
 
 const suggestMd = process.argv[2];
 const root = process.argv[3] || process.cwd();
 
+// When rsc is wired in more than one scope (user + project), every scope runs this script and the
+// always-on body lands once per scope. Both invocations share Claude Code's session_id, so the
+// first one to claim the event emits and the rest stay silent. `source` is part of the key so a
+// later compaction — which reuses the session_id — still re-injects, as it must.
+// No session id (no stdin / older Claude Code) → claimOnce fails open and we emit as before.
+const hook = readHookInput();
+const emitBody = hook.session_id
+  ? claimOnce(`ss:${hook.session_id}:${hook.source || 'startup'}`)
+  : true;
+
 const has = (...p) => existsSync(join(root, ...p));
 
 // Is a Context7 MCP server configured for this project (.mcp.json → mcpServers.context7)?
@@ -31,7 +43,64 @@ function auditDue() {
   } catch { return true; }
 }
 
-try { process.stdout.write(readFileSync(suggestMd, 'utf8')); } catch { /* missing → emit nothing */ }
+if (emitBody) {
+  try { process.stdout.write(readFileSync(suggestMd, 'utf8')); } catch { /* missing → emit nothing */ }
+}
+
+// De-dup above only works when EVERY wired scope runs an updated hook. A scope left behind keeps
+// emitting its own copy and cannot be silenced from here, so the only honest move is to say which
+// scope is lagging and how to fix it. Cadence-limited (this is advice, not an alarm) and opt-out-able.
+const SCOPE_WARN_DAYS = 7;
+
+function versionAt(scopeRoot) {
+  try { return readFileSync(join(scopeRoot, '.rsc', '.version'), 'utf8').trim() || null; } catch { return null; }
+}
+
+function isWiredScope(scopeRoot) {
+  try { return readFileSync(join(scopeRoot, '.claude', 'settings.json'), 'utf8').includes('.rsc/'); } catch { return false; }
+}
+
+function olderThan(a, b) {
+  const pa = String(a).split('.').map(Number); const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return true;
+    if ((pa[i] || 0) > (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+function scopeWarnDue() {
+  try {
+    const { lastRun } = JSON.parse(readFileSync(join(root, '.rsc', 'dup-scope.json'), 'utf8'));
+    return (Date.now() - new Date(lastRun).getTime()) / 86400000 >= SCOPE_WARN_DAYS;
+  } catch { return true; }
+}
+
+if (!has('.rsc', '.no-scope-check') && scopeWarnDue()) {
+  // The complementary scope: from a project root it is the user's home, and vice versa.
+  const home = homedir();
+  const other = resolve(root) === resolve(home) ? (hook.cwd && resolve(hook.cwd) !== resolve(home) ? hook.cwd : null) : home;
+  const mine = versionAt(root);
+  const theirs = other ? versionAt(other) : null;
+  // Both versions must be readable to make a claim; an unreadable scope is not evidence of a problem.
+  if (other && mine && theirs && isWiredScope(other) && olderThan(theirs, mine)) {
+    process.stdout.write(`
+===== rsc duplicate rsc scope =====
+rsc is wired in TWO scopes and one is out of date, so this session receives the always-on
+block and the SDD gate TWICE — once per scope. Only the updated scope can de-duplicate.
+  this scope:    ${root} (${mine})
+  lagging scope: ${other} (${theirs})
+ACTION: update the lagging scope, then it will stay silent on its own:
+  cd "${other}" && npx @ericrisco/rsc@latest
+Opt out with .rsc/.no-scope-check · this notice repeats at most every ${SCOPE_WARN_DAYS} days.
+===================================
+`);
+    try {
+      mkdirSync(join(root, '.rsc'), { recursive: true });
+      writeFileSync(join(root, '.rsc', 'dup-scope.json'), JSON.stringify({ lastRun: new Date().toISOString() }) + '\n');
+    } catch { /* unwritable → the notice simply repeats next session */ }
+  }
+}
 
 const profile = join(root, '02-DOCS', 'wiki', 'harness', 'user-profile.md');
 const optout = join(root, '.rsc', '.no-harness');

package/targets/userprompt-gate.mjs

@@ -13,22 +13,19 @@
 // Fail-open (never blocks a turn). Opt out per project with .rsc/.no-feature-gate.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { claimOnce, readHookInput, SDD_GATE_TEXT } from './hook-once.mjs';
 
 const root = process.argv[2] || process.cwd();
 
 // Opt-out: a project that does not want the always-on gate drops this marker file.
 if (existsSync(join(root, '.rsc', '.no-feature-gate'))) process.exit(0);
 
-process.stdout.write(`===== rsc SDD new-feature gate (highest precedence) =====
-Before acting on this turn: if the user wants to BUILD, ADD, or CHANGE a feature — in
-ANY language, judged by intent, not by keywords — you MUST route it through SDD via
-\`specify\` FIRST. No feature code is written by ANY skill (stack skills included —
-nextjs/react/fastapi/flutter/go/postgresdb/building-agents/design — and any builder skill
-such as chatbot/course-builder/marketing) until a spec AND a plan exist and the user has
-approved them. No skill outranks this gate.
-- Unclear / in-between? -> \`specify\` (the safe default; a skipped spec is where drift hides).
-- One-line / low-risk change, or a bug fix restoring intended behaviour? -> skip the chain,
-  do it, and say so out loud.
-Full gate + decision table live in the always-on \`suggest\` body; method in \`sdd\`.
-=========================================================
-`);
+// rsc wired in both user and project scope runs this once per scope, so the gate lands twice on
+// every turn. `prompt_id` is unique per turn and identical across scopes, which makes the dedup
+// exact — no time heuristic needed. Older Claude Code has no prompt_id: fall back to the prompt
+// text, and if there is nothing to key on at all, emit (a duplicated gate beats a missing one).
+const hook = readHookInput();
+const turnKey = hook.prompt_id || (hook.prompt ? `p${hook.prompt.length}:${hook.prompt.slice(0, 64)}` : null);
+if (hook.session_id && turnKey && !claimOnce(`up:${hook.session_id}:${turnKey}`)) process.exit(0);
+
+process.stdout.write(SDD_GATE_TEXT);