@ericrisco/rsc 1.3.6 → 1.4.0

package/README.md

@@ -281,15 +281,33 @@ The harness travels by git, but not all of it — and the split is the point.
 | `02-DOCS/raw/worklog/.rsc-memory/` | Preferred session journal when a local wiki exists; protected with git's local exclude |
 | The skill entries rsc manages | Symlinks on macOS/Linux, real copies on Windows — two incompatible shapes of one thing |
 
-Whoever clones runs **one command** and ends up with the same harness:
+Three files carry the harness through git: `.rsc.json` (what the team decided),
+`.claude/settings.json` (the wiring), and `.claude/rsc-bootstrap.mjs` — the small file that
+notices, in a clone, that the rest is not there yet. **Commit all three.** If your project
+ignores the assistant's directory wholesale, rsc adds the lines that keep those files versioned —
+verified against git, not against the pattern.
+
+**And say it plainly, because committing it is the point:** `.claude/rsc-bootstrap.mjs` is code that
+runs on every session and every shell call, so a pull request that edits *that file* runs on the
+machine of whoever reviews the branch. That is true of `.claude/settings.json` already, and of any
+hook-based harness — but it is worth knowing before you agree to commit a third one. Review changes
+to it the way you would review a CI workflow.
+
+Whoever clones runs **one command** and ends up with the same harness — at the version the
+project pinned, which is the `catalogVersion` in its `.rsc.json`:
 
 ```bash
-npx @ericrisco/rsc@latest sync
+npx @ericrisco/rsc@<catalogVersion> sync
 ```
 
-Same skills, same version — `.rsc.json` pins the catalog, so a teammate who clones in three
-months gets what you had, not what shipped since. Upgrading is a deliberate act, never a side
-effect of rebuilding.
+**You do not have to know that, or find it.** Open the project and the assistant tells you, in
+the first message: what is missing, what would be installed, and the exact command, naming the
+pinned version. It asks; it does not install anything on its own and it does not hold up
+whatever you sat down to do. Say no and it stops asking on that machine.
+
+Not `@latest`, and the difference is the whole point of sharing: a teammate who clones in three
+months gets what you had, not what shipped since. Upgrading is something a person decides, writes
+into `.rsc.json`, and commits — and then it reaches everyone through git, like any other change.
 
 When someone changes the harness and you `git pull`, `rsc doctor` tells you what no longer
 matches. **Nothing is ever written to your machine by a pull** — you are told, and you decide.
@@ -309,10 +327,12 @@ Recognise any of these? They are all the same fix.
 | `"target": "codex"` when you work in Claude Code | |
 | `This target has no hook injection` and you did not expect that | |
 | Skills appear that you never asked for | |
-| You cloned a repo and your assistant sees no skills at all | |
 | A hook seems to run several times per turn | |
 | Template lines showed up inside your hand-written `AGENTS.md` | |
 
+(A *fresh* clone is not in this table any more: nothing is broken there, the harness was simply
+never built on that machine, and the assistant now says so itself — see **sharing by git** above.)
+
 ```bash
 npx @ericrisco/rsc@latest repair
 ```

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.6",
+  "version": "1.4.0",
   "counts": {
     "skills": 272,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "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/install-apply.js

@@ -2,6 +2,7 @@
 import { rmSync, existsSync, cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, appendFileSync, readdirSync } from 'node:fs';
 import { join, dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import {
@@ -66,6 +67,9 @@ function ensureBase(id, cwd, baseVersions) {
 export function generatedHookFiles({ target, cwd, policy }) {
   if (target !== 'claude') return [];
   const lifecycle = [
+    // Committed, not machine state — and therefore the one entry here that, if omitted, leaves an
+    // executable behind in a tree the user pushes.
+    join(cwd, '.claude', 'rsc-bootstrap.mjs'),
     join(cwd, '.rsc', 'session-start.mjs'),
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     join(cwd, '.rsc', 'hook-once.mjs'),
@@ -287,6 +291,32 @@ export function ignoreLocalState(cwd = process.cwd(), target) {
   // keeps this idempotent against a .gitignore a human wrote in their own spelling.
   const norm = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
   const present = new Set(text.split('\n').map(norm));
+  // `.rsc/` is machine state and stays ignored. The two files below are the opposite: they are the
+  // whole reason a clone can help itself, and a project that excluded the assistant's directory
+  // wholesale (rsc's own repo does exactly that, so copying the example is likely) swallows both with
+  // no symptom at all.
+  //
+  // Asked of GIT, not of the pattern. The first attempt at this reasoned about spellings and shipped
+  // a negation that was INERT in every case it fired: git does not descend into an excluded
+  // directory, so `!.claude/rsc-bootstrap.mjs` under `.claude/` rescues nothing. Measured, not
+  // argued — and the lesson is the one this repo keeps relearning, that a rule believed and untrue is
+  // worse than no rule.
+  const RESCUE = ['.claude/rsc-bootstrap.mjs', '.claude/settings.json'];
+  const swallowed = RESCUE.filter((f) => {
+    try {
+      return spawnSync('git', ['check-ignore', '-q', '--', f], { cwd }).status === 0;
+    } catch {
+      return false;
+    }
+  });
+  if (swallowed.length) {
+    // Append-only, and this exact order is what makes it work at all: re-include the directory so git
+    // will descend into it, exclude everything inside it again, then rescue by name. Verified against
+    // git itself — `settings.local.json` and the skill entries stay ignored.
+    const dir = swallowed[0].split('/')[0];
+    for (const line of [`!${dir}/`, `${dir}/*`, ...swallowed.map((f) => `!${f}`)]) wanted.push(line);
+  }
+
   const add = wanted.filter((w) => !present.has(norm(w)));
   if (!add.length) return null;
 

package/scripts/lib/onboarding.js

@@ -4,6 +4,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
 import { TARGET_IDS } from '../../targets/index.js';
 import { resolveAgentNames } from '../../targets/agents.js';
 import { loadManifest, skillsForProfile } from './manifest.js';
+import { readManifest } from './manifest-file.js';
 import { managedPathsForInstall } from '../install-apply.js';
 
 export const ONBOARDING_SCHEMA_VERSION = 1;
@@ -68,7 +69,17 @@ export function scanProject(root = process.cwd()) {
   let markdownCount = 0;
   let sourceFileCount = 0;
   const visit = (dir) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    // A directory we are not allowed to open is a fact about that directory, not a reason to abandon
+    // the install. Reported from a real Windows box: the global harness died walking `Temp\WinSAT`,
+    // which Windows protects, on 1.3.2 and again on 1.3.6 — so it had never worked there at all.
+    // The safe form already existed in `detect-repo.js` and was simply not reused here.
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
       if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
       const path = join(dir, entry.name);
       const rel = relative(absolute, path).split(sep).join('/');
@@ -175,7 +186,30 @@ export function buildOnboardingPlan(record, evidence) {
   const catalog = loadManifest();
   const catalogIds = new Set(catalog.skills.map((skill) => skill.id));
   const detectedSkills = (evidence.stacks || []).filter((stack) => catalogIds.has(stack));
-  const skills = [...new Set([...skillsForProfile(catalog, profile), ...detectedSkills])].sort();
+  // Skills the user asked for BY NAME are kept across an update; skills a profile handed out are not.
+  //
+  // Without this, an update recomputed the set from the profile and the detected stacks alone, and
+  // the install step then deleted from disk whatever was not in that fresh set. Reported from the
+  // field: six skills added with `rsc add` — seo-geo, astro, landing-copy, brand-identity, press-kit,
+  // article-writing — deleted by the update. And "volvió a borrar": every single time, because
+  // nothing ever taught the recomputation to look at the manifest.
+  //
+  // But preserving everything declared is too blunt, and a test older than this fix says so: choosing
+  // a narrower scope on purpose has to be able to REMOVE what the wider one installed. Both cases are
+  // "onboard ran again with a different record", so the difference cannot come from how it was
+  // invoked — it has to come from where the skill came from.
+  //
+  // And there it is, already in the catalog: a profile skill declares its profiles, and a skill you
+  // can only get by naming it declares none. So — what a profile gave you, a profile may take away;
+  // what you asked for by name, only you may. Filtered against the catalog on the way in, because
+  // preserving a declaration is not the same as trusting it.
+  //
+  // `readManifest` returns null on a first install, which is the most common path of all; reaching
+  // through that null would have broken every fresh install in order to protect updates.
+  const inAnyProfile = new Set(catalog.skills.filter((s) => (s.profiles || []).length).map((s) => s.id));
+  const declared = (readManifest(evidence.root ?? process.cwd())?.skills ?? [])
+    .filter((id) => catalogIds.has(id) && !inAnyProfile.has(id));
+  const skills = [...new Set([...skillsForProfile(catalog, profile), ...detectedSkills, ...declared])].sort();
   const baseAgents = needsSdd;
   const hooks = needsSdd;
   const agents = baseAgents ? resolveAgentNames(skills, []).sort() : [];

package/skills/suggest/SKILL.md

@@ -61,7 +61,7 @@ name it and offer it. This runs mid-conversation, not only at project start.
    `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
+   overlaps. 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.
@@ -88,7 +88,6 @@ You are injected into every session, so you are the only thing that can notice a
 harness before its owner does — and its owner usually cannot, because the symptoms name
 nothing they recognise. When any of these is true, act on it **once** in the session:
 
-- the assistant sees no skills in a project that clearly has a harness;
 - `.rsc.json` exists and what it declares is not what is installed;
 - the same hook seems to run several times;
 - the harness is wired for an assistant that is not the one running.
@@ -96,6 +95,10 @@ nothing they recognise. When any of these is true, act on it **once** in the ses
 Run `npx @ericrisco/rsc doctor`, and say in one line what is wrong **as a symptom**, not as
 a cause. Then:
 
+- **Nothing built** — `.rsc.json` without `.rsc/`: a clone. Name
+  `npx @ericrisco/rsc@<catalogVersion in .rsc.json> sync`, that exact version, **never** `@latest`
+  — a release nobody here adopted is drift. Ask in one line, **keep working either way**; silence
+  is not a no, `.rsc/.no-harness` is.
 - Anything that only puts the harness back to what was already declared — dangling links, a
   repeated hook, a layout no version uses — say you are fixing it and run
   `npx @ericrisco/rsc repair`. Restoring is not deciding, and a recoverable copy is kept.
@@ -103,8 +106,7 @@ a cause. Then:
   teammate added, disarming a gate — **ask first**. A `git pull` never rewrites someone's
   machine.
 
-Offer once. A "no" holds for the session; a new session may look again, because the problem
-has not gone away. Never mention it when the harness is healthy.
+Offer once per session. Never mention any of it when the harness is healthy.
 
 ## 4. First contact
 

package/targets/claude.js

@@ -45,6 +45,13 @@ export function hookWiringOf(entry) {
 // other settings are preserved. Empty event arrays (and an empty hooks object) are
 // pruned so we don't leave noise behind.
 export function unwireHook(paths) {
+  // The bootstrap lives in the COMMITTED tree, so leaving it behind does not just orphan a file the
+  // way a stray `.rsc/` entry would — it leaves an executable in something the user pushes. Nothing
+  // else removes it: uninstall and purge only ever knew about `.rsc/`.
+  try {
+    rmSync(join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs'), { force: true });
+  } catch { /* never let cleanup be the thing that fails */ }
+
   const file = paths.hookTarget;
   if (!existsSync(file)) return [];
   let settings;
@@ -79,6 +86,23 @@ export function unwireHook(paths) {
 const P = '${CLAUDE_PROJECT_DIR}';
 const at = (...seg) => `${P}/${seg.join('/')}`;
 
+// Everything below points at `.rsc/`, which git does not carry — so in a clone every one of these
+// commands runs against a file that is not there and the client shows the module loader's stack
+// trace instead of a hook. The fix is not to make each script survive its own absence (it cannot:
+// the guards import only node builtins, so a missing entry file fails before a line of theirs runs).
+// The fix is to point the wiring at a file that IS committed, and let it decide: delegate when the
+// harness is mounted, speak once when it is not.
+//
+// The script's own path stays in the command as an argument, so every dedup/unwire needle
+// (`.rsc/session-start.`, `.rsc/ship-guard.`, …) still matches and idempotency is untouched.
+// Three modes, because a hook's event decides what it is allowed to say. `announce` is the one hook
+// that may open with the offer (one per session, no marker needed). `guard` is a shell guard, and in
+// an unbuilt harness it is the only place that can notice someone is about to do the thing the
+// missing guard protected. `quiet` delegates and never speaks.
+const BOOTSTRAP = '.claude/rsc-bootstrap.mjs';
+const viaBootstrap = (mode, target, ...args) =>
+  [`node "${at(...BOOTSTRAP.split('/'))}"`, `"${mode}"`, `"${P}"`, `"${target}"`, ...args].join(' ');
+
 export function wireHook(paths, sourceMd, policy = {}) {
   const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
@@ -89,6 +113,11 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
+  // The one harness file that belongs in the committed tree rather than in `.rsc/`: it is the only
+  // thing standing between a clone and seven stack traces, so it has to survive `git clone`.
+  const bootstrapDest = join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs');
+  mkdirSync(dirname(bootstrapDest), { recursive: true });
+  copyFileSync(join(HERE, 'clone-bootstrap.mjs'), bootstrapDest);
 
   let suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
   const operationsSuggest = join(paths.projectRoot, '.rsc', 'suggest-always-on.md');
@@ -96,7 +125,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
     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 cmd = viaBootstrap('announce', at('.rsc', 'session-start.mjs'), `"${suggestRel}"`, `"${P}"`);
 
   const file = paths.hookTarget;
   const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
@@ -115,9 +144,9 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // 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];
+  const written = [paths.hookTarget, scriptDest, wlDest, bootstrapDest];
   copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
-  const wlCmd = `node "${at('.rsc', 'worklog-checkpoint.mjs')}" "${P}"`;
+  const wlCmd = viaBootstrap('quiet', at('.rsc', 'worklog-checkpoint.mjs'), `"${P}"`);
   for (const event of ['PreCompact', 'SessionEnd']) {
     settings.hooks[event] ||= [];
     settings.hooks[event] = settings.hooks[event].filter(
@@ -137,7 +166,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sello.mjs is ship-guard's sibling import (hooks are materialized file-by-file,
   // so the deterministic sello core must land next to the guard that loads it).
   copyFileSync(join(HERE, 'sello.mjs'), join(paths.projectRoot, '.rsc', 'sello.mjs'));
-  const sgCmd = `node "${at('.rsc', 'ship-guard.mjs')}" "${P}"`;
+  const sgCmd = viaBootstrap('guard', at('.rsc', 'ship-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/ship-guard.'),
@@ -151,7 +180,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
   const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
   copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
-  const dgCmd = `node "${at('.rsc', 'danger-guard.mjs')}" "${P}"`;
+  const dgCmd = viaBootstrap('guard', at('.rsc', 'danger-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/danger-guard.'),
   );
@@ -166,7 +195,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // .rsc/.no-gitmoji.
   const gmDest = join(paths.projectRoot, '.rsc', 'gitmoji-guard.mjs');
   copyFileSync(join(HERE, 'gitmoji-guard.mjs'), gmDest);
-  const gmCmd = `node "${at('.rsc', 'gitmoji-guard.mjs')}" "${P}"`;
+  const gmCmd = viaBootstrap('guard', at('.rsc', 'gitmoji-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/gitmoji-guard.'),
   );
@@ -182,7 +211,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // (non-rsc) UserPromptSubmit hooks are preserved.
   const fgDest = join(paths.projectRoot, '.rsc', 'userprompt-gate.mjs');
   copyFileSync(join(HERE, 'userprompt-gate.mjs'), fgDest);
-  const fgCmd = `node "${at('.rsc', 'userprompt-gate.mjs')}" "${P}"`;
+  const fgCmd = viaBootstrap('quiet', at('.rsc', 'userprompt-gate.mjs'), `"${P}"`);
   settings.hooks.UserPromptSubmit ||= [];
   settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),

package/targets/clone-bootstrap.mjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+// The one piece of the harness that travels in git.
+//
+// `project-manifest` settled what gets committed: the manifest (what the team decided) travels, the
+// wiring travels, and `.rsc/` does not — its contents are machine-shaped, symlinks on one OS and
+// real copies on another, and committing either shape breaks the other. That boundary is right and
+// this file does not move it.
+//
+// What it left behind is the hole this file fills: the committed wiring points into the directory
+// that does not travel, so the first session in a clone runs seven hooks against seven files that
+// are not there. The person does not get a warning, they get the module loader's stack trace — and
+// three of the seven are shell guards, so they get it again on every shell call. `project-manifest`
+// already promised the opposite ("quien clona se entera de que tiene que reconstruir sin que nadie
+// se lo diga"); this is the promise being kept.
+//
+// So the wiring points HERE instead, and this file is committed. Two jobs, in this order:
+//
+//   1. The harness is mounted  → delegate to the real script and say NOTHING of our own. The healthy
+//      case is almost everyone, every session, and it must cost zero bytes of context (P5 — this
+//      repo's own scar is 207 KB paid per turn). One existsSync is not paid in tokens; a line of
+//      output is.
+//   2. The harness is not mounted → say what is wrong as a symptom, name what would be installed,
+//      and get out of the way. Never block the turn, never write anything first.
+//
+// It never throws. A bootstrap that can crash is the bug it exists to remove.
+
+import { existsSync, readFileSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const PACKAGE = '@ericrisco/rsc';
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
+
+/**
+ * Validated at the parse boundary AND again here, on purpose.
+ *
+ * These functions are exported and they are the ones that build the sentence a person is told to run
+ * EXACTLY. A single validation point is only as good as every caller reaching it, and the caller that
+ * skips it is the one nobody remembers writing. Checking again where the string is used costs one
+ * regex and removes the possibility entirely.
+ */
+const safeVersion = (v) => (typeof v === 'string' && SEMVER.test(v) ? v : null);
+
+/**
+ * What the project declares, as a value — never as an exception.
+ * A corrupt manifest is a state we report, not a crash we propagate (spec AC#20).
+ */
+export function readManifest(root) {
+  const path = join(root, '.rsc.json');
+  if (!existsSync(path)) return { state: 'absent' };
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    return { state: 'unreadable', reason: err?.code ?? 'unreadable' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { state: 'unreadable', reason: 'not valid JSON' };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { state: 'unreadable', reason: 'not an object' };
+  }
+  // Ids, and only ids. `skills: [{id:"orient"}]` is valid JSON and used to throw inside `join()` —
+  // before the delegate ran, so a mounted and perfectly healthy harness lost its whole always-on layer
+  // over a manifest someone hand-edited. This file is COMMITTED into user repos, which means old
+  // copies of it live on forever in projects nobody will update; it has to be maximally suspicious of
+  // the only input it gets.
+  // An allowlist, not a type check. `.rsc.json` travels through `git pull`, so its contents are
+  // written by anyone who can open a pull request — and this feature now copies them into the text
+  // the model reads. A newline closes rsc's own `=====` frame and opens a forged one; a `;` turns the
+  // command we tell someone to run EXACTLY into two commands; a `..` walks out of the project and
+  // turns the divergence notice into an oracle for what exists on the reviewer's disk.
+  //
+  // None of that is what a skill id is. A skill id is a short lowercase name, so that is all that is
+  // accepted, and anything else is simply not there.
+  const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+  const ids = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && ID.test(x)) : []);
+  const skills = ids(parsed.skills);
+  const own = ids(parsed.ownSkills);
+  // A manifest with nothing declared is not a clone waiting to be equipped; there is nothing to offer.
+  if (!skills.length && !own.length) return { state: 'absent' };
+  return {
+    state: 'declared',
+    skills,
+    own,
+    // Same reasoning, and it matters more here: this string is pasted into the command we tell a
+    // person to run *exactly*. A version, or nothing — "no version pinned" is a true and harmless
+    // thing to say, and it is what an unusable value becomes.
+    catalogVersion: SEMVER.test(String(parsed.catalogVersion ?? '')) ? parsed.catalogVersion : null,
+    targets: Array.isArray(parsed.targets) ? parsed.targets : [],
+  };
+}
+
+/**
+ * Is what is installed still what the project declares?
+ *
+ * `.rsc/skills/<id>` is the canonical home of a skill's content on every assistant — the per-target
+ * directories (`.claude/skills/`, `.codex/rsc/`, …) are links into it — so one rule answers this for
+ * all seventeen without teaching this file a single target's layout.
+ *
+ * Only what is DECLARED AND MISSING is reported. Not the reverse: an extra directory could equally be
+ * a skill someone wrote by hand, and this repo has already broken a person's own work once by
+ * assuming otherwise. When it cannot be told apart, it is left alone.
+ */
+export function evaluateHarness(root, manifest) {
+  if (manifest.state !== 'declared') return { verdict: 'unknown', missing: [], ownMissing: [] };
+  // Catalog skills: `.rsc/skills/<id>` is where their content lands, and it is the same on all
+  // seventeen assistants — the per-target directories are links into it.
+  const fromCatalog = (id) => existsSync(join(root, '.rsc', 'skills', id));
+  // Own skills are a different thing in a different place, and conflating them is how a healthy
+  // project ends up nagged every session about work that is already correct. `.rsc/skills/` is filled
+  // by copying FROM THE CATALOG, and an own skill is by definition not in the catalog, so it can never
+  // appear there — looking for it there reports it missing forever, and the `sync` we would prescribe
+  // could never fix it. They live where their assistant keeps skills, which is what this repo's own
+  // `divergence()` already checks.
+  const OWN_DIRS = [
+    ['.claude', 'skills'], ['.codex', 'rsc'], ['.cursor', 'rules'], ['.windsurf', 'rules'],
+    ['.clinerules'], ['.roo', 'rules'], ['.continue', 'rules'], ['.junie'], ['.kiro', 'steering'],
+    ['.antigravity'], ['.opencode'], ['.rsc', 'skills'],
+  ];
+  const fromTeam = (name) => OWN_DIRS.some((dir) => existsSync(join(root, ...dir, name)));
+  const missing = manifest.skills.filter((id) => !fromCatalog(id));
+  const ownMissing = manifest.own.filter((name) => !fromTeam(name));
+  if (!missing.length && !ownMissing.length) return { verdict: 'current', missing: [], ownMissing: [] };
+  return { verdict: 'behind', missing, ownMissing };
+}
+
+/**
+ * What to say when the harness works but no longer matches what the team decided — the other half of
+ * the feature: building a clone and bringing a stale one up to date are the same transaction, and
+ * both converge on the MANIFEST, never on the newest release.
+ *
+ * The own skills are named separately and deliberately kept out of the sentence that follows the
+ * command: rsc does not install them, their version is the commit, and listing them next to a thing
+ * that installs would be a promise nothing keeps.
+ */
+export function composeDivergence(manifest, evaluation) {
+  const version = safeVersion(manifest.catalogVersion);
+  const command = version ? `npx ${PACKAGE}@${version} sync` : `npx ${PACKAGE} sync`;
+  let text =
+    '===== rsc =====\n' +
+    'This project declares a harness that no longer matches what is built here — someone changed\n' +
+    'it and git brought the change; nothing is broken.\n';
+  if (evaluation.missing.length) {
+    text += `MISSING, declared in .rsc.json: ${evaluation.missing.join(', ')}.\n`;
+  }
+  // Before the command, never after: anything sitting under the action reads as part of what the
+  // action installs, and these are the one thing rsc will not install. Their version is the commit.
+  if (evaluation.ownMissing.length) {
+    text +=
+      `ALSO DECLARED, written by the team: ${evaluation.ownMissing.join(', ')} — these arrive through\n` +
+      'git, not through any command, and rsc never installs or overwrites them.\n';
+  }
+  return (
+    text +
+    'ACTION: mention it in one line and carry on with what the user asked. To converge, run:\n' +
+    `  ${command}\n` +
+    '===============\n'
+  );
+}
+
+/**
+ * The text a person sees, built from the manifest alone.
+ * Pure: it decides nothing about disk and writes nothing, so it can be tested without one.
+ */
+export function composeOffer(manifest) {
+  if (manifest.state === 'absent') return { offers: false, text: '' };
+  if (manifest.state === 'unreadable') {
+    return {
+      offers: false,
+      text:
+        '===== rsc =====\n' +
+        `This project declares a harness, but its manifest cannot be read (${manifest.reason}).\n` +
+        'Nothing has been installed and nothing was changed. Someone on the team needs to fix\n' +
+        '.rsc.json before the harness can be rebuilt here.\n' +
+        '===============\n',
+    };
+  }
+  // The version is named, never guessed: what gets installed is what the team pinned, and a person
+  // accepting an install on a repo they just cloned is entitled to read the exact thing first
+  // (spec AC#21). No pin is itself a fact worth showing, not a blank to fill in.
+  //
+  // And it has to be IN THE COMMAND, not only in the prose above it. `npx @ericrisco/rsc sync`
+  // resolves to the latest published package, so an offer phrased that way hands a clone whatever
+  // shipped since — the exact divergence the pin exists to prevent, introduced by the feature meant
+  // to honour it. Pinned, the command is reproducible three months from now (spec AC#6).
+  const version = safeVersion(manifest.catalogVersion);
+  const pin = version ? `${PACKAGE}@${version}` : `${PACKAGE} (no version pinned)`;
+  const command = version ? `npx ${PACKAGE}@${version} sync` : `npx ${PACKAGE} sync`;
+  const count = manifest.skills.length;
+  const own = manifest.own.length ? `, plus ${manifest.own.length} written by the team (never overwritten)` : '';
+  return {
+    offers: true,
+    text:
+      '===== rsc =====\n' +
+      'This project declares a harness that is not built on this machine, so the assistant\n' +
+      "cannot see any of the project's skills right now. Nothing is broken and nothing was\n" +
+      'changed — the harness simply does not travel through git, by design.\n' +
+      '\n' +
+      `WOULD INSTALL: ${pin} — ${count} skill(s) as pinned in .rsc.json${own}.\n` +
+      'It writes .rsc/ and the skill entries; it never touches anything written by hand.\n' +
+      '\n' +
+      'ACTION: ask the user whether to build it, in one line, and continue with their request\n' +
+      'either way — this must not hold up what they asked for. If there is nobody to ask (CI, an\n' +
+      'unattended run), do NOT install: say it is missing and carry on. On a yes, run EXACTLY:\n' +
+      `  ${command}\n` +
+      '(the version is the one this project pinned. Do not substitute `@latest`: a release nobody\n' +
+      ' on this team adopted is not an upgrade, it is two people quietly drifting apart.)\n' +
+      "On a no, create .rsc/.no-harness so this is not offered again on this machine.\n" +
+      '===============\n',
+  };
+}
+
+/**
+ * Delegate to the real hook script, preserving what it believes about how it was invoked.
+ * `gitmoji-guard` only runs its main block when `process.argv[1]` is its own path, so the splice is
+ * load-bearing, not tidiness: without it the guard loads and silently does nothing. The four
+ * The three arguments this file owns are dropped in the same move, together with our own path, so the delegate sees exactly the argv the
+ * wiring used to hand it directly — anything less and every hook would need to learn about us.
+ */
+async function delegate(target, ownArgc) {
+  // `realpathSync` and not `target` as given: the delegate may run its own identity check, and
+  // `gitmoji-guard` does exactly that. Its `import.meta.url` comes back from the loader with
+  // symlinks resolved, so handing it the raw path makes its main block silently not run — the guard
+  // loads, denies nothing, and reports success. Same trap as `sameFile` below, one level down.
+  // One resolved value for both: argv[1] and the import specifier must agree, or a delegate that
+  // checks its own identity loads and then does nothing — which under `--preserve-symlinks` is
+  // exactly what happened.
+  const resolved = realpathSync(target);
+  process.argv.splice(1, ownArgc + 1, resolved);
+  await import(pathToFileURL(resolved).href);
+}
+
+/**
+ * @param {string} target the real hook script the wiring would have called
+ * @param {string} root the project root, as the client resolved it
+ * @param {boolean} announce whether this hook is the one allowed to speak (SessionStart only)
+ */
+/**
+ * The protections a missing harness takes away, named by the thing a person is about to do rather
+ * than by the guard that is gone — "you are about to commit and the commit checks are not here" is
+ * actionable; "ship-guard is not installed" is not.
+ *
+ * RECOGNISING one of these is judgement and is declared NON-BINDING (P2): the list is deliberately
+ * short and will miss things, and missing one costs a reminder, never a failure. What IS binding,
+ * and what the tests hold, is everything around it — that it reminds at most once, that it never
+ * denies a tool call, and that it stays silent for ordinary work.
+ */
+const PROTECTED = [
+  // `git -C <path> commit` is not an edge case: it is the form this workspace's own CLAUDE.md
+  // mandates, so without it the reminder would essentially never fire where it was written.
+  { re: /\bgit\s+(-C\s+\S+\s+)?(commit|cz)\b/, what: 'commit' },
+  { re: /\bgit\s+(-C\s+\S+\s+)?push\b/, what: 'push' },
+  { re: /\bgit\s+(-C\s+\S+\s+)?merge\b/, what: 'merge' },
+  { re: /\bgit\s+(-C\s+\S+\s+)?(switch|checkout)\s+(main|master)\b/, what: 'switch to the trunk' },
+  { re: /\bnpm\s+publish\b/, what: 'publish' },
+  { re: /\brm\s+-rf\b/, what: 'delete files irreversibly' },
+];
+
+/**
+ * "Have we already reminded them in this project?" — kept in the OS temp directory, keyed by the
+ * project path, and NEVER inside the project. The user's tree stays untouched until they consent,
+ * which is the whole point of the first offer (spec AC#2); a note to ourselves about how many times
+ * we have spoken is not their file to carry.
+ */
+function alreadyReminded(root) {
+  // Keyed on the RESOLVED path: the same project reached through a symlinked alias is the same
+  // project, and keying on the raw string warned twice.
+  let key = root;
+  try {
+    key = realpathSync(root);
+  } catch { /* unresolvable is still a usable key */ }
+  // A per-user directory at 0700, not a bare name in a world-writable one. On Linux and in CI
+  // containers `os.tmpdir()` is `/tmp` at 1777: the sticky bit stops anyone deleting our file, but
+  // nothing stops them CREATING it first — and a planted empty file silences the one risk reminder
+  // this design promises, while a planted DANGLING symlink turns our write into a file created at a
+  // path they chose, owned by the person we were trying to help.
+  const dir = join(tmpdir(), `rsc-${process.getuid ? process.getuid() : 'u'}`);
+  const mark = join(dir, `offer-${createHash('sha256').update(key).digest('hex').slice(0, 16)}`);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch { /* fall through: the write below is what actually decides */ }
+  try {
+    // `wx` is the whole fix: create-or-fail, and it refuses to follow a symlink. Success means WE
+    // made it and this is the first reminder. Failure means it already existed — planted or genuine,
+    // and either way the honest reading is "do not speak again".
+    writeFileSync(mark, '', { flag: 'wx' });
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** The second and last offer: only when they are about to do the thing the absent harness guarded. */
+function remindOnProtectedAction(root) {
+  let command = '';
+  try {
+    const payload = JSON.parse(readStdin() || '{}');
+    command = String(payload?.tool_input?.command ?? '');
+  } catch { return; }
+  const hit = PROTECTED.find(({ re }) => re.test(command));
+  if (!hit) return;
+  // Read BEFORE claiming the one reminder this project gets: a run with nothing to say must not spend
+  // it. Otherwise a project whose manifest arrives later by `git pull` has already used up its budget
+  // on a session where it could not have said anything.
+  const manifest = readManifest(root);
+  if (manifest.state !== 'declared') return;
+  if (alreadyReminded(root)) return;
+  const version = safeVersion(manifest.catalogVersion);
+  const pin = version ? `@${version}` : '';
+  // The envelope, not bare stdout. A `PreToolUse` hook's plain stdout is transcript-only, so the one
+  // message this path is allowed to send would have gone to a place nobody looks. Every sibling guard
+  // in this repo already wraps its output this way. And no `permissionDecision`: informing someone is
+  // not denying them, and nothing here may ever cost a person their tool call.
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext:
+        `rsc: you are about to ${hit.what}, and this project's checks for that are not built on ` +
+        'this machine. Nothing is blocked, and this is the last time it will be mentioned. ' +
+        `To build them: npx ${PACKAGE}${pin} sync`,
+    },
+  }));
+}
+
+/**
+ * @param {string} target the real hook script the wiring would have called
+ * @param {string} root the project root, as the client resolved it
+ * @param {'announce'|'quiet'|'guard'} mode which hook this is, and therefore what it may say
+ */
+export async function bootstrap(target, root, mode, ownArgc = 3) {
+  const mounted = existsSync(target);
+
+  // Declining is a decision, and it is respected whole: no opening offer, no divergence note, and no
+  // risk reminder either. Ignoring the offer is a different thing entirely — that leaves the door open.
+  const declined = existsSync(join(root, '.rsc', '.no-harness'));
+
+  if (mounted) {
+    // The harness works. It may still be out of date, and a manifest that arrived by `git pull` is
+    // exactly the case that used to pass in silence — half the feature missing. Say it, then get out
+    // of the way: being behind is not a reason to stop working.
+    if (mode === 'announce' && !declined) {
+      const manifest = readManifest(root);
+      const evaluation = evaluateHarness(root, manifest);
+      if (evaluation.verdict === 'behind') process.stdout.write(composeDivergence(manifest, evaluation));
+    }
+    return delegate(target, ownArgc);
+  }
+
+  if (declined) return;
+  if (mode === 'guard') return remindOnProtectedAction(root);
+  // Only one hook per session opens with the offer, so the person is told once and not seven times —
+  // settled by WHICH hook this is, with no marker in their tree (spec AC#2).
+  if (mode !== 'announce') return;
+  const { text } = composeOffer(readManifest(root));
+  if (text) process.stdout.write(text);
+}
+
+/**
+ * "Was this file run directly?" — and the answer must survive a symlink.
+ *
+ * The idiomatic `import.meta.url === pathToFileURL(process.argv[1]).href` is wrong here, and wrong
+ * in the most expensive way: `import.meta.url` is what the ESM loader resolved (symlinks RESOLVED),
+ * while `process.argv[1]` is the raw string the client passed (symlinks INTACT). One symlinked
+ * component anywhere in the project path — `/tmp` and `/var` on macOS, or the ordinary
+ * `~/code -> /Volumes/external/code` — and they differ, this block never runs, node exits 0 having
+ * printed nothing, and EVERY hook becomes a silent no-op. Including the danger guard.
+ *
+ * It would even look correct: "zero bytes in the healthy case" is satisfied, for entirely the wrong
+ * reason, while `doctor` keeps reporting every hook as properly wired.
+ */
+function sameFile(a, b) {
+  if (!a || !b) return false;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+}
+
+// Argument order is ours, then the delegate's untouched: <mode> <root> <target> [the real args…].
+if (sameFile(fileURLToPath(import.meta.url), process.argv[1])) {
+  const [mode, root, target] = process.argv.slice(2);
+  // Fail open on the exit code, always: the harness is a convenience and never costs someone their
+  // turn. But failing open is not the same as failing SILENT. A blanket catch here would swallow a
+  // genuine crash inside any of the six delegated scripts, and a guard that crashed would become
+  // indistinguishable from a guard that allowed — which is how a safety guard stops being one
+  // without anybody finding out. So: absence is expected and stays quiet; anything else says so on
+  // stderr and still exits 0.
+  try {
+    await bootstrap(target, root ?? process.cwd(), mode);
+  } catch (err) {
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND') {
+      process.stderr.write(`rsc: hook failed and was ignored — ${err?.message ?? err}\n`);
+    }
+  }
+}