@ericrisco/rsc 2.0.4 → 2.0.6

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.4",
+  "version": "2.0.6",
   "counts": {
     "skills": 273,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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

@@ -17,6 +17,16 @@ 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';
+
+// 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).
@@ -223,6 +233,11 @@ 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),
     // Counted, never interpreted — by spec, the gap log's reader is the user.
     automationGaps: countGaps(root),
     memory,

package/scripts/install-apply.js

@@ -5,10 +5,12 @@ 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 { 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';
@@ -114,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)];
 }
 
@@ -121,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
@@ -151,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

package/targets/_md-block.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { linkOrCopy } from './index.js';
+import { ensureShadowClaudeMd } from './agents-md-shadow.js';
 
 // Shared adapter for every assistant whose "always-on" surface is a plain
 // markdown instructions/rules file (AGENTS.md, copilot-instructions.md, a
@@ -33,7 +34,13 @@ export function wireHook(paths, sourceMd, policy = {}) {
   }
   mkdirSync(dirname(paths.hookTarget), { recursive: true });
   writeFileSync(paths.hookTarget, doc);
-  return [paths.hookTarget];
+
+  // This file may BE the root AGENTS.md, which Claude Code 2.1.277+ reads as project instructions
+  // when no CLAUDE.md exists — doubling an always-on body the SessionStart hook already prints.
+  // No-op unless the Claude Code target is also wired here. Called from both adapters so the fix
+  // holds whichever assistant the user installs second. See targets/agents-md-shadow.js.
+  const shadow = ensureShadowClaudeMd(paths.projectRoot);
+  return shadow ? [paths.hookTarget, shadow] : [paths.hookTarget];
 }
 
 // Inverse of wireHook: remove the marked rsc-suggest block from the shared

package/targets/agents-md-shadow.js

@@ -0,0 +1,153 @@
+// agents-md-shadow.js — keep the always-on body from arriving twice in Claude Code.
+//
+// THE DEFECT. rsc delivers its always-on layer through two different surfaces, one per
+// assistant family:
+//   - Claude Code  → a SessionStart hook (targets/claude.js) that PRINTS suggest's body.
+//   - AGENTS.md family (codex, opencode, amp, jules, zed) → the body is written INTO the
+//     root AGENTS.md between markers (targets/_md-block.js).
+// Wiring both in one project is an ordinary install — this repo's own workspace does it.
+// Until Claude Code 2.1.277 the two never met, because Claude Code did not read AGENTS.md.
+//
+// From 2.1.277 it does: with NO CLAUDE.md in the working directory or above it, Claude Code
+// reads the root AGENTS.md as the project instructions. In a dual-wired project that makes
+// the same ~7 KB body land twice per session — once printed by the hook, once loaded from
+// the file. Anthropic documents the shape of this exact collision and its remedy ("A
+// SessionStart hook that prints AGENTS.md: remove it. Once Claude reads AGENTS.md directly,
+// the hook adds a second copy to the context").
+//
+// WHY THIS IS NOT SOLVED BY MAKING THE HOOK STAY SILENT. The hook cannot know whether it is
+// talking to a Claude Code that reads AGENTS.md: the SessionStart payload carries session_id,
+// cwd, source and sometimes model — there is no version field, and no env var exposes one.
+// Staying silent on a guess would, on every client older than 2.1.277, swallow the always-on
+// layer completely. hook-once.mjs states the rule this file obeys: "A duplicated block costs
+// context; a swallowed always-on layer costs the session its behaviour."
+//
+// THE FIX, version-free. Claude Code reads AGENTS.md only when no CLAUDE.md exists. So give
+// it one. A CLAUDE.md at the project root makes every Claude Code — old or new — take the
+// hook as the single source of the always-on body, and leaves AGENTS.md to the assistants it
+// was written for. No version sniffing, no guess, same bytes on every client.
+//
+// The shadow deliberately does NOT `@AGENTS.md`-import: the import would expand the rsc block
+// into context and recreate the duplication it exists to prevent.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+
+// The marker _md-block.js wraps the always-on body in. Its presence in a root AGENTS.md is
+// what makes that file a second carrier of the body rather than the user's own prose.
+const SUGGEST_MARK = '<!-- rsc-suggest:start -->';
+
+// Identifies a CLAUDE.md as ours. Block-level HTML comments are stripped from Claude Code's
+// context before injection, so everything explanatory below costs the user zero tokens.
+export const SHADOW_MARK = '<!-- rsc:claude-md-shadow -->';
+
+export const SHADOW_BODY = `${SHADOW_MARK}
+# Project instructions
+
+Claude Code reads this file. Every other assistant wired in this project reads \`AGENTS.md\`.
+
+Project instructions for Claude Code go below.
+
+<!--
+  Why rsc created this file
+  =========================
+  rsc's always-on layer reaches Claude Code through its SessionStart hook, and reaches the
+  AGENTS.md-family assistants through the root AGENTS.md. From Claude Code 2.1.277, a project
+  with no CLAUDE.md is read through AGENTS.md directly — which would deliver that same body a
+  second time, every session. The existence of this file is what prevents it.
+
+  Do NOT add "@AGENTS.md" here: the import would expand the always-on block into context and
+  bring the duplication back.
+
+  rsc removes this file on uninstall while it is still untouched. Edit it and it is yours —
+  rsc then leaves it alone, and it keeps doing its job just as well.
+-->
+`;
+
+// The three files whose presence stops Claude Code reading AGENTS.md (per its memory docs).
+// A user's own CLAUDE.md already does the shadow's job, so we never touch a project that has one.
+const CLAUDE_MD_FORMS = ['CLAUDE.md', join('.claude', 'CLAUDE.md'), 'CLAUDE.local.md'];
+
+// Claude Code looks for those files in the working directory AND every directory above it, so a
+// CLAUDE.md two levels up already suppresses the AGENTS.md read. Walking up costs a few stats and
+// keeps us from planting a file that was never needed.
+function claudeMdAboveOrAt(root) {
+  let dir = root;
+  for (;;) {
+    for (const form of CLAUDE_MD_FORMS) if (existsSync(join(dir, form))) return join(dir, form);
+    const up = dirname(dir);
+    if (up === dir || dir === parse(dir).root) return null;
+    dir = up;
+  }
+}
+
+// Is the Claude Code target wired in this project? Same predicate session-start.mjs and doctor
+// use: an rsc command in .claude/settings.json. The backslash normalization is not cosmetic —
+// a Windows install stores the path with separators that JSON escapes as pairs, and reading only
+// for `.rsc/` answered "not wired" on the exact platform where duplication hurt most.
+function claudeWired(root) {
+  try {
+    return readFileSync(join(root, '.claude', 'settings.json'), 'utf8')
+      .replace(/\\\\/g, '/')
+      .includes('.rsc/');
+  } catch { return false; }
+}
+
+// Does the root AGENTS.md carry rsc's always-on block (as opposed to being the user's own prose)?
+function agentsMdCarriesBody(root) {
+  try { return readFileSync(join(root, 'AGENTS.md'), 'utf8').includes(SUGGEST_MARK); } catch { return false; }
+}
+
+/**
+ * Write the shadow CLAUDE.md when — and only when — this project is in the configuration that
+ * duplicates: Claude Code wired, the root AGENTS.md carrying rsc's block, and no CLAUDE.md of
+ * any form at the root or above it.
+ *
+ * Called from BOTH adapters' wireHook. Installs run one target per call, so whichever of the two
+ * is wired second is the one that sees the full picture; calling from both is what makes the fix
+ * independent of the order the user picks their assistants in.
+ *
+ * @returns the path written, or null when nothing was needed. Never throws: a shadow we could not
+ * write costs context, and that must not be the thing that fails an install.
+ */
+export function ensureShadowClaudeMd(projectRoot) {
+  try {
+    const dest = shadowTarget(projectRoot);
+    if (!dest) return null;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, SHADOW_BODY);
+    return dest;
+  } catch { return null; }
+}
+
+/**
+ * Where the shadow would go, or null when this project does not need one — the decision without
+ * the write, so the installer can declare the file BEFORE it exists. A path this returns but the
+ * install plan omits is a file no --dry-run mentions and no `rsc restore` can bring back.
+ *
+ * @param assumeClaudeWired for a claude install in flight: settings.json names the project as
+ * wired only after wireHook writes it, so at plan time the answer has to be assumed, not read.
+ */
+export function shadowTarget(projectRoot, { assumeClaudeWired = false } = {}) {
+  try {
+    if (!assumeClaudeWired && !claudeWired(projectRoot)) return null;
+    if (!agentsMdCarriesBody(projectRoot)) return null;
+    if (claudeMdAboveOrAt(projectRoot)) return null;
+    return join(projectRoot, 'CLAUDE.md');
+  } catch { return null; }
+}
+
+/**
+ * Take back exactly what we gave: remove the shadow only while it is byte-identical to what
+ * ensureShadowClaudeMd wrote. The moment the user edits it, it is their project instructions —
+ * uninstalling rsc must not delete those. Same discipline _md-block.js applies to its block.
+ *
+ * @returns the path removed, or null.
+ */
+export function removeShadowClaudeMd(projectRoot) {
+  try {
+    const dest = join(projectRoot, 'CLAUDE.md');
+    if (readFileSync(dest, 'utf8') !== SHADOW_BODY) return null;
+    rmSync(dest, { force: true });
+    return dest;
+  } catch { return null; }
+}

package/targets/claude.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSyn
 import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkOrCopy } from './index.js';
+import { ensureShadowClaudeMd, removeShadowClaudeMd } from './agents-md-shadow.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -52,11 +53,16 @@ export function unwireHook(paths) {
     rmSync(join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs'), { force: true });
   } catch { /* never let cleanup be the thing that fails */ }
 
+  // The shadow CLAUDE.md exists only to keep the hook from being doubled by a natively-read
+  // AGENTS.md. Unwiring the hook removes the reason for it. Only ever takes back an untouched one.
+  const shadow = removeShadowClaudeMd(paths.projectRoot);
+  const removed = shadow ? [shadow] : [];
+
   const file = paths.hookTarget;
-  if (!existsSync(file)) return [];
+  if (!existsSync(file)) return removed;
   let settings;
-  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
-  if (!settings.hooks) return [];
+  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return removed; }
+  if (!settings.hooks) return removed;
   for (const event of Object.keys(settings.hooks)) {
     settings.hooks[event] = (settings.hooks[event] || []).filter((e) => {
       const s = hookWiringOf(e);
@@ -66,7 +72,7 @@ export function unwireHook(paths) {
   }
   if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file];
+  return [...removed, file];
 }
 
 // SessionStart runs a project-local session-start.mjs via `node`: it prints
@@ -236,5 +242,11 @@ export function wireHook(paths, sourceMd, policy = {}) {
 
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+
+  // settings.json now names this project as rsc-wired, which is the predicate the shadow reads —
+  // so this call belongs AFTER the write, not before it. No-op unless the root AGENTS.md also
+  // carries the always-on body and no CLAUDE.md exists: see targets/agents-md-shadow.js.
+  const shadow = ensureShadowClaudeMd(paths.projectRoot);
+  if (shadow) written.push(shadow);
   return written;
 }

package/targets/clone-bootstrap.mjs

@@ -33,6 +33,19 @@ import { pathToFileURL, fileURLToPath } from 'node:url';
 const PACKAGE = '@ericrisco/rsc';
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
 
+/**
+ * The `.no-*` switches that are the TEAM's decision, and therefore the only ones a manifest may
+ * speak about. Canonical copy: `targets/opt-outs.js`, which carries the reasoning.
+ *
+ * Duplicated on purpose and not by oversight. This file is COMMITTED into user repos and runs with
+ * the package possibly not installed, so it cannot import anything — the same constraint that makes
+ * `sello.mjs` a materialized sibling. A test holds the two copies equal, because duplication that
+ * nothing checks is just drift with a head start.
+ */
+export const PROJECT_OPT_OUTS = [
+  'audit', 'claudemd-check', 'danger-guard', 'feature-gate', 'gitmoji', 'ship-guard', 'worktree-cleanup',
+];
+
 /**
  * Validated at the parse boundary AND again here, on purpose.
  *
@@ -93,6 +106,11 @@ export function readManifest(root) {
     // 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 : [],
+    // Same allowlist, same reason, and it bites harder here: these names are pasted into the
+    // notice a model reads. A switch is a plain lowercase name or it is not a switch — and only
+    // the ones the team is allowed to decide for everybody get through at all.
+    optOuts: ids(parsed.optOuts).filter((n) => PROJECT_OPT_OUTS.includes(n)).sort(),
+    tier: ['balanced', 'heavy'].includes(parsed.tier) ? parsed.tier : null,
   };
 }
 
@@ -108,7 +126,9 @@ export function readManifest(root) {
  * 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: [] };
+  if (manifest.state !== 'declared') {
+    return { verdict: 'unknown', missing: [], ownMissing: [], optOutsMissing: [], tierDiffers: null };
+  }
   // 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));
@@ -126,8 +146,23 @@ export function evaluateHarness(root, manifest) {
   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 };
+  // A gate the team disarmed that is still armed here. Declared-and-missing only, exactly as for
+  // skills above: a marker this machine has and the manifest does not could be a decision somebody
+  // is still making, and this file does not tell people what to think about their own work.
+  const optOutsMissing = manifest.optOuts.filter((n) => !existsSync(join(root, '.rsc', `.no-${n}`)));
+  const tierDiffers = manifest.tier && manifest.tier !== localTier(root) ? manifest.tier : null;
+  if (!missing.length && !ownMissing.length && !optOutsMissing.length && !tierDiffers) {
+    return { verdict: 'current', missing: [], ownMissing: [], optOutsMissing: [], tierDiffers: null };
+  }
+  return { verdict: 'behind', missing, ownMissing, optOutsMissing, tierDiffers };
+}
+
+/** The tier this machine actually runs at — `balanced` is the documented default, not a guess. */
+function localTier(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, '.rsc', 'developer.json'), 'utf8')).tier === 'heavy'
+      ? 'heavy' : 'balanced';
+  } catch { return 'balanced'; }
 }
 
 /**
@@ -149,6 +184,15 @@ export function composeDivergence(manifest, evaluation) {
   if (evaluation.missing.length) {
     text += `MISSING, declared in .rsc.json: ${evaluation.missing.join(', ')}.\n`;
   }
+  // Named as the convention they are, never as the file that implements them: "the team disarmed
+  // the commit-message check" is something a person can agree or disagree with; ".no-gitmoji is
+  // absent" is a fact about a directory they have never opened.
+  if (evaluation.optOutsMissing?.length) {
+    text += `DISARMED BY THE TEAM, still armed here: ${evaluation.optOutsMissing.join(', ')}.\n`;
+  }
+  if (evaluation.tierDiffers) {
+    text += `DECLARED developer tier: ${evaluation.tierDiffers} — this machine runs the default.\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) {

package/targets/opt-outs.js

@@ -0,0 +1,40 @@
+// Which `.no-*` switches are the TEAM's decision and which are THIS MACHINE's.
+//
+// `project-manifest` moved disarmed gates into the committed declaration because they are
+// decisions and decisions should not evaporate on `git clone`. What it did not settle is that
+// not every switch is the same kind of decision, and one of them is actively dangerous to share:
+//
+//   `.no-harness` means "do not offer to build the harness ON THIS MACHINE" — the bootstrap says
+//   exactly that when it offers it. Let it travel and one person declining, once, would silence
+//   the offer in every future clone: a whole team losing the harness because somebody's laptop
+//   said no. The same reasoning covers an MCP connection (consent is individual), a check that
+//   compares two scopes of one machine, and a nudge that can only fire in a project with no
+//   `.git/` — which a clone, by construction, is not.
+//
+// A table and not a chain of ifs, so a test can iterate it and `clone-bootstrap.mjs` — which is
+// committed, standalone and cannot import from the package — can be held against it instead of
+// drifting away from it in silence.
+
+/** Decisions of the project: they belong in `.rsc.json` and are rebuilt in a clone. */
+export const PROJECT_OPT_OUTS = [
+  'audit',            // cadence of this project's skill audit
+  'claudemd-check',   // the root CLAUDE.md context budget
+  'danger-guard',     // foot-gun denial, keyed to the committed user profile
+  'feature-gate',     // per-turn re-injection of the SDD gate
+  'gitmoji',          // the commit-message convention
+  'ship-guard',       // branch/trunk discipline
+  'worktree-cleanup', // the reaper's notice (it only ever names, never acts)
+];
+
+/** Decisions of one machine: never written to the manifest, never applied from it. */
+export const MACHINE_OPT_OUTS = [
+  'context7',   // an MCP connection is machine wiring, and its consent is individual
+  'git',        // only fires with no .git/, which a clone cannot be
+  'harness',    // "not offered again ON THIS MACHINE" — the bootstrap's own words
+  'scope-check',// compares the project and home scopes OF THIS MACHINE
+];
+
+export const isProjectOptOut = (name) => PROJECT_OPT_OUTS.includes(name);
+
+/** The project-level subset of a manifest's `optOuts`, unknown names dropped. */
+export const projectOptOuts = (list) => [...new Set((list || []).filter(isProjectOptOut))].sort();

package/targets/session-start.mjs

@@ -194,19 +194,31 @@ ACTION: run \`npx @ericrisco/rsc audit\`. Opt out with .rsc/.no-audit.
 // it's a relocation, not a delete). Opt out with .rsc/.no-claudemd-check.
 const CLAUDEMD_MAX_LINES = 200;
 if (!has('.rsc', '.no-claudemd-check')) {
+  // WHICH file is the project's instructions is no longer a constant. From Claude Code 2.1.277, a
+  // project with no CLAUDE.md is read through its root AGENTS.md instead — same per-turn cost, same
+  // adherence rot when it grows, and until now nothing measured it. Measure the file that is
+  // actually being loaded: CLAUDE.md when there is one, otherwise AGENTS.md.
+  const name = has('CLAUDE.md') ? 'CLAUDE.md' : (has('AGENTS.md') ? 'AGENTS.md' : null);
   try {
-    const lines = readFileSync(join(root, 'CLAUDE.md'), 'utf8').split('\n').length;
+    const lines = readFileSync(join(root, name), 'utf8').split('\n').length;
     if (lines > CLAUDEMD_MAX_LINES) {
+      // Only the CLAUDE.md claim is unconditional. A client older than 2.1.277 does not read
+      // AGENTS.md at all, and this hook cannot tell which it is talking to (the SessionStart
+      // payload carries no version), so the AGENTS.md line says when the cost applies instead of
+      // asserting it — a notice that overstates its case is the kind that gets opted out of.
+      const why = name === 'CLAUDE.md'
+        ? "it's read every turn, so each line costs context"
+        : "Claude Code 2.1.277+ loads it every turn when there is no CLAUDE.md, so each line costs context";
       process.stdout.write(`
-===== rsc CLAUDE.md hygiene =====
-CLAUDE.md is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (it's read every turn, so each line costs context).
+===== rsc ${name} hygiene =====
+${name} is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (${why}).
 ACTION: offload the Knowledge map / overgrown sections into 02-DOCS/wiki/index.md and leave a short
-pointer in CLAUDE.md (no info lost — it's a move). The \`harness\` skill owns the procedure.
+pointer in ${name} (no info lost — it's a move). The \`harness\` skill owns the procedure.
 Opt out with .rsc/.no-claudemd-check.
 =================================
 `);
     }
-  } catch { /* no CLAUDE.md → nothing to check */ }
+  } catch { /* no instructions file (name === null) → nothing to check */ }
 }
 
 // Worktree sweep: a worktree whose work already reached the trunk is landed work wearing the same