@damiangilgonzalez/harness 1.3.12 → 1.3.14

package/README.md

@@ -73,6 +73,9 @@ accompaniment, project kind and goal **before it writes anything**, reads only t
 root, and shows every selected or deferred skill, agent and hook with its reason. Relay those
 questions to the user; never invent or default their answers. The first pass writes nothing and
 prints a SHA-256 plan id. Only rerun with `--accept-plan <id>` after the user accepts that exact plan.
+If the project already has a skill of its own with a catalog name, the plan lists it under
+**Your own skills this plan replaces** — tell the user before accepting; renaming their folder and
+regenerating the plan keeps theirs.
 
 For a non-interactive agent, collect the answers and preview the same plan explicitly:
 
@@ -247,7 +250,7 @@ rsc consult "I want to launch a SaaS"  # recommend only, no install
 rsc registry refresh                 # write .rsc/skill-registry.{json,md}
 rsc list                             # installed skills, agents and commands
 rsc capabilities                    # installed/available surfaces + memory mode
-rsc doctor                           # health, missing backing, hooks and local memory
+rsc doctor                           # health, missing backing, hooks and local memory; exits 1 when unhealthy
 rsc memory status                    # full / assisted / unsupported / degraded
 rsc memory save --session handoff    # force a deterministic local checkpoint
 rsc memory resume                    # print this branch/worktree continuation
@@ -284,23 +287,43 @@ The harness travels by git, but not all of it — and the split is the point.
 | `docs/raw/worklog/.rsc-memory/` | Preferred session journal when a local wiki exists; protected with git's local exclude |
 | The skill entries rsc manages | Symlinks on macOS/Linux, real copies on Windows — two incompatible shapes of one thing |
 
-Whoever clones runs **one command** and ends up with the same harness:
+Three files carry the harness through git: `.rsc.json` (what the team decided),
+`.claude/settings.json` (the wiring), and `.claude/rsc-bootstrap.mjs` — the small file that
+notices, in a clone, that the rest is not there yet. **Commit all three.** If your project
+ignores the assistant's directory wholesale, rsc adds the lines that keep those files versioned —
+verified against git, not against the pattern.
+
+**And say it plainly, because committing it is the point:** `.claude/rsc-bootstrap.mjs` is code that
+runs on every session and every shell call, so a pull request that edits *that file* runs on the
+machine of whoever reviews the branch. That is true of `.claude/settings.json` already, and of any
+hook-based harness — but it is worth knowing before you agree to commit a third one. Review changes
+to it the way you would review a CI workflow.
+
+Whoever clones runs **one command** and ends up with the same harness — at the version the
+project pinned, which is the `catalogVersion` in its `.rsc.json`:
 
 ```bash
-npx @damiangilgonzalez/harness@latest sync
+npx @damiangilgonzalez/harness@<catalogVersion> sync
 ```
 
-Same skills, same version — `.rsc.json` pins the catalog, so a teammate who clones in three
-months gets what you had, not what shipped since. Upgrading is a deliberate act, never a side
-effect of rebuilding.
+**You do not have to know that, or find it.** Open the project and the assistant tells you, in
+the first message: what is missing, what would be installed, and the exact command, naming the
+pinned version. It asks; it does not install anything on its own and it does not hold up
+whatever you sat down to do. Say no and it stops asking on that machine.
+
+Not `@latest`, and the difference is the whole point of sharing: a teammate who clones in three
+months gets what you had, not what shipped since. Upgrading is something a person decides, writes
+into `.rsc.json`, and commits — and then it reaches everyone through git, like any other change.
 
 When someone changes the harness and you `git pull`, `rsc doctor` tells you what no longer
 matches. **Nothing is ever written to your machine by a pull** — you are told, and you decide.
 
 **Own skills.** A skill your team wrote lives in the repo and already works for whoever clones,
-with no command at all. Declare it in `.rsc.json` under `ownSkills` and `doctor` will also say
-when someone is missing it — that is all declaring does. rsc never installs, updates or
-overwrites it: its version is the commit.
+with no command at all. rsc never installs, updates or overwrites it: its version is the commit.
+Installing a catalog skill of the same name is refused rather than silently winning, and `doctor`
+lists what is yours by reading the files themselves — no list to keep in `.rsc.json`, because a
+list somebody has to remember to update is a list that goes quietly stale. Declaring a skill under
+`ownSkills` still works and still reports when someone is missing it.
 
 
 ## 🩹 Something's off? One command
@@ -312,10 +335,12 @@ Recognise any of these? They are all the same fix.
 | `"target": "codex"` when you work in Claude Code | |
 | `This target has no hook injection` and you did not expect that | |
 | Skills appear that you never asked for | |
-| You cloned a repo and your assistant sees no skills at all | |
 | A hook seems to run several times per turn | |
 | Template lines showed up inside your hand-written `AGENTS.md` | |
 
+(A *fresh* clone is not in this table any more: nothing is broken there, the harness was simply
+never built on that machine, and the assistant now says so itself — see **sharing by git** above.)
+
 ```bash
 npx @damiangilgonzalez/harness@latest repair
 ```
@@ -660,7 +685,7 @@ The richer surfaces are intentionally narrower than skill support:
 | Windsurf, Cline, Roo | unsupported | yes | unsupported |
 | Antigravity, Zed, Continue, Amp, Jules, Aider | unsupported | unsupported | unsupported |
 
-`manifest.json` is the generated public inventory: 33 agents (4 base + 29
+`manifest.json` is the generated public inventory: 34 agents (5 base + 29
 selective specialists) and 43 command entries (10 fixed + 33 stack aliases).
 Unsupported means rsc writes nothing for that surface; it does not emulate a
 provider feature with an unverified file.

package/manifest.json

@@ -1,8 +1,8 @@
 {
-  "version": "1.3.12",
+  "version": "1.3.14",
   "counts": {
     "skills": 291,
-    "agents": 33,
+    "agents": 34,
     "commands": 43,
     "fixedCommands": 10
   },
@@ -5988,6 +5988,14 @@
         "fastapi"
       ]
     },
+    {
+      "id": "finding-verifier",
+      "description": "Adversarial verifier of review findings: takes ONE consolidated finding and tries to prove it false against the code. Default stance: the finding is false; only a reproduced or traced failure is CONFIRMED. Fresh context, edits nothing.",
+      "role": "refuter",
+      "tier": "balanced",
+      "tools": null,
+      "skills": []
+    },
     {
       "id": "flutter-build-resolver",
       "description": "Flutter build resolver: reproduces a failing build and applies the minimum verified repair. NOT widget review or package modernization.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damiangilgonzalez/harness",
-  "version": "1.3.12",
+  "version": "1.3.14",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {
@@ -64,5 +64,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "rscFixes": []
 }

package/scripts/doctor.js

@@ -1,10 +1,12 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { hooksDir, hooksDirIsOurs } from '../targets/worktree-reaper.mjs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
 import { divergence } from './lib/divergence.js';
 import { loadManifest } from './lib/manifest.js';
+import { readManifest as readProjectManifest } from './lib/manifest-file.js';
 import { listBackups } from './lib/backups.js';
 import { WORKFLOW_GATE_TEXT } from '../targets/hook-once.mjs';
 import { isEnabled, checkSello, readSello, countFindings, readEffectiveConfig, validateRiskConfig } from '../targets/sello.mjs';
@@ -15,6 +17,17 @@ import { resolveCommands, commandPath, targetHasCommands } from '../targets/comm
 import { inspectMemoryWiring } from '../targets/memory.js';
 import { metricsSummary } from '../targets/session-memory-core.mjs';
 import { agentPath } from '../targets/agents.js';
+import { projectOptOuts } from '../targets/opt-outs.js';
+import { versionReport } from './lib/versions.js';
+
+// Gates the committed manifest says the team disarmed, still armed here. Read through the same
+// partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
+// manifest (`harness`, `context7`) is not reported as something to converge on.
+function optOutsNotApplied(root) {
+  let manifest = null;
+  try { manifest = readProjectManifest(root); } catch { return []; }
+  return projectOptOuts(manifest?.optOuts).filter((n) => !existsSync(join(root, '.rsc', `.no-${n}`)));
+}
 
 // The sello's health, surfaced where the user already looks (spec: non-blocking
 // findings live in the project and are SUMMARIZED here, never nagged about).
@@ -52,6 +65,10 @@ function selloStatus(root) {
 //
 // Hookless targets get an empty list by construction: their always-on surface is a
 // markdown block with no script behind it, so there is nothing that can go missing.
+// A quoted span counts as a path only if it starts like one and holds no shell operator: a whole
+// `sh -c '…'` snippet is not a path, and reading it as one reports a present script missing.
+const SCRIPT_RE =
+  /"((?:[A-Za-z]:)?[\\/~][^"&;|]*[\\/]\.rsc[\\/][^"\s]+?\.mjs)"|'((?:[A-Za-z]:)?[\\/~][^'&;|]*[\\/]\.rsc[\\/][^'\s]+?\.mjs)'|([^"'\s]*[\\/]\.rsc[\\/][^"'\s]+\.mjs)/g;
 export function missingHookScripts({ target, home = homedir(), cwd = process.cwd() } = {}) {
   if (HOOKLESS_TARGETS.has(target)) return [];
   const file = targetPaths(target, home, cwd).hookTarget;
@@ -71,14 +88,85 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
   const expand = (c) => c.split('${CLAUDE_PROJECT_DIR}').join(cwd);
   for (const raw of commands) {
     const cmd = expand(raw);
-    for (const m of cmd.matchAll(/["']?([^"'\s]*[\\/]\.rsc[\\/][^"'\s]+\.mjs)["']?/g)) {
-      const script = m[1];
+    // Quoted forms first: a project path may hold a space, and stopping at whitespace kept only
+    // the tail (`entreno/.rsc/x.mjs`), which then resolved against the cwd and read as missing (#283).
+    for (const m of cmd.matchAll(SCRIPT_RE)) {
+      const script = m[1] ?? m[2] ?? m[3];
       if (!existsSync(script)) seen.add(script);
     }
   }
   return [...seen];
 }
 
+// Is the post-merge trigger actually armed in this clone? Three states, because they need three
+// different answers: armed, absent (repair it), or someone else's (leave it — chaining is our job
+// at install time, and overwriting a husky hook to fix a convenience would be indefensible).
+function worktreeCleanupStatus(root) {
+  if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
+  if (existsSync(join(root, '.rsc', '.no-worktree-cleanup'))) return { state: 'off-by-choice' };
+  // Ask git where hooks live instead of assuming `.git/hooks`. Until 2.0.1 this read the assumed
+  // path, so on a repo with its own `core.hooksPath` it found our inert file there and answered
+  // `armed` about a hook git would never run — the check confirming the exact failure it exists to
+  // catch. `unreachable` is its own state on purpose: `repair` re-runs the same install, so
+  // recommending it here would send the reader round the same loop (P6 wants a way out, not a ring).
+  const dir = hooksDir(root);
+  if (!hooksDirIsOurs(root, dir)) {
+    return {
+      state: 'unreachable',
+      action: `git reads hooks from ${dir}, which belongs to this repo or to another tool (husky, lefthook, a committed dispatcher). rsc will not write there. To arm the cleanup, add \`node "$(git rev-parse --show-toplevel)/.rsc/worktree-reaper.mjs" "$(git rev-parse --show-toplevel)" auto\` to your own post-merge hook.`,
+    };
+  }
+  const hook = join(dir, 'post-merge');
+  if (!existsSync(hook)) {
+    return { state: 'absent', action: 'Run `npx @damiangilgonzalez/harness repair` to arm the post-merge cleanup in this clone.' };
+  }
+  try {
+    const armed = readFileSync(hook, 'utf8').includes('rsc-managed worktree cleanup');
+    return armed
+      ? { state: 'armed' }
+      : { state: 'foreign', action: 'A post-merge hook from another tool is in place; `npx @damiangilgonzalez/harness repair` chains ours behind it.' };
+  } catch { return { state: 'unreadable' }; }
+}
+
+// Every skill this catalog ships declares its origin in its own frontmatter: `risco` for the skills
+// inherited from the original catalog, `damiangil` for the ones this fork added. So "is this ours?"
+// is answerable from the file itself, and does not need the list in
+// `.rsc.json` that nobody ever filled: that list is parallel accounting (P3), it has been empty in
+// every project since it was introduced, and `doctor` has been faithfully reporting on the emptiness.
+//
+// Failing towards "the user's" is deliberate. Reading a catalog skill as the user's leaves a file
+// that stops being updated; reading the user's as the catalog's invites something to overwrite it.
+// Only one of those loses work.
+const CATALOG_ORIGINS = new Set(['risco', 'damiangil']);
+
+function ownSkillsIn(paths, declared = []) {
+  const present = [];
+  let dir;
+  try { dir = dirname(paths.skillDir('_')); } catch { return { present, missing: [], declared }; }
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { /* nothing installed here yet */ }
+  for (const entry of entries) {
+    // Symlinks included, deliberately. rsc installs a catalog skill AS a symlink into `.rsc/skills/`
+    // and a hand-written one is a real directory, so the entry type is itself a provenance signal —
+    // and skipping symlinks would have made the frontmatter check below dead code that still looked
+    // like it worked. It did: a mutant that removed the check passed every test until this line was
+    // fixed. Both signals are read now, and the frontmatter is the one that decides.
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const md = join(dir, entry.name, 'SKILL.md');
+    if (!existsSync(md)) continue;
+    let origin = null;
+    try {
+      const head = readFileSync(md, 'utf8').slice(0, 2048);
+      origin = (/^origin:\s*(\S+)\s*$/m.exec(head) || [])[1] || null;
+    } catch { continue; }
+    if (!CATALOG_ORIGINS.has(origin)) present.push(entry.name);
+  }
+  // Declared-but-absent stays meaningful for anyone who did fill the list by hand, and it is the
+  // only half a derivation cannot cover: a file that is gone cannot describe itself.
+  const missing = declared.filter((name) => !existsSync(paths.skillDir(name)));
+  return { present: present.sort(), missing, declared };
+}
+
 export function doctor({ target, home, cwd }) {
   const root = cwd || process.cwd();
   const paths = targetPaths(target, home, cwd);
@@ -120,7 +208,7 @@ export function doctor({ target, home, cwd }) {
   const missingAgents = (state.agents || []).filter((id) => {
     const path = agentPath(target, root, id);
     return path && !existsSync(path);
-  }).map((id) => ({ id, action: 'Run `npx @damiangilgonzalez/harness sync` to restore this managed agent.' }));
+  }).map((id) => ({ id, path: agentPath(target, root, id), action: 'Run `npx @damiangilgonzalez/harness sync` to restore this managed agent.' }));
   const report = {
     target,
     installed: Object.keys(state.skills),
@@ -134,6 +222,11 @@ export function doctor({ target, home, cwd }) {
       latest: backups[0]?.id || null,
     },
     contextBudget: contextBudget({ target, home, cwd }),
+    // The worktree cleanup's trigger is a git hook, and `.git/hooks/` is not cloned. So a repo can
+    // carry a perfectly healthy harness and still never clean up, on every machine but the one that
+    // ran the installer. Reported, never nagged about: `repair` is what puts it back (P6).
+    worktreeCleanup: worktreeCleanupStatus(root),
+    ownSkills: ownSkillsIn(paths, readProjectManifest(root)?.ownSkills || []),
     sello: selloStatus(root),
     // Whether this harness has a design identity at all. `design` has always DECLARED that it
     // stops without one; until lib/design-identity.js nothing checked it (P2). Reported here,
@@ -148,6 +241,14 @@ export function doctor({ target, home, cwd }) {
     gitmojiGuard: state.policy?.gitmojiGuard === false
       ? 'deferred'
       : existsSync(join(root, '.rsc', '.no-gitmoji')) ? 'opted-out' : 'armed',
+    // The reverse of the same honesty, one level up: a gate the TEAM disarmed in the committed
+    // manifest and that is still armed on this machine. Nothing is applied from here — a pull
+    // never rewrites somebody's machine — so the only thing owed is saying it out loud, and
+    // saying it every run, because a notice offered once per session is a notice missed.
+    optOutsNotApplied: optOutsNotApplied(root),
+    // First thing to read on any bug report: a project behind its CLI runs old hooks, and "it is
+    // already fixed" only helps once the fix is in `.rsc/`.
+    versions: versionReport(root),
     // Counted, never interpreted — by spec, the gap log's reader is the user.
     automationGaps: countGaps(root),
     memory,
@@ -157,9 +258,12 @@ export function doctor({ target, home, cwd }) {
     commandOrphans,
     commandCollisions: state.commandCollisions || [],
   };
+  // #277 — the three "missing" lists share one shape, { id, path, action }, so whoever builds on top
+  // of doctor reads them the same way; and `healthy` is what the exit code says.
   for (const [id, e] of Object.entries(state.skills)) {
-    for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);
+    for (const f of e.files) if (!existsSync(f)) report.missing.push({ id, path: f, action: 'Run `npx @ericrisco/rsc sync` to restore this managed skill.' });
   }
+  report.healthy = report.hookWired && !report.missing.length && !missingAgents.length && !missingCommands.length;
   return report;
 }
 
@@ -383,6 +487,18 @@ export function contextBudget({ target, home = homedir(), cwd = process.cwd() }
     });
   }
   const drift = divergence({ cwd, target, home });
+  // A separate finding, not a fourth clause of the one below: that one says this checkout
+  // is behind its own team, and the fix is to align with the declaration. This one says the
+  // declaration itself is behind the catalog, so aligning with it changes nothing. Folded
+  // together, the report would name the right skill and the wrong reason.
+  if (drift.floorMissing?.length) {
+    findings.push({
+      id: 'floor-missing',
+      severity: 'high',
+      summary: `.rsc.json predates a skill the catalog now requires: ${drift.floorMissing.join(', ')}. The always-on body routes work to it, so that route currently answers nowhere.`,
+      action: 'Run `npx @damiangilgonzalez/harness sync` — it adds what the catalog requires and touches nothing else.',
+    });
+  }
   if (drift.missing.length || drift.extra.length || drift.ownMissing.length) {
     // The day-two case: a teammate changed the harness and this checkout has not caught
     // up. Reported always, even after someone declines to align — the divergence does not