rvlib-shipkit 0.36.0 → 0.37.1

package/CHANGELOG.md

@@ -1,4 +1,21 @@
-# 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
+
+- **The leak guard grew an allowlist, because it had no way to be wrong.** Every keyword matched as a case-insensitive substring over the staged added lines, so a four letter row landed inside a real npm dependency name and inside a base64 integrity hash in `bun.lock`, and that lockfile became uncommittable forever with no per repo override of any kind. The only way past was `--no-verify`, which disarms every other gate too, so the guard was training people to switch it off. Two answers ship, in this order. A `w:<word>` keyword row now matches on word boundaries spelled in unicode rather than with `\b`, which is ascii only and would let an accented name match inside a longer accented word: that makes the PATTERN smarter rather than the guard looser, and it is opt in, so a keyword file that carries no `w:` row behaves exactly as before. Then `repo.config.ts hooks.leakAllow` (with the machine-global twin `~/.rv-private/leak-allow.json`) declares a known-good match: `paths` names the files, `patterns` names the keywords, and `inHashes` narrows to a match that falls inside a content hash, where the bytes are an address rather than prose. `paths` plus `patterns` is the shape to reach for, because it waives one keyword in named files while the same keyword still blocks everywhere else, and a single occurrence outside a hash refuses an `inHashes` entry outright.
+- **A waiver is never silent.** Each entry carries a required `reason`, every waiver that fires PRINTS with that reason and the entry that owns it (on the FAIL path too, so a partial waive is visible beside what still blocks), and `hooks list` counts the declared waivers. An entry with no reason, with neither `paths` nor `patterns`, or with an unknown key dies at config load through `defineRepo`, and an allowlist file that will not parse waives nothing and WARNs, so a broken waiver leaves the guard stricter rather than looser.
+- **A tracked allowlist never becomes a copy of the private keyword list.** An entry names a keyword by FINGERPRINT (`fp:` plus 12 hex of its sha256), printed beside every hit, which is how a waiver gets written without anyone typing the private word into git. `repo.config.ts` takes the fingerprint form alone and refuses a literal by name. The private machine-global file may use either. The honest limit is stated in the source: a fingerprint stops the list being read off a tracked file and is no defence against a targeted guess.
+- The staged diff is now parsed per FILE (`addedLinesByFile`), so a hit says which file it came from and a waiver can name one. Which file a line belongs to is decided by COUNTING each hunk body from the size its header declares, never by trusting a `+++ …` line wherever it appears: an added line whose own text starts with `++` reaches the parser looking exactly like a file header, and believing one inside a hunk would let ordinary looking text drop every added line after it (`++ /dev/null`) or file the rest under a name a waiver covers (`++ b/bun.lock`). Substring rows match through a case-insensitive regex instead of `indexOf` over a lowercased copy, because one unicode character lowercases into two and slides every offset after it, and those offsets are what decide whether a match sits inside a content hash. A content-hash span is consulted ONLY by an entry that asked for `inHashes`: an api token is also a long base64 run, so skipping those spans by default would silence the guard on the exact shape it exists to catch.
 
 ## 0.36.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.36.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/hooks/leak-guard.ts

@@ -4,10 +4,23 @@
 //
 // the keyword file is deliberately untracked (a list of things to grep for
 // is itself private). absent file → loud skip, never a silent pass.
+//
+// a keyword matches as a SUBSTRING, which is what catches a private name
+// glued into a hostname or an identifier. The cost is a false positive a repo
+// cannot escape: a four letter row lands inside a dependency name or inside a
+// base64 integrity hash in a lockfile, and that lockfile is uncommittable
+// forever. A guard that cries wolf is a guard people answer with --no-verify,
+// which protects nothing. Two answers, in this order. `w:<word>` rows match on
+// word boundaries, which makes the PATTERN smarter rather than the guard
+// looser. An ALLOWLIST waives a known-good match in a named context, and every
+// waiver that fires is PRINTED with its reason, so a reader sees what was let
+// through and why.
+import { createHash } from 'crypto'
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { basename, join } from 'path'
 
-export type LeakHit = { where: string; pattern: string }
+export type LeakHit = { where: string; pattern: string; file?: string }
+export type LeakWaiver = LeakHit & { reason: string; source: string }
 
 /** what a hit REPORTS. The matched string is private by construction, and a
  *  gate that prints it verbatim puts it in a terminal, a CI log and any paste
@@ -15,16 +28,66 @@ export type LeakHit = { where: string; pattern: string }
 export const maskPattern = (p: string): string =>
     p.startsWith('re:') || p.length <= 6 ? p : `${p.slice(0, 3)}…${p.slice(-2)} (${p.length} chars)`
 
+/** a stable name for a pattern that does not CARRY it, so a tracked allowlist
+ *  points at a private keyword without becoming a copy of the private keyword
+ *  list. Printed beside every hit, which is how a waiver gets written without
+ *  anyone typing the word.
+ *
+ *  Honest scope: this stops the list being READ off a tracked file. It is no
+ *  defence against a targeted guess, because a short keyword has a small
+ *  search space and whoever already suspects the word can confirm it. */
+export const patternFingerprint = (pattern: string): string =>
+    'fp:' + createHash('sha256').update(pattern.toLowerCase()).digest('hex').slice(0, 12)
+
+/** one known-good match a repo (or this machine) waives.
+ *
+ *  `paths` alone waives every pattern in those files. `patterns` alone waives
+ *  those patterns everywhere. The PAIR is the shape to reach for: this
+ *  pattern, in these files, while the same pattern still blocks anywhere else.
+ *  `inHashes` narrows further, to a match that lands inside a content hash. */
+export type LeakAllowEntry = {
+    /** why this match is known good. Printed every time the waiver fires, so
+     *  a reader months later can judge it. Required. */
+    reason: string
+    /** staged paths this entry covers: a repo-relative path, a bare basename
+     *  ('bun.lock'), or a 'dir/' prefix. Absent = every target, the commit
+     *  message included. */
+    paths?: string[]
+    /** the patterns this entry waives, named by FINGERPRINT (`fp:` + 12 hex,
+     *  printed beside every hit). Absent = every pattern, on `paths` alone.
+     *  A TRACKED source (repo.config.ts) takes the fingerprint form only: a
+     *  literal there puts the private keyword into git. */
+    patterns?: string[]
+    /** waive only a match that falls inside a content hash (an npm `sha512-…`
+     *  integrity field, a 40+ char base64 run). The bytes of a content address
+     *  are arithmetic, not prose, so a keyword inside one is noise. The same
+     *  keyword on a normal line of the same file still blocks. */
+    inHashes?: boolean
+}
+
 export type LeakGuardResult =
     | { status: 'skipped'; reason: string }
-    | { status: 'clean'; patterns: number }
-    | { status: 'hit'; hits: LeakHit[]; patterns: number }
+    | { status: 'clean'; patterns: number; waived: LeakWaiver[]; notes: string[] }
+    | { status: 'hit'; hits: LeakHit[]; patterns: number; waived: LeakWaiver[]; notes: string[] }
+
+export type ParsedPatterns = {
+    substrings: string[]
+    words: { word: string; re: RegExp }[]
+    regexes: { row: string; re: RegExp }[]
+}
+
+const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 /** Parse the keyword file: blank lines and `#` comments dropped, `re:<pattern>`
- *  rows become case-insensitive regexes, everything else a case-insensitive
- *  substring. */
-export function parsePatterns(text: string): { substrings: string[]; regexes: { row: string; re: RegExp }[] } {
+ *  rows become case-insensitive regexes, `w:<word>` rows match on word
+ *  boundaries, everything else a case-insensitive substring.
+ *
+ *  A `w:` row REPORTS as the bare word, so its mask and its fingerprint are
+ *  the same with or without the prefix: adding the prefix to a row never
+ *  invalidates a waiver already written against it. */
+export function parsePatterns(text: string): ParsedPatterns {
     const substrings: string[] = []
+    const words: { word: string; re: RegExp }[] = []
     const regexes: { row: string; re: RegExp }[] = []
     for (const raw of text.split('\n')) {
         const row = raw.trim()
@@ -32,24 +95,134 @@ export function parsePatterns(text: string): { substrings: string[]; regexes: {
         if (row.startsWith('re:')) {
             try { regexes.push({ row, re: new RegExp(row.slice(3), 'i') }) }
             catch { /* a malformed row must not disable the whole guard */ }
+        } else if (row.startsWith('w:')) {
+            const word = row.slice(2).trim().toLowerCase()
+            // \b is ascii-only in JS, which lets an accented name match inside
+            // a longer accented word: the boundary is spelled in unicode
+            if (word !== '') words.push({ word, re: new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(word)}(?![\\p{L}\\p{N}_])`, 'giu') })
         } else substrings.push(row.toLowerCase())
     }
-    return { substrings, regexes }
+    return { substrings, words, regexes }
 }
 
-function scan(haystack: string, where: string, p: ReturnType<typeof parsePatterns>, hits: LeakHit[]): void {
-    const lower = haystack.toLowerCase()
-    for (const s of p.substrings) if (lower.includes(s)) hits.push({ where, pattern: s })
-    for (const r of p.regexes) if (r.re.test(haystack)) hits.push({ where, pattern: r.row })
+type Span = [start: number, end: number]
+
+// a substring row is matched by a case-insensitive REGEX rather than by
+// indexOf over a lowercased copy: one unicode character (İ) lowercases into
+// two, which slides every offset after it, and the offsets are what decide
+// whether a match sits inside a content hash. Compiled once per keyword.
+const subRe = new Map<string, RegExp>()
+const substringRegex = (s: string): RegExp => {
+    const hit = subRe.get(s)
+    if (hit != null) return hit
+    const re = new RegExp(escapeRegex(s), 'gi')
+    subRe.set(s, re)
+    return re
 }
 
-export type LeakGuardOpts = {
-    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
-    keywordFile?: string
-    /** extra text to scan (a commit message, a release note) */
-    text?: { label: string; content: string }[]
-    /** scan the staged diff + staged paths (default true) */
-    staged?: boolean
+/** every occurrence of every pattern, keyed by the id a hit reports. */
+function occurrences(haystack: string, p: ParsedPatterns): Map<string, Span[]> {
+    const found = new Map<string, Span[]>()
+    const push = (id: string, span: Span): void => {
+        const prev = found.get(id)
+        if (prev == null) found.set(id, [span])
+        else prev.push(span)
+    }
+    for (const s of p.substrings) for (const m of haystack.matchAll(substringRegex(s))) push(s, [m.index, m.index + m[0].length])
+    for (const w of p.words) for (const m of haystack.matchAll(w.re)) push(w.word, [m.index, m.index + m[0].length])
+    for (const r of p.regexes) {
+        const g = new RegExp(r.re.source, r.re.flags.includes('g') ? r.re.flags : r.re.flags + 'g')
+        for (const m of haystack.matchAll(g)) push(r.row, [m.index, m.index + m[0].length])
+    }
+    return found
+}
+
+// an npm/yarn integrity field, and any long base64 run. ONLY an entry that
+// asked for `inHashes` consults this: an api token is also a long base64 run,
+// so skipping these by default would be the guard going quiet on the exact
+// shape it exists to catch.
+const HASH_SPAN = /(?:sha\d{1,3}|md5)-[A-Za-z0-9+/=]{16,}|[A-Za-z0-9+/]{40,}={0,2}/gi
+
+const hashSpans = (text: string): Span[] => [...text.matchAll(HASH_SPAN)].map((m): Span => [m.index, m.index + m[0].length])
+
+const inside = (span: Span, spans: Span[]): boolean => spans.some(([a, b]) => span[0] >= a && span[1] <= b)
+
+/** a path selector: a repo-relative path, a bare basename, or a 'dir/' prefix. */
+function pathCovered(file: string | undefined, selectors: string[]): boolean {
+    if (file == null) return false
+    return selectors.some((s) => s === file || (s.endsWith('/') && file.startsWith(s)) || (!s.includes('/') && basename(file) === s))
+}
+
+export type LoadedAllow = LeakAllowEntry & { source: string }
+
+/** what the guard reads: one file's added lines, one staged path, or a text
+ *  the caller handed in (a commit message). */
+export type ScanTarget = { where: string; content: string; file?: string }
+
+/** the whole decision, with no git and no disk in it: which matches block,
+ *  which are waived, by whom, and why. */
+export function evaluateLeak(targets: ScanTarget[], p: ParsedPatterns, allow: LoadedAllow[]): { hits: LeakHit[]; waived: LeakWaiver[] } {
+    const hits: LeakHit[] = []
+    const waived: LeakWaiver[] = []
+    // one row per distinct (where, file, pattern): a keyword hit 40 times in
+    // one file is one finding
+    const seen = new Set<string>()
+    for (const t of targets) {
+        const found = occurrences(t.content, p)
+        if (found.size === 0) continue
+        let hashes: Span[] | null = null
+        for (const [id, spans] of found) {
+            const key = `${t.where} ${t.file ?? ''} ${id}`
+            if (seen.has(key)) continue
+            seen.add(key)
+            const fp = patternFingerprint(id)
+            const entry = allow.find((a) => {
+                if (a.paths != null && !pathCovered(t.file, a.paths)) return false
+                if (a.patterns != null && !a.patterns.some((x) => x === fp || x.toLowerCase() === id)) return false
+                if (a.inHashes === true) {
+                    hashes ??= hashSpans(t.content)
+                    if (!spans.every((s) => inside(s, hashes!))) return false
+                }
+                return true
+            })
+            if (entry == null) hits.push({ where: t.where, pattern: id, file: t.file })
+            else waived.push({ where: t.where, pattern: id, file: t.file, reason: entry.reason, source: entry.source })
+        }
+    }
+    return { hits, waived }
+}
+
+const ALLOW_KEYS = ['reason', 'paths', 'patterns', 'inHashes']
+const FINGERPRINT = /^fp:[0-9a-f]{12}$/
+
+/** why an entry cannot be used, or null. `tracked` = the source is committed
+ *  (repo.config.ts), where a literal pattern publishes the private word the
+ *  guard exists to keep out of git. */
+export function leakAllowProblem(entry: unknown, where: string, tracked: boolean): string | null {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) return `${where}: every entry is an object`
+    const e = entry as Record<string, unknown>
+    for (const k of Object.keys(e)) if (!ALLOW_KEYS.includes(k)) return `${where}: unknown key '${k}' (known: ${ALLOW_KEYS.join(', ')})`
+    if (typeof e['reason'] !== 'string' || e['reason'].trim() === '') return `${where}: needs a 'reason' — a waiver nobody can judge later is a hole`
+    if (e['paths'] == null && e['patterns'] == null)
+        return `${where}: needs 'paths' or 'patterns' — an entry with neither waives every pattern in every file, which is the guard switched off`
+    for (const k of ['paths', 'patterns'] as const) {
+        const v = e[k]
+        if (v == null) continue
+        if (!Array.isArray(v) || v.length === 0 || v.some((x) => typeof x !== 'string' || x.trim() === ''))
+            return `${where}: '${k}' is a non-empty array of non-empty strings`
+    }
+    if (e['inHashes'] != null && typeof e['inHashes'] !== 'boolean') return `${where}: 'inHashes' is a boolean`
+    if (tracked)
+        for (const x of (e['patterns'] as string[] | undefined) ?? [])
+            if (!FINGERPRINT.test(x))
+                return `${where}: '${x}' — a tracked allowlist names a pattern by FINGERPRINT (fp:…, printed beside every hit), never by value, or the private keyword lands in git`
+    return null
+}
+
+/** every problem in a declared allowlist. `defineRepo` throws on the first. */
+export function leakAllowProblems(entries: unknown, where: string, tracked: boolean): string[] {
+    if (!Array.isArray(entries)) return [`${where}: leakAllow is an array of entries`]
+    return entries.map((e, i) => leakAllowProblem(e, `${where}[${i}]`, tracked)).filter((x): x is string => x != null)
 }
 
 /** the machine-global list every repo's guard also reads: one private list
@@ -62,36 +235,138 @@ export function globalKeywordFile(): string | null {
     return existsSync(p) ? p : null
 }
 
+/** the machine-global allowlist, the twin of the keyword file. It is private,
+ *  so it may name a pattern by value as well as by fingerprint. */
+export function globalAllowFile(): string | null {
+    const home = process.env.HOME ?? ''
+    if (home === '') return null
+    const p = join(home, '.rv-private', 'leak-allow.json')
+    return existsSync(p) ? p : null
+}
+
+/** read an allowlist file (`LeakAllowEntry[]` as JSON). A file that will not
+ *  parse, or an entry that cannot be used, is a NOTE and never a failure: a
+ *  waiver that does not load leaves the guard stricter, never looser. */
+export function loadAllowFile(path: string, tracked: boolean): { entries: LoadedAllow[]; notes: string[] } {
+    let parsed: unknown
+    try { parsed = JSON.parse(readFileSync(path, 'utf8')) }
+    catch (e) { return { entries: [], notes: [`${path} is not readable JSON (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — its waivers are IGNORED`] } }
+    if (!Array.isArray(parsed)) return { entries: [], notes: [`${path} holds an array of allowlist entries — its waivers are IGNORED`] }
+    const entries: LoadedAllow[] = []
+    const notes: string[] = []
+    parsed.forEach((raw, i) => {
+        const problem = leakAllowProblem(raw, `${path}[${i}]`, tracked)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else entries.push({ ...(raw as LeakAllowEntry), source: `${basename(path)}[${i}]` })
+    })
+    return { entries, notes }
+}
+
+export type LeakGuardOpts = {
+    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
+    keywordFile?: string
+    /** extra text to scan (a commit message, a release note) */
+    text?: { label: string; content: string }[]
+    /** scan the staged diff + staged paths (default true) */
+    staged?: boolean
+    /** the repo's declared waivers (repo.config.ts hooks.leakAllow). Tracked,
+     *  so fingerprints only. */
+    allow?: LeakAllowEntry[]
+    /** override the machine-global allowlist path; null reads none */
+    allowFile?: string | null
+}
+
+/** git c-quotes a path that carries a space or a non-ascii byte. */
+function unquotePath(p: string): string {
+    if (!p.startsWith('"')) return p
+    try { return JSON.parse(p) as string } catch { return p.slice(1, -1) }
+}
+
+/** `@@ -old,n +new,m @@`, the only line that says how long a hunk body is. */
+const HUNK_HEADER = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/
+
+/** ADDED lines only, grouped by the file that receives them: what this commit
+ *  puts INTO the object store. Removed and context lines are already in
+ *  history, and a commit that DELETES private content must never be blocked by
+ *  that content. The grouping is what lets a waiver name a file.
+ *
+ *  A `+++ x` line is a file header only OUTSIDE a hunk body. Inside one it is
+ *  an added line whose own text starts with `++`, and reading it as a header
+ *  is a hole in both directions: `++ /dev/null` would drop every added line
+ *  after it in that file, and `++ b/bun.lock` would file them under a name a
+ *  waiver covers. So the hunk body is COUNTED, from the size its header
+ *  declares. A header this does not recognise (a combined `@@@` diff) opens an
+ *  unbounded body that only the next file closes, which is the safe direction:
+ *  content is still scanned, and no line inside it can name a file. */
+export function addedLinesByFile(diff: string): { file: string; content: string }[] {
+    const out: { file: string; content: string }[] = []
+    let current: { file: string; lines: string[] } | null = null
+    let oldLeft = 0
+    let newLeft = 0
+    const flush = (): void => {
+        if (current != null && current.lines.length > 0) out.push({ file: current.file, content: current.lines.join('\n') })
+        current = null
+    }
+    const add = (line: string): void => { if (current != null) current.lines.push(line.slice(1)) }
+    for (const line of diff.split('\n')) {
+        // a `diff --git ` at column 0 can never be diff CONTENT: a content line
+        // always carries its ' ', '+' or '-' prefix first
+        if (line.startsWith('diff --git ')) {
+            flush()
+            oldLeft = 0
+            newLeft = 0
+        } else if (oldLeft > 0 || newLeft > 0) {
+            if (line.startsWith('+')) { newLeft--; add(line) }
+            else if (line.startsWith('-')) oldLeft--
+            else if (!line.startsWith('\\')) { oldLeft--; newLeft-- } // '' counts for neither
+        } else if (line.startsWith('@@')) {
+            const h = HUNK_HEADER.exec(line)
+            oldLeft = h == null ? Infinity : h[1] == null ? 1 : Number(h[1])
+            newLeft = h == null ? Infinity : h[2] == null ? 1 : Number(h[2])
+        } else if (line.startsWith('+++ ')) {
+            flush()
+            const p = unquotePath(line.slice(4).trim())
+            current = p === '/dev/null' ? null : { file: p.startsWith('b/') ? p.slice(2) : p, lines: [] }
+        } else if (line.startsWith('+')) add(line) // a stray added line outside any hunk is still content
+    }
+    flush()
+    return out
+}
+
 export function runLeakGuard(root: string, o: LeakGuardOpts = {}): LeakGuardResult {
     const rel = o.keywordFile ?? '.rv-private/banned-keywords.txt'
     const file = join(root, rel)
     const sources = [existsSync(file) ? file : null, globalKeywordFile()].filter((f): f is string => f != null)
     if (sources.length === 0) return { status: 'skipped', reason: `${rel} not found and no ~/.rv-private/banned-keywords.txt — no keyword list, no leak guard` }
     const patterns = parsePatterns(sources.map((f) => readFileSync(f, 'utf8')).join('\n'))
-    const count = patterns.substrings.length + patterns.regexes.length
+    const count = patterns.substrings.length + patterns.words.length + patterns.regexes.length
     if (count === 0) return { status: 'skipped', reason: `keyword file(s) have no patterns (${sources.join(', ')})` }
 
-    const hits: LeakHit[] = []
+    const notes: string[] = []
+    const allow: LoadedAllow[] = []
+    ;(o.allow ?? []).forEach((e, i) => {
+        const problem = leakAllowProblem(e, `repo.config.ts hooks.leakAllow[${i}]`, true)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else allow.push({ ...e, source: `repo.config.ts hooks.leakAllow[${i}]` })
+    })
+    const globalAllow = o.allowFile === undefined ? globalAllowFile() : o.allowFile
+    if (globalAllow != null && existsSync(globalAllow)) {
+        const g = loadAllowFile(globalAllow, false)
+        allow.push(...g.entries)
+        notes.push(...g.notes)
+    }
+
+    const targets: ScanTarget[] = []
     if (o.staged !== false) {
-        // staged CONTENT (what lands in the object store) and staged PATHS
-        // (a filename can leak as loudly as a line of code)
         const diff = Bun.spawnSync(['git', 'diff', '--cached'], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
-        if (diff.exitCode === 0) {
-            // ADDED lines only: what this commit puts INTO the object store.
-            // removed/context lines are already in history, and a commit that
-            // deletes private content must never be blocked by that content
-            const added = diff.stdout.toString().split('\n')
-                .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
-                .join('\n')
-            scan(added, 'staged content', patterns, hits)
-        }
+        if (diff.exitCode === 0)
+            for (const f of addedLinesByFile(diff.stdout.toString())) targets.push({ where: 'staged content', file: f.file, content: f.content })
+        // a filename can leak as loudly as a line of code
         const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
-        if (names.exitCode === 0) scan(names.stdout.toString(), 'staged path', patterns, hits)
+        if (names.exitCode === 0) for (const n of names.stdout.toString().split('\n')) if (n.trim() !== '') targets.push({ where: 'staged path', file: n, content: n })
     }
-    for (const t of o.text ?? []) scan(t.content, t.label, patterns, hits)
+    for (const t of o.text ?? []) targets.push({ where: t.label, content: t.content })
 
-    // one row per distinct (where, pattern) — a keyword hit 40 times is one finding
-    const seen = new Set<string>()
-    const unique = hits.filter((h) => { const k = h.where + ' ' + h.pattern; if (seen.has(k)) return false; seen.add(k); return true })
-    return unique.length > 0 ? { status: 'hit', hits: unique, patterns: count } : { status: 'clean', patterns: count }
+    const { hits, waived } = evaluateLeak(targets, patterns, allow)
+    return hits.length > 0 ? { status: 'hit', hits, patterns: count, waived, notes } : { status: 'clean', patterns: count, waived, notes }
 }

package/src/hooks/run-hooks.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
-import { globalKeywordFile, maskPattern, runLeakGuard } from './leak-guard.ts'
+import { globalAllowFile, globalKeywordFile, maskPattern, patternFingerprint, runLeakGuard, type LeakAllowEntry, type LeakHit, type LeakWaiver } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -21,6 +21,14 @@ export type HooksConfig = {
     commitMsg?: { id: string; cmd: string[] }[]
     /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
     keywordFile?: string
+    /** known-good leak-guard matches this repo waives: a lockfile whose
+     *  dependency names or integrity hashes collide with a keyword is the
+     *  motivating case. Each entry carries a reason, and a waiver that fires
+     *  PRINTS, so nothing passes silently. This file is tracked, so an entry
+     *  names a pattern by fingerprint (`fp:…`, printed beside every hit) and
+     *  never by value. The machine-global twin is ~/.rv-private/leak-allow.json.
+     *  hooks/leak-guard.ts */
+    leakAllow?: LeakAllowEntry[]
     /** staged-path prefixes that may never enter git (local state like
      *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
     blockedPaths?: string[]
@@ -148,6 +156,29 @@ function seedKeywordFile(root: string, keywordFile?: string): string | null {
 
 export type GateOutcome = { id: string; ok: boolean; lines: string[] }
 
+/** a hit line: the masked pattern plus its FINGERPRINT, which is the token a
+ *  waiver is written against, so nobody has to type the private word to
+ *  exempt it. The file rides along for a content hit; a staged-PATH hit adds
+ *  nothing, because there the path IS what matched. */
+const hitLine = (x: LeakHit): string =>
+    `      ${x.where}${x.where === 'staged content' && x.file != null ? ` ${x.file}` : ''}: ${maskPattern(x.pattern)} [${patternFingerprint(x.pattern)}]`
+
+/** what the allowlist let through, one line per waiver. An allowlist that
+ *  fires invisibly is a silent weakening, so a waived match is as loud as a
+ *  blocked one and carries the reason its author wrote. */
+function waivedLines(waived: LeakWaiver[]): string[] {
+    const rows = new Map<string, { pattern: string; reason: string; source: string; targets: Set<string> }>()
+    for (const w of waived) {
+        const key = `${w.pattern} ${w.source}`
+        const row = rows.get(key) ?? { pattern: w.pattern, reason: w.reason, source: w.source, targets: new Set<string>() }
+        row.targets.add(w.file ?? w.where)
+        rows.set(key, row)
+    }
+    return [...rows.values()].map(
+        (r) => `      waived ${maskPattern(r.pattern)} [${patternFingerprint(r.pattern)}] in ${r.targets.size} target(s) — ${r.reason} (${r.source})`,
+    )
+}
+
 /** the pre-commit gate: built-in leak guard, then the repo's own commands.
  *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
@@ -156,16 +187,27 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
     const h = config.hooks ?? {}
     const out: GateOutcome[] = []
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, allow: h.leakAllow })
         if (r.status === 'skipped') out.push({ id: 'leak-guard', ok: true, lines: [`skip: leak-guard (${r.reason})`] })
-        else if (r.status === 'clean') out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean (${r.patterns} pattern(s))`] })
+        else if (r.status === 'clean') out.push({
+            id: 'leak-guard',
+            ok: true,
+            lines: [
+                `ok: leak-guard clean (${r.patterns} pattern(s)${r.waived.length === 0 ? '' : `, ${r.waived.length} waived`})`,
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
+            ],
+        })
         else out.push({
             id: 'leak-guard',
             ok: false,
             lines: [
                 `FAIL: leak-guard matched ${r.hits.length} banned pattern(s) — this commit would leak private content`,
-                ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`),
+                ...r.hits.map(hitLine),
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
                 `      fix: remove the content, or edit the keyword file if the pattern is wrong`,
+                `      a known-good match: repo.config.ts hooks.leakAllow += { reason, paths, patterns: ['<the fp: above>'] }`,
             ],
         })
     }
@@ -242,9 +284,11 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
     // the leak guard also reads the MESSAGE, a private name pasted into a
     // commit body is as public as one pasted into a file
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, text: [{ label: 'commit message', content: message }] })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, allow: h.leakAllow, text: [{ label: 'commit message', content: message }] })
         if (r.status === 'hit')
-            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`)] })
+            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map(hitLine), ...waivedLines(r.waived)] })
+        else if (r.status === 'clean' && r.waived.length > 0)
+            out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean in the commit message (${r.waived.length} waived)`, ...waivedLines(r.waived)] })
     }
     for (const c of h.commitMsg ?? []) {
         const r = await spawnWithTimeout([...c.cmd, messageFile], { cwd: root, timeoutMs: 60_000 })
@@ -265,8 +309,12 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     // a gate listed as active but unable to fire is worse than no listing:
     // this surface exists so nobody has to guess
     const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.rv-private list)`
+    // a waiver nobody can enumerate is a hole nobody can audit: the count of
+    // declared exemptions belongs on the same surface as the gate itself
+    const waivers = (h.leakAllow ?? []).length + (globalAllowFile() != null ? 1 : 0)
+    const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.rv-private/leak-allow.json'}`
     return [
-        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt`,
+        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),

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

@@ -22,6 +22,7 @@ import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
 import { BUILTIN_RULE_IDS, validateRules } from './rules/rule-registry.ts'
 import type { Rule } from './rules/rule.ts'
+import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
@@ -89,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
@@ -202,6 +203,12 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
     // a smoke typo would land as a run that visits nothing and exits 0
     if (c.smoke != null) validateSmokeConfig(c.smoke)
+    // a leak-guard waiver is the one config row that can make a gate quieter,
+    // so a malformed one dies here rather than being dropped at commit time
+    if (c.hooks?.leakAllow != null) {
+        const problems = leakAllowProblems(c.hooks.leakAllow, 'defineRepo: hooks.leakAllow', true)
+        if (problems.length > 0) throw new Error(problems[0])
+    }
     if (c.credsReadCommand != null && !/\{name\}/.test(c.credsReadCommand))
         throw new Error(`defineRepo: credsReadCommand must carry {name} (and {field} for get | account), e.g. 'my-secrets {field} {name}'`)
     if (c.smoke?.login != null && (c.credsReadCommand ?? '') === '')

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 })