@ericrisco/rsc 0.1.17 → 0.1.19

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.17",
+  "version": "0.1.19",
   "counts": {
     "skills": 231
   },

package/package.json

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

package/scripts/audit.js

@@ -0,0 +1,224 @@
+// audit.js — inventory installed skills (project + machine), surface possible
+// overlap and over-install (bloat). Advisory only: every finding is a "review
+// this", never a hard error. Run on demand (`rsc audit`), at `init`, and nudged
+// periodically by the SessionStart hook when the last run is stale.
+//
+// Signals it leans on, all already in the repo:
+//   - manifest.json    → the catalog (id, description, tags) — what a skill is
+//   - .rsc/skills/<id>  → the project's single source of truth for installed skills
+//   - ~/.claude/skills  → machine/user-scope skills
+//   - detectRepo()      → coarse stack signals, to judge "no footprint here"
+//   - DOMAINS           → the catalog grouped by intent, to judge overlap/heaviness
+import { existsSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { loadManifest } from './lib/manifest.js';
+import { detectRepo } from './detect-repo.js';
+import { DOMAINS } from './lib/domains.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// The control plane + SDD pipeline always coexist by design — never flag them as
+// overlap or bloat. A pipeline of phases is not "too many skills".
+const FLOOR_DOMAINS = ['Core & control plane', 'Spec-Driven Development'];
+// Domains whose skills imply a concrete stack in the repo. Only these get the
+// "no footprint detected" check — content/business skills can't be judged from code.
+const CODE_DOMAINS = [
+  'Languages',
+  'Frameworks & app stacks',
+  'Databases & data layer',
+  'Ship & operate — platforms',
+];
+
+// detectRepo() is coarse (a handful of stack tags). Expand each detected signal to
+// the sibling skills it implies, so "Next.js detected" doesn't flag react/vercel as
+// orphans. Anything outside the expanded set in a CODE_DOMAIN is advisory bloat.
+const STACK_SIBLINGS = {
+  nextjs: ['nextjs', 'react', 'typescript', 'nodejs', 'vercel', 'design', 'tailwind'],
+  design: ['design', 'nextjs', 'react'],
+  fastapi: ['fastapi', 'python', 'sql'],
+  go: ['go'],
+  postgresdb: ['postgresdb', 'sql', 'prisma-orm', 'drizzle-orm', 'db-migrations', 'supabase', 'neon'],
+  deployment: ['deployment', 'docker', 'github-actions', 'vercel', 'netlify', 'railway', 'render', 'fly-io'],
+};
+
+const OVERLAP_SHARED_TAGS = 3; // pair in same domain sharing ≥ this many tags → "similar ground"
+const HEAVY_DOMAIN_COUNT = 5;  // > this many installed in one (non-floor) domain → "heavy"
+const STALE_DAYS = 14;         // periodic nudge cadence (used by the SessionStart hook)
+
+function domainOf(id) {
+  const d = DOMAINS.find((dom) => dom.ids.includes(id));
+  return d ? d.title : 'Uncategorized';
+}
+
+function subdirs(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name);
+  } catch { return []; }
+}
+
+// Installed in THIS project = whatever has a real base under .rsc/skills/<id>,
+// intersected with the catalog (ignore stray dirs). This is target-agnostic: the
+// shared base is the single source of truth regardless of which assistants link it.
+export function installedProject(cwd, catalogIds) {
+  const set = new Set(catalogIds);
+  return subdirs(join(cwd, '.rsc', 'skills')).filter((id) => set.has(id)).sort();
+}
+
+// Installed on the MACHINE = user-scope Claude skills (~/.claude/skills/<id>),
+// intersected with the catalog. Best-effort; other assistants' user scopes vary.
+export function installedMachine(home, catalogIds) {
+  const set = new Set(catalogIds);
+  return subdirs(join(home, '.claude', 'skills')).filter((id) => set.has(id)).sort();
+}
+
+function findOverlaps(ids, tagsById) {
+  const out = [];
+  const content = ids.filter((id) => !FLOOR_DOMAINS.includes(domainOf(id)));
+  for (let i = 0; i < content.length; i++) {
+    for (let j = i + 1; j < content.length; j++) {
+      const a = content[i];
+      const b = content[j];
+      if (domainOf(a) !== domainOf(b)) continue;
+      const shared = (tagsById[a] || []).filter((t) => (tagsById[b] || []).includes(t));
+      if (shared.length >= OVERLAP_SHARED_TAGS) {
+        out.push({ a, b, domain: domainOf(a), sharedTags: shared });
+      }
+    }
+  }
+  return out;
+}
+
+function findHeavyDomains(ids) {
+  const byDomain = {};
+  for (const id of ids) {
+    const d = domainOf(id);
+    if (FLOOR_DOMAINS.includes(d)) continue;
+    (byDomain[d] ||= []).push(id);
+  }
+  return Object.entries(byDomain)
+    .filter(([, list]) => list.length > HEAVY_DOMAIN_COUNT)
+    .map(([domain, list]) => ({ domain, count: list.length, ids: list.sort() }));
+}
+
+function findNoFootprint(ids, tagsById, detected) {
+  if (!detected.length) return []; // can't judge a non-code / empty repo — stay silent
+  const covered = new Set(detected.flatMap((sig) => STACK_SIBLINGS[sig] || [sig]));
+  const out = [];
+  for (const id of ids) {
+    const dom = domainOf(id);
+    if (!CODE_DOMAINS.includes(dom)) continue;
+    const tags = tagsById[id] || [];
+    const hasFootprint = covered.has(id) || tags.some((t) => covered.has(t));
+    if (!hasFootprint) {
+      out.push({ id, domain: dom, reason: `no detected footprint (repo looks like: ${detected.join(', ')})` });
+    }
+  }
+  return out;
+}
+
+export function audit({
+  cwd = process.cwd(),
+  home = homedir(),
+  manifest = loadManifest(),
+  date = new Date().toISOString().slice(0, 10),
+} = {}) {
+  const catalogIds = manifest.skills.map((s) => s.id);
+  const tagsById = Object.fromEntries(manifest.skills.map((s) => [s.id, s.tags || []]));
+
+  const project = installedProject(cwd, catalogIds);
+  const machine = installedMachine(home, catalogIds);
+  const detected = detectRepo(cwd);
+
+  const overlaps = findOverlaps(project, tagsById);
+  const heavyDomains = findHeavyDomains(project);
+  const noFootprint = findNoFootprint(project, tagsById, detected);
+
+  const byDomain = {};
+  for (const id of project) (byDomain[domainOf(id)] ||= []).push(id);
+
+  const findings = overlaps.length + heavyDomains.length + noFootprint.length;
+  const headline = findings === 0
+    ? `${project.length} skills installed — nothing to flag.`
+    : `${project.length} installed · ${overlaps.length} possible overlap, ${heavyDomains.length} heavy domain(s), ${noFootprint.length} with no footprint.`;
+
+  return {
+    date,
+    project: { root: cwd, installed: project, byDomain },
+    machine: { root: join(home, '.claude', 'skills'), installed: machine },
+    detectedStacks: detected,
+    overlaps,
+    heavyDomains,
+    noFootprint,
+    summary: {
+      projectCount: project.length,
+      machineCount: machine.length,
+      overlapCount: overlaps.length,
+      heavyCount: heavyDomains.length,
+      noFootprintCount: noFootprint.length,
+      clean: findings === 0,
+      headline,
+    },
+  };
+}
+
+export function renderAuditMarkdown(report) {
+  const L = [];
+  L.push(`# Skill audit — ${report.date}`, '');
+  L.push(report.summary.headline, '');
+  L.push(`- Project skills: **${report.summary.projectCount}** (\`${report.project.root}\`)`);
+  L.push(`- Machine skills: **${report.summary.machineCount}** (\`${report.machine.root}\`)`);
+  L.push(`- Detected stacks: ${report.detectedStacks.length ? report.detectedStacks.join(', ') : '(none detected)'}`, '');
+
+  if (report.overlaps.length) {
+    L.push('## Possible overlap (review — not necessarily wrong)', '');
+    for (const o of report.overlaps) {
+      L.push(`- \`${o.a}\` ↔ \`${o.b}\` — same domain *${o.domain}*, share: ${o.sharedTags.join(', ')}`);
+    }
+    L.push('');
+  }
+  if (report.heavyDomains.length) {
+    L.push('## Heavy domains (more than usual for one project)', '');
+    for (const h of report.heavyDomains) {
+      L.push(`- **${h.domain}** — ${h.count} installed: ${h.ids.map((i) => `\`${i}\``).join(', ')}`);
+    }
+    L.push('');
+  }
+  if (report.noFootprint.length) {
+    L.push('## Installed but no footprint detected (verify)', '');
+    for (const n of report.noFootprint) {
+      L.push(`- \`${n.id}\` (${n.domain}) — ${n.reason}`);
+    }
+    L.push('');
+  }
+  if (report.summary.clean) L.push('Nothing to flag. The installed set fits the project.', '');
+
+  L.push('---', `_Advisory only. Trim with \`npx @ericrisco/rsc uninstall <id>\`. Re-run with \`npx @ericrisco/rsc audit\`._`);
+  return L.join('\n') + '\n';
+}
+
+// Persist a stamp the SessionStart hook reads to decide if a periodic audit is due.
+export function stampAudit(cwd, date = new Date().toISOString()) {
+  const dir = join(cwd, '.rsc');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'audit.json'), JSON.stringify({ lastRun: date }, null, 2) + '\n');
+}
+
+// Write the report into the harness wiki when one exists; always stamp .rsc/audit.json.
+export function writeAuditReport(report, cwd = process.cwd()) {
+  const written = [];
+  const wikiHarness = join(cwd, '02-DOCS', 'wiki', 'harness');
+  if (existsSync(join(cwd, '02-DOCS', 'wiki'))) {
+    mkdirSync(wikiHarness, { recursive: true });
+    const file = join(wikiHarness, `skill-audit-${report.date}.md`);
+    writeFileSync(file, renderAuditMarkdown(report));
+    written.push(file);
+  }
+  stampAudit(cwd, `${report.date}T00:00:00.000Z`);
+  return written;
+}
+
+export { STALE_DAYS, ROOT };

package/scripts/install-apply.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { rmSync, existsSync, cpSync, mkdirSync } from 'node:fs';
+import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
@@ -7,11 +7,24 @@ import { targetPaths, writeSkill, wireHook, baseDir } from '../targets/index.js'
 import { readState, writeState } from './lib/state.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CLI_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
 
-// Materialize the real skill files into the project-local base exactly once.
-// Re-installs and other assistants reuse it instead of copying again.
-function ensureBase(id, cwd) {
+// `.rsc/.version` records the CLI version the shared bases (.rsc/skills/) were
+// materialized at — the single, target-agnostic source of truth for "installed
+// skills version" (read by the SessionStart update check too).
+const versionFile = (cwd) => join(cwd, '.rsc', '.version');
+function readBaseVersion(cwd) {
+  try { return readFileSync(versionFile(cwd), 'utf8').trim(); } catch { return undefined; }
+}
+
+// Materialize the real skill files into the project-local base. Normally copied
+// once and reused; when `refresh` is set (a different CLI version than the base was
+// materialized at) the base is re-copied so a reinstall actually updates content.
+// Skills are read-only catalog (user customization lives in 02-DOCS/CLAUDE.md), so
+// overwriting on a version change is safe.
+function ensureBase(id, cwd, refresh) {
   const dest = baseDir(id, cwd);
+  if (refresh && existsSync(dest)) rmSync(dest, { recursive: true, force: true });
   if (!existsSync(dest)) {
     mkdirSync(dirname(dest), { recursive: true });
     cpSync(join(ROOT, 'skills', id), dest, { recursive: true });
@@ -23,16 +36,22 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
   const state = readState(paths.stateFile);
+  // Refresh bases when installing a different version than they were materialized at
+  // (or a pre-versioning install where the marker is absent). Same version → no-op.
+  const refresh = readBaseVersion(cwd) !== CLI_VERSION;
   for (const step of plan) {
     if (step.kind === 'skill') {
-      const base = ensureBase(step.id, cwd);
+      const base = ensureBase(step.id, cwd, refresh);
       const files = await writeSkill(target, step.id, base, step.to);
       state.skills[step.id] = { files, base };
     } else if (step.kind === 'hook') {
-      await wireHook(target, paths, join(ensureBase('suggest', cwd), 'SKILL.md'));
+      await wireHook(target, paths, join(ensureBase('suggest', cwd, refresh), 'SKILL.md'));
     }
   }
+  state.version = CLI_VERSION;
   writeState(paths.stateFile, state);
+  mkdirSync(dirname(versionFile(cwd)), { recursive: true });
+  writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
   return state;
 }
 

package/scripts/rsc.js

@@ -8,6 +8,7 @@ import { applyInstall, listInstalled, uninstall } from './install-apply.js';
 import { doctor } from './doctor.js';
 import { say, select, pickFrom, banner, confirm } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
+import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
 
 const argv = process.argv.slice(2);
@@ -175,6 +176,17 @@ async function main() {
       for (const o of toOutcomes(ids)) say(`${o.id}\t${o.label}`);
       return;
     }
+    case 'audit': {
+      const report = audit();
+      const written = writeAuditReport(report);
+      say(report.summary.headline);
+      for (const o of report.overlaps) say(`  ~ overlap: ${o.a} ↔ ${o.b} (${o.sharedTags.join(', ')})`);
+      for (const h of report.heavyDomains) say(`  ! heavy: ${h.domain} — ${h.count} skills`);
+      for (const n of report.noFootprint) say(`  ? no footprint: ${n.id} (${n.reason})`);
+      if (written.length) say(`\nReport: ${written[0]}`);
+      else say('\n(no harness wiki here — printed above only; run `harness` to keep a written record)');
+      return;
+    }
     case 'list':
       return void say(listInstalled({ target }).join('\n') || '(nothing installed)');
     case 'doctor':
@@ -201,7 +213,7 @@ async function main() {
     }
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | registry refresh | doctor | uninstall <id>');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | uninstall <id>');
   }
 }
 

package/skills/init/SKILL.md

@@ -137,6 +137,29 @@ npx @ericrisco/rsc add <skill> [<skill> ...]
 
 Install only skills their answers justify — same discipline as "no speculative tools". Full skill map, sample printouts per scenario, and the requirements-first decision pattern → `references/recommend-skills.md`.
 
+### Phase 3.5 — GROUND THE PROJECT (git · live docs · skill audit)
+
+Three quick, enforced setup checks once the skills are installed. The SessionStart hook nudges each
+of these too; doing them here means the user starts clean.
+
+1. **Version control is required.** If the workspace has no `.git/`, offer `git init` (recommended —
+   the SDD chain and the ship guard assume git). If the user declines, write an empty `.rsc/.no-git`
+   so the decision is persisted and neither you nor the hook asks again. Log the decision.
+2. **Offer Context7 (live library docs).** For a software project, offer to wire the Context7 MCP
+   once: `claude mcp add --transport http context7 https://mcp.context7.com/mcp`. If they don't want
+   it, write `.rsc/.no-context7`. (It gives version-correct docs instead of guessing from memory.)
+3. **Run a skill audit.** After installing, run `npx @ericrisco/rsc audit`. It inventories the skills
+   installed for this project and on the machine, and flags possible overlap or skills with no
+   footprint here — so the project starts with the right set, not a pile. It re-runs on a cadence via
+   the SessionStart nudge. Summarize the result at the user's accompaniment level.
+4. **Danger guard follows `technical_level`.** When you record `technical_level: non-technical` (or
+   `mixed`, or while no profile exists yet), a `PreToolUse` guard (`.rsc/danger-guard.mjs`) **blocks**
+   irreversible foot-gun commands (`rm -rf`, `git push --force`, `git reset --hard`, `DROP`/`TRUNCATE`,
+   `DELETE`/`UPDATE` with no `WHERE`, `dd` to a device, `curl | bash`, …) and asks for a safer
+   alternative. A fully `technical` user is never guarded. It only turns off if the **user explicitly
+   asks** to allow dangerous commands — then write `.rsc/.no-danger-guard`. Mention this protection
+   exists when you set a non-technical level so the user is not surprised by a block.
+
 ### Phase 4 — HANDOFF
 
 Tell the user to install `harness` (`npx @ericrisco/rsc add harness`) and then run the **`harness`** skill to actually scaffold the `01-TOOLS/` + `02-DOCS/` workspace. `init` stops here — it has set the profile, recorded the discovery, and recommended the skills. `harness` reads the profile and builds the structure.

package/skills/ship/SKILL.md

@@ -81,6 +81,16 @@ git diff main...HEAD | grep -icE 'api[_-]?key|secret|password|token|BEGIN .*PRIV
   | sed 's/^/secret-hits: /'
 ```
 
+### Automated guard (PreToolUse) — you cannot quietly abandon a feature
+
+When rsc is installed for Claude Code, a `PreToolUse` hook (`.rsc/ship-guard.mjs`) enforces this
+phase at the one deterministic moment it matters: it **denies** any Bash command that switches to
+`main`/`master` or merges while the current feature branch has **uncommitted changes** or **commits
+that were never pushed**. The denial reason names the branch and routes you here. The guard is
+local-only (no network), **fail-open** (any ambiguity allows the command), and can be disabled per
+project with `.rsc/.no-ship-guard`. It guarantees the 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 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

@@ -57,7 +57,34 @@ export function wireHook(paths) {
     settings.hooks[event].push({ hooks: [{ type: 'command', command: wlCmd }] });
   }
 
+  // Ship guard: a PreToolUse(Bash) hook that DENIES switching to / merging the trunk
+  // while the current feature branch has uncommitted or unpushed work — forcing the
+  // commit → push → PR close (the `ship` skill). Materialized + node-run (Windows-safe),
+  // registered idempotently, fail-open, opt-out via .rsc/.no-ship-guard. Other
+  // (non-rsc) PreToolUse hooks are preserved.
+  const sgDest = join(paths.projectRoot, '.rsc', 'ship-guard.mjs');
+  copyFileSync(join(HERE, 'ship-guard.mjs'), sgDest);
+  const sgCmd = `node "${sgDest}" "${paths.projectRoot}"`;
+  settings.hooks.PreToolUse ||= [];
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    (e) => !JSON.stringify(e).includes('.rsc/ship-guard.'),
+  );
+  settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: sgCmd }] });
+
+  // Danger guard: a PreToolUse(Bash) hook that DENIES irreversible foot-gun commands
+  // (rm -rf, git push --force, DROP/TRUNCATE, DELETE/UPDATE without WHERE, dd to /dev,
+  // curl|bash, …) when the user-profile says the user is NON-technical (default-safe
+  // when no profile exists yet; never guards a fully `technical` user). Materialized +
+  // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
+  const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
+  copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
+  const dgCmd = `node "${dgDest}" "${paths.projectRoot}"`;
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    (e) => !JSON.stringify(e).includes('.rsc/danger-guard.'),
+  );
+  settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: dgCmd }] });
+
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file, scriptDest, wlDest];
+  return [file, scriptDest, wlDest, sgDest, dgDest];
 }

package/targets/danger-guard.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// rsc Danger guard (claude). Wired by targets/claude.js onto PreToolUse (matcher Bash)
+// as `node ...` so it runs on every platform including Windows.
+//   argv[2] = absolute project root   stdin = PreToolUse hook JSON
+//
+// For a NON-TECHNICAL user (per 02-DOCS/wiki/harness/user-profile.md → technical_level),
+// it DENIES irreversible, foot-gun Bash commands and tells the agent to find a safer,
+// scoped alternative. A fully `technical` user is never guarded. Default-safe: if there
+// is no profile yet, the harness convention is "assume non-technical", so the guard is ON.
+//
+// Disable per project with .rsc/.no-danger-guard — but only when the USER explicitly asks
+// for it (the deny message says so). Fail-open on any internal error (never brick a shell).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.argv[2] || process.cwd();
+
+function allow() { process.exit(0); }
+function deny(why) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `BLOCKED for a non-technical user — this command ${why}. ` +
+        `Do NOT run it: explain the risk in plain language and propose a safer, scoped alternative ` +
+        `(name exact paths, add a WHERE clause, back up first, etc.). ` +
+        `Only if the USER explicitly insists on allowing dangerous commands here, create .rsc/.no-danger-guard to disable this guard.`,
+    },
+  }));
+  process.exit(0);
+}
+
+if (existsSync(join(root, '.rsc', '.no-danger-guard'))) allow();
+
+// technical_level === 'technical' → not guarded. non-technical / mixed / missing → guarded.
+function technicalLevel() {
+  try {
+    const txt = readFileSync(join(root, '02-DOCS', 'wiki', 'harness', 'user-profile.md'), 'utf8');
+    const m = txt.match(/technical_level:\s*([a-z-]+)/i);
+    return m ? m[1].toLowerCase() : null;
+  } catch { return null; }
+}
+if (technicalLevel() === 'technical') allow();
+
+// Only Bash commands can be dangerous here.
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { allow(); }
+if ((input.tool_name || input.toolName) !== 'Bash') allow();
+const cmd = input.tool_input?.command || input.toolInput?.command || '';
+if (typeof cmd !== 'string' || !cmd) allow();
+
+// --- the dangerous-command list ---------------------------------------------
+// High-signal, low-false-positive. Each rule: what it catches and the plain why.
+const noWhere = (verbRe) => verbRe.test(cmd) && !/\bwhere\b/i.test(cmd);
+
+function isRmRecursiveForce() {
+  if (!/\brm\b/.test(cmd)) return false;
+  const hasR = /(-[a-z]*r[a-z]*|--recursive)\b/i.test(cmd);
+  const hasF = /(-[a-z]*f[a-z]*|--force)\b/i.test(cmd);
+  return hasR && hasF; // -rf / -fr / -r -f / --recursive --force
+}
+
+const RULES = [
+  { id: 'rm-rf', why: 'deletes whole files/folders irreversibly (rm with -r and -f)', match: isRmRecursiveForce },
+  { id: 'find-delete', why: 'mass-deletes matched files (find … -delete / -exec rm)', match: () => /\bfind\b[^|;&]*(-delete\b|-exec\s+rm\b)/i.test(cmd) },
+  { id: 'dd-disk', why: 'overwrites a raw disk device and can destroy the whole drive (dd of=/dev/…)', match: () => /\bdd\b[^|;&]*\bof=\/dev\//i.test(cmd) },
+  { id: 'mkfs', why: 'formats a filesystem, erasing everything on it (mkfs)', match: () => /\bmkfs(\.\w+)?\b/i.test(cmd) },
+  { id: 'curl-pipe-shell', why: 'pipes a downloaded script straight into a shell (curl|bash) — runs untrusted code', match: () => /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/i.test(cmd) },
+
+  { id: 'git-push-force', why: 'force-pushes and can overwrite shared history for everyone (git push --force)', match: () => /\bgit\s+push\b[^|;&]*(--force(?!-with-lease)\b|\s-f\b)/i.test(cmd) },
+  { id: 'git-reset-hard', why: 'throws away all uncommitted work with no undo (git reset --hard)', match: () => /\bgit\s+reset\b[^|;&]*--hard\b/i.test(cmd) },
+  { id: 'git-clean', why: 'permanently deletes untracked files (git clean -f)', match: () => /\bgit\s+clean\b[^|;&]*-[a-z]*f/i.test(cmd) },
+  { id: 'git-branch-D', why: 'force-deletes a branch even if its work was never merged (git branch -D)', match: () => /\bgit\s+branch\b[^|;&]*\s-D\b/.test(cmd) },
+
+  { id: 'sql-drop', why: 'drops an entire database/schema/table (DROP …)', match: () => /\bdrop\s+(database|schema|table)\b/i.test(cmd) },
+  { id: 'sql-truncate', why: 'empties an entire table (TRUNCATE)', match: () => /\btruncate\s+(table\s+)?\S/i.test(cmd) },
+  { id: 'sql-delete-no-where', why: 'deletes EVERY row — a DELETE with no WHERE clause', match: () => noWhere(/\bdelete\s+from\s+\S/i) },
+  { id: 'sql-update-no-where', why: 'rewrites EVERY row — an UPDATE with no WHERE clause', match: () => noWhere(/\bupdate\s+\S+\s+set\b/i) },
+  { id: 'mongo-wipe', why: 'drops a collection/database or deletes all documents (drop()/dropDatabase/deleteMany({}))', match: () => /\.drop\(\s*\)|dropdatabase\s*\(|deletemany\(\s*\{\s*\}\s*\)|\.remove\(\s*\{\s*\}\s*\)/i.test(cmd) },
+];
+
+for (const rule of RULES) {
+  try { if (rule.match()) deny(rule.why); } catch { /* a rule erroring must never block */ }
+}
+
+allow();

package/targets/session-start.mjs

@@ -8,13 +8,34 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+const STALE_AUDIT_DAYS = 14; // periodic skill-audit cadence (kept in sync with scripts/audit.js)
+
 const suggestMd = process.argv[2];
 const root = process.argv[3] || process.cwd();
 
+const has = (...p) => existsSync(join(root, ...p));
+
+// Is a Context7 MCP server configured for this project (.mcp.json → mcpServers.context7)?
+function hasContext7() {
+  try {
+    const mcp = JSON.parse(readFileSync(join(root, '.mcp.json'), 'utf8'));
+    return Boolean(mcp.mcpServers && mcp.mcpServers.context7);
+  } catch { return false; }
+}
+
+// Has a skill audit run within the cadence? Missing stamp → never audited → due.
+function auditDue() {
+  try {
+    const { lastRun } = JSON.parse(readFileSync(join(root, '.rsc', 'audit.json'), 'utf8'));
+    return (Date.now() - new Date(lastRun).getTime()) / 86400000 >= STALE_AUDIT_DAYS;
+  } catch { return true; }
+}
+
 try { process.stdout.write(readFileSync(suggestMd, 'utf8')); } catch { /* missing → emit nothing */ }
 
 const profile = join(root, '02-DOCS', 'wiki', 'harness', 'user-profile.md');
 const optout = join(root, '.rsc', '.no-harness');
+const profileExists = existsSync(profile);
 if (!existsSync(profile) && !existsSync(optout)) {
   process.stdout.write(`
 ===== rsc onboarding =====
@@ -47,3 +68,79 @@ Originals are copied, never moved; deleting an emptied folder needs explicit con
 `);
   }
 }
+
+// Git required: version control is the substrate the SDD chain + ship guard assume.
+// If the project is not under git, push for it once per session. Persist the user's
+// "no" as .rsc/.no-git so the decision lives in a file and we stop re-asking.
+if (!has('.git') && !has('.rsc', '.no-git')) {
+  process.stdout.write(`
+===== rsc git required =====
+This project is NOT under version control (no .git/).
+The SDD flow and the ship guard assume git. ACTION: offer to run \`git init\` now
+(recommended). If the user declines, create .rsc/.no-git so I stop asking.
+============================
+`);
+}
+
+// Context7 MCP: only for active rsc projects (a profile exists). If the live-docs MCP
+// isn't wired, nudge to add it once. Opt out per project with .rsc/.no-context7.
+if (profileExists && !hasContext7() && !has('.rsc', '.no-context7')) {
+  process.stdout.write(`
+===== rsc context7 MCP =====
+Context7 (live, version-correct library docs) is not configured for this project.
+ACTION: install it once — \`claude mcp add --transport http context7 https://mcp.context7.com/mcp\`
+then reload the session. If you don't want it here: create .rsc/.no-context7.
+============================
+`);
+}
+
+// Periodic skill audit: for active rsc projects, nudge to re-audit when the last run
+// is stale (or never ran). Running \`rsc audit\` stamps .rsc/audit.json and silences
+// this for the cadence. Opt out with .rsc/.no-audit.
+if (profileExists && auditDue() && !has('.rsc', '.no-audit')) {
+  process.stdout.write(`
+===== rsc skill audit =====
+A skill audit is due (runs at most every ${STALE_AUDIT_DAYS} days). It flags overlapping
+skills and skills with no footprint in this project.
+ACTION: run \`npx @ericrisco/rsc audit\`. Opt out with .rsc/.no-audit.
+===========================
+`);
+}
+
+// Update check: compare the installed version (.rsc/.version, written at install)
+// against the latest published on npm, and nudge the agent to offer an update.
+// Fail-silent (offline / missing baseline / parse error → nothing). Disable with
+// RSC_NO_UPDATE_CHECK=1. RSC_LATEST overrides the npm lookup (tests / mirrors).
+function isNewer(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+if (!process.env.RSC_NO_UPDATE_CHECK) {
+  try {
+    const installed = readFileSync(join(root, '.rsc', '.version'), 'utf8').trim();
+    let latest = process.env.RSC_LATEST;
+    if (!latest) {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 1500);
+      const res = await fetch('https://registry.npmjs.org/@ericrisco%2frsc/latest', { signal: ctrl.signal });
+      clearTimeout(timer);
+      latest = (await res.json()).version;
+    }
+    if (installed && latest && isNewer(latest, installed)) {
+      process.stdout.write(`
+===== rsc update available =====
+rsc ${latest} is out — you have ${installed}.
+ACTION: tell the user a new version is available and, if they say yes, run:
+  npx @ericrisco/rsc@latest
+(That reinstalls and refreshes the skill content to the latest.)
+================================
+`);
+    }
+  } catch { /* offline / no baseline / parse error → stay silent */ }
+}

package/targets/ship-guard.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// rsc Ship guard (claude). Wired by targets/claude.js onto PreToolUse (matcher Bash)
+// as `node ...` so it runs on every platform including Windows.
+//   argv[2] = absolute project root   stdin = PreToolUse hook JSON
+//
+// Enforces the "close the feature before you leave it" rule at the one deterministic
+// moment it matters: when a Bash command tries to switch to the trunk (main/master)
+// or merge into it. If the current feature branch has uncommitted changes or commits
+// that were never pushed, the guard DENIES the command and tells the agent to run
+// `ship` (commit → push → PR). Opening the PR itself is `ship`'s job and the skill's
+// hard rule; this hook guarantees you cannot quietly abandon unsaved/unpushed work.
+//
+// Design: precise (only fires on a trunk switch/merge), local-only (no network, no gh),
+// and FAIL-OPEN — any ambiguity (detached HEAD, no repo, git error) allows the command.
+// Opt out per project with .rsc/.no-ship-guard.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const root = process.argv[2] || process.cwd();
+
+function allow() { process.exit(0); }
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: 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();
+if (!existsSync(join(root, '.git'))) allow();
+
+// Read the tool call. Only Bash commands can move branches.
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { allow(); }
+if ((input.tool_name || input.toolName) !== 'Bash') allow();
+const command = input.tool_input?.command || input.toolInput?.command || '';
+if (typeof command !== 'string' || !command) 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/;
+if (!TRUNK.test(command) && !MERGE.test(command)) allow();
+
+const git = (...args) => {
+  const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+};
+
+const branch = git('rev-parse', '--abbrev-ref', 'HEAD');
+// Not on a feature branch (already trunk, detached, or git failed) → nothing to guard.
+if (!branch || branch === 'HEAD' || branch === 'main' || branch === 'master') allow();
+
+const tail = '\n(If this is intentional and you accept the risk, create .rsc/.no-ship-guard to disable this guard.)';
+
+// 1) Uncommitted work would be carried off the feature branch.
+const dirty = git('status', '--porcelain');
+if (dirty && dirty.length > 0) {
+  deny(`You're leaving feature branch "${branch}" with uncommitted changes. Commit them first — run the \`ship\` skill (commit → push → PR), don't abandon the diff.${tail}`);
+}
+
+// 2) Commits exist but were never pushed.
+const upstream = git('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}');
+if (upstream) {
+  const ahead = git('rev-list', '--count', `${upstream}..HEAD`);
+  if (ahead && Number(ahead) > 0) {
+    deny(`Feature branch "${branch}" has ${ahead} commit(s) not pushed to ${upstream}. Push them and open the PR — run the \`ship\` skill — before switching to the trunk.${tail}`);
+  }
+} else {
+  // No upstream at all: if the branch carries commits beyond the trunk, it was never pushed.
+  const aheadOfTrunk = git('rev-list', '--count', 'main..HEAD') ?? git('rev-list', '--count', 'master..HEAD');
+  if (aheadOfTrunk && Number(aheadOfTrunk) > 0) {
+    deny(`Feature branch "${branch}" was never pushed (no upstream, ${aheadOfTrunk} commit(s) ahead of the trunk). Push it and open a PR — run the \`ship\` skill — before leaving it.${tail}`);
+  }
+}
+
+allow();