@ericrisco/rsc 1.2.2 → 1.3.0

package/scripts/rsc.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { loadManifest, skillsForProfile } from './lib/manifest.js';
-import { detectTarget, resolveTargets, TARGETS } from '../targets/index.js';
+import { detectTarget, installedTargets, resolveTargets, TARGETS } from '../targets/index.js';
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
 import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purge, collisions } from './install-apply.js';
 import { stackAgentNames } from '../targets/agents.js';
 import { doctor } from './doctor.js';
-import { say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
+import { ask, say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
 import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
@@ -15,9 +15,32 @@ import { listBackups, restoreBackup } from './lib/backups.js';
 import { runUpgrade } from './lib/upgrade.js';
 import { diagnose, repair } from './lib/repair.js';
 import { DEFAULT_SKILL_FLOOR, withDefaultSkillFloor } from './lib/default-skill-floor.js';
+import { readManifest, writeManifest } from './lib/manifest-file.js';
+import {
+  normalizeOnboarding, missingOnboardingFields, scanProject,
+  buildOnboardingPlan, decodeGoal, encodeGoal, identifyPlan, recommendDeferredComponents,
+} from './lib/onboarding.js';
+import { applyAcceptedOnboarding, verifyOnboarding } from './lib/onboarding-apply.js';
 
-const argv = process.argv.slice(2);
-const cmd = argv[0];
+const rawArgv = process.argv.slice(2);
+const GLOBAL_VALUE_FLAGS = new Set([
+  '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--accept-plan',
+]);
+const COMMANDS = new Set(['onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'sello', 'repair', 'uninstall', 'purge']);
+function positionalTokens(input) {
+  const out = [];
+  for (let i = 0; i < input.length; i++) {
+    if (GLOBAL_VALUE_FLAGS.has(input[i]) || input[i] === '--profile' || input[i] === '--without') { i++; continue; }
+    if (input[i].startsWith('--')) continue;
+    out.push(input[i]);
+  }
+  return out;
+}
+const candidate = positionalTokens(rawArgv)[0];
+const cmd = candidate || undefined;
+const argv = cmd && COMMANDS.has(cmd)
+  ? [cmd, ...rawArgv.filter((_, index) => index !== rawArgv.indexOf(cmd))]
+  : rawArgv;
 
 const targetLabel = (id) => TARGETS.find((t) => t.id === id)?.label || id;
 
@@ -32,6 +55,184 @@ function requestedIds(start = 1) {
   return ids;
 }
 
+function onboardingInput(targets) {
+  const value = (name) => {
+    const v = flag(name);
+    return typeof v === 'string' && !v.startsWith('--') ? v : undefined;
+  };
+  return {
+    schemaVersion: 1,
+    technicalLevel: value('technical-level'),
+    accompaniment: value('accompaniment'),
+    projectKind: value('project-kind'),
+    goal: value('goal') || (value('goal-base64') ? decodeGoal(value('goal-base64')) : undefined),
+    softwareScope: value('software-scope'),
+    targets,
+  };
+}
+
+function onboardingRequired(raw, action = 'onboard') {
+  const payload = {
+    code: 'RSC_ONBOARDING_REQUIRED',
+    schemaVersion: 1,
+    missing: missingOnboardingFields(raw),
+    recovery: `Run npx @ericrisco/rsc@latest ${action} --technical-level <non-technical|mixed|technical> --accompaniment <L0|L1|L2|L3> --project-kind <software|operations|research|content|mixed> --goal "<what you want>" --target <assistant>`,
+  };
+  console.error(`RSC_ONBOARDING_REQUIRED ${JSON.stringify(payload)}`);
+  process.exitCode = 2;
+}
+
+function hasDeclaredHarness(manifest = readManifest()) {
+  if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.targets) || !manifest.targets.length
+    || !manifest.targets.every((target) => TARGETS.some((known) => known.id === target))
+    || !Array.isArray(manifest.skills) || !manifest.skills.length) return false;
+  const receipt = manifest.onboarding;
+  if (receipt) {
+    try {
+      const verified = receipt.schemaVersion === 1
+        && identifyPlan(receipt.plan) === receipt.acceptedPlanId
+        && verifyOnboarding(process.cwd(), receipt.plan, receipt.acceptedPlanId).length === 0;
+      if (verified) return true;
+      if (receipt.maintenanceDrift && installedTargets(process.cwd()).some((target) => manifest.targets.includes(target))) return true;
+    } catch { return false; }
+  }
+  // Backward compatibility is evidence-based: an actually installed pre-onboarding
+  // harness keeps its maintenance commands. A hand-written or merely committed
+  // declaration with no local state cannot bypass first contact.
+  return installedTargets(process.cwd()).some((target) => manifest.targets.includes(target));
+}
+
+function markMaintenanceDrift(action) {
+  const manifest = readManifest();
+  if (!manifest?.onboarding) return;
+  writeManifest(process.cwd(), {
+    ...manifest,
+    onboarding: {
+      ...manifest.onboarding,
+      maintenanceDrift: { action, recordedAt: new Date().toISOString(), requiresReassessment: true },
+    },
+  });
+}
+
+function renderPlan(plan, planId) {
+  say('RSC_ONBOARDING_PLAN');
+  say(`Plan id: ${planId}`);
+  say(`Project: ${plan.record.projectKind}${plan.record.softwareScope ? ` (${plan.record.softwareScope})` : ''}`);
+  say(`Targets: ${plan.policy.targets.join(', ')}`);
+  say('Selected:');
+  for (const decision of plan.decisions.filter((d) => d.state === 'selected')) say(`  + ${decision.kind}/${decision.id} — ${decision.reason}`);
+  say('Deferred:');
+  for (const decision of plan.decisions.filter((d) => d.state === 'deferred')) say(`  - ${decision.kind}/${decision.id} — ${decision.reason} Reevaluate: ${decision.reevaluateWhen.join('; ')}`);
+  say('Excluded:');
+  for (const decision of plan.decisions.filter((d) => d.state === 'excluded')) say(`  × ${decision.kind}/${decision.id} — ${decision.reason}`);
+  say('Managed paths:');
+  for (const path of plan.governedPaths) say(`  ${path}`);
+  if (plan.evidence.parentHarness) say(`Parent harness detected at ${plan.evidence.parentHarness}; it is not inherited by this plan.`);
+  const pieces = [
+    'npx @ericrisco/rsc@latest onboard',
+    `--technical-level ${plan.record.technicalLevel}`,
+    `--accompaniment ${plan.record.accompaniment}`,
+    `--project-kind ${plan.record.projectKind}`,
+    `--goal-base64 ${encodeGoal(plan.record.goal)}`,
+    ...(plan.record.softwareScope ? [`--software-scope ${plan.record.softwareScope}`] : []),
+    `--target ${plan.record.targets.join(',')}`,
+    `--accept-plan ${planId}`,
+  ];
+  say(`Accept exactly this plan: ${pieces.join(' ')}`);
+}
+
+async function runOnboarding(targets) {
+  const raw = onboardingInput(targets);
+  if (isInteractive() && missingOnboardingFields(raw).length) {
+    await banner(loadManifest().counts.skills);
+    say('Before rsc writes anything, it will learn how to help and show the exact harness plan.');
+    raw.technicalLevel ||= await select('How technical should the conversation be?', [
+      { key: 'non-technical', label: 'Plain language — explain terms and avoid code jargon' },
+      { key: 'mixed', label: 'Mixed — concise explanations with useful technical detail' },
+      { key: 'technical', label: 'Technical — assume I am comfortable with code and tooling' },
+    ]);
+    raw.accompaniment ||= await select('How much accompaniment do you want?', [
+      { key: 'L0', label: 'L0 — results only' },
+      { key: 'L1', label: 'L1 — brief reasons, questions only when needed' },
+      { key: 'L2', label: 'L2 — explain each relevant decision' },
+      { key: 'L3', label: 'L3 — guide me through everything' },
+    ]);
+    raw.projectKind ||= await select('What are you building or running?', [
+      { key: 'software', label: 'Software or a website' },
+      { key: 'operations', label: 'Operations, a company or a process' },
+      { key: 'research', label: 'Research or a knowledge base' },
+      { key: 'content', label: 'Content or publishing' },
+      { key: 'mixed', label: 'A combination of these' },
+    ]);
+    raw.goal ||= await ask('What do you want this project to achieve? > ');
+    if ((raw.projectKind === 'software' || raw.projectKind === 'mixed') && !raw.softwareScope) {
+      raw.softwareScope = await select('How much software work is expected now?', [
+        { key: 'small', label: 'Small — one focused tool or a few simple changes' },
+        { key: 'growing', label: 'Growing — several related features or integrations' },
+        { key: 'complex', label: 'Complex — multiple systems, teams or critical behavior' },
+      ]);
+    }
+    if (!raw.targets?.length) raw.targets = await selectAgents();
+    if (!raw.technicalLevel || !raw.accompaniment || !raw.projectKind || !raw.goal || !raw.targets?.length) {
+      say('Cancelled — nothing was touched.');
+      return;
+    }
+  }
+  if (missingOnboardingFields(raw).length) return onboardingRequired(raw);
+  let record;
+  try { record = normalizeOnboarding(raw); } catch (error) {
+    console.error(`RSC_ONBOARDING_INVALID: ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+  const plan = buildOnboardingPlan(record, scanProject(process.cwd()));
+  const planId = identifyPlan(plan);
+  const accepted = flag('accept-plan');
+  if (!accepted) {
+    renderPlan(plan, planId);
+    if (!isInteractive()) return;
+    if (!(await confirm('Accept this exact harness plan?'))) return void say('Cancelled — nothing was touched.');
+  }
+  if (accepted && accepted !== planId) {
+    console.error(`RSC_PLAN_CHANGED: accepted ${accepted}, current plan is ${planId}. Regenerate the plan and ask the user to accept the new id.`);
+    process.exitCode = 3;
+    return;
+  }
+  try {
+    await applyAcceptedOnboarding({ cwd: process.cwd(), plan, planId });
+    say(`RSC_ONBOARDING_READY ${planId}`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 4;
+  }
+}
+
+function runReassessment() {
+  const manifest = readManifest();
+  const plan = manifest?.onboarding?.plan;
+  if (!plan) {
+    console.error('RSC_ONBOARDING_REQUIRED: no accepted onboarding receipt. Run npx @ericrisco/rsc@latest onboard');
+    process.exitCode = 2;
+    return;
+  }
+  const recommendations = recommendDeferredComponents(plan, scanProject(process.cwd()));
+  if (!recommendations.length) return void say('RSC_REASSESSMENT_NO_CHANGE');
+  say('RSC_REASSESSMENT_RECOMMENDED');
+  for (const item of recommendations) say(`  ${item.kind}/${item.id}: ${item.explanation}`);
+  const record = recommendations[0].suggestedRecord || plan.record;
+  say('Review a new plan; nothing has been installed:');
+  say([
+    'npx @ericrisco/rsc@latest onboard',
+    `--technical-level ${record.technicalLevel}`,
+    `--accompaniment ${record.accompaniment}`,
+    `--project-kind ${record.projectKind}`,
+    `--goal-base64 ${encodeGoal(record.goal)}`,
+    ...(record.softwareScope ? [`--software-scope ${record.softwareScope}`] : []),
+    `--target ${record.targets.join(',')}`,
+  ].join(' '));
+  say('Show the new plan and ask the user to accept its id before applying it.');
+}
+
 function editDistance(a, b) {
   const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
@@ -73,7 +274,7 @@ function reportUnknown(ids) {
 // flag says which: `purge` sweeps every target by design, and the catalog/consult
 // side barely touches one, so blocking them would be a regression, not a safeguard.
 const NEEDS_TARGET = new Set([
-  'add', 'install', 'list', 'doctor', 'sync', 'uninstall', 'capabilities', 'catalog', 'registry',
+  'onboard', 'add', 'install', 'list', 'doctor', 'sync', 'uninstall', 'capabilities', 'catalog', 'registry',
 ]);
 
 function flag(name) {
@@ -317,24 +518,38 @@ async function main() {
   const target = targets[0];
   switch (cmd) {
     case undefined:
-      return wizard(f ? targets : null);
+      return hasDeclaredHarness() ? wizard(f ? targets : null) : runOnboarding(f ? targets : []);
+    case 'onboard':
+      return runOnboarding(f ? targets : []);
+    case 'reassess':
+      return runReassessment();
     case 'add': {
+      if (!hasDeclaredHarness()) return onboardingRequired(onboardingInput(targets));
       const requested = requestedIds();
       const selected = classifyRequested(requested);
       if (reportUnknown(selected.unknown)) return;
       const ids = withDefaultSkillFloor(selected.skills);
       if (!argv.includes('--force') && !(await guardCollisions(targets, ids))) return;
-      for (const t of targets) await applyInstall({ skillIds: ids, agentIds: selected.agents, target: t });
+      const currentManifest = readManifest();
+      const receipt = currentManifest?.onboarding;
+      const maintainedIds = receipt ? [...new Set([...(currentManifest.skills || []), ...(receipt.plan.policy.skills || []), ...ids])].sort() : ids;
+      const policy = receipt ? { ...receipt.plan.policy, skills: maintainedIds } : undefined;
+      for (const t of targets) await applyInstall({ skillIds: maintainedIds, agentIds: selected.agents, target: t, policy });
+      markMaintenanceDrift(`add ${requested.join(',')}`);
       say(`✅ Installed for ${targets.join(', ')}: ${requested.join(', ')}`);
       return void say('   ↻ Reload/restart your assistant so the new skill activates.');
     }
     case 'install': {
+      if (!hasDeclaredHarness()) return onboardingRequired(onboardingInput(targets));
       const profile = flag('profile') || 'minimal';
       const without = argv.filter((a, i) => argv[i - 1] === '--without');
       let ids = skillsForProfile(loadManifest(), profile);
       ids = withDefaultSkillFloor(ids).filter((id) => !without.includes(id));
       if (!argv.includes('--force') && !(await guardCollisions(targets, ids))) return;
-      for (const t of targets) await applyInstall({ skillIds: ids, target: t });
+      const receipt = readManifest()?.onboarding;
+      const policy = receipt ? { ...receipt.plan.policy, skills: ids } : undefined;
+      for (const t of targets) await applyInstall({ skillIds: ids, target: t, policy });
+      markMaintenanceDrift(`install ${profile}`);
       say(`✅ Profile '${profile}' installed for ${targets.join(', ')} (${ids.length} skills)`);
       printAgentHandoff();
       return;
@@ -806,7 +1021,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
       say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
       say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
       process.exitCode = 1;

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/design/scripts/verify.sh

@@ -91,7 +91,10 @@ search() {
   # only exercising whichever one happens to be installed.
   if have rg && [ -z "${VERIFY_FORCE_GREP:-}" ]; then
     # rg already ignores .gitignore'd paths (node_modules, .next, dist); also skip self.
-    rg -n --no-heading --glob "!$SELF_NAME" "$@"
+    # Always name the search root. run_tell_table feeds its registry through stdin;
+    # without an explicit path ripgrep treats that stdin as the search corpus and
+    # silently checks the registry text instead of the project files.
+    rg -n --no-heading --glob "!$SELF_NAME" "$@" .
   else
     # last arg is the pattern; everything before are paths/globs we ignore for grep.
     # `${*: -1}` (last positional) is supported on bash 3.2; the space before -1 is required.

package/skills/suggest/SKILL.md

@@ -42,6 +42,9 @@ request. If the user engaged **SDD autopilot**, that one consent covers the whol
 through the phases without re-asking.
 
 If `specify` / `sdd` are not installed, offer to add them (§2) before routing.
+When `.rsc.json` records SDD as deferred, first run `npx @ericrisco/rsc@latest reassess`.
+Stay silent on `RSC_REASSESSMENT_NO_CHANGE`. If it reports new evidence, explain what changed and
+show the new plan command; SDD still needs a newly accepted plan id and is never added silently.
 
 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.

package/targets/_md-block.js

@@ -17,8 +17,11 @@ export function writeSkill(id, fromDir, toPath) {
   return linkOrCopy(fromDir, toPath);
 }
 
-export function wireHook(paths, sourceMd) {
-  const body = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+export function wireHook(paths, sourceMd, policy = {}) {
+  const full = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+  const body = policy.codeHooks === false
+    ? `# rsc-suggest — always-on operations layer\n\nRead \`02-DOCS/wiki/harness/user-profile.md\` before acting. Use \`orient\` to keep the user situated and \`suggest\` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n`
+    : full;
   const block = `${MARK_START}\n${body}\n${MARK_END}`;
   let doc = existsSync(paths.hookTarget) ? readFileSync(paths.hookTarget, 'utf8') : '';
   if (doc.includes(MARK_START)) {

package/targets/claude.js

@@ -79,7 +79,7 @@ export function unwireHook(paths) {
 const P = '${CLAUDE_PROJECT_DIR}';
 const at = (...seg) => `${P}/${seg.join('/')}`;
 
-export function wireHook(paths) {
+export function wireHook(paths, sourceMd, policy = {}) {
   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
@@ -90,8 +90,12 @@ export function wireHook(paths) {
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
-  const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;
-  const suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
+  let suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
+  const operationsSuggest = join(paths.projectRoot, '.rsc', 'suggest-always-on.md');
+  if (policy.codeHooks === false) {
+    writeFileSync(operationsSuggest, '# rsc-suggest — always-on operations layer\n\nRead `02-DOCS/wiki/harness/user-profile.md` before acting. Use `orient` to keep the user situated and `suggest` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n');
+    suggestRel = at('.rsc', 'suggest-always-on.md');
+  } else if (existsSync(operationsSuggest)) rmSync(operationsSuggest, { force: true });
   const cmd = `node "${at('.rsc', 'session-start.mjs')}" "${suggestRel}" "${P}"`;
 
   const file = paths.hookTarget;
@@ -111,6 +115,7 @@ export function wireHook(paths) {
   // the workspace has no harness wiki. Registered idempotently on both events, with
   // any prior rsc worklog-checkpoint entry (.sh or .mjs) dropped first.
   const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.mjs');
+  const written = [paths.hookTarget, scriptDest, wlDest];
   copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
   const wlCmd = `node "${at('.rsc', 'worklog-checkpoint.mjs')}" "${P}"`;
   for (const event of ['PreCompact', 'SessionEnd']) {
@@ -121,6 +126,7 @@ export function wireHook(paths) {
     settings.hooks[event].push({ hooks: [{ type: 'command', command: wlCmd }] });
   }
 
+  if (policy.codeHooks !== false) {
   // Ship guard: a PreToolUse(Bash) hook that DENIES switching to / merging the trunk
   // while the current feature branch has uncommitted or unpushed work — forcing the
   // commit → push → PR close (the `ship` skill). Materialized + node-run (Windows-safe),
@@ -182,8 +188,24 @@ export function wireHook(paths) {
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),
   );
   settings.hooks.UserPromptSubmit.push({ hooks: [{ type: 'command', command: fgCmd }] });
+  written.push(sgDest, dgDest, gmDest, fgDest, join(paths.projectRoot, '.rsc', 'sello.mjs'));
+  } else {
+    for (const event of ['PreToolUse', 'UserPromptSubmit']) {
+      if (!settings.hooks[event]) continue;
+      settings.hooks[event] = settings.hooks[event].filter((entry) => {
+        const body = hookWiringOf(entry);
+        return !body.includes('.rsc/ship-guard.') && !body.includes('.rsc/danger-guard.') &&
+          !body.includes('.rsc/gitmoji-guard.') && !body.includes('.rsc/userprompt-gate.');
+      });
+      if (!settings.hooks[event].length) delete settings.hooks[event];
+    }
+    for (const name of ['ship-guard.mjs', 'danger-guard.mjs', 'gitmoji-guard.mjs', 'userprompt-gate.mjs', 'sello.mjs']) {
+      rmSync(join(paths.projectRoot, '.rsc', name), { force: true });
+    }
+    written.push(operationsSuggest);
+  }
 
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file, scriptDest, wlDest, sgDest, dgDest, gmDest, fgDest];
+  return written;
 }

package/targets/cursor.js

@@ -8,8 +8,11 @@ export function writeSkill(id, fromDir, toPath) {
   return [toPath];
 }
 
-export function wireHook(paths, sourceMd) {
-  const body = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+export function wireHook(paths, sourceMd, policy = {}) {
+  const full = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+  const body = policy.codeHooks === false
+    ? `# rsc-suggest — always-on operations layer\n\nRead \`02-DOCS/wiki/harness/user-profile.md\` before acting. Use \`orient\` and offer missing skills through \`suggest\` only when needed.\n`
+    : full;
   mkdirSync(dirname(paths.hookTarget), { recursive: true });
   writeFileSync(paths.hookTarget, `---\ndescription: rsc auto-suggest\nalwaysApply: true\n---\n${body}`);
   return [paths.hookTarget];

package/targets/index.js

@@ -169,8 +169,8 @@ export function writeSkill(target, id, fromDir, toPath) {
   return ADAPTER[SPEC[target].adapter].writeSkill(id, fromDir, toPath);
 }
 
-export function wireHook(target, paths, sourceMd) {
-  return ADAPTER[SPEC[target].adapter].wireHook(paths, sourceMd);
+export function wireHook(target, paths, sourceMd, policy) {
+  return ADAPTER[SPEC[target].adapter].wireHook(paths, sourceMd, policy);
 }
 
 // Inverse of wireHook — remove rsc's always-on surface for a target (settings.json