@damiangilgonzalez/harness 1.3.12 → 1.3.13

package/README.md

@@ -284,23 +284,43 @@ The harness travels by git, but not all of it — and the split is the point.
 | `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 @damiangilgonzalez/harness@latest sync
+npx @damiangilgonzalez/harness@<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.
 
 **Own skills.** A skill your team wrote lives in the repo and already works for whoever clones,
-with no command at all. Declare it in `.rsc.json` under `ownSkills` and `doctor` will also say
-when someone is missing it — that is all declaring does. rsc never installs, updates or
-overwrites it: its version is the commit.
+with no command at all. rsc never installs, updates or overwrites it: its version is the commit.
+Installing a catalog skill of the same name is refused rather than silently winning, and `doctor`
+lists what is yours by reading the files themselves — no list to keep in `.rsc.json`, because a
+list somebody has to remember to update is a list that goes quietly stale. Declaring a skill under
+`ownSkills` still works and still reports when someone is missing it.
 
 
 ## 🩹 Something's off? One command
@@ -312,10 +332,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 @damiangilgonzalez/harness@latest repair
 ```

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.12",
+  "version": "1.3.13",
   "counts": {
     "skills": 291,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damiangilgonzalez/harness",
-  "version": "1.3.12",
+  "version": "1.3.13",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {
@@ -64,5 +64,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "rscFixes": []
 }

package/scripts/doctor.js

@@ -1,10 +1,12 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+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';
 import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
 import { divergence } from './lib/divergence.js';
 import { loadManifest } from './lib/manifest.js';
+import { readManifest as readProjectManifest } from './lib/manifest-file.js';
 import { listBackups } from './lib/backups.js';
 import { WORKFLOW_GATE_TEXT } from '../targets/hook-once.mjs';
 import { isEnabled, checkSello, readSello, countFindings, readEffectiveConfig, validateRiskConfig } from '../targets/sello.mjs';
@@ -15,6 +17,17 @@ import { resolveCommands, commandPath, targetHasCommands } from '../targets/comm
 import { inspectMemoryWiring } from '../targets/memory.js';
 import { metricsSummary } from '../targets/session-memory-core.mjs';
 import { agentPath } from '../targets/agents.js';
+import { projectOptOuts } from '../targets/opt-outs.js';
+import { versionReport } from './lib/versions.js';
+
+// Gates the committed manifest says the team disarmed, still armed here. Read through the same
+// partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
+// manifest (`harness`, `context7`) is not reported as something to converge on.
+function optOutsNotApplied(root) {
+  let manifest = null;
+  try { manifest = readProjectManifest(root); } catch { return []; }
+  return projectOptOuts(manifest?.optOuts).filter((n) => !existsSync(join(root, '.rsc', `.no-${n}`)));
+}
 
 // The sello's health, surfaced where the user already looks (spec: non-blocking
 // findings live in the project and are SUMMARIZED here, never nagged about).
@@ -79,6 +92,75 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
   return [...seen];
 }
 
+// Is the post-merge trigger actually armed in this clone? Three states, because they need three
+// 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) {
+  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 @damiangilgonzalez/harness repair` to arm the post-merge cleanup in this clone.' };
+  }
+  try {
+    const armed = readFileSync(hook, 'utf8').includes('rsc-managed worktree cleanup');
+    return armed
+      ? { state: 'armed' }
+      : { state: 'foreign', action: 'A post-merge hook from another tool is in place; `npx @damiangilgonzalez/harness repair` chains ours behind it.' };
+  } catch { return { state: 'unreadable' }; }
+}
+
+// Every skill this catalog ships declares its origin in its own frontmatter: `risco` for the skills
+// inherited from the original catalog, `damiangil` for the ones this fork added. So "is this ours?"
+// is answerable from the file itself, and does not need the list in
+// `.rsc.json` that nobody ever filled: that list is parallel accounting (P3), it has been empty in
+// every project since it was introduced, and `doctor` has been faithfully reporting on the emptiness.
+//
+// Failing towards "the user's" is deliberate. Reading a catalog skill as the user's leaves a file
+// that stops being updated; reading the user's as the catalog's invites something to overwrite it.
+// Only one of those loses work.
+const CATALOG_ORIGINS = new Set(['risco', 'damiangil']);
+
+function ownSkillsIn(paths, declared = []) {
+  const present = [];
+  let dir;
+  try { dir = dirname(paths.skillDir('_')); } catch { return { present, missing: [], declared }; }
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { /* nothing installed here yet */ }
+  for (const entry of entries) {
+    // Symlinks included, deliberately. rsc installs a catalog skill AS a symlink into `.rsc/skills/`
+    // and a hand-written one is a real directory, so the entry type is itself a provenance signal —
+    // and skipping symlinks would have made the frontmatter check below dead code that still looked
+    // like it worked. It did: a mutant that removed the check passed every test until this line was
+    // fixed. Both signals are read now, and the frontmatter is the one that decides.
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const md = join(dir, entry.name, 'SKILL.md');
+    if (!existsSync(md)) continue;
+    let origin = null;
+    try {
+      const head = readFileSync(md, 'utf8').slice(0, 2048);
+      origin = (/^origin:\s*(\S+)\s*$/m.exec(head) || [])[1] || null;
+    } catch { continue; }
+    if (!CATALOG_ORIGINS.has(origin)) present.push(entry.name);
+  }
+  // Declared-but-absent stays meaningful for anyone who did fill the list by hand, and it is the
+  // only half a derivation cannot cover: a file that is gone cannot describe itself.
+  const missing = declared.filter((name) => !existsSync(paths.skillDir(name)));
+  return { present: present.sort(), missing, declared };
+}
+
 export function doctor({ target, home, cwd }) {
   const root = cwd || process.cwd();
   const paths = targetPaths(target, home, cwd);
@@ -134,6 +216,11 @@ export function doctor({ target, home, cwd }) {
       latest: backups[0]?.id || null,
     },
     contextBudget: contextBudget({ target, home, cwd }),
+    // The worktree cleanup's trigger is a git hook, and `.git/hooks/` is not cloned. So a repo can
+    // carry a perfectly healthy harness and still never clean up, on every machine but the one that
+    // ran the installer. Reported, never nagged about: `repair` is what puts it back (P6).
+    worktreeCleanup: worktreeCleanupStatus(root),
+    ownSkills: ownSkillsIn(paths, readProjectManifest(root)?.ownSkills || []),
     sello: selloStatus(root),
     // Whether this harness has a design identity at all. `design` has always DECLARED that it
     // stops without one; until lib/design-identity.js nothing checked it (P2). Reported here,
@@ -148,6 +235,14 @@ export function doctor({ target, home, cwd }) {
     gitmojiGuard: state.policy?.gitmojiGuard === false
       ? 'deferred'
       : existsSync(join(root, '.rsc', '.no-gitmoji')) ? 'opted-out' : 'armed',
+    // The reverse of the same honesty, one level up: a gate the TEAM disarmed in the committed
+    // manifest and that is still armed on this machine. Nothing is applied from here — a pull
+    // never rewrites somebody's machine — so the only thing owed is saying it out loud, and
+    // saying it every run, because a notice offered once per session is a notice missed.
+    optOutsNotApplied: optOutsNotApplied(root),
+    // First thing to read on any bug report: a project behind its CLI runs old hooks, and "it is
+    // already fixed" only helps once the fix is in `.rsc/`.
+    versions: versionReport(root),
     // Counted, never interpreted — by spec, the gap log's reader is the user.
     automationGaps: countGaps(root),
     memory,
@@ -383,6 +478,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 @damiangilgonzalez/harness 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

@@ -2,13 +2,17 @@
 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, pathToFileURL } 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 { shadowTarget } from '../targets/agents-md-shadow.js';
 import {
   targetHasAgents, reconcileAgents, agentPath, agentNames,
-  resolveAgentNames, agentByName, allAgentNames, readDeveloperTier,
+  resolveAgentNames, agentByName, allAgentNames, readDeveloperTier, writeDeveloperTier,
 } from '../targets/agents.js';
+import { projectOptOuts } from '../targets/opt-outs.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 {
@@ -66,6 +70,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'),
@@ -109,6 +116,12 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
       out.push(step.to, ...generatedHookFiles({ target, cwd, policy }));
     }
   }
+  // The shadow CLAUDE.md that keeps a natively-read AGENTS.md from doubling the always-on body.
+  // Written by whichever of the two adapters is wired second, so it is declared for both families,
+  // not just for claude. A claude install must assume its own wiring: settings.json does not name
+  // it yet at plan time.
+  const shadow = shadowTarget(cwd, { assumeClaudeWired: target === 'claude' });
+  if (shadow) out.push(shadow);
   return [...new Set(out)];
 }
 
@@ -116,17 +129,56 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
 // which is machine-local and therefore lost on every clone: a team that disarmed the
 // gitmoji guard found it armed again on the next checkout, with nobody having decided
 // that. They are decisions, so they belong in the committed declaration.
+//
+// Two distinctions this function exists to keep, both of which used to be collapsed:
+//
+//   ABSENT is not EMPTY. In a clone `.rsc/` does not exist, and reading "no markers here" as
+//   "the team re-armed everything" would have sync quietly delete the decision it came to
+//   rebuild. Unreadable returns null — "I know nothing" — and the caller keeps what was
+//   declared. A readable directory with no markers returns [], which IS a statement: somebody
+//   deleted the last marker, and deleting it is how a gate gets re-armed.
+//
+//   Not every switch is the team's to make. `.no-harness` and friends are decisions of one
+//   machine (see targets/opt-outs.js), and committing them would impose one laptop's answer on
+//   every future clone. They stay local, and never reach the declaration.
 function localDecisions(cwd) {
   const dir = join(cwd, '.rsc');
-  let optOuts = [];
+  let optOuts = null;
   try {
-    optOuts = readdirSync(dir).filter((f) => f.startsWith('.no-')).map((f) => f.slice(4)).sort();
-  } catch { /* no .rsc yet */ }
+    optOuts = projectOptOuts(readdirSync(dir).filter((f) => f.startsWith('.no-')).map((f) => f.slice(4)));
+  } catch { /* no .rsc yet → null, meaning "unknown", never "none" */ }
   let tier = null;
   try { tier = JSON.parse(readFileSync(join(dir, 'developer.json'), 'utf8')).tier ?? null; } catch { /* unset */ }
   return { optOuts, tier };
 }
 
+// The other half of the same promise: what the declaration says is rebuilt as the real local
+// state a hook can see. Hooks are materialized standalone under `.rsc/` and decide with one
+// `existsSync` — they cannot read the manifest, and making them read it would let a `git pull`
+// change how somebody's session behaves in silence, which `project-manifest` ruled out on
+// purpose. So the manifest is applied HERE, inside the install the person chose to run.
+//
+// Only ever on a machine where `.rsc/` did not exist: there, "no marker" carries no information
+// and the declaration is all there is. Where `.rsc/` is already built, the local state is the
+// authority — otherwise the next sync would silently undo a re-arm, and the gate coming back
+// would look like a bug in the guard rather than a decision nobody made.
+export function hydrateLocalDecisions(cwd, manifest) {
+  const applied = { optOuts: [], tier: null };
+  if (!manifest) return applied;
+  const dir = join(cwd, '.rsc');
+  for (const name of projectOptOuts(manifest.optOuts)) {
+    const file = join(dir, `.no-${name}`);
+    if (existsSync(file)) continue;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, `Declared in .rsc.json by this project; rebuilt here by rsc ${CLI_VERSION}.\n`);
+    applied.optOuts.push(name);
+  }
+  if (manifest.tier && !existsSync(join(dir, 'developer.json'))) {
+    applied.tier = writeDeveloperTier(cwd, manifest.tier);
+  }
+  return applied;
+}
+
 // Record the decision, merging so a second assistant never erases the first: installing
 // into codex on a machine that already had claude is adding, not replacing. Union, sorted
 // where order carries no meaning, so the file stays diffable and a merge conflict stays
@@ -146,17 +198,25 @@ export function recordInManifest({ cwd, target, skillIds, agentIds = [], catalog
     ownSkills: prev.ownSkills || [],
     catalogVersion,
     tier: tier ?? prev.tier ?? null,
-    optOuts: optOuts.length ? optOuts : (prev.optOuts || []),
+    optOuts: optOuts ?? projectOptOuts(prev.optOuts),
     memory: prev.memory,
     onboarding: onboarding ?? prev.onboarding,
   });
 }
 
 export async function applyInstall({ skillIds = [], agentIds = [], target, home, cwd = process.cwd(), operation = 'install', dryRun = false, policy, onboarding }) {
+  // Read BEFORE anything can create it — the backup writes under `.rsc/`, and one line later the
+  // answer would always be "yes, it exists". This single boolean is what separates a clone (the
+  // declaration is the only thing that knows what the team decided) from a built machine (the
+  // local markers are the authority, and a pull must not overwrite them).
+  const fromScratch = !existsSync(join(cwd, '.rsc'));
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd, hooks: policy?.alwaysOn !== false });
   const managedPaths = managedPathsForInstall({ skillIds, agentIds, target, home, cwd, policy });
   if (dryRun) return { dryRun: true, skills: skillIds, agents: agentIds, paths: managedPaths };
+  // Rebuild the declared decisions first, so everything below (the agent tier especially) reads
+  // the state the team declared rather than the default it would otherwise assume.
+  if (fromScratch) hydrateLocalDecisions(cwd, readManifest(cwd));
   const state = readState(paths.stateFile);
   const backup = createBackup({ cwd, operation, target, paths: managedPaths, cliVersion: CLI_VERSION });
   // Decide base refresh per skill (see baseVersionsFile): a base is re-materialized when
@@ -237,8 +297,30 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
   recordInManifest({ cwd, target, skillIds, agentIds, onboarding });
+  // The worktree cleanup's trigger. It lives in `.git/hooks/`, which is NOT cloned, so it has to be
+  // (re)written by every operation that touches a user's repo — install, sync and repair all land
+  // here. Target-agnostic on purpose: it is a git hook, not an assistant hook, and a cleanup that
+  // only worked for one of the sixteen assistants would be a cleanup nobody could rely on. The
+  // reaper travels with it for the same reason; until now only the Claude adapter materialized it,
+  // although `managedPathsForInstall` has always declared it for every target.
+  // Only where the accepted plan governs code hooks. An operations harness — company, research,
+  // 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'))) 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
@@ -287,6 +369,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;
 
@@ -482,7 +590,19 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   const ids = Object.keys(state.skills || {});
   const manifest = readManifest(cwd);
   const governedSkills = manifest?.onboarding?.plan?.policy?.skills;
-  const declared = governedSkills || (ids.length ? ids : (manifest?.skills || []));
+  // The accepted plan is a FLOOR, not a ceiling. Reading it as the whole declaration is what deleted
+  // users' skills: `add` recorded the new skill in `manifest.skills` — the living list — and sync
+  // 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 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. 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/capabilities.js

@@ -44,6 +44,12 @@ function agentSpecFor(target, root) {
   return { dir: dirname(p), ext };
 }
 
+// A real file, or a link that leads to one. `statSync` follows; a dangling link throws and is
+// therefore not a file, which is the answer we want.
+function isFile(path) {
+  try { return statSync(path).isFile(); } catch { return false; }
+}
+
 // Real files only. Directories (a dir named `foo.md` is not an agent), dangling
 // symlinks and dotfiles are not capabilities.
 function entriesWithExt(dir, ext) {
@@ -96,8 +102,19 @@ export function listSkills({ target, home, cwd = process.cwd() } = {}) {
     try {
       for (const e of readdirSync(paths.dir, { withFileTypes: true })) {
         if (e.name.startsWith('.')) continue;
-        if (ext) { if (e.isFile() && e.name.endsWith(ext)) out.push({ id: e.name.slice(0, -ext.length), scope }); }
-        else if (e.isDirectory() && existsSync(join(paths.dir, e.name, 'SKILL.md'))) out.push({ id: e.name, scope });
+        // Ask what a skill IS, never how it was put on disk. A `Dirent` from `withFileTypes`
+        // describes the LINK and not its target, so `isDirectory()`/`isFile()` are both false for
+        // every skill on macOS and Linux — where a symlink per assistant, pointing at one shared
+        // copy, is the layout the installer deliberately writes. Windows gets real files (relative
+        // dir symlinks need Developer Mode there), which is why this read as correct for so long
+        // and why CI never caught it.
+        //
+        // `existsSync` and `statSync` follow links on their own, so one question answers all three
+        // platforms with no branch: is there a SKILL.md behind this name? Following a link is not
+        // the same as believing anything — a dangling link, a directory with no SKILL.md and a
+        // plain file all still fail it.
+        if (ext) { if (e.name.endsWith(ext) && isFile(join(paths.dir, e.name))) out.push({ id: e.name.slice(0, -ext.length), scope }); }
+        else if (existsSync(join(paths.dir, e.name, 'SKILL.md'))) out.push({ id: e.name, scope });
       }
     } catch { /* unreadable scope → contributes nothing */ }
   }

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/scripts/lib/onboarding-apply.js

@@ -4,6 +4,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyInstall, pruneSharedBases, removeTargetInstall } from '../install-apply.js';
 import { targetPaths } from '../../targets/index.js';
+import { targetHasAgents } from '../../targets/agents.js';
 import { readState } from './state.js';
 import { readManifest, writeManifest } from './manifest-file.js';
 import { encodeGoal, identifyPlan } from './onboarding.js';
@@ -11,6 +12,22 @@ import { createBackup, restoreBackup } from './backups.js';
 
 const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
 
+/**
+ * What THIS target should be holding, which is not the same question as what the project decided.
+ *
+ * The policy is the PROJECT's: "these are the agents this project wants." Whether an assistant can
+ * hold a subagent at all is the TARGET's business, and nine of the seventeen cannot — amp, jules,
+ * zed, antigravity, windsurf, cline, roo, continue and aider have no such concept. The installer
+ * always knew this and correctly wrote none; the verifier did not, and demanded the project's list
+ * from every target, so onboarding could never complete on any of the nine. Since the failure rolls
+ * back, what the person got was empty directory shells and no harness — with a recovery command
+ * that leads straight back to the same wall.
+ *
+ * Asking amp for a subagent is not a divergence. It is a category error, and this is where the two
+ * categories stop being confused.
+ */
+export const expectedAgentsFor = (target, plan) => (targetHasAgents(target) ? (plan.policy.agents || []) : []);
+
 function inside(root, path) {
   return path === root || path.startsWith(`${root}${sep}`);
 }
@@ -92,7 +109,7 @@ export function verifyOnboarding(cwd, plan, planId) {
   for (const target of plan.policy.targets) {
     const state = readState(targetPaths(target, undefined, cwd).stateFile);
     if (!sameSet(Object.keys(state.skills || {}), plan.policy.skills)) differences.push(`${target}: installed skills differ from accepted policy`);
-    if (!sameSet(state.agents || [], plan.policy.agents || [])) differences.push(`${target}: installed agents differ from accepted policy`);
+    if (!sameSet(state.agents || [], expectedAgentsFor(target, plan))) differences.push(`${target}: installed agents differ from accepted policy`);
     if (state.policy?.alwaysOn !== plan.policy.alwaysOn) differences.push(`${target}: always-on policy differs`);
     if (state.policy?.codeHooks !== plan.policy.codeHooks) differences.push(`${target}: code-hook policy differs`);
     if (state.policy?.memory !== plan.policy.memory) differences.push(`${target}: memory policy differs`);

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('/');
@@ -169,7 +180,21 @@ 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 — every `rsc add`,
+  // on every update. But choosing a narrower scope on purpose still has to be able to REMOVE what the
+  // wider one installed, so the difference comes from where the skill came from: a profile skill
+  // declares its profiles, and a skill you can only get by naming it declares none. 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.
+  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 = needsWorkflow;
   const hooks = needsWorkflow;
   const agents = baseAgents ? resolveAgentNames(skills, []).sort() : [];