@ericrisco/rsc 2.0.1 → 2.0.3

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.1",
+  "version": "2.0.3",
   "counts": {
     "skills": 273,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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.' };
   }

package/scripts/install-apply.js

@@ -252,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

package/skills/worktrees/SKILL.md

@@ -75,7 +75,11 @@ Run this in order. Each check prevents a class of "lost work" you can't easily u
    local HEAD. Stale base = predictable merge pain later. Default: fresh from `origin/<default>`.
 6. **Choose a name** tied to the feature slug — the same `<slug>` the spec and plan use
    (`feat/<slug>`), so the branch, the spec at `02-DOCS/wiki/sdd/specs/<slug>.md`, and the plan at
-   `02-DOCS/wiki/sdd/plans/<slug>.md` all line up and are trivially traceable.
+   `02-DOCS/wiki/sdd/plans/<slug>.md` all line up and are trivially traceable. A change that is not
+   a feature takes the type that fits — `fix/<slug>`, `docs/<slug>`, `chore/<slug>` — from the same
+   Conventional Commits vocabulary the commit guard already enforces here. **The prefix is load
+   bearing**: the automatic cleanup uses it, with the location, as the two signals that say a
+   worktree is ours to remove. A name outside that vocabulary is never swept for you.
 
 Only once the tree state is understood and the user's WIP is accounted for do you create anything.
 
@@ -189,7 +193,7 @@ the dial controls verbosity, never whether you check before risking someone's WI
 | "There's uncommitted WIP, I'll stash it and switch" | A worktree avoids the stash entirely and can't drop it. Use a worktree; if you must stash, confirm with the user and name the stash. |
 | "I'll branch off local HEAD, fetching is slow" | Stale base = merge conflicts you pay for later. Branch off an up-to-date `origin/<default>` unless the user wants HEAD. |
 | "The worktree's dirty but I'll `remove --force` to clean up" | Force-removing a dirty/unmerged worktree throws away work irreversibly. Resolve or confirm explicitly first; never silent-force. |
-| "I'll name it `wip` / `temp` / `branch2`" | An untraceable name divorces the branch from its spec/plan. Name it `feat/<slug>` to match the SDD artifacts. |
+| "I'll name it `wip` / `temp` / `branch2`" | An untraceable name divorces the branch from its spec/plan, and the automatic cleanup will not claim it. Use `<type>/<slug>` — `feat/` for a feature, `fix/`, `docs/`, `chore/` for the rest. |
 | "I'll create the worktree AND start writing code right here" | This skill only isolates. Hand a clean isolated workspace to `implement`; don't blur the two steps. |
 | "Already on a feature branch, I'll make a worktree anyway" | Redundant isolation is just clutter. If the current branch is already isolated and clean, say so and proceed. |
 | "I'll record the worktree path into 02-DOCS so it's tracked" | Isolation is plumbing, not knowledge. No artifact; the branch name traces it. Don't pollute the wiki. |

package/targets/worktree-reaper.mjs

@@ -53,8 +53,20 @@ export const REGENERABLE_FILES = ['.DS_Store', 'Thumbs.db', '.coverage'];
 // Trunk candidates, most authoritative first. The remote tip beats a local branch that may be stale.
 const TRUNKS = ['origin/main', 'main', 'origin/master', 'master'];
 
-// Branch shapes `worktrees` imposes on the isolation it creates.
-const RSC_BRANCH = /^(?:feat|feature)\//;
+// Branch shapes the catalog's isolation produces.
+//
+// `worktrees` documents `feat/<slug>`, and while SDD was the only lane that was the whole set:
+// every isolated branch was a feature. 2.0.0 made FTD the default and FTD names a branch for what
+// it is — a fix is not a feature — so `fix/`, `docs/` and `chore/` fell outside, scored as half a
+// signal, and were never swept, while `ftd` promises in writing that the cleanup is automatic once
+// the branch lands. Found by using it: the two fixes released on 2026-09-18 both had to be removed
+// by hand. These are the Conventional Commits types, which is what the commit guard already
+// enforces on every commit in a project rsc governs — so the branch shape and the commit shape now
+// come from the same vocabulary instead of two that drifted apart.
+//
+// Widening one signal, never the conjunction: a branch outside this vocabulary is still `ambiguous`
+// wherever it sits, and one of these in a directory rsc does not own is still `ambiguous` too.
+const RSC_BRANCH = /^(?:feat|feature|fix|docs|chore|refactor|test|perf|ci|build|style)\//;
 
 function git(cwd, args) {
   // 64 MiB, because node's 1 MiB default kills git mid-write on any worktree with a few thousand
@@ -428,6 +440,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 +489,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 +511,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 };
   }
 }