@ericrisco/rsc 2.0.0 → 2.0.2

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0",
+  "version": "2.0.2",
   "counts": {
     "skills": 273,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -1,3 +1,4 @@
+import { hooksDir, hooksDirIsOurs } from '../targets/worktree-reaper.mjs';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
@@ -84,9 +85,21 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
 // different answers: armed, absent (repair it), or someone else's (leave it — chaining is our job
 // at install time, and overwriting a husky hook to fix a convenience would be indefensible).
 function worktreeCleanupStatus(root) {
-  const hook = join(root, '.git', 'hooks', 'post-merge');
   if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
   if (existsSync(join(root, '.rsc', '.no-worktree-cleanup'))) return { state: 'off-by-choice' };
+  // Ask git where hooks live instead of assuming `.git/hooks`. Until 2.0.1 this read the assumed
+  // path, so on a repo with its own `core.hooksPath` it found our inert file there and answered
+  // `armed` about a hook git would never run — the check confirming the exact failure it exists to
+  // catch. `unreachable` is its own state on purpose: `repair` re-runs the same install, so
+  // recommending it here would send the reader round the same loop (P6 wants a way out, not a ring).
+  const dir = hooksDir(root);
+  if (!hooksDirIsOurs(root, dir)) {
+    return {
+      state: 'unreachable',
+      action: `git reads hooks from ${dir}, which belongs to this repo or to another tool (husky, lefthook, a committed dispatcher). rsc will not write there. To arm the cleanup, add \`node "$(git rev-parse --show-toplevel)/.rsc/worktree-reaper.mjs" "$(git rev-parse --show-toplevel)" auto\` to your own post-merge hook.`,
+    };
+  }
+  const hook = join(dir, 'post-merge');
   if (!existsSync(hook)) {
     return { state: 'absent', action: 'Run `npx @ericrisco/rsc repair` to arm the post-merge cleanup in this clone.' };
   }
@@ -445,6 +458,18 @@ export function contextBudget({ target, home = homedir(), cwd = process.cwd() }
     });
   }
   const drift = divergence({ cwd, target, home });
+  // A separate finding, not a fourth clause of the one below: that one says this checkout
+  // is behind its own team, and the fix is to align with the declaration. This one says the
+  // declaration itself is behind the catalog, so aligning with it changes nothing. Folded
+  // together, the report would name the right skill and the wrong reason.
+  if (drift.floorMissing?.length) {
+    findings.push({
+      id: 'floor-missing',
+      severity: 'high',
+      summary: `.rsc.json predates a skill the catalog now requires: ${drift.floorMissing.join(', ')}. The always-on body routes work to it, so that route currently answers nowhere.`,
+      action: 'Run `npx @ericrisco/rsc sync` — it adds what the catalog requires and touches nothing else.',
+    });
+  }
   if (drift.missing.length || drift.extra.length || drift.ownMissing.length) {
     // The day-two case: a teammate changed the harness and this checkout has not caught
     // up. Reported always, even after someone declines to align — the divergence does not

package/scripts/install-apply.js

@@ -10,6 +10,7 @@ import {
   resolveAgentNames, agentByName, allAgentNames, readDeveloperTier,
 } from '../targets/agents.js';
 import { readState, writeState } from './lib/state.js';
+import { withDefaultSkillFloor } from './lib/default-skill-floor.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { createBackup } from './lib/backups.js';
 import {
@@ -251,15 +252,20 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   // content — declares a narrower set of paths, and writing a git hook it never agreed to would be
   // acting outside the plan the user accepted (P4). Caught by the onboarding route-inventory gate,
   // which is exactly the kind of catch that justifies its existence.
+  // The answer used to be discarded, so a hook that could not arm looked exactly like one that
+  // did — and the only place that could have noticed, `doctor`, was reading the same wrong path.
+  // Reported 2026-09-18. Carried out, never thrown: the harness installing is the point, and the
+  // merge hook is a convenience layered on top of it.
+  let mergeHook = { installed: false, state: 'skipped' };
   try {
     if (policy?.codeHooks === false) throw new Error('code hooks not governed by the accepted plan');
     mkdirSync(join(cwd, '.rsc'), { recursive: true });
     cpSync(join(ROOT, 'targets', 'worktree-reaper.mjs'), join(cwd, '.rsc', 'worktree-reaper.mjs'));
     const { installMergeHook } = await import('../targets/worktree-reaper.mjs');
-    if (existsSync(join(cwd, '.git'))) installMergeHook(cwd);
-  } catch { /* a project without git, or a read-only .git: the cleanup simply does not arm here */ }
+    if (existsSync(join(cwd, '.git'))) mergeHook = installMergeHook(cwd);
+  } catch (err) { mergeHook = { installed: false, state: 'skipped', reason: err.message }; }
   ignoreLocalState(cwd, target);
-  return { ...state, backup };
+  return { ...state, backup, mergeHook };
 }
 
 // `.rsc/` holds local machine state — hook scripts, install markers, the sello's
@@ -534,9 +540,16 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   // then rebuilt from a governed list that predated it and pruned the difference, recursively.
   // Reported by a user and reproduced 2026-09-17. The receipt stays untouched, because it is
   // hash-checked against what the user accepted and is not a log of what happened since.
-  const declared = governedSkills
+  const declaredRaw = governedSkills
     ? [...new Set([...governedSkills, ...(manifest?.skills || [])])].sort()
     : (ids.length ? ids : (manifest?.skills || []));
+  // A declaration is frozen at the moment it was written, so a skill the catalog later makes
+  // mandatory never reaches an existing harness: `add` and `install` apply the floor, sync did
+  // not, and sync is the only one an upgrade runs. 2.0.0 shipped the three-lane decisor inside
+  // `suggest` — already declared, so already upgraded — routing ordinary work to an `ftd` that
+  // sync had no reason to fetch. Applied only to a harness that already declares something: a
+  // directory declaring nothing is not a harness missing its floor.
+  const declared = declaredRaw.length ? withDefaultSkillFloor(declaredRaw) : declaredRaw;
   const declaredAgents = state.explicitAgents?.length ? state.explicitAgents : (manifest?.agents || []);
   if (!declared.length && !declaredAgents.length) return dryRun ? { dryRun: true, synced: [], syncedAgents: [], paths: [] } : { synced: [], syncedAgents: [], backup: null };
   if (dryRun) {

package/scripts/lib/default-skill-floor.js

@@ -4,7 +4,12 @@
 // `orient` and `suggest` are runtime always-on. `bro` is installed by default
 // but remains conditionally loaded: its description routes human-language asks
 // without paying for its body on unrelated turns.
-export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'bro']);
+//
+// `ftd` joined in 2.0.1 by the same criterion as `suggest`: the always-on decisor
+// routes ordinary work to `../ftd/SKILL.md`, so a harness without it has a default
+// lane that points at nothing. Membership of every profile was not enough — a
+// declaration written before the skill existed never gains it (see `syncInstalled`).
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'bro', 'ftd']);
 
 export function withDefaultSkillFloor(skillIds = []) {
   return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];

package/scripts/lib/divergence.js

@@ -2,6 +2,7 @@ import { readManifest } from './manifest-file.js';
 import { readState } from './state.js';
 import { targetPaths } from '../../targets/index.js';
 import { existsSync } from 'node:fs';
+import { DEFAULT_SKILL_FLOOR } from './default-skill-floor.js';
 
 // What the team declared versus what is on this machine.
 //
@@ -15,10 +16,13 @@ import { existsSync } from 'node:fs';
 //   ownMissing — declared team skill, absent from the repo. Aligning says so and writes
 //                nothing: it comes from the repo, not from us.
 //   extra      — installed BY RSC, no longer declared.
+//   floorMissing — a skill the catalog makes mandatory that this declaration predates.
+//                Not drift between teammates: drift between the harness and the catalog,
+//                and the only bucket that survives everyone running the same `git pull`.
 // A hand-written skill that nobody declared is in none of them. Not declaring is a valid
 // way to keep things of your own, not an oversight to correct.
 export function divergence({ cwd = process.cwd(), target, home } = {}) {
-  const empty = { missing: [], extra: [], ownMissing: [] };
+  const empty = { missing: [], extra: [], ownMissing: [], floorMissing: [] };
   const manifest = readManifest(cwd);
   if (!manifest) return empty;
 
@@ -29,5 +33,8 @@ export function divergence({ cwd = process.cwd(), target, home } = {}) {
     missing: (manifest.skills || []).filter((id) => !installed.has(id)),
     extra: [...installed].filter((id) => !(manifest.skills || []).includes(id)),
     ownMissing: (manifest.ownSkills || []).filter((name) => !existsSync(paths.skillDir(name))),
+    // Read off the declaration, not off the disk: a skill installed by hand into a harness
+    // that still does not declare it is one sync away from being pruned again.
+    floorMissing: DEFAULT_SKILL_FLOOR.filter((id) => !(manifest.skills || []).includes(id)),
   };
 }

package/targets/worktree-reaper.mjs

@@ -428,6 +428,41 @@ node "$root/.rsc/worktree-reaper.mjs" "$root" auto 2>/dev/null || true
 exit 0
 `;
 
+/**
+ * Where git will ACTUALLY look for hooks, asked of git rather than assumed.
+ *
+ * The assumption was `<root>/.git/hooks`, and it is wrong in three ordinary situations at once:
+ * a repo that sets `core.hooksPath` (husky v9 writes `.husky/_`, lefthook and committed
+ * `.githooks/` dispatchers do the same), a linked worktree where `.git` is a FILE and the mkdir
+ * raised ENOTDIR, and a submodule. Reported from a user's repo on 2026-09-18 against 2.0.1: rsc
+ * wrote the hook where git does not look, `doctor` read the same wrong path back, and the report
+ * said `armed` about something that could never run. Verified there and here that a single
+ * `rev-parse` answers all three.
+ *
+ * `--path-format=absolute` needs git 2.31 (Mar 2021). Older git gets the old path — which is
+ * correct whenever `core.hooksPath` is unset, i.e. the case it was always right about.
+ */
+export function hooksDir(root) {
+  const r = git(root, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+  if (r.ok && r.out) return r.out;
+  return join(real(root), '.git', 'hooks');
+}
+
+// Whether that directory is ours to write in. Inside the repository's own git dir: yes, it is
+// private plumbing that is never cloned and never committed. Anywhere else it belongs to the user
+// or to another tool — a committed `.githooks/` is their source tree (writing there would put rsc
+// in their diff, and moving an existing hook aside would rename a TRACKED file), and `.husky/_` is
+// regenerated by husky, so anything we left there disappears on their next install. Report it and
+// let the person decide; that is P4, and it is the same reasoning the comment on this function has
+// claimed since the hook shipped, finally applied instead of only stated.
+export function hooksDirIsOurs(root, dir) {
+  const r = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!r.ok || !r.out) return false;
+  const gitDir = real(r.out);
+  const target = real(dir);
+  return target === gitDir || target.startsWith(gitDir + sep);
+}
+
 /**
  * Install the trigger. The judgement has existed and been tested for a while; what never existed was
  * something that runs it at the moment work lands. `post-merge` is that moment, and it covers both
@@ -442,7 +477,10 @@ exit 0
  */
 export function installMergeHook(root) {
   try {
-    const dir = join(real(root), '.git', 'hooks');
+    const dir = hooksDir(root);
+    if (!hooksDirIsOurs(root, dir)) {
+      return { installed: false, state: 'unreachable', reason: `git reads hooks from ${dir}, which belongs to this repository or to another tool — rsc will not write there.` };
+    }
     const hook = join(dir, 'post-merge');
     mkdirSync(dir, { recursive: true });
     if (existsSync(hook)) {
@@ -461,7 +499,7 @@ export function installMergeHook(root) {
     chmodSync(hook, 0o755);
     return { installed: true, chained: existsSync(join(dir, 'post-merge.rsc-local')) };
   } catch (err) {
-    return { installed: false, reason: err.message };
+    return { installed: false, state: 'failed', reason: err.message };
   }
 }