rvlib-shipkit 0.37.0 → 0.37.1

package/CHANGELOG.md

@@ -1,4 +1,14 @@
-# Changelog
+## 0.37.1
+
+- **SK013 no longer wires a Bash guard that cannot run.** A consumer that runs shipkit from a checkout by ABSOLUTE path, with no `rvlib-shipkit` dependency and no `node_modules`, carried `bun "$CLAUDE_PROJECT_DIR/node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts"`, so every Bash call of every agent in that repo printed `Module not found`, while the rule only WARNed `not installed yet, bun install` and the gate stayed green. `bun install` installs nothing in a repo that declares no dependency, so that WARN now fires only when `package.json` declares `rvlib-shipkit`, and otherwise the missing guard FAILs. `guardCommand` glued an absolute cli path under the project dir (`$CLAUDE_PROJECT_DIR//Users/...`), and it now writes the absolute path alone. The lint resolves an absolute guard path too, where it used to pass any form it could not read. The fixer, which `shipkit ci` runs by default, repoints a guard whose script does not exist at the copy the repo actually runs: the cli path its scripts name when a guard sits beside it (a repo's own `src/cli.ts` matches the same script shape), else its declared dependency, else the shipkit doing the fixing, which is what the launcher falls back to. A guard that resolves, or waits on a declared install, stays as written, and a target that does not resolve itself is never written.
+
+- **The gate says what an undeclared floor costs, and declares nothing on a repo's behalf.** A slot with no `inputs`, no `ttl` and no `never` is measured every run, and `resolveFloor` declares none for any of the five, so a second gate over an UNCHANGED tree re-runs everything: 17.4s per gate measured on a field repo, 14.8s of it the test task, against the shape an agent actually runs (verify, commit, verify again). Nothing pointed at the repair either, since `shipkit init` scaffolded no `defaults` block, so a fresh repo stayed that way until somebody read `shipkit keys --burn-down` and knew what to write. `init` now scaffolds the commented `defaults` line naming the fix.
+- **What this release deliberately does NOT do is auto-declare `['.']` for those slots**, and the reason is worth more than the speed. `['.']` is not the work tree, it is the TRACKED tree: `git-scan` force-adds only a path a declaration NAMES, so an ignored path enters a key by NAME and never by content. Every floor task reads ignored content in an ordinary repo, a suite through its fixtures and its local database, tsc and the two graph walks through generated types and `node_modules`. Measured on a scratch repo: warm the ledger with two green runs, break a gitignored file the suite reads, and the third gate prints `ok: test (replayed, 0.0s saved)` over a suite that exits 1. `tests/floor-cache-safety.test.ts` holds that repro, watched fail, with the declaring lookalike beside it still replaying. Speed here is bought by a REPO declaring what its own tasks read, which is the only declaration with a real hit rate anyway.
+- Two doc sentences that argued the other way are corrected where they live: `TaskDef.inputs` no longer says `['.']` "cannot under declare", and the `git-key` header no longer promises the never-cached default is the whole safety story without naming who can declare on a unit's behalf.
+
+- **SK004 asks git what is ignored, instead of trusting the text it wrote.** The rule compared the managed block to the expected string and stopped there, so it reported `current` over a repo where git ignored none of what the block claims. Two ways that happens, both from the field. A bare `printf 'work/\n' >> .gitignore` onto a file whose last line carried no terminator fuses the two into `sourcework/`, which ignores neither path, and the file ends with a newline afterwards so nothing textual looks wrong (cost in that repo: 1.1GB and 700 screenshots pushed across four commits, a rejected push, and a `git filter-repo` rewrite). And a negation below the block is the DOCUMENTED override, so nothing stopped one landing on `.rv-private/`, the directory holding the keyword list the leak guard itself reads. Every policy pattern is now probed through one `git check-ignore --stdin` call and a contradiction FAILs, naming the pattern and the `check-ignore -v` that reports the winning line. The three venue folders stay exempt, because unignoring one is how a live listing ships. A `.gitignore` that does not end with a newline is now a FAIL of its own, since that missing byte is the trap rather than a cosmetic defect, and `--fix` terminates the file even when the block is current. Outside a git repo the rule states the block went unverified rather than reporting a green nothing measured.
+
+- **A check declaration the gate's own formatter wrote was unreadable to the gate.** `BLOCKING_RE` and `GATE_RE` both ended in `\s*$`, and oxfmt (which the fix pass RUNS) terminates every statement with a semicolon. So `shipkit ci` reformatted `export const blocking = false` into `export const blocking = false;`, then failed the file with `does not declare whether it blocks` and printed as the fix the exact line it had just written. Two repos in the field shipped `// oxfmt-ignore` workarounds to get a green gate. The worse half was silent: a `export const gate = false;` was not read either, so a world probe that had opted out of the gate quietly re-entered it, and a repo could declare fifteen off-gate probes and watch all fifteen run. Both readers now accept an optional `as const` and an optional semicolon through one shared tail. `INPUTS_RE`, `TTL_RE` and `NEVER_RE` never anchored the line end, so they were never affected. Pinned by three tests: the formatted shapes, the gate opt-out in both spellings, and a CONTROL that the unterminated shapes and a silent file still read as before.
 
 ## 0.37.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.37.0",
+    "version": "0.37.1",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/core/discover-checks.ts

@@ -42,7 +42,11 @@ export type DiscoveredCheck = {
 
 // read without importing: checks run as subprocesses, and discovery must stay
 // pure-fs. `export const blocking = true` (or false), nothing cleverer.
-const BLOCKING_RE = /^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)\s*$/m
+// the tail is the gate's OWN formatter: oxfmt terminates every statement, and
+// the fix pass runs it, so a reader that refuses a semicolon refuses the shape
+// the gate itself just wrote.
+const TAIL = String.raw`(?:\s+as\s+const)?\s*;?\s*$`
+const BLOCKING_RE = new RegExp(String.raw`^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)` + TAIL, 'm')
 // `export const inputs = ['a', 'b']`, single or multi line. Anything cleverer
 // (a computed list, a spread) is deliberately unreadable here and lands as no
 // declaration, which means never cached: a scanner guessing at a program is
@@ -53,7 +57,7 @@ const NEVER_RE = /^\s*export\s+const\s+never\s*(?::\s*string\s*)?=\s*['"]([^'"]+
 // `export const gate = false` takes a check out of `shipkit ci`. Only the
 // literal false opts out: anything unreadable stays in the gate, because a
 // scanner that guesses its way to SKIPPING a check is how coverage disappears
-const GATE_RE = /^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false\s*$/m
+const GATE_RE = new RegExp(String.raw`^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false` + TAIL, 'm')
 const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
 
 export function discoverChecks(root: string): DiscoveredCheck[] {

package/src/core/floor.ts

@@ -68,6 +68,24 @@ function builtinFloorTask(id: string, root: string): { task: TaskDef; source: Fl
     return `no package.json '${id}' script`
 }
 
+// NOTHING here declares a read set on a repo's behalf, and that is a decision
+// rather than an omission. A floor slot with no `inputs` is measured every run,
+// which costs speed and never correctness (ledger/git-key.ts owns that default).
+//
+// The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
+// under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
+// path a declaration NAMES, so an ignored path enters the key by name and never
+// by content. Every floor slot reads ignored content in an ordinary repo, a
+// suite through its fixtures and a local database, tsc and the graph walks
+// through generated types and node_modules. Shipped for one day, that made the
+// gate print `ok: test (replayed)` over a suite that exits 1
+// (tests/floor-cache-safety.test.ts holds the repro).
+//
+// Speed here is bought by a REPO saying what its own tasks read, in
+// `defaults`, which is the only declaration with a real hit rate anyway.
+// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
+// still undeclared, and the gate prints the cost of it once per run.
+
 export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     const pkgPath = join(root, 'package.json')
     let scripts: Record<string, string> = {}

package/src/core/task-runner.ts

@@ -36,8 +36,12 @@ export type TaskDef = {
      *  speed and never correctness. A list MISSING a path the command reads is
      *  the one that costs correctness: the key cannot move when that path
      *  changes, so the answer replays over a tree it no longer describes. Over
-     *  declaring costs a re-run, under declaring is a false green, and `['.']`
-     *  is the whole work tree and cannot under declare. A task carries no code
+     *  declaring costs a re-run, under declaring is a false green. `['.']` is
+     *  the whole TRACKED tree, and it is NOT a catch-all: an ignored path
+     *  enters a key by name and never by content, so a task reading a
+     *  gitignored fixture, a built dir or a .env under declares with `['.']`
+     *  exactly as it would with a narrow list. A task that reads the network,
+     *  a keychain or the clock declares `ttl`, never `inputs`. A task carries no code
      *  closure, so the script it runs belongs in here too.
      *  Declaring both this and `ttl` is a registration failure. */
     inputs?: string[]

package/src/init-repo.ts

@@ -29,10 +29,14 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'], selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'], the .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // lint, typecheck, imports:check and cycles replay off the tracked tree.
+    // \`test\` measures every run until you say what it reads, because an
+    // ignored path (a fixture, a local db, a .env) is not in a tree key:
+    // defaults: { test: { inputs: ['tests', 'src', 'package.json'] } },
     // .comfy-ts/ holds schema dumps naming a private model collection.
     // gitignore (SK004) is advisory, this pre-commit gate is not
     hooks: { blockedPaths: ['.comfy-ts/'] },
-    // the mandated reviewer agent type (rule SK008). Uncomment with YOUR
+    // the declared reviewer agent type (rule SK008). Uncomment with YOUR
     // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
     // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
     // health checks need no config. Drop a <name>.check.ts file anywhere,

package/src/ledger/git-key.ts

@@ -16,8 +16,11 @@
 //   NEITHER  declares nothing. Never cached. This is the DEFAULT, and it is
 //            the whole safety story: forgetting to declare costs speed, never
 //            correctness, so the burn-down list below is a to-do rather than a
-//            hazard. Declaring BOTH is a registration failure, loud, because
-//            the two answers contradict each other.
+//            hazard. It holds only while nothing declares ON a unit's behalf:
+//            the gate floor gives `['.']` to the four slots tracked source
+//            decides and deliberately leaves `test` here (core/floor.ts says
+//            why). Declaring BOTH is a registration failure, loud, because the
+//            two answers contradict each other.
 //
 // CROSS WORKTREE. Every component here is content addressed or a version
 // string; not one of them is an absolute path. Two worktrees of one repo

package/src/repo-config.ts

@@ -90,12 +90,12 @@ export type RepoConfig = {
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
     visibility?: 'private' | 'public'
-    /** the reviewer agent type this repo mandates: `.claude/agents/<name>.md`,
+    /** the reviewer agent type this repo declares: `.claude/agents/<name>.md`,
      *  whose system prompt points at `brief` (an md file holding the standing
      *  review framing — one home, shared across repos). `tools` overrides the
      *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
      *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
-     *  mandated reviewer. */
+     *  declared reviewer. */
     reviewer?: { name: string; brief: string; tools?: string[] }
     /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
      *  repo keeps as a direct tool call. Declared per NAME, never as a list of

package/src/rules/SK004-gitignore-policy.ts

@@ -7,6 +7,7 @@
 // PLACE — lines below it (e.g. a live venue's `!.rv-itch/` override, where
 // last-match-wins) keep their position; everything outside the block is
 // never touched. `shipkit init` writes the same block through this fixer.
+import { execFileSync } from 'child_process'
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
@@ -58,6 +59,60 @@ export function policyPatterns(config: RepoConfig): string[] {
     return [...POLICY_LINES.filter((l) => !l.startsWith('#')), ...(config.gitignore ?? [])]
 }
 
+// the three venue folders are DESIGNED to be unignored below the block once a
+// listing is live (last-match-wins, the comment inside POLICY_LINES says so),
+// so an override on one of them is the mechanism working. Every other policy
+// path is a claim the block makes, and a claim git contradicts is a bug.
+function endsWithNewline(root: string): boolean {
+    const p = join(root, '.gitignore')
+    if (!existsSync(p)) return true
+    const text = readFileSync(p, 'utf8')
+    return text === '' || text.endsWith('\n')
+}
+
+const OVERRIDABLE = new Set(['.rv-itch/', '.rv-steam/', '.rv-discord/'])
+
+/** a path git can be asked about, for a pattern that may be a glob or a dir */
+function probePath(pattern: string): string {
+    if (pattern.endsWith('/')) return `${pattern}probe`
+    // `.*.tmp-*` and `*.loras.local.txt`: a literal standing in for the glob
+    return pattern.includes('*') ? pattern.replace(/\*/g, 'probe') : pattern
+}
+
+/** which of `paths` git does NOT ignore. null when this is not a git repo, so
+ *  a rule can say it did not measure rather than report a green it invented */
+export function notIgnored(root: string, paths: string[]): string[] | null {
+    if (paths.length === 0) return []
+    try {
+        // --stdin -z -n: one call, every path, and `-n` makes git print a row
+        // for the MISSES too, which is the answer we want
+        const out = execFileSync('git', ['check-ignore', '--stdin', '-z', '-n', '-v'], {
+            cwd: root, input: paths.join('\0'), encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        // -v -z rows are source\0line\0pattern\0path; an unignored path has an
+        // empty source and an empty pattern
+        const f = out.split('\0')
+        const miss: string[] = []
+        for (let i = 0; i + 3 < f.length + 1; i += 4) {
+            if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
+        }
+        return miss
+    } catch (e) {
+        // exit 1 means "none of them are ignored", which is an ANSWER, and git
+        // still wrote the rows we parse. Anything else (no repo, no git) is not
+        const err = e as { status?: number; stdout?: string }
+        if (err.status === 1 && typeof err.stdout === 'string') {
+            const f = err.stdout.split('\0')
+            const miss: string[] = []
+            for (let i = 0; i + 3 < f.length + 1; i += 4) {
+                if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
+            }
+            return miss
+        }
+        return null
+    }
+}
+
 type Parsed = { text: string; crlf: boolean; lines: string[]; b: number; e: number }
 
 function parse(root: string): Parsed | null {
@@ -122,11 +177,48 @@ export const gitignorePolicy: Rule = {
             case 'missing-block': return t.fail('.gitignore has no shipkit policy block — contract surfaces can leak into git')
             case 'corrupted': return t.fail('.gitignore policy block corrupted (unpaired marker)')
             case 'stale': return t.fail('.gitignore policy block is stale — the policy or repo-contributed lines moved since it was written')
-            case 'current': return t.ok(`.gitignore policy block current (${policyPatterns(env.config).length} patterns)`)
         }
+        // an unterminated last line is a TRAP, not a cosmetic defect: the next
+        // `>> .gitignore` fuses onto it and the result is one pattern that
+        // ignores neither path, with the file ending in a newline afterwards
+        // so nothing textual looks wrong
+        if (!endsWithNewline(env.root)) {
+            t.fail('.gitignore does not end with a newline — the next append fuses onto its last line and ignores neither path')
+            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) terminates it' })
+            return
+        }
+        // the block states what must be ignored. git is the only thing that
+        // knows whether it IS: a stray negation below the block, or a line
+        // fused into another, leaves the text current over a broken repo
+        const claimed = policyPatterns(env.config).filter((p) => !OVERRIDABLE.has(p))
+        const probes = new Map(claimed.map((p) => [probePath(p), p]))
+        const miss = notIgnored(env.root, [...probes.keys()])
+        if (miss == null) {
+            // not a git repo (a fixture, or a dir before `git init`). Say the
+            // verification did not run rather than reporting a green nothing
+            // measured, and stay quiet: there is nothing wrong here to fix
+            t.ok(`.gitignore policy block current (${claimed.length} patterns)`)
+            t.lines.push({ kind: 'skip', text: 'not a git repo here, so nothing verified the block against what git actually ignores' })
+            return
+        }
+        if (miss.length > 0) {
+            const names = [...new Set(miss.map((m) => probes.get(m) ?? m))]
+            t.fail(`.gitignore block claims ${names.join(', ')} ignored, git says otherwise — a negation below the block, or a line fused into its neighbour`)
+            t.lines.push({ kind: 'fix-fail', text: `git check-ignore -v ${miss[0]} names the line that wins` })
+            return
+        }
+        t.ok(`.gitignore policy block current, ${claimed.length} patterns verified against git`)
     },
     fix: (env: RuleEnv): FixResult => {
         const before = blockState(env.root, env.config)
+        // terminate an unterminated file even when the block itself is current:
+        // that missing byte is what the next append fuses onto
+        let terminated: string | null = null
+        if (before === 'current' && !endsWithNewline(env.root)) {
+            const p = join(env.root, '.gitignore')
+            atomicWrite(p, `${readFileSync(p, 'utf8')}\n`)
+            terminated = '.gitignore terminated with a newline (the next append would have fused onto its last line)'
+        }
         const blockSummary = before === 'current'
             ? null
             : before === 'missing-file' ? '.gitignore created with the policy block'
@@ -137,10 +229,10 @@ export const gitignorePolicy: Rule = {
         // the block must be written FIRST: untracking a path the ignore list
         // does not yet carry leaves it staged for re-add on the next `git add`
         const un = untrackGenerated(env.root, { enabled: env.config.untrackGenerated })
-        const parts = [blockSummary]
+        const parts = [blockSummary, terminated]
         if (un.did === 'untracked') parts.push(`untracked ${un.paths.join(', ')} (generated, now gitignored, committed as ${un.commit})`)
         if (un.did === 'refused') parts.push(`left ${trackedGeneratedPaths(env.root).join(', ')} tracked: ${un.why}`)
         const summary = parts.filter((x): x is string => x != null).join(' · ')
-        return { changed: blockSummary != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
+        return { changed: blockSummary != null || terminated != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
     },
 }

package/src/rules/SK008-reviewer-agent.ts

@@ -1,4 +1,4 @@
-// SK008 — the mandated reviewer agent type. A repo that declares
+// SK008 — the declared reviewer agent type. A repo that declares
 // `reviewer: { name, brief }` must carry `.claude/agents/<name>.md`: an agent
 // definition whose system prompt POINTS at the brief file (ONE home for the
 // text, so review framing can never drift per repo) and whose `tools:` line
@@ -50,7 +50,7 @@ export function briefMissing(root: string, brief: string): boolean {
 function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
     return `---
 name: ${reviewer.name}
-description: The mandated critical reviewer for this repo. Use before every commit, and whenever a diff needs judging against what was actually asked for. Judges whether a change should exist at all, not just whether it is correct.
+description: The critical reviewer for this repo. Whether a review is worth its wall clock is the session's call: reach for it on code whose failure the gate cannot see, and tell it to verify by running rather than to opine. Judges whether a change should exist at all, not just whether it is correct.
 tools: ${(reviewer.tools ?? REVIEWER_TOOLS).join(', ')}
 model: opus
 ---
@@ -82,7 +82,7 @@ export const reviewerAgent: Rule = {
         const rel = reviewerAgentPath(r.name)
         const p = join(env.root, rel)
         if (briefMissing(env.root, r.brief)) t.fail(`the declared brief '${r.brief}' does not exist — every review's mandated first action would fail`)
-        if (!existsSync(p)) return t.fail(`${rel} missing — the mandated reviewer type is unavailable, so every review runs on whatever framing the spawner improvised`)
+        if (!existsSync(p)) return t.fail(`${rel} missing — the declared reviewer type is unavailable, so any review runs on whatever framing the spawner improvised`)
         const issues = reviewerAgentIssues(readFileSync(p, 'utf8'), r)
         for (const i of issues) t.fail(`${rel}: ${i}`)
         if (issues.length === 0 && !t.failed) t.ok(`${rel} → ${r.brief}`)

package/src/rules/SK013-one-way-in-policy.ts

@@ -13,7 +13,7 @@
 // TRACKED on purpose: `.claude/settings.local.json` is gitignored by the house
 // scaffold, so a policy written there would bind exactly one checkout.
 import { existsSync, mkdirSync, readFileSync } from 'fs'
-import { dirname, join } from 'path'
+import { dirname, isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -36,19 +36,30 @@ export function exemptSlots(c: RepoConfig): Set<string> {
     return off
 }
 
-/** how the hook invokes the guard. `$CLAUDE_PROJECT_DIR` because a hook's cwd
- *  is not promised to be the repo root */
+/** how the hook invokes the guard. A relative path hangs off
+ *  `$CLAUDE_PROJECT_DIR` because a hook's cwd is not promised to be the repo
+ *  root, and an absolute one stands alone */
 export function guardCommand(bin?: string): string {
     const path = bin == null
         ? 'node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts'
         : bin.replace(/cli\.ts$/, 'hooks/one-way-in-guard.ts')
-    return `bun "$CLAUDE_PROJECT_DIR/${path}"`
+    return isAbsolute(path) ? `bun "${path}"` : `bun "$CLAUDE_PROJECT_DIR/${path}"`
 }
 
-/** a guard under `node_modules/` that is not there yet says the dependency is
- *  not installed, which `bun install` fixes and no edit to this repo can. Any
- *  other unresolvable path is a config this repo chose and got wrong. */
-const isUninstalledDep = (rel: string): boolean => rel.startsWith('node_modules/')
+const readPkg = (root: string): { scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null => {
+    try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as never } catch { return null }
+}
+
+const declaresShipkit = (root: string): boolean => {
+    const pkg = readPkg(root)
+    return pkg?.dependencies?.['rvlib-shipkit'] != null || pkg?.devDependencies?.['rvlib-shipkit'] != null
+}
+
+/** a guard under `node_modules/` that is not there yet, in a repo that
+ *  declares rvlib-shipkit, says the dependency is not installed, which
+ *  `bun install` fixes and no edit to this repo can. Without the declaration
+ *  no install ever brings it, so it is a path this repo got wrong like any other. */
+const isUninstalledDep = (root: string, rel: string): boolean => rel.startsWith('node_modules/') && declaresShipkit(root)
 
 const readSettings = (root: string): Settings | null => {
     const p = join(root, SETTINGS_PATH)
@@ -65,21 +76,32 @@ const guardHookCommand = (s: Settings): string | null => {
 
 const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
 
-/** the guard file the hook command points at, resolved against the repo root.
+/** the guard file the hook command points at, resolved against the repo root
+ *  when it hangs off `$CLAUDE_PROJECT_DIR`, as written when it is absolute.
  *  A hook whose script does not exist errors on EVERY Bash call and refuses
  *  nothing, so the agent sees only the bare deny, which is the one failure
  *  this rule exists to prevent. Declaring it and never running it is worse
  *  than not declaring it, so it FAILs. */
 function guardScriptMissing(root: string, command: string): string | null {
-    const m = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)
-    const rel = m?.[1]
-    if (rel == null) return null // a form this rule cannot resolve is not a form it may condemn
-    return existsSync(join(root, rel)) ? null : rel
+    const rel = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)?.[1]
+    if (rel != null) return existsSync(join(root, rel)) ? null : rel
+    const abs = /^bun\s+["']?(\/[^"'\s]+)["']?/.exec(command.trim())?.[1]
+    if (abs != null) return existsSync(abs) ? null : abs
+    return null // a form this rule cannot resolve is not a form it may condemn
 }
 
-const readBin = (root: string): string | undefined => {
-    try { return inferBin((JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}) }
-    catch { return undefined }
+/** the guard the fixer writes: the cli path the scripts run when a guard sits
+ *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
+ *  repo's own dependency, else the copy of shipkit doing the fixing, which is
+ *  the one the launcher falls back to in a repo that has none */
+export function guardCommandFor(root: string): string {
+    const bin = inferBin(readPkg(root)?.scripts ?? {})
+    if (bin != null) {
+        const fromBin = guardCommand(bin)
+        if (guardScriptMissing(root, fromBin) == null) return fromBin
+    }
+    if (declaresShipkit(root)) return guardCommand()
+    return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
 export const oneWayInPolicy: Rule = {
@@ -115,7 +137,7 @@ export const oneWayInPolicy: Rule = {
             // that fixes it, not a red gate on a repo nobody has installed yet,
             // and the deny list is the floor throughout. A path this repo chose
             // and got wrong is still a FAIL: it will never resolve on its own.
-            if (missing != null && isUninstalledDep(missing))
+            if (missing != null && isUninstalledDep(env.root, missing))
                 t.warn(
                     `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which is not installed yet — until then a refusal names no replacement, and the deny list is the whole floor`,
                     `bun install (or bun add -d rvlib-shipkit)`,
@@ -149,10 +171,24 @@ export const oneWayInPolicy: Rule = {
             s.permissions = { ...s.permissions, deny: [...deny, ...added] }
             changes.push(`${added.length} raw runner(s) denied`)
         }
+        const wantGuard = guardCommandFor(env.root)
         if (!hasGuardHook(s)) {
             const pre = s.hooks?.['PreToolUse'] ?? []
-            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: guardCommand(readBin(env.root)) }] }] }
+            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: wantGuard }] }] }
             changes.push('PreToolUse guard wired (every refusal names the shipkit command)')
+        } else {
+            // a guard that cannot run errors on every Bash call, so it is repointed
+            // at the copy this repo runs. One that resolves, or waits on a declared
+            // install, is the repo's choice and stays as written
+            for (const m of s.hooks?.['PreToolUse'] ?? [])
+                for (const h of m.hooks ?? []) {
+                    if (h.command?.includes('one-way-in-guard') !== true) continue
+                    const missing = guardScriptMissing(env.root, h.command)
+                    if (missing == null || isUninstalledDep(env.root, missing) || h.command === wantGuard) continue
+                    if (guardScriptMissing(env.root, wantGuard) != null) continue
+                    changes.push(`PreToolUse guard repointed from ${missing}, which does not exist`)
+                    h.command = wantGuard
+                }
         }
         if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
         mkdirSync(dirname(p), { recursive: true })