@ericrisco/rsc 1.0.2 → 1.0.4

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.2",
+  "version": "1.0.4",
   "counts": {
     "skills": 258
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -6,6 +6,36 @@ import { readState } from './lib/state.js';
 import { loadManifest } from './lib/manifest.js';
 import { listBackups } from './lib/backups.js';
 import { SDD_GATE_TEXT } from '../targets/hook-once.mjs';
+import { isEnabled, checkSello, readSello, countFindings, readEffectiveConfig, validateRiskConfig } from '../targets/sello.mjs';
+
+// 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).
+// An INERT gate must never read as an armed one — a config that silently disables
+// enforcement is reported here, loudly.
+function selloStatus(root) {
+  try {
+    if (!isEnabled(root)) return { enabled: false };
+    const sello = readSello(root);
+    const verdict = checkSello(root);
+    const out = {
+      enabled: true,
+      decidedBy: readEffectiveConfig(root)?.scope,
+      check: verdict.code,
+      status: sello.missing ? 'none' : sello.corrupt ? 'corrupt' : sello.status,
+      nonBlockingFindings: countFindings(root),
+    };
+    if (verdict.warning) out.warning = verdict.warning;
+    if (verdict.code === 'no-trunk') out.inert = 'no-trunk';
+    if (existsSync(join(root, '.rsc', '.no-ship-guard'))) {
+      out.note = 'ship-guard branch-hygiene rules are opted out (.rsc/.no-ship-guard); the sello itself still enforces.';
+    }
+    try {
+      const { lowered } = validateRiskConfig(readEffectiveConfig(root) || {});
+      if (lowered.length) out.loweredClasses = lowered;
+    } catch (e) { out.configError = e.message; }
+    return out;
+  } catch { return { enabled: false }; }
+}
 
 export function doctor({ target, home, cwd }) {
   const root = cwd || process.cwd();
@@ -25,6 +55,7 @@ export function doctor({ target, home, cwd }) {
       latest: backups[0]?.id || null,
     },
     contextBudget: contextBudget({ target, home, cwd }),
+    sello: selloStatus(root),
   };
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);

package/scripts/install-apply.js

@@ -62,6 +62,7 @@ function generatedHookFiles({ target, cwd }) {
     join(cwd, '.rsc', 'danger-guard.mjs'),
     join(cwd, '.rsc', 'userprompt-gate.mjs'),
     join(cwd, '.rsc', 'hook-once.mjs'),
+    join(cwd, '.rsc', 'sello.mjs'),
   ];
 }
 

package/scripts/rsc.js

@@ -327,6 +327,175 @@ async function main() {
       say('Use: npx @ericrisco/rsc registry refresh | registry status');
       return;
     }
+    case 'sello': {
+      // Deterministic transitions of the sello (review receipt). The `review` skill
+      // orchestrates the lenses; every state change and every check runs HERE, token-free.
+      const S = await import('../targets/sello.mjs');
+      const root = S.resolveRoot(process.cwd());
+      const sub = argv[1];
+      const paths = S.selloPaths(root);
+      // flag() yields boolean true for a valueless flag; every string flag below
+      // goes through this so `--lenses` with no value is a usage error, not a crash.
+      const str = (name) => { const v = flag(name); return typeof v === 'string' ? v : undefined; };
+      switch (sub) {
+        case 'on':
+        case 'off': {
+          // --global writes the user-scope switch (every project inherits it);
+          // without it, the project switch, which always wins over the global one.
+          const isGlobal = argv.includes('--global');
+          const target = isGlobal ? S.globalConfigPath() : paths.config;
+          const cfg = (isGlobal ? S.readGlobalConfig() : S.readConfig(root)) || {};
+          delete cfg.scope; // derived, never persisted
+          // `off` never validates: it is the recovery advertised by every deny
+          // message, so a broken config must not be able to lock it away.
+          if (sub === 'on') {
+            try { S.validateRiskConfig(cfg); } catch (e) { say(e.message); process.exitCode = 1; return; }
+          }
+          const { writeFileSync, mkdirSync } = await import('node:fs');
+          const { dirname } = await import('node:path');
+          mkdirSync(dirname(target), { recursive: true });
+          writeFileSync(target, JSON.stringify({ ...cfg, enabled: sub === 'on' }, null, 2) + '\n');
+          const where = isGlobal ? 'for every project (global)' : 'for this project';
+          say(sub === 'on'
+            ? `✅ sello ON ${where}. Risk-0 changes (docs/copy) still pass silently; everything else needs a review before commit/push/PR.`
+            : `✅ sello OFF ${where}. Delivery behaves exactly as before.`);
+          if (isGlobal) {
+            const p = S.readConfig(root);
+            if (p && p.enabled !== undefined && p.enabled !== (sub === 'on')) {
+              say(`   ⚠️  this project overrides it (project = ${p.enabled ? 'on' : 'off'}); the project switch always wins. Change it with \`sello ${p.enabled ? 'off' : 'on'}\` here.`);
+            }
+          }
+          return;
+        }
+        case 'freeze': {
+          const cfg = S.readEffectiveConfig(root);
+          const candidate = S.computeCandidate(root, cfg);
+          if (!candidate) { say(S.MESSAGES.noTrunk()); process.exitCode = 1; return; }
+          const paths2 = Object.keys(candidate.files);
+          if (!paths2.length) { say('sello: nothing to freeze — the working tree matches the trunk base.'); return; }
+          const risk = S.classifyRisk(paths2, cfg);
+          if (risk.configError) say(`⚠️  ${risk.configError}\n   (using the default risk table until it is fixed)`);
+          const required = S.lensesRequired(risk.tier, cfg);
+          S.writeSello(root, { status: 'frozen', ...candidate, risk, required, lenses: [], createdAt: new Date().toISOString() });
+          say(`🧊 frozen: ${paths2.length} file(s), risk tier ${risk.tier} → ${required} lens(es) required.`);
+          for (const [p, c] of Object.entries(risk.classes)) if (c !== 'default' && c !== 'docs') say(`   ${p} → ${c}`);
+          if (risk.lowered?.length) say(`   (lowered by config: ${risk.lowered.join(', ')})`);
+          return;
+        }
+        case 'approve':
+        case 'block': {
+          const sello = S.readSello(root);
+          if (sello.missing || sello.corrupt || !sello.status) { say(S.MESSAGES.notFrozen()); process.exitCode = 1; return; }
+          const cfg = S.readEffectiveConfig(root);
+          const current = S.computeCandidate(root, cfg);
+          const changed = current && Object.keys({ ...sello.files, ...current.files })
+            .some((p) => sello.files[p] !== current.files[p]);
+          if (sub === 'approve' && (changed || sello.base !== current?.base)) {
+            say(S.MESSAGES.staleFreeze()); process.exitCode = 1; return;
+          }
+          const lenses = (str('lenses') || '').split(',').map((s) => s.trim()).filter(Boolean);
+          const required = sello.required ?? S.lensesRequired(sello.risk?.tier ?? 1, cfg);
+          // An incomplete panel must not seal silently (spec error path): the user
+          // may still accept the gap, but only on purpose.
+          if (sub === 'approve' && lenses.length < required && !argv.includes('--accept-partial-lenses')) {
+            say(S.MESSAGES.partialLenses(lenses.length, required)); process.exitCode = 1; return;
+          }
+          const note = str('note');
+          if (note) S.appendFindings(root, [`${new Date().toISOString().slice(0, 10)} ${note}`]);
+          const status = sub === 'approve' ? 'approved' : 'blocked';
+          const next = { ...sello, status, lenses, reason: str('reason') };
+          S.writeSello(root, next);
+          S.appendLog(root, {
+            at: new Date().toISOString(), status, base: sello.base, risk: sello.risk?.tier,
+            files: Object.keys(sello.files).length, lenses, digest: S.candidateDigest(sello),
+            partialLenses: lenses.length < required || undefined, reason: str('reason'),
+          });
+          say(sub === 'approve'
+            ? `✅ sealed with ${lenses.length}/${required} lens(es)${lenses.length ? `: ${lenses.join(', ')}` : ''}.`
+            : '⛔ blocked — fix and re-review.');
+          return;
+        }
+        case 'budget': {
+          const sello = S.readSello(root);
+          if (sello.missing || sello.corrupt) { say(S.MESSAGES.notFrozen()); process.exitCode = 1; return; }
+          const lines = Number(flag('lines'));
+          if (!Number.isFinite(lines) || lines <= 0) { say('Use: rsc sello budget --lines <N>'); process.exitCode = 1; return; }
+          S.writeSello(root, { ...sello, budget: { lines, declaredAt: new Date().toISOString() } });
+          say(`📏 fix budget declared: ${lines} line(s). budget-check will hold the fix to it.`);
+          return;
+        }
+        case 'budget-check': {
+          const sello = S.readSello(root);
+          if (sello.missing || sello.corrupt || !sello.budget) { say('sello: no declared budget. Recover: run `rsc sello budget --lines <N>` BEFORE fixing.'); process.exitCode = 1; return; }
+          const current = S.computeCandidate(root, S.readEffectiveConfig(root));
+          const spent = S.budgetSpent(sello, current || { numstat: {} });
+          if (spent <= sello.budget.lines) { say(`✅ within budget: ~${spent}/${sello.budget.lines} line(s).`); return; }
+          const justify = str('justify');
+          if (typeof justify === 'string' && justify.trim()) {
+            S.writeSello(root, { ...sello, budget: { ...sello.budget, exceeded: spent, justification: justify } });
+            S.appendFindings(root, [`budget exceeded (~${spent}/${sello.budget.lines}): ${justify}`]);
+            say(`⚠️ over budget (~${spent}/${sello.budget.lines}) — justification recorded.`);
+            return;
+          }
+          say(S.MESSAGES.overBudget(spent, sello.budget.lines));
+          process.exitCode = 1;
+          return;
+        }
+        case 'check': {
+          const verdict = S.checkSello(root);
+          if (verdict.warning) say(`⚠️  ${verdict.warning}`);
+          if (verdict.ok) { say(`✅ sello check: ${verdict.code}`); return; }
+          say(verdict.message);
+          process.exitCode = 1;
+          return;
+        }
+        case 'report': {
+          const { existsSync, readFileSync } = await import('node:fs');
+          say(existsSync(paths.findings) ? readFileSync(paths.findings, 'utf8') : '(no non-blocking findings recorded)');
+          return;
+        }
+        case 'status': {
+          const { existsSync } = await import('node:fs');
+          const { join } = await import('node:path');
+          const enabled = S.isEnabled(root);
+          const verdict = S.checkSello(root);
+          const sello = S.readSello(root);
+          const cfg = S.readEffectiveConfig(root);
+          let lowered = [];
+          let configError;
+          try { ({ lowered } = S.validateRiskConfig(cfg || {})); } catch (e) { configError = e.message; }
+          const globalCfg = S.readGlobalConfig();
+          const projectCfg = S.readConfig(root);
+          say(JSON.stringify({
+            enabled,
+            // Which scope decided, and what each one says — two scopes quietly
+            // disagreeing is a failure this harness has already lived through.
+            decidedBy: cfg?.scope,
+            scopes: {
+              global: globalCfg?.enabled === undefined ? 'unset' : globalCfg.enabled ? 'on' : 'off',
+              project: projectCfg?.enabled === undefined ? 'unset' : projectCfg.enabled ? 'on' : 'off',
+            },
+            check: verdict.code,
+            // An inert gate must never look armed: name every reason it is standing down.
+            inert: enabled && ['no-trunk', 'disabled'].includes(verdict.code) ? verdict.code : undefined,
+            shipGuardOptOut: existsSync(join(root, '.rsc', '.no-ship-guard')) || undefined,
+            warning: verdict.warning,
+            configError,
+            loweredClasses: lowered.length ? lowered : undefined,
+            status: sello.missing ? 'none' : sello.corrupt ? 'corrupt' : sello.status,
+            risk: sello.risk?.tier,
+            lenses: sello.lenses,
+            lensesRequired: sello.required,
+            budget: sello.budget,
+            nonBlockingFindings: S.countFindings(root),
+          }, null, 2));
+          return;
+        }
+        default:
+          say('Use: npx @ericrisco/rsc sello on|off [--global]|status|freeze|approve --lenses a,b [--accept-partial-lenses]|block --reason "…"|budget --lines N|budget-check [--justify "…"]|check|report');
+          return;
+      }
+    }
     case 'uninstall': {
       const dry = argv.includes('--dry-run');
       // `uninstall --all` is an alias for a full purge.
@@ -339,7 +508,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | sync | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | sync | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
   }
 }
 

package/skills/review/SKILL.md

@@ -102,6 +102,52 @@ End every review you give with one of three, and nothing mushy in between:
 - **`APPROVE WITH NITS`** — mergeable; the nits are the author's call.
 - **`CHANGES REQUESTED`** — one or more blockers/should-fix. List exactly what unblocks it.
 
+### The sello — when this project opted in
+
+If the sello is on — `.rsc/sello-config.json` in the project, or `~/.rsc/sello-config.json` for
+every project (`sello on --global`; the project switch always wins) — the review's verdict is
+**sealed to the exact bytes reviewed**, and the ship gate refuses commit/push/PR on anything else.
+
+**What the sello does and does not prove.** It binds bytes, not intent: it guarantees *what ships
+is what was reviewed*, never *the review was good*. You are the one calling `sello approve`, so it
+is self-attested — drift protection between review and delivery, not tamper-evidence. Sealing
+without actually running the lenses produces a valid sello and a worthless one.
+
+Every state transition is deterministic CLI, never tokens:
+
+```text
+1. npx @ericrisco/rsc sello freeze      → hashes the candidate, prints risk tier + lens count
+2. Run the lenses (below), filter findings, decide
+3a. approved → npx @ericrisco/rsc sello approve --lenses correctness,security,tests
+3b. blocked  → npx @ericrisco/rsc sello block --reason "<the blocking finding>"
+```
+
+`approve` refuses to seal with fewer lenses than the tier requires — pass them all, or accept the
+gap deliberately with `--accept-partial-lenses` (it is recorded). Every approval also appends to
+`.rsc/sello-log.jsonl`, so what shipped under which verdict survives the next freeze.
+
+**Lenses by risk tier** — tier 0 never reaches you (the gate passes docs/copy silently);
+tier 1 → run the single most relevant pass from the table above yourself; tier 2 → dispatch
+**three parallel fresh-context subagents** (correctness · security · tests-as-evidence), each
+given only the diff and told to *refute* readiness, not confirm it. Fresh context is the point:
+a reviewer who inherits the implementer's context inherits its blind spots.
+
+**A finding blocks only if it survives all three filters** — no exceptions, and eagerness to
+find something is not evidence:
+
+1. **Causal** — introduced by *this* change. Pre-existing defects → note with
+   `--note "<finding>"` (they land in `.rsc/sello-findings.md`, surfaced by `doctor`) and
+   suggest an issue; they never block this delivery.
+2. **Severity** — only `blocker` blocks. `should-fix`/`nit` → `--note`.
+3. **Evidence** — a `repro` or a concrete failure scenario. A suspicion without one is a
+   `[question]`, and questions don't block.
+
+**Fixing a blocker is budgeted, one attempt.** Before touching anything: estimate the fix and
+declare it — `npx @ericrisco/rsc sello budget --lines <N>`. After the fix:
+`sello budget-check` (over budget → justify with `--justify "…"` or shrink; an unexplained
+overrun is how over-engineering enters disguised as a fix). Then `sello freeze` + re-review
+**only the divergence**, and approve. Still broken after one attempt → stop, hand it to the human.
+
 ---
 
 ## RECEIVING a review

package/skills/ship/SKILL.md

@@ -72,6 +72,17 @@ the command), and can be disabled per project with `.rsc/.no-ship-guard`. It gua
 commit → push step; opening the PR is still this skill's job (and its hard rule). If the guard
 blocks you, do not work around it — run ship.
 
+The same guard also enforces the **sello** where it was opted into — per project
+(`.rsc/sello-config.json`) or for all of them (`~/.rsc/sello-config.json` via
+`sello on --global`, with the project switch always winning; `rsc sello status` prints which
+scope decided): commit, push and PR are denied unless the change's exact bytes match the
+sealed, approved review — one byte of drift, a moved base, or a missing review on a risk>0 change
+all block, and every denial names its way out (re-run `review`, or `npx @ericrisco/rsc sello off`).
+Risk-0 changes (docs/copy) always pass silently. Off by default; the flow lives in the `review`
+skill. Note `.rsc/.no-ship-guard` opts out of the branch-hygiene rules above but **not** of the
+sello, which has its own switch. The sello binds bytes, not intent — it proves what ships is what
+was reviewed, never that the review was any good.
+
 ## The three landing options — always present exactly three
 
 This mirrors the harness "siempre 3 opciones" pattern. Gather the one fact that changes the answer (does this repo use PRs / require review on `main`?), then present **exactly three** with an honest recommendation matched to the workflow and the accompaniment level.

package/targets/claude.js

@@ -90,6 +90,9 @@ export function wireHook(paths) {
   // (non-rsc) PreToolUse hooks are preserved.
   const sgDest = join(paths.projectRoot, '.rsc', 'ship-guard.mjs');
   copyFileSync(join(HERE, 'ship-guard.mjs'), sgDest);
+  // 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 "${sgDest}" "${paths.projectRoot}"`;
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(

package/targets/sello.mjs

@@ -0,0 +1,433 @@
+// sello.mjs — the deterministic core of the "sello" (review receipt) system.
+//
+// A sello binds a review verdict to the EXACT bytes that were reviewed. The ship
+// gate (ship-guard.mjs) refuses to commit/push/PR anything whose bytes differ from
+// what was sealed. Opt-in per project via .rsc/sello-config.json — absent or
+// disabled, nothing here runs and the harness behaves exactly as before.
+//
+// TRUST MODEL — read this before believing a sello. It binds BYTES, not intent:
+// it proves "what ships is what was reviewed", never "the review was any good".
+// `sello approve` is an unauthenticated local command and the reviewing agent is
+// the one that calls it, so the sello is SELF-ATTESTED: it is drift protection
+// between review and delivery, not tamper-evidence against the agent or the user.
+// Anyone who can write .rsc/ can seal anything — which is why `sello off` is a
+// documented one-liner rather than something to defeat.
+//
+// Design rules (constitution):
+//  - P1: everything in this file is an algorithm — no tokens, no judgment.
+//  - P2: every gate has a test (tests/sello.test.js), including the risk table itself.
+//  - P4: the sello is the artifact that makes an approval binding to a candidate.
+//  - P6: every deny message carries its own `Recover:` line, asserted by test.
+//  - P7: risk-0 changes (docs/copy) pass in complete silence.
+//
+// Materialized to .rsc/sello.mjs as a sibling of ship-guard.mjs (hooks are copied
+// file-by-file, so imports must be sibling-relative — same pattern as hook-once.mjs).
+
+import { existsSync, lstatSync, readFileSync, readlinkSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+// ---------------------------------------------------------------- paths & config
+
+// The sello's own state can never be part of the candidate it seals: writing the
+// sello would mutate the change being sealed, so `freeze` → `approve` could never
+// converge (a permanent, unrecoverable delivery lockout). Excluded whether the
+// project tracks .rsc/ or not.
+export const SELLO_STATE_PATHS = [
+  '.rsc/sello.json', '.rsc/sello-config.json', '.rsc/sello-findings.md', '.rsc/sello-log.jsonl',
+];
+
+export function selloPaths(root) {
+  return {
+    config: join(root, '.rsc', 'sello-config.json'),
+    state: join(root, '.rsc', 'sello.json'),
+    findings: join(root, '.rsc', 'sello-findings.md'),
+    log: join(root, '.rsc', 'sello-log.jsonl'),
+  };
+}
+
+// The user-scope switch: turn the sello on once for every project instead of
+// per repo. RSC_SELLO_HOME exists so tests can point it somewhere disposable
+// (same escape hatch as hook-once's marker dir).
+export function selloHome() {
+  return process.env.RSC_SELLO_HOME || homedir();
+}
+export function globalConfigPath(home = selloHome()) {
+  return join(home, '.rsc', 'sello-config.json');
+}
+
+function readJson(path) {
+  try {
+    const cfg = JSON.parse(readFileSync(path, 'utf8'));
+    return cfg && typeof cfg === 'object' ? cfg : null;
+  } catch { return null; }
+}
+
+// Project-scope config only — this is what `sello on/off` writes.
+export function readConfig(root) {
+  return readJson(selloPaths(root).config);
+}
+export function readGlobalConfig() {
+  return readJson(globalConfigPath());
+}
+
+// What actually governs a project: global as the base, project keys on top.
+// PRECEDENCE IS EXPLICIT AND SURFACED — this harness has already been bitten by
+// two scopes silently disagreeing (a project opt-out that never reached the
+// user-scope guard), so `scope` says which one decided and `status`/`doctor`
+// print it.
+export function readEffectiveConfig(root) {
+  const g = readGlobalConfig();
+  const p = readConfig(root);
+  if (!g && !p) return null;
+  const merged = { ...(g || {}), ...(p || {}) };
+  merged.scope = p && p.enabled !== undefined ? 'project'
+    : g && g.enabled !== undefined ? 'global'
+      : 'none';
+  return merged;
+}
+
+export function isEnabled(root) {
+  const cfg = readEffectiveConfig(root);
+  return !!(cfg && cfg.enabled === true);
+}
+
+// The CLI can run from any subdirectory; the guard always runs from the project
+// root. Both must compute the same candidate, so both resolve to the git toplevel.
+export function resolveRoot(root) {
+  const r = spawnSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() || root : root;
+}
+
+// ---------------------------------------------------------------- risk table
+//
+// Risk is classified by WHAT a path touches, never by how many lines changed.
+// Tiers: 0 = nulo (docs/copy — silent), 1 = normal (one lens), 2 = alto (full panel).
+// A path is scored by the HIGHEST tier of every row it matches — first-match-wins
+// would let the docs row shadow a floor class (`credentials.txt`, `.claude/CLAUDE.md`)
+// and hand a silent pass to exactly what the floor exists to guard.
+
+export const RISK_TABLE = [
+  { class: 'docs', tier: 0, pattern: '(^|/)(docs|doc)/|\\.(md|mdx|markdown|txt|rst)$|(^|/)LICENSE$|(^|/)CHANGELOG' },
+  { class: 'secrets', tier: 2, pattern: '(^|/)\\.env(\\.|$)|(^|/)(secrets?|credentials?)(/|\\.|-|$)|\\.(pem|key|p12|pfx)$|(^|/)[^/]*(secret|credential)[^/]*$' },
+  { class: 'auth', tier: 2, pattern: '(^|/)(auth|authn|authz|login|session|oauth|sso)(/|\\.|-)' },
+  { class: 'ci', tier: 2, pattern: '(^|/)\\.github/workflows/|(^|/)\\.gitlab-ci\\.yml$|(^|/)Jenkinsfile$' },
+  { class: 'migrations', tier: 2, pattern: '(^|/)migrations?/' },
+  { class: 'billing', tier: 2, pattern: '(^|/)(billing|payments?|checkout|stripe)(/|\\.|-)' },
+  { class: 'harness', tier: 2, pattern: '(^|/)\\.rsc/|(^|/)\\.claude/|(^|/)CLAUDE\\.md$' },
+];
+export const FLOOR_CLASSES = ['secrets', 'harness'];
+export const DEFAULT_TIER = 1;
+// User-supplied patterns are compiled inside a PreToolUse hook, so a catastrophic
+// one would hang the user's own delivery. Bounded, not sandboxed — the same file
+// holds the kill switch, so this is a foot-gun guard, not a security boundary.
+export const MAX_PATTERN_LEN = 200;
+export const MAX_RAISE_RULES = 64;
+
+// A project override may RAISE freely and may LOWER only explicitly (naming a known
+// class), never below tier 1, and never a floor class. Throws with a recoverable
+// message; callers fall back to the DEFAULT table, never to a flat tier.
+export function validateRiskConfig(cfg) {
+  const risk = cfg?.risk;
+  if (!risk) return { table: RISK_TABLE, lowered: [] };
+  const lowered = [];
+  const extra = [];
+  const raise = risk.raise || [];
+  if (raise.length > MAX_RAISE_RULES) {
+    throw new Error(`sello: too many "raise" rules (${raise.length} > ${MAX_RAISE_RULES}). ${MESSAGES.badRiskConfig}`);
+  }
+  for (const r of raise) {
+    if (!r?.pattern || typeof r.pattern !== 'string') {
+      throw new Error(`sello: a "raise" entry has no pattern. ${MESSAGES.badRiskConfig}`);
+    }
+    if (r.pattern.length > MAX_PATTERN_LEN) {
+      throw new Error(`sello: pattern longer than ${MAX_PATTERN_LEN} chars. ${MESSAGES.badRiskConfig}`);
+    }
+    try { new RegExp(r.pattern); }
+    catch (e) { throw new Error(`sello: uncompilable pattern ${JSON.stringify(r.pattern)} (${e.message}). ${MESSAGES.badRiskConfig}`); }
+    extra.push({ class: r.class || 'custom', tier: r.tier === 1 ? 1 : 2, pattern: r.pattern });
+  }
+  for (const l of risk.lower || []) {
+    const cls = typeof l === 'string' ? l : l?.class;
+    if (FLOOR_CLASSES.includes(cls)) {
+      throw new Error(`sello: the "${cls}" class can never be lowered — secrets and the harness's own configuration keep their risk tier under every configuration. ${MESSAGES.badRiskConfig}`);
+    }
+    if (!RISK_TABLE.some((row) => row.class === cls)) {
+      throw new Error(`sello: cannot lower unknown class "${cls}". ${MESSAGES.badRiskConfig}`);
+    }
+    lowered.push(cls);
+  }
+  const table = [
+    ...extra,
+    ...RISK_TABLE.map((row) => (lowered.includes(row.class) ? { ...row, tier: 1 } : row)),
+  ];
+  return { table, lowered };
+}
+
+// → {tier, classes: {path: class}, lowered, configError} — a path scores the MAX
+// tier of every row it matches; unmatched paths land on DEFAULT_TIER.
+export function classifyRisk(paths, cfg = null) {
+  let table = RISK_TABLE;
+  let lowered = [];
+  let configError = null;
+  try { ({ table, lowered } = validateRiskConfig(cfg || {})); }
+  catch (e) { configError = e.message; table = RISK_TABLE; lowered = []; }
+
+  const compiled = table.map((r) => ({ ...r, re: new RegExp(r.pattern) }));
+  const classes = {};
+  let tier = 0;
+  for (const p of paths) {
+    let best = -1;
+    let cls = 'default';
+    for (const row of compiled) {
+      if (row.re.test(p) && row.tier > best) { best = row.tier; cls = row.class; }
+    }
+    if (best < 0) { best = DEFAULT_TIER; cls = 'default'; }
+    classes[p] = cls;
+    if (best > tier) tier = best;
+  }
+  return { tier, classes, lowered, configError };
+}
+
+// How many lenses a tier requires (capped by an explicit config knob, floor 1).
+export function lensesRequired(tier, cfg = null) {
+  const base = tier === 0 ? 0 : tier === 1 ? 1 : 3;
+  const cap = Number(cfg?.lenses);
+  if (base > 0 && Number.isFinite(cap) && cap >= 1) return Math.min(base, Math.floor(cap));
+  return base;
+}
+
+// ---------------------------------------------------------------- candidate
+
+// core.quotePath makes git escape non-ASCII paths ("caf\303\251.js"); the escaped
+// name matches no file on disk, so the file would hash as deleted and any later
+// mutation of it would sail through the gate. -z gives raw NUL-separated paths.
+function git(root, ...args) {
+  const r = spawnSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], {
+    encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  });
+  return r.status === 0 ? (r.stdout || '') : null;
+}
+const nulList = (out) => (out || '').split('\0').filter(Boolean);
+
+export function trunkRef(root, cfg = null) {
+  const configured = typeof cfg?.trunk === 'string' ? [cfg.trunk, `origin/${cfg.trunk}`] : [];
+  for (const ref of [...configured, 'origin/main', 'origin/master', 'main', 'master']) {
+    if (git(root, 'rev-parse', '--verify', '--quiet', ref) !== null) return ref;
+  }
+  return null;
+}
+
+// The candidate is the change vs the trunk merge-base: every path that differs
+// between that base and the working tree (committed on the branch, staged, unstaged
+// or untracked), each hashed byte-for-byte. Deleted paths hash to "D". Symlinks hash
+// their target string, never the pointed-at bytes (an out-of-repo link must not be
+// read, and a link to a FIFO would hang the hook).
+export function computeCandidate(rawRoot, cfg = null) {
+  const root = resolveRoot(rawRoot);
+  const trunk = trunkRef(root, cfg);
+  if (!trunk) return null;
+  const head = git(root, 'rev-parse', 'HEAD');
+  const base = head ? (git(root, 'merge-base', 'HEAD', trunk) || '').trim() : null;
+  if (!base) return null;
+
+  const names = new Set();
+  for (const n of nulList(git(root, 'diff', '--name-only', '-z', base))) names.add(n);
+  for (const n of nulList(git(root, 'ls-files', '--others', '--exclude-standard', '-z'))) names.add(n);
+  for (const p of SELLO_STATE_PATHS) names.delete(p);
+
+  const files = {};
+  const numstat = {};
+  for (const name of [...names].sort()) {
+    const abs = join(root, name);
+    let st = null;
+    try { st = lstatSync(abs); } catch { st = null; }
+    if (!st) { files[name] = 'D'; continue; }
+    if (st.isSymbolicLink()) {
+      files[name] = 'L:' + createHash('sha256').update(readlinkSync(abs)).digest('hex');
+    } else if (st.isFile()) {
+      files[name] = createHash('sha256').update(readFileSync(abs)).digest('hex');
+    } else {
+      files[name] = 'S'; // socket/fifo/device — never read, but its presence counts
+    }
+  }
+  for (const line of (git(root, 'diff', '--numstat', base) || '').split('\n')) {
+    const m = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
+    if (m) numstat[m[3]] = (m[1] === '-' ? 0 : Number(m[1])) + (m[2] === '-' ? 0 : Number(m[2]));
+  }
+  // Untracked files never appear in numstat, so a fix hidden in a new file would
+  // cost zero budget. Count their lines.
+  for (const n of nulList(git(root, 'ls-files', '--others', '--exclude-standard', '-z'))) {
+    if (SELLO_STATE_PATHS.includes(n) || numstat[n] !== undefined) continue;
+    try {
+      const st = lstatSync(join(root, n));
+      if (st.isFile()) numstat[n] = readFileSync(join(root, n), 'utf8').split('\n').length;
+    } catch { /* unreadable → not counted */ }
+  }
+  return { base, files, numstat };
+}
+
+export function candidateDigest(candidate) {
+  const body = Object.keys(candidate.files).sort().map((p) => `${p}:${candidate.files[p]}`).join('\n');
+  return createHash('sha256').update(`${candidate.base}\n${body}`).digest('hex');
+}
+
+// ---------------------------------------------------------------- sello state
+
+export function readSello(root) {
+  const p = selloPaths(resolveRoot(root)).state;
+  if (!existsSync(p)) return { missing: true };
+  try {
+    const s = JSON.parse(readFileSync(p, 'utf8'));
+    if (!s || typeof s !== 'object' || !s.files || !s.base) return { corrupt: true };
+    return s;
+  } catch { return { corrupt: true }; }
+}
+
+export function writeSello(rawRoot, sello) {
+  const p = selloPaths(resolveRoot(rawRoot)).state;
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(sello, null, 2) + '\n');
+}
+
+// A durable record of what was delivered under which verdict — the sello file
+// itself is overwritten by the next freeze, so without this the trail dies.
+export function appendLog(rawRoot, entry) {
+  const p = selloPaths(resolveRoot(rawRoot)).log;
+  mkdirSync(dirname(p), { recursive: true });
+  appendFileSync(p, JSON.stringify(entry) + '\n');
+}
+
+export function appendFindings(rawRoot, lines) {
+  if (!lines?.length) return;
+  const p = selloPaths(resolveRoot(rawRoot)).findings;
+  mkdirSync(dirname(p), { recursive: true });
+  const header = existsSync(p) ? '' : '# sello — hallazgos no bloqueantes\n\nSe acumulan aquí; `rsc sello report` los muestra. No interrumpen nada.\n';
+  const flat = lines.map((l) => `- ${String(l).replace(/\s*\n\s*/g, ' ')}`);
+  appendFileSync(p, header + flat.join('\n') + '\n');
+}
+
+export function countFindings(rawRoot) {
+  const p = selloPaths(resolveRoot(rawRoot)).findings;
+  if (!existsSync(p)) return 0;
+  return readFileSync(p, 'utf8').split('\n').filter((l) => l.startsWith('- ')).length;
+}
+
+// ---------------------------------------------------------------- delivery detection
+//
+// Does this shell command actually DELIVER? Two failure modes to avoid, both real:
+// denying `grep -rn "git push" docs/` (the words inside a string are not a delivery)
+// and allowing `git -C . commit` (a first-class agent pattern — cwd resets between
+// Bash calls, so agents pass -C routinely).
+// Flags that may sit between the binary and the subcommand: --long, --long=value,
+// and single-letter flags that take a separate value (-C path, -c k=v, -R owner/repo).
+const GIT_OPTS = '(?:-{1,2}[\\w-]+(?:=\\S+)?\\s+|-[A-Za-z]\\s+\\S+\\s+)*';
+const GIT_DELIVERY = new RegExp(`\\bgit\\s+${GIT_OPTS}(?:commit|push)(?![\\w-])`);
+const GH_DELIVERY = new RegExp(`\\bgh\\s+${GIT_OPTS}pr\\s+${GIT_OPTS}(?:create|merge)(?![\\w-])`);
+
+export function isDeliveryCommand(command) {
+  if (typeof command !== 'string' || !command) return false;
+  // Blank out quoted strings so a command that merely MENTIONS the words is not
+  // mistaken for one that runs them.
+  const bare = command.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
+  return GIT_DELIVERY.test(bare) || GH_DELIVERY.test(bare);
+}
+
+// ---------------------------------------------------------------- messages (P6)
+//
+// Every message that can DENY an action carries a `Recover:` line naming the exact
+// way out. tests/sello.test.js iterates MESSAGES and asserts this for every entry —
+// a block without its recovery is the one thing this system may never produce.
+
+export const MESSAGES = {
+  noReview: (tier) =>
+    `sello: this change is risk tier ${tier} and has no review. ` +
+    `Recover: run the \`review\` skill (it freezes, reviews and approves the sello), or \`npx @ericrisco/rsc sello off\` to turn the sello off for this project.`,
+  diverged: (paths) =>
+    `sello: the change no longer matches what was reviewed — ${paths.slice(0, 5).join(', ')}${paths.length > 5 ? ` (+${paths.length - 5} more)` : ''} differ from the sealed bytes. ` +
+    `Recover: re-run the \`review\` skill on the divergence (only what changed is re-reviewed), or \`npx @ericrisco/rsc sello off\` for this project.`,
+  baseMoved: () =>
+    `sello: the sello belongs to a different base — the branch was rebased/merged, or this sello was left over from a change that already shipped. Either way nothing has reviewed the current candidate. ` +
+    `Recover: re-run the \`review\` skill (only the divergence is re-reviewed), or \`npx @ericrisco/rsc sello off\` for this project.`,
+  corrupt: () =>
+    `sello: the sello file is unreadable, which counts as "no review" — nothing is ever approved by default. ` +
+    `Recover: re-run the \`review\` skill to produce a fresh sello, or \`npx @ericrisco/rsc sello off\` for this project.`,
+  blocked: (reason) =>
+    `sello: the review left this change BLOCKED${reason ? ` (${reason})` : ''}. ` +
+    `Recover: fix the blocking findings and re-run the \`review\` skill, or \`npx @ericrisco/rsc sello off\` for this project.`,
+  notFrozen: () =>
+    `sello: nothing is frozen yet, so there is nothing to approve. ` +
+    `Recover: run \`npx @ericrisco/rsc sello freeze\` first, then review, then approve.`,
+  staleFreeze: () =>
+    `sello: the change mutated after it was frozen — approving now would seal bytes nobody reviewed. ` +
+    `Recover: run \`npx @ericrisco/rsc sello freeze\` again and re-review the divergence.`,
+  overBudget: (spent, budget) =>
+    `sello: the fix touched ~${spent} line(s) but the declared budget was ${budget} — an unexplained overrun is how over-engineering gets in. ` +
+    `Recover: re-run with --justify "<why the budget was not enough>" to record the reason, or shrink the fix.`,
+  partialLenses: (given, required) =>
+    `sello: risk tier needs ${required} lens(es) but only ${given} were recorded — an incomplete panel must not seal silently. ` +
+    `Recover: run the missing lenses and pass them all to --lenses, or accept the gap on purpose with --accept-partial-lenses.`,
+  badRiskConfig:
+    'Recover: fix .rsc/sello-config.json — "raise" entries need a valid pattern under 200 chars; "lower" only accepts known classes and never "secrets" or "harness". `npx @ericrisco/rsc sello off` always works, even with a broken config.',
+  riskUnknown: () =>
+    `sello: the risk of this change could not be evaluated, so it is treated as risk tier 1 (never silently as 0). ` +
+    `Recover: check that this is a git repository with a reachable trunk (origin/main, main, or "trunk" in .rsc/sello-config.json), then retry.`,
+  noTrunk: () =>
+    `sello: no trunk branch found (looked for origin/main, origin/master, main, master), so the gate cannot compute what changed and is standing down. ` +
+    `Recover: set {"trunk": "<your branch>"} in .rsc/sello-config.json so the sello knows what to diff against.`,
+};
+
+// ---------------------------------------------------------------- the check
+//
+// The single verdict function the guard, the CLI and the tests all share.
+// → {ok: true, code} | {ok: false, code, message}
+
+export function checkSello(rawRoot) {
+  const root = resolveRoot(rawRoot);
+  const cfg = readEffectiveConfig(root);
+  if (!cfg || cfg.enabled !== true) return { ok: true, code: 'disabled' };
+
+  const candidate = computeCandidate(root, cfg);
+  if (!candidate) {
+    // Fail open, but never silently: doctor/status surface this so an inert gate
+    // in a develop-based repo cannot masquerade as an armed one.
+    return { ok: true, code: 'no-trunk', warning: MESSAGES.noTrunk() };
+  }
+
+  const paths = Object.keys(candidate.files);
+  if (paths.length === 0) return { ok: true, code: 'clean' };
+
+  const risk = classifyRisk(paths, cfg);
+  // P7 first, before any sello state is consulted: a docs-only change must never
+  // be blocked by a leftover sello from some other change.
+  if (risk.tier === 0) return { ok: true, code: 'risk0' };
+
+  const sello = readSello(root);
+  if (sello.missing) return { ok: false, code: 'no-review', message: MESSAGES.noReview(risk.tier) };
+  if (sello.corrupt) return { ok: false, code: 'corrupt', message: MESSAGES.corrupt() };
+  if (sello.status === 'blocked') return { ok: false, code: 'blocked', message: MESSAGES.blocked(sello.reason) };
+  if (sello.status !== 'approved') return { ok: false, code: 'no-review', message: MESSAGES.noReview(risk.tier) };
+  if (sello.base !== candidate.base) return { ok: false, code: 'base-moved', message: MESSAGES.baseMoved() };
+
+  const diverged = [];
+  const sealed = sello.files || {};
+  for (const p of new Set([...Object.keys(sealed), ...paths])) {
+    if (sealed[p] !== candidate.files[p]) diverged.push(p);
+  }
+  if (diverged.length) return { ok: false, code: 'diverged', message: MESSAGES.diverged(diverged) };
+  return { ok: true, code: 'sealed' };
+}
+
+// Fix-budget accounting: |numstat delta| vs the frozen totals (untracked files
+// included — see computeCandidate). Approximate by construction: a same-size
+// rewrite costs 0 and a moved hunk double-counts. It bounds sprawl, not edits.
+export function budgetSpent(frozen, current) {
+  let spent = 0;
+  const all = new Set([...Object.keys(frozen.numstat || {}), ...Object.keys(current.numstat || {})]);
+  for (const p of all) {
+    spent += Math.abs((current.numstat?.[p] || 0) - (frozen.numstat?.[p] || 0));
+  }
+  return spent;
+}

package/targets/ship-guard.mjs

@@ -31,8 +31,9 @@ function deny(reason) {
   process.exit(0);
 }
 
-// Opt-out and "not a git repo" both mean: nothing to enforce.
-if (existsSync(join(root, '.rsc', '.no-ship-guard'))) allow();
+// "Not a git repo" means: nothing to enforce. (The .no-ship-guard opt-out is checked
+// AFTER the sello below — it opts out of THIS guard's branch-hygiene rules, not of a
+// different feature that happens to share the hook. The sello has its own switch.)
 if (!existsSync(join(root, '.git'))) allow();
 
 // Read the tool call. Only Bash commands can move branches.
@@ -42,6 +43,24 @@ if ((input.tool_name || input.toolName) !== 'Bash') allow();
 const command = input.tool_input?.command || input.toolInput?.command || '';
 if (typeof command !== 'string' || !command) allow();
 
+// ---- sello gate (opt-in) ----------------------------------------------------
+// When the sello is ON for this project, delivery commands (commit, push, PR)
+// must match the sealed bytes. OFF (the default) → this block is a no-op and the
+// guard behaves exactly as before. checkSello itself fails open on environment
+// problems and denies only on real divergence/no-review/corruption (spec).
+// Deliberately BEFORE the .no-ship-guard opt-out: that file disables this guard's
+// branch-hygiene rules; the sello is a separate opt-in with its own `sello off`.
+try {
+  const { checkSello, isEnabled, isDeliveryCommand } = await import(new URL('./sello.mjs', import.meta.url));
+  if (isDeliveryCommand(command) && isEnabled(root)) {
+    const verdict = checkSello(root);
+    if (!verdict.ok) deny(verdict.message);
+  }
+} catch { /* sello lib missing/unloadable → nothing to enforce, fail open */ }
+
+// Ship-guard's own opt-out (branch hygiene only — the sello above already ran).
+if (existsSync(join(root, '.rsc', '.no-ship-guard'))) allow();
+
 // Does this command try to land on / move to the trunk?
 const TRUNK = /\bgit\s+(?:checkout|switch)\s+(?:-{1,2}\S+\s+)*(?:main|master)\b/;
 const MERGE = /\bgit\s+merge\b/;