rvlib-shipkit 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.33.0
+
+- **ONE WAY IN, enforced. A wired repo's `test`, `lint` and `typecheck` scripts route through shipkit, and the harness refuses the raw runner.** Measured in a real wired repo before this: `"lint": "eslint ."`, `"test": "bun test"`, no ci script, an empty `.claude/`. An agent doing the obvious thing ran the tool, shipkit never heard the call, and the cache it was building was worthless. **This changes the shape of every wired repo's package.json**, and 0.32.0 already shipped the first half of it without saying so, which is the gap this note closes. Rule SK001 (blocking, autofixable) now FAILs a governed script that runs the tool directly; the fix slides the body to `<id>:raw` and makes the name `shipkit ci --only <id>`. `<id>:raw` is what the gate itself runs, and what you use to iterate on one suite. Those THREE names only: `imports:check` and `cycles` are shipkit's own vocabulary, and `fmt` is the slot the fix pass invokes by script, so routing it would make the fixer call itself. `resolveFloor` moved to `core/floor.ts` and refuses to run a routed script, which spawns the gate from inside the gate.
+- **New rule SK013 (blocking, autofixable) writes the harness half**, because a package.json cannot reach it: `bun test` is a bun builtin and no script can intercept it. A tracked `.claude/settings.json` gets `permissions.deny` for every raw runner plus a PreToolUse guard, both rendered from ONE table. The deny is the floor, unbypassable in either direction; the guard is the messenger, because a bare deny tells the model only that it was denied and it then goes hunting for another runner. Every refusal names the shipkit command, the narrow way in, and the exact line that lifts it. The guard reads the deny list out of the settings FILE, so deleting one `Bash(...)` line lifts both mechanisms at once. It also catches what a prefix rule cannot (`CI=1 bun test`, `./node_modules/.bin/tsc`) and segments at quote depth zero, so a commit message quoting a runner is data. SK013 FAILs when the declared guard script does not resolve: a hook that errors refuses nothing.
+- **`shipkit init` repairs an existing repo, not just a fresh one**, calling the same fixers `shipkit check --fix` runs. That is the half that matters, because the repos that need this most already exist. `shipkit start` inherits it.
+- **A `--only` run repairs the mechanical slots ALONE.** The structural rule fixers rewrite package.json and repo config, and arming rewrites `hooks/`. That is the right price for the full gate and the wrong one for `bun run test`, which now routes here: the reflex verb must not leave files in an agent's diff that it never wrote, and under CI a formatting rewrite came back as a test failure.
+- **Escaping it**: delete the `Bash(<runner>*)` line from `.claude/settings.json`; or `repo.config.ts oneWayIn: { exempt: ['test'] }`, which drops the script requirement and the shell rules together (an unknown name throws at config load); a slot turned off with `defaults: { lint: false }` is exempt already. `bun run test:raw <name filter>` stays open for iterating on one suite. A repo with sub-packages gives each one its own `test:raw`, or the escape does not reach where the work is. The formatter is deliberately not denied at all.
+- `--allow-dirty` now says WHY it is safe in one place and not the other: `npm publish` packs the working tree, not the commit, so dirt in other paths cannot reach the tarball and dirt inside the unit ships a half-written file under a tag that describes something else.
+
 ## 0.32.0
 
 - **`shipkit pb collection <name>` scaffolds a PocketBase collection's whole UI folder.** Building a CRUD screen meant retyping a schema that already exists in the app's generated types, one column at a time, and the boring half of that is exactly where a column goes missing. The command reads `src/pb.types.ts` (`.tsx` and `.d.ts` too), resolves one collection, and writes `src/collections/<name>/`: `columns.tsx` with one entry per response field, `card.tsx`, `grid.tsx` over `LiveGrid`, `form.tsx` (a create/edit modal writing through `db` fire and forget), and an `index.ts` calling `defineCollectionUI`. It then registers the folder in `src/collections/index.ts`, creating that file when it is the first one, because a collection folder nothing imports is dead code whose failure mode is a runtime throw. A field the schema cannot turn into a cell on its own (relation, file, json, raw html) is emitted COMMENTED with the reason rather than dropped, because a missing column is invisible and a commented one takes ten seconds to accept or delete. The card leads on the fields a human reads, not on the first three of an alphabetical record block, and the label picks the first of `name`, `label`, `title`, `number`, `code`, `email`, else `id`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.32.0",
+    "version": "0.33.0",
     "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",
     "type": "module",
@@ -28,6 +28,9 @@
         "mobx": "^7.0.0",
         "mobx-react-lite": "^5.0.0"
     },
+    "scripts": {
+        "test:raw": "bun test"
+    },
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",

package/src/core/canonical-scripts.ts

@@ -60,7 +60,9 @@ export function routedBody(id: string, opts: ScriptStyle = {}): string {
  *  under a shipkit checkout (a repo calling rvlib's source-graph cli by path)
  *  is not a route back in. */
 export function routesToShipkit(body: string): boolean {
-    return /\bshipkit\b/.test(body) && /\bci\b/.test(body)
+    // the `ci` verb must belong to the shipkit invocation, not merely appear
+    // somewhere in the line: `shipkit contracts && bun run x:ci` routes nothing
+    return /\bshipkit\b\S*(?:\s+\S+)*?\s+ci(?:\s|$)/.test(body.split(/&&|\|\||;/)[0] ?? body)
 }
 
 // recover the consumption style from existing scripts: any shipkit command

package/src/core/one-way-in-policy.ts

@@ -0,0 +1,183 @@
+// ONE WAY IN, the harness half (build/shipkit.md). The package.json half
+// (rule SK001) routes `bun run test` into shipkit, but `bun test` is a bun
+// BUILTIN: no script can intercept it, so a package.json alone leaves the
+// reflex wide open. Claude Code permission rules can close it.
+//
+// ONE table, two renderings, because two hand-kept lists drift:
+//   - `permissions.deny` in .claude/settings.json — declarative, unbypassable
+//     (deny beats allow at every settings level, and bypassPermissions mode
+//     does not lift it), and it survives a missing bun.
+//   - a PreToolUse hook — the only thing that can put a REASON in front of the
+//     model. A bare deny says "Permission to use Bash with command bun test
+//     has been denied." and nothing else, so the agent goes looking for
+//     another way in, which is the failure this whole file exists to prevent.
+// The deny is the floor and the hook is the messenger. When the hook cannot
+// run, enforcement degrades to terse rather than to nothing.
+//
+// Subprocesses are NOT intercepted (verified): shipkit spawning oxlint or
+// `bun run test:raw` from inside a permitted `shipkit ci` is invisible to
+// these rules, which is exactly what makes the gate itself still work.
+
+export type RawRunner = {
+    /** the command head as an agent types it — the deny rule is this + `*` */
+    head: string
+    /** the floor slot it answers, so ONE exemption governs the script name and
+     *  the shell command together: a repo that keeps `test` raw is not then
+     *  refused `bun test` */
+    slot: 'test' | 'lint' | 'typecheck'
+    /** the shipkit command that answers the same question, cache and all */
+    use: string
+    /** the narrower way in, when there is one: iterating on a single repro
+     *  test while you fix a bug is not a verification and stays normal. A
+     *  FILTER, not a path: `bun run` quotes what it forwards, and bun reads a
+     *  quoted path as a name filter that then matches nothing */
+    iterate?: string
+}
+
+// the house stack, plus the foreign runners a wired repo is actually found
+// carrying. Kept tight on purpose: a deny an agent hits for no good reason
+// teaches it to route around the whole file.
+export const RAW_RUNNERS: readonly RawRunner[] = [
+    { head: 'bun test', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'bunx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'npx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'npx jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'bunx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
+    { head: 'npx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
+    { head: 'tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
+    { head: 'bunx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'npx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'npx eslint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'eslint', slot: 'lint', use: 'shipkit ci --only lint' },
+]
+
+// the FORMATTER is deliberately absent, and that is not an oversight. It
+// answers no cached question and produces no green anyone could mistake for a
+// verification, shipkit's own fix pass runs it BY SCRIPT (`bun run fmt`), and
+// denying the bare binary while that stays open would be theatre. `shipkit ci`
+// formats before it gates, which is the only reason the reflex matters at all.
+
+/** the `permissions.deny` entries, in the syntax Claude Code matches:
+ *  `Bash(<head>*)` is a prefix match, and a compound command is checked one
+ *  segment at a time, so `cd x && bun test` is caught too */
+export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
+    const off = new Set(exemptSlots)
+    return RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`)
+}
+
+/** what a refusal says. Never just the ban: a refusal with no replacement
+ *  sends the agent hunting for another runner. `segment` is the part of the
+ *  command that offended, shown only when it says more than the head already
+ *  does: a long compound refused on `CI=1 bun test --timeout 5` otherwise
+ *  leaves the reader guessing which of its clauses was the problem */
+export function refusal(r: RawRunner, segment?: string): string {
+    const alt = r.iterate == null ? '' : `, or \`${r.iterate}\` to iterate on ONE suite while you fix a bug`
+    const which = segment == null || segment.trim() === '' || segment.trim() === r.head ? '' : ` (refused on \`${segment.trim().slice(0, 80)}\`)`
+    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit.md, ONE WAY IN).`
+}
+
+/** shell wrappers that do not change what is being run */
+const WRAPPERS = new Set(['time', 'timeout', 'nice', 'nohup', 'stdbuf', 'command', 'builtin', 'sudo', 'env'])
+
+/** the heads a settings file actually denies. The guard asks THE FILE rather
+ *  than the table, so deleting a `Bash(...)` line lifts the deny AND the
+ *  hook's refusal in one edit: two mechanisms an agent has to find and lift
+ *  separately is the deny it cannot escape, which is worse than the disease */
+export function deniedHeads(settings: unknown): Set<string> {
+    const deny = (settings as { permissions?: { deny?: unknown } } | null)?.permissions?.deny
+    const out = new Set<string>()
+    if (!Array.isArray(deny)) return out
+    for (const rule of deny) {
+        const m = typeof rule === 'string' ? /^Bash\((.+?)\*?\)$/.exec(rule) : null
+        if (m != null) out.add(m[1]!.trim())
+    }
+    return out
+}
+
+/** a word that could be the name of a program. Anything carrying a quote, a
+ *  parenthesis or a bracket is prose or code, not an invocation, and matching
+ *  it is how a guard earns a reputation for crying wolf */
+const PROGRAM_WORD = /^[\w./@+-]+$/
+
+/** split a command line on the shell operators, at QUOTE DEPTH ZERO only.
+ *  Without that, `git commit -m "why cd x && bun test is refused"` splits
+ *  inside the message and the second half reads as a command. House commit
+ *  bodies are dense and multi-line, so this is not a corner case here, it is
+ *  the most common shape of command an agent runs. */
+export function shellSegments(command: string): string[] {
+    // everything after a heredoc opener is the document, never a command
+    const shell = command.split(/<<-?\s*['"]?\w+/)[0] ?? command
+    const out: string[] = []
+    let cur = ''
+    let quote: '"' | "'" | null = null
+    for (let i = 0; i < shell.length; i++) {
+        const ch = shell[i]!
+        if (quote != null) {
+            cur += ch
+            if (ch === '\\' && quote === '"') { cur += shell[++i] ?? ''; continue }
+            if (ch === quote) quote = null
+            continue
+        }
+        if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue }
+        if (ch === '\n' || ch === ';' || ch === '|' || ch === '&') {
+            // `&&` and `||` are one operator, and a lone `&` backgrounds
+            if ((ch === '&' || ch === '|') && shell[i + 1] === ch) i++
+            out.push(cur)
+            cur = ''
+            continue
+        }
+        cur += ch
+    }
+    out.push(cur)
+    return out
+}
+
+/** the raw runner this shell command reaches for, plus the segment that
+ *  offended, or null.
+ *
+ *  Deliberately conservative in BOTH directions. It must catch the forms a
+ *  prefix deny rule misses (a leading `CI=1`, `./node_modules/.bin/tsc`), and
+ *  it must never fire on a command that merely CONTAINS the words: a heredoc
+ *  body is data and so is a quoted commit message, and a false refusal teaches
+ *  an agent to route around the whole file. So: the heredoc body is dropped,
+ *  segments are cut at quote depth zero, each is reduced to its first program
+ *  word, and that word must match a head exactly or as the basename of a path.
+ *  Longest head first, so `bunx tsc` is never reported as `tsc`. `only`
+ *  narrows to the heads this repo really denies. */
+export function rawRunnerIn(command: string, only?: ReadonlySet<string>): RawRunner | null {
+    return rawRunnerHit(command, only)?.runner ?? null
+}
+
+export function rawRunnerHit(command: string, only?: ReadonlySet<string>): { runner: RawRunner; segment: string } | null {
+    const heads = [...RAW_RUNNERS]
+        .filter((r) => only == null || only.has(r.head))
+        .sort((a, b) => b.head.length - a.head.length)
+    for (const seg of shellSegments(command)) {
+        let s = seg.trim().replace(/^[(){}\s]+/, '')
+        // leading VAR=value assignments, then a wrapper word, repeatedly. A
+        // wrapper's own flags and durations go with it (`timeout 60 bun test`)
+        let wrapped = false
+        for (;;) {
+            const next = s.replace(/^\w+=(?:"[^"]*"|'[^']*'|\S*)\s+/, '')
+            if (next !== s) { s = next; continue }
+            const w = /^(\S+)\s+/.exec(s)
+            if (w != null && WRAPPERS.has(w[1]!.split('/').pop() ?? '')) { s = s.slice(w[0].length); wrapped = true; continue }
+            if (wrapped && w != null && /^(?:-\S*|\d+[smhd]?)$/.test(w[1]!)) { s = s.slice(w[0].length); continue }
+            break
+        }
+        const words = s.split(/\s+/).filter((w) => w !== '')
+        const first = words[0]
+        if (first == null || !PROGRAM_WORD.test(first)) continue
+        // a path-qualified binary counts: ./node_modules/.bin/tsc IS tsc
+        const program = first.split('/').pop() ?? first
+        for (const r of heads) {
+            const parts = r.head.split(' ')
+            if (parts[0] !== program) continue
+            if (parts.length === 1 || words[1] === parts[1]) return { runner: r, segment: seg }
+        }
+    }
+    return null
+}

package/src/core/run-ci.ts

@@ -102,8 +102,16 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
+    // a NARROWED run repairs only the mechanical slots. The structural rule
+    // fixers rewrite package.json and repo config, and arming rewrites hooks/:
+    // that is the right price for the full gate and the wrong one for
+    // `bun run test`, which routes here and must answer the one question its
+    // name promises without leaving files in the agent's diff that it never
+    // wrote. Under CI it is worse than surprising, a formatting rewrite comes
+    // back as a test failure.
+    const narrowed = (o.onlyIds ?? []).length > 0
     if (o.fix !== false)
-        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, armHooks: o.armHooks === true, print: sink })).failed
+        fixFailed = (await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink })).failed
     else sink('skip: fix pass (--no-fix)')
     const all = allTasks(c, root)
     const { disabled, unfilled } = all
@@ -124,7 +132,14 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
     // look like a full one (the fresh-repo floor gap)
-    for (const u of unfilled) sink(`skip: ${u.id} (${u.reason})`)
+    for (const u of unfilled) {
+        sink(`skip: ${u.id} (${u.reason})`)
+        // asked for BY NAME and unfillable: this is where an agent lands after
+        // the harness refused it the raw runner, so the line says what to add
+        // rather than leaving it with `unknown task id` and no next move
+        if ((o.onlyIds ?? []).includes(u.id))
+            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
+    }
     // the release survey is ~4s of network that five discovered checks need
     // and the TASKS do not. Started HERE it overlaps lint/typecheck/test and
     // costs the run nothing; started inside the first check that wants it, it

package/src/hooks/one-way-in-guard.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+// the PreToolUse guard for ONE WAY IN (core/one-way-in-policy.ts owns the
+// table and the wording). Its ONE job is to refuse a raw runner with the
+// shipkit command to type instead: `permissions.deny` already blocks these,
+// but a bare deny tells the model only that it was denied, and a refusal with
+// no replacement just sends it looking for another way in.
+//
+// It runs before EVERY Bash call, so it stays a leaf: one tiny import, one
+// small json read, no clipanion, no repo config. Anything it cannot decide it
+// waves through, because a guard that fails closed on its own bugs would wedge
+// a repo with no way to tell why, and `permissions.deny` is still the floor
+// underneath it. Measured at ~10ms per call.
+import { deniedHeads, rawRunnerHit, refusal } from '../core/one-way-in-policy.ts'
+
+const input = await Bun.stdin.text()
+let command = ''
+try {
+    const ev = JSON.parse(input) as { tool_name?: string; tool_input?: { command?: string } }
+    if (ev.tool_name !== 'Bash') process.exit(0)
+    command = ev.tool_input?.command ?? ''
+} catch {
+    process.exit(0)
+}
+// the settings file is the authority on WHICH runners this repo refuses, so
+// deleting one `Bash(...)` line lifts the deny and this refusal together
+const settingsPath = `${process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd()}/.claude/settings.json`
+let denied: Set<string>
+try {
+    denied = deniedHeads(await Bun.file(settingsPath).json())
+} catch {
+    process.exit(0)
+}
+const hit = command === '' || denied.size === 0 ? null : rawRunnerHit(command, denied)
+if (hit == null) process.exit(0)
+// exit 2 is the block: stderr becomes the reason the model reads
+// naming the segment earns its place only when the command had MORE in it:
+// on a bare call it repeats the head back at the reader
+console.error(refusal(hit.runner, hit.segment.trim() === command.trim() ? undefined : hit.segment))
+process.exit(2)

package/src/init-repo.ts

@@ -9,7 +9,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
-import { hasTestFiles } from './rules/SK001-package-json-shape.ts'
+import { hasTestFiles, packageJsonShape } from './rules/SK001-package-json-shape.ts'
+import { oneWayInPolicy } from './rules/SK013-one-way-in-policy.ts'
 import { reportToMotherhome } from './core/motherhome.ts'
 import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
@@ -67,6 +68,9 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         const cfg = await loadRepoConfig(root)
         const g = await gitignorePolicy.fix!({ root, config: cfg })
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        // the repos that need ONE WAY IN most are the ones that already exist,
+        // so a re-run REPAIRS rather than only seeding a fresh checkout
+        await repairOneWayIn(root, cfg, p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -99,6 +103,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // `shipkit check --fix SK004`, one code path
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+    await repairOneWayIn(root, defineRepo({ name }), p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -128,3 +133,16 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     if (opts.noPublish !== true) p('next: `shipkit ci` is the gate — run it to check your work')
     return 0
 }
+
+/** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
+ *  (build/shipkit.md). Nothing here is a second implementation: rule SK001
+ *  routes the package.json scripts, rule SK013 writes the harness policy, and
+ *  init just calls them so a wired repo is born enforced and a re-run repairs
+ *  one that was not. The deny is a RESTRICTION, which is why it lands
+ *  unconditionally where the scaffold's allow list stays opt in. */
+async function repairOneWayIn(root: string, config: Parameters<typeof defineRepo>[0], p: (line: string) => void): Promise<void> {
+    const pkg = await packageJsonShape.fix!({ root, config })
+    if (pkg.changed) p(`ok: package.json — ${pkg.summary}`)
+    const policy = await oneWayInPolicy.fix!({ root, config })
+    p(policy.changed ? `ok: ${policy.summary}` : `ok: .claude/settings.json already closes every raw runner`)
+}

package/src/rules/SK001-package-json-shape.ts

@@ -12,7 +12,8 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { canonicalBodies, conditionalBodies, inferBin, ROUTED_SCRIPTS, rawName, routedBody, routesToShipkit } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
-import { resolveFloor, type RepoConfig } from '../repo-config.ts'
+import { resolveFloor } from '../core/floor.ts'
+import type { RepoConfig } from '../repo-config.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
 
 type Pkg = { name?: string; private?: boolean; license?: string; scripts?: Record<string, string> }

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

@@ -0,0 +1,136 @@
+// SK013 — the harness half of ONE WAY IN (build/shipkit.md). Rule SK001 routes
+// the package.json scripts, and that alone is not enough: `bun test` is a bun
+// BUILTIN, so no script can intercept it and the reflex stays open. This rule
+// makes the repo carry the two things that CAN close it, and repairs them:
+//
+//   - `permissions.deny` — declarative and unbypassable (deny beats allow at
+//     every settings level, and bypassPermissions does not lift it)
+//   - a PreToolUse hook — the only way to put a REASON in front of the model.
+//     A bare deny says only that the call was denied, and a refusal with no
+//     replacement sends the agent looking for another runner.
+//
+// Both are generated from ONE table (core/one-way-in-policy.ts). The file is
+// 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, writeFileSync } from 'fs'
+import { dirname, 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'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const OWNER = 'build/shipkit.md'
+export const SETTINGS_PATH = '.claude/settings.json'
+
+type Settings = {
+    permissions?: { deny?: string[] }
+    hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<{ type?: string; command?: string }> }>>
+}
+
+/** slots this repo does not route, so it must not be refused the shell command
+ *  either: ONE declaration governs the script name and the raw call together */
+export function exemptSlots(c: RepoConfig): Set<string> {
+    const off = new Set(c.oneWayIn?.exempt ?? [])
+    for (const [slot, def] of Object.entries(c.defaults ?? {})) if (def === false) off.add(slot)
+    return off
+}
+
+/** how the hook invokes the guard. `$CLAUDE_PROJECT_DIR` because a hook's cwd
+ *  is not promised to be the repo root */
+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}"`
+}
+
+const readSettings = (root: string): Settings | null => {
+    const p = join(root, SETTINGS_PATH)
+    if (!existsSync(p)) return null
+    try { return JSON.parse(readFileSync(p, 'utf8')) as Settings } catch { return null }
+}
+
+const guardHookCommand = (s: Settings): string | null => {
+    for (const m of s.hooks?.['PreToolUse'] ?? [])
+        for (const h of m.hooks ?? [])
+            if (h.command?.includes('one-way-in-guard') === true) return h.command
+    return null
+}
+
+const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
+
+/** the guard file the hook command points at, resolved against the repo root.
+ *  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 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 }
+}
+
+export const oneWayInPolicy: Rule = {
+    id: 'SK013',
+    blocking: true,
+    title: 'one way in policy',
+    owner: OWNER,
+    lint: (t, env) => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return t.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
+        const s = readSettings(env.root)
+        if (s == null) {
+            t.fail(`${SETTINGS_PATH} ${existsSync(join(env.root, SETTINGS_PATH)) ? 'is unparseable' : 'missing'} — nothing stops an agent typing \`bun test\`, and a package.json script cannot intercept a bun builtin`)
+            return
+        }
+        const have = new Set(s.permissions?.deny ?? [])
+        const missing = want.filter((r) => !have.has(r))
+        if (missing.length > 0)
+            t.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
+        const guard = guardHookCommand(s)
+        if (guard == null)
+            t.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
+        else {
+            const missing = guardScriptMissing(env.root, guard)
+            if (missing != null)
+                t.fail(
+                    `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which does not exist — every Bash call errors and no refusal ever names the shipkit command`,
+                    `bun install (or bun add -d rvlib-shipkit)`,
+                )
+        }
+        if (!t.failed) t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s), with the replacement named`)
+    },
+    // MERGES, never rewrites: this file also carries the attribution silencer,
+    // a repo's own allow list and its own hooks, and clobbering those to fix a
+    // deny list would cost more than the finding it repairs
+    fix: (env: RuleEnv): FixResult => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }
+        const p = join(env.root, SETTINGS_PATH)
+        const existing = readSettings(env.root)
+        if (existing == null && existsSync(p)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
+        const s: Settings = existing ?? {}
+        const changes: string[] = []
+        const deny = s.permissions?.deny ?? []
+        const added = want.filter((r) => !deny.includes(r))
+        if (added.length > 0) {
+            s.permissions = { ...s.permissions, deny: [...deny, ...added] }
+            changes.push(`${added.length} raw runner(s) denied`)
+        }
+        if (!hasGuardHook(s)) {
+            const pre = s.hooks?.['PreToolUse'] ?? []
+            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: guardCommand(readBin(env.root)) }] }] }
+            changes.push('PreToolUse guard wired (every refusal names the shipkit command)')
+        }
+        if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, JSON.stringify(s, null, 2) + '\n')
+        return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
+    },
+}

package/src/rules/rule-registry.ts

@@ -15,6 +15,7 @@ import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 import { configBarrelImport } from './SK012-config-barrel-import.ts'
+import { oneWayInPolicy } from './SK013-one-way-in-policy.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -29,6 +30,7 @@ export const RULES: readonly Rule[] = [
     undeclaredReleaseUnit,
     siblingUnitRanges,
     configBarrelImport,
+    oneWayInPolicy,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/scaffold/files/claude-settings-local.json

@@ -3,10 +3,8 @@
     "allow": [
       "Bash(shipkit *)",
       "Bash(bun run *)",
-      "Bash(bun test*)",
       "Bash(bun install*)",
       "Bash(bun add *)",
-      "Bash(bunx tsc*)",
       "Bash(bunx wrangler*)",
       "Bash(git status*)",
       "Bash(git diff*)",
@@ -15,7 +13,6 @@
       "Bash(git commit*)",
       "Bash(git push*)",
       "Bash(curl *)",
-      "Bash(oxlint*)",
       "Bash(./deploy.sh)"
     ],
     "deny": []

package/src/scaffold/files/verify-skill.md

@@ -11,7 +11,7 @@ description: Prove a change in THIS project actually works — drive the real fl
 
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
-- Logic → fast headless `bun test` (tiny ~10-line test files reusing fixtures).
+- Logic → fast headless bun tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <name filter>` is the narrow way in.
 - Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.