@damiangilgonzalez/harness 1.3.7

package/targets/session-start.mjs

@@ -0,0 +1,279 @@
+#!/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, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { claimOnce, readHookInput } from './hook-once.mjs';
+
+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();
+
+// When rsc is wired in more than one scope (user + project), every scope runs this script and the
+// always-on body lands once per scope. Both invocations share Claude Code's session_id, so the
+// first one to claim the event emits and the rest stay silent. `source` is part of the key so a
+// later compaction — which reuses the session_id — still re-injects, as it must.
+// No session id (no stdin / older Claude Code) → claimOnce fails open and we emit as before.
+const hook = readHookInput();
+const emitBody = hook.session_id
+  ? claimOnce(`ss:${hook.session_id}:${hook.source || 'startup'}`)
+  : true;
+
+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; }
+}
+
+if (emitBody) {
+  try { process.stdout.write(readFileSync(suggestMd, 'utf8')); } catch { /* missing → emit nothing */ }
+}
+
+// De-dup above only works when EVERY wired scope runs an updated hook. A scope left behind keeps
+// emitting its own copy and cannot be silenced from here, so the only honest move is to say which
+// scope is lagging and how to fix it. Cadence-limited (this is advice, not an alarm) and opt-out-able.
+const SCOPE_WARN_DAYS = 7;
+
+function versionAt(scopeRoot) {
+  try { return readFileSync(join(scopeRoot, '.rsc', '.version'), 'utf8').trim() || null; } catch { return null; }
+}
+
+function isWiredScope(scopeRoot) {
+  // settings.json stores the wired command with the separator the installing platform produced, and
+  // JSON escapes a Windows backslash as a pair. Looking only for `.rsc/` therefore answered "not
+  // wired" for every Windows scope — which made THIS detector, the one that warns about a duplicated
+  // always-on body, blind on the exact platform where the body was being injected four times.
+  //
+  // Normalized inline rather than imported: hooks are materialized file by file, so this script can
+  // only import a sibling in `.rsc/`. `targets/claude.js` (hookWiringOf) and `scripts/doctor.js`
+  // carry the same one-liner for the same reason; the duplication is the price of the hook layout.
+  try {
+    const raw = readFileSync(join(scopeRoot, '.claude', 'settings.json'), 'utf8');
+    return raw.replace(/\\\\/g, '/').includes('.rsc/');
+  } catch { return false; }
+}
+
+function olderThan(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;
+}
+
+function scopeWarnDue() {
+  try {
+    const { lastRun } = JSON.parse(readFileSync(join(root, '.rsc', 'dup-scope.json'), 'utf8'));
+    return (Date.now() - new Date(lastRun).getTime()) / 86400000 >= SCOPE_WARN_DAYS;
+  } catch { return true; }
+}
+
+if (!has('.rsc', '.no-scope-check') && scopeWarnDue()) {
+  // The complementary scope: from a project root it is the user's home, and vice versa.
+  const home = homedir();
+  const other = resolve(root) === resolve(home) ? (hook.cwd && resolve(hook.cwd) !== resolve(home) ? hook.cwd : null) : home;
+  const mine = versionAt(root);
+  const theirs = other ? versionAt(other) : null;
+  // Both versions must be readable to make a claim; an unreadable scope is not evidence of a problem.
+  if (other && mine && theirs && isWiredScope(other) && olderThan(theirs, mine)) {
+    process.stdout.write(`
+===== rsc duplicate rsc scope =====
+rsc is wired in TWO scopes and one is out of date, so this session receives the always-on
+block and the SDD gate TWICE — once per scope. Only the updated scope can de-duplicate.
+  this scope:    ${root} (${mine})
+  lagging scope: ${other} (${theirs})
+ACTION: update the lagging scope, then it will stay silent on its own:
+  cd "${other}" && npx @damiangilgonzalez/harness@latest
+Opt out with .rsc/.no-scope-check · this notice repeats at most every ${SCOPE_WARN_DAYS} days.
+===================================
+`);
+    try {
+      mkdirSync(join(root, '.rsc'), { recursive: true });
+      writeFileSync(join(root, '.rsc', 'dup-scope.json'), JSON.stringify({ lastRun: new Date().toISOString() }) + '\n');
+    } catch { /* unwritable → the notice simply repeats next session */ }
+  }
+}
+
+const profile = join(root, '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: 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, 'docs', 'inbox');
+if (existsSync(join(root, '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 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 @damiangilgonzalez/harness audit\`. Opt out with .rsc/.no-audit.
+===========================
+`);
+}
+
+// CLAUDE.md hygiene: the root CLAUDE.md is read on EVERY turn, so an overgrown one (usually
+// the Knowledge map accreting a row per wiki article) is a permanent context tax that rots
+// adherence. When it passes the ~200-line 2026 budget, nudge to offload the index into
+// docs/wiki/index.md and keep CLAUDE.md a short pointer (the `harness` skill owns the move;
+// it's a relocation, not a delete). Opt out with .rsc/.no-claudemd-check.
+const CLAUDEMD_MAX_LINES = 200;
+if (!has('.rsc', '.no-claudemd-check')) {
+  try {
+    const lines = readFileSync(join(root, 'CLAUDE.md'), 'utf8').split('\n').length;
+    if (lines > CLAUDEMD_MAX_LINES) {
+      process.stdout.write(`
+===== rsc CLAUDE.md hygiene =====
+CLAUDE.md is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (it's read every turn, so each line costs context).
+ACTION: offload the Knowledge map / overgrown sections into docs/wiki/index.md and leave a short
+pointer in CLAUDE.md (no info lost — it's a move). The \`harness\` skill owns the procedure.
+Opt out with .rsc/.no-claudemd-check.
+=================================
+`);
+    }
+  } catch { /* no CLAUDE.md → nothing to check */ }
+}
+
+// Worktree sweep: a worktree whose work already reached the trunk is landed work wearing the same
+// clothes as live work, and the list stops being readable once a couple of them pile up. `ship`
+// retires the one it just landed; this is for the merge that happened somewhere else — a pull request
+// accepted in the forge, a merge by hand, a session that ended before ship. It only ever NAMES them:
+// at session start the user has asked for nothing, and acting on disk before they say a word is how a
+// safeguard earns itself an opt-out. Silent when there is nothing to say. Off with .rsc/.no-worktree-cleanup.
+if (has('.git')) {
+  try {
+    // No opt-out check here: `classifyWorktrees` returns nothing when the project turned the cleanup
+    // off, so a second check could never fail and would only look like protection (P2). Test 36 holds
+    // the behaviour end to end, through this hook.
+    const W = await import('./worktree-reaper.mjs');
+    {
+      const candidates = W.classifyWorktrees(root).filter((c) => c.verdict !== 'skip');
+      if (candidates.length) {
+        process.stdout.write(`
+===== rsc worktree cleanup =====
+${candidates.length} worktree(s) hold work that is already in the trunk:
+${candidates.map((c) => W.summarize(c, root)).join('\n')}
+ACTION: offer to retire them in ONE line and wait for a yes. On a yes run:
+  npx @damiangilgonzalez/harness worktrees reap          (the ones marked safe)
+  npx @damiangilgonzalez/harness worktrees reap <path>   (one the user confirmed by name)
+A yes in bulk covers only the safe ones; anything marked \`ask\` is confirmed on its own.
+A no holds for this session. Permanent off: .rsc/.no-worktree-cleanup
+================================
+`);
+      }
+    }
+  } catch { /* reaper missing or git unhappy → say nothing; this is never worth breaking startup for */ }
+}
+
+// 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/@damiangilgonzalez%2fharness/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 @damiangilgonzalez/harness@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,101 @@
+#!/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);
+}
+
+// "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.
+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();
+
+// ---- 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/;
+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/userprompt-gate.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// rsc UserPromptSubmit payload (claude). Re-injects the SDD new-feature gate as the
+// MOST-RECENT instruction on every user turn. The SessionStart hook already injects the
+// full gate (the `suggest` body) once per session, but in a long session — or one with
+// many installed skills whose descriptions crowd the context — that single injection can
+// lose salience and a strongly-matched stack/builder skill can pull the model straight to
+// code. This keeps the precedence rule in front of the model every turn, so the gate is
+// independent of skill count and session length. Stdout is added to context for
+// UserPromptSubmit, so a plain print is enough (no JSON needed).
+//
+// Invoked as `node userprompt-gate.mjs <projectRoot>` (not bash) so it runs on Windows too.
+//   argv[2] = absolute project root
+// Fail-open (never blocks a turn). Opt out per project with .rsc/.no-feature-gate.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { claimOnce, readHookInput, WORKFLOW_GATE_TEXT } from './hook-once.mjs';
+
+const root = process.argv[2] || process.cwd();
+
+// Opt-out: a project that does not want the always-on gate drops this marker file.
+if (existsSync(join(root, '.rsc', '.no-feature-gate'))) process.exit(0);
+
+// rsc wired in both user and project scope runs this once per scope, so the gate lands twice on
+// every turn. `prompt_id` is unique per turn and identical across scopes, which makes the dedup
+// exact — no time heuristic needed. Older Claude Code has no prompt_id: fall back to the prompt
+// text, and if there is nothing to key on at all, emit (a duplicated gate beats a missing one).
+const hook = readHookInput();
+const turnKey = hook.prompt_id || (hook.prompt ? `p${hook.prompt.length}:${hook.prompt.slice(0, 64)}` : null);
+if (hook.session_id && turnKey && !claimOnce(`up:${hook.session_id}:${turnKey}`)) process.exit(0);
+
+process.stdout.write(WORKFLOW_GATE_TEXT);

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
+// 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, '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 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 docs/wiki/harness/decisions.md.
+Skip entirely if this was a pure read/answer turn with no changes.
+==================================
+`);