@ericrisco/rsc 0.1.16 → 0.1.18

package/README.md

@@ -273,7 +273,7 @@ duplicated. The wizard asks which ones; `--target a,b` does it non-interactively
 
 | Target | Skill destination (→ `.rsc/skills/<id>/`) | Always-on detector |
 | --- | --- | --- |
-| `claude` | `.claude/skills/rsc/<id>/` → symlink | SessionStart hook in `.claude/settings.json` |
+| `claude` | `.claude/skills/<id>/` → symlink (copy on Windows) | SessionStart hook in `.claude/settings.json` |
 | `codex` | `.codex/rsc/<id>/` → symlink | block in `AGENTS.md` |
 | `copilot` | `.github/rsc/<id>/` → symlink | block in `.github/copilot-instructions.md` |
 | `cursor` | `.cursor/rules/<id>.mdc` (converted) | always-apply rule |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.16",
+  "version": "0.1.18",
   "counts": {
     "skills": 231
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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/author-skill/references/rsc-conventions.md

@@ -49,10 +49,14 @@ profiles: [core, full]           # optional: named-profile membership
 
 ## Invocation
 
-There are no bundles and no `/<bundle>:<id>` namespacing. A skill installs under
-the target's rsc namespace (e.g. `~/.claude/skills/rsc/<id>/`) and is invoked by
-its `name`. The `suggest` detector is always installed (the floor) and proposes
-installing any skill a task needs via `npx @ericrisco/rsc add <id>`.
+There are no bundles and no `/<bundle>:<id>` namespacing. Most targets install a
+skill under their own rsc folder (e.g. `.codex/rsc/<id>/`), reached from that
+assistant's instructions file. **Claude is the exception:** Claude Code only
+discovers project skills one level under `.claude/skills/`, so rsc skills install
+**flat** at `.claude/skills/<id>/SKILL.md` (a nested `.claude/skills/rsc/<id>/`
+is never discovered). A skill is invoked by its `name`. The `suggest` detector is
+always installed (the floor) and proposes installing any skill a task needs via
+`npx @ericrisco/rsc add <id>`.
 
 ## Wiring steps for a new skill
 

package/skills/harness/references/wiki-protocol.md

@@ -388,7 +388,8 @@ generalizes the SDD session-summary convention to *any* work.
 
 - **Hook — `PreCompact` / `SessionEnd`** (Claude Code): fires right before context
   is lost or the session ends. The hook only *reminds*; the agent writes the
-  worklog (Karpathy: the LLM writes). Wired by `targets/` → `.rsc/worklog-checkpoint.sh`.
+  worklog (Karpathy: the LLM writes). Wired by `targets/` → `.rsc/worklog-checkpoint.mjs`
+  (run via `node`, so it works on Windows too).
 - **Explicit milestone**: after a commit or a shipped feature, capture a worklog.
 - **Daily curation automation**: distills any pending worklog raw on a timer (see
   Continuous Improvement and `daily-curation-automation.md`).

package/skills/init/SKILL.md

@@ -137,6 +137,22 @@ 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.
+
 ### 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

@@ -1,27 +1,34 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, chmodSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkOrCopy } from './index.js';
 
+const HERE = dirname(fileURLToPath(import.meta.url));
+
 export function writeSkill(id, fromDir, toPath) {
+  // Migrate away from the legacy nested layout (.claude/skills/rsc/<id>) that
+  // Claude Code never discovered — it only reads .claude/skills/<name>/SKILL.md.
+  // toPath is now .claude/skills/<id>; drop the stale rsc/ sibling if present.
+  const legacy = join(dirname(toPath), 'rsc');
+  if (existsSync(legacy)) rmSync(legacy, { recursive: true, force: true });
   return linkOrCopy(fromDir, toPath);
 }
 
-// SessionStart runs a project-local session-start.sh: it cats suggest's always-on
-// body (preserving prior behavior) and appends an onboarding banner when the
-// workspace has no harness profile yet. We materialize the script next to the
-// shared base and point the hook at it. Any prior rsc SessionStart entry (the old
-// `cat …/suggest/SKILL.md` form or a previous script form) is dropped before we
-// add the current one — idempotent, and it migrates legacy hooks in place. Other
-// (non-rsc) SessionStart hooks are preserved.
+// SessionStart runs a project-local session-start.mjs via `node`: it prints
+// suggest's always-on body, an onboarding banner when the workspace has no harness
+// profile yet, and an auto-ingest nudge when the inbox has un-ingested material. We
+// invoke with `node` (not bash) so the hook runs on Windows too. We materialize the
+// script next to the shared base and point the hook at it. Any prior rsc SessionStart
+// entry (the old `cat …/suggest/SKILL.md` form, or a previous `.sh`/`.mjs` script
+// form) is dropped before we add the current one — idempotent, migrating legacy and
+// bash-era hooks in place. Other (non-rsc) SessionStart hooks are preserved.
 export function wireHook(paths) {
-  const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.sh');
+  const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
-  copyFileSync(join(dirname(fileURLToPath(import.meta.url)), 'session-start.sh'), scriptDest);
-  chmodSync(scriptDest, 0o755);
+  copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
   const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;
-  const cmd = `bash "${scriptDest}" "${suggestMd}" "${paths.projectRoot}"`;
+  const cmd = `node "${scriptDest}" "${suggestMd}" "${paths.projectRoot}"`;
 
   const file = paths.hookTarget;
   const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
@@ -29,28 +36,42 @@ export function wireHook(paths) {
   settings.hooks.SessionStart ||= [];
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter((e) => {
     const s = JSON.stringify(e);
-    return !s.includes('skills/rsc/suggest') && !s.includes('.rsc/session-start.sh');
+    // drop legacy cat-form and any prior session-start script (.sh from the bash era, or .mjs)
+    return !s.includes('skills/rsc/suggest') && !s.includes('.rsc/session-start.');
   });
   settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: cmd }] });
 
   // Worklog checkpoint: PreCompact + SessionEnd run a project-local
-  // worklog-checkpoint.sh that reminds the agent to capture what we did this
-  // session into 02-DOCS/raw/worklog/ (the work-driven on-ramp). Silent when the
-  // workspace has no harness wiki. Registered idempotently on both events, with
-  // any prior rsc worklog-checkpoint entry dropped first.
-  const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.sh');
-  copyFileSync(join(dirname(fileURLToPath(import.meta.url)), 'worklog-checkpoint.sh'), wlDest);
-  chmodSync(wlDest, 0o755);
-  const wlCmd = `bash "${wlDest}" "${paths.projectRoot}"`;
+  // worklog-checkpoint.mjs via `node` that reminds the agent to capture what we did
+  // this session into 02-DOCS/raw/worklog/ (the work-driven on-ramp). Silent when
+  // the workspace has no harness wiki. Registered idempotently on both events, with
+  // any prior rsc worklog-checkpoint entry (.sh or .mjs) dropped first.
+  const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.mjs');
+  copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
+  const wlCmd = `node "${wlDest}" "${paths.projectRoot}"`;
   for (const event of ['PreCompact', 'SessionEnd']) {
     settings.hooks[event] ||= [];
     settings.hooks[event] = settings.hooks[event].filter(
-      (e) => !JSON.stringify(e).includes('.rsc/worklog-checkpoint.sh'),
+      (e) => !JSON.stringify(e).includes('.rsc/worklog-checkpoint.'),
     );
     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 }] });
+
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file, scriptDest, wlDest];
+  return [file, scriptDest, wlDest, sgDest];
 }

package/targets/index.js

@@ -11,16 +11,22 @@ export function baseDir(id, cwd = process.cwd()) {
   return join(cwd, '.rsc', 'skills', id);
 }
 
-// Point an assistant's skill folder at the shared base via a relative symlink.
-// Falls back to a real copy when the filesystem rejects symlinks (e.g. Windows
-// without privileges). Idempotent: replaces any existing link/dir at toPath.
+// Point an assistant's skill folder at the shared base. On macOS/Linux a relative
+// symlink avoids duplication. On Windows we copy real files: relative `dir`
+// symlinks require Developer Mode/admin and are not reliably followed by skill
+// discovery, so correctness wins over de-duplication. Idempotent: replaces any
+// existing link/dir at toPath.
 export function linkOrCopy(fromDir, toPath) {
   mkdirSync(dirname(toPath), { recursive: true });
   try { lstatSync(toPath); rmSync(toPath, { recursive: true, force: true }); } catch { /* nothing there */ }
-  try {
-    symlinkSync(relative(dirname(toPath), fromDir), toPath, 'dir');
-  } catch {
+  if (process.platform === 'win32') {
     cpSync(fromDir, toPath, { recursive: true });
+  } else {
+    try {
+      symlinkSync(relative(dirname(toPath), fromDir), toPath, 'dir');
+    } catch {
+      cpSync(fromDir, toPath, { recursive: true });
+    }
   }
   return [toPath];
 }
@@ -31,7 +37,7 @@ export function linkOrCopy(fromDir, toPath) {
 // is a single converted file, not a linked directory.
 const SPEC = {
   // JSON-hook + linked skill dirs
-  claude: { root: '.claude/skills/rsc', hook: '.claude/settings.json', adapter: 'claude' },
+  claude: { root: '.claude/skills', hook: '.claude/settings.json', adapter: 'claude' },
   // Converted .mdc rules
   cursor: { root: '.cursor/rules', hook: '.cursor/rules/rsc-suggest.mdc', adapter: 'cursor', skillExt: '.mdc' },
   // AGENTS.md family — all read the same root AGENTS.md

package/targets/session-start.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// rsc SessionStart payload (claude). Wired by targets/claude.js as `node ...` so
+// it runs on every platform including Windows (no bash dependency).
+//   argv[2] = absolute path to suggest's SKILL.md   argv[3] = absolute project root
+// Always emits suggest's always-on body; appends an onboarding banner when the
+// workspace has no harness profile yet, and an auto-ingest nudge when there is
+// un-ingested material waiting in the inbox.
+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 =====
+Fresh setup: 02-DOCS/wiki/harness/user-profile.md is missing.
+ACTION: invoke \`init\` now (first contact: technical level + accompaniment dial) before the task.
+If the user does not want a harness here: create .rsc/.no-harness
+==========================
+`);
+}
+
+// Auto-Ingest nudge: when a harness wiki exists and the inbox holds a real file
+// (anything other than README.md / dotfiles / the _processed archive), tell the
+// agent to run the Auto-Ingest Sweep. The hook only reminds; the agent does the
+// scan + ingest. Cheap signal here; the thorough workspace scan lives in the sweep.
+const inbox = join(root, '02-DOCS', 'inbox');
+if (existsSync(join(root, '02-DOCS', 'wiki')) && existsSync(inbox)) {
+  let pending = false;
+  try {
+    pending = readdirSync(inbox, { withFileTypes: true })
+      .some((e) => e.isFile() && e.name !== 'README.md' && !e.name.startsWith('.'));
+  } catch { /* unreadable → no nudge */ }
+  if (pending) {
+    process.stdout.write(`
+===== rsc auto-ingest =====
+Un-ingested material is waiting in 02-DOCS/inbox/.
+ACTION: run the Auto-Ingest Sweep now — ingest inbox/, then scan the workspace
+(minus .rscignore) for un-ingested documents, recording them in wiki/.ingested.json.
+Originals are copied, never moved; deleting an emptied folder needs explicit consent.
+===========================
+`);
+  }
+}
+
+// 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();

package/targets/worklog-checkpoint.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// rsc Worklog checkpoint (claude). Wired by targets/claude.js onto PreCompact and
+// SessionEnd as `node ...` so it runs on every platform including Windows.
+//   argv[2] = absolute project root
+// Reminds the agent to run a Worklog Sweep (capture what we did this session into
+// 02-DOCS/raw/worklog/). The hook only reminds; the agent writes the worklog.
+// Silent when this workspace has no harness wiki yet.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.argv[2] || process.cwd();
+
+// No harness wiki here → nothing to document into. Stay silent.
+if (!existsSync(join(root, '02-DOCS', 'wiki'))) process.exit(0);
+
+process.stdout.write(`
+===== rsc worklog checkpoint =====
+If this session did meaningful work (files changed, a decision made, a commit),
+run a WORKLOG SWEEP before context is lost:
+  1. Write 02-DOCS/raw/worklog/<YYYY-MM-DD>-<slug>.md using the harness
+     wiki-worklog-template.md (what we did · why · files touched · outcome · next).
+  2. Compile it into wiki/ (update existing articles first; wikilinks + Related);
+     append significant decisions to 02-DOCS/wiki/harness/decisions.md.
+Skip entirely if this was a pure read/answer turn with no changes.
+==================================
+`);

package/targets/session-start.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-# rsc SessionStart payload (claude). Wired by targets/claude.js.
-#   $1 = absolute path to suggest's SKILL.md   $2 = absolute project root
-# Always emits suggest's always-on body; appends an onboarding banner when the
-# workspace has no harness profile yet, and an auto-ingest nudge when there is
-# un-ingested material waiting in the inbox.
-set -u
-
-cat "$1" 2>/dev/null
-
-profile="$2/02-DOCS/wiki/harness/user-profile.md"
-optout="$2/.rsc/.no-harness"
-
-if [ ! -f "$profile" ] && [ ! -f "$optout" ]; then
-  cat <<'BANNER'
-
-===== rsc onboarding =====
-Fresh setup: 02-DOCS/wiki/harness/user-profile.md is missing.
-ACTION: invoke `init` now (first contact: technical level + accompaniment dial) before the task.
-If the user does not want a harness here: create .rsc/.no-harness
-==========================
-BANNER
-fi
-
-# Auto-Ingest nudge: when a harness wiki exists and the inbox holds a real file
-# (anything other than README.md / dotfiles / the _processed archive), tell the
-# agent to run the Auto-Ingest Sweep. The hook only reminds; the agent does the
-# scan + ingest. Cheap signal here; the thorough workspace scan lives in the sweep.
-inbox="$2/02-DOCS/inbox"
-if [ -d "$2/02-DOCS/wiki" ] && [ -d "$inbox" ]; then
-  pending=$(find "$inbox" -maxdepth 1 -type f ! -name 'README.md' ! -name '.*' 2>/dev/null | head -1)
-  if [ -n "$pending" ]; then
-    cat <<'BANNER'
-
-===== rsc auto-ingest =====
-Un-ingested material is waiting in 02-DOCS/inbox/.
-ACTION: run the Auto-Ingest Sweep now — ingest inbox/, then scan the workspace
-(minus .rscignore) for un-ingested documents, recording them in wiki/.ingested.json.
-Originals are copied, never moved; deleting an emptied folder needs explicit consent.
-===========================
-BANNER
-  fi
-fi

package/targets/worklog-checkpoint.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-# rsc Worklog checkpoint payload (claude). Wired by targets/claude.js onto the
-# PreCompact and SessionEnd hooks.
-#   $1 = absolute project root
-# Reminds the agent to run a Worklog Sweep (capture what we did this session into
-# 02-DOCS/raw/worklog/ so the harness can compile it into the wiki). The hook only
-# REMINDS — the agent writes the worklog (Karpathy: the LLM writes the wiki).
-# Silent when this workspace has no harness wiki yet (nothing to document into).
-set -u
-
-root="${1:-$PWD}"
-
-# No harness wiki here → nothing to do. Stay silent.
-[ -d "$root/02-DOCS/wiki" ] || exit 0
-
-cat <<'BANNER'
-
-===== rsc worklog checkpoint =====
-If this session did meaningful work (files changed, a decision made, a commit),
-run a WORKLOG SWEEP before context is lost:
-  1. Write 02-DOCS/raw/worklog/<YYYY-MM-DD>-<slug>.md using the harness
-     wiki-worklog-template.md (what we did · why · files touched · outcome · next).
-  2. Compile it into wiki/ (update existing articles first; wikilinks + Related);
-     append significant decisions to 02-DOCS/wiki/harness/decisions.md.
-Skip entirely if this was a pure read/answer turn with no changes.
-==================================
-BANNER