rvlib-shipkit 0.31.0 → 0.33.0

package/src/core/floor.ts

@@ -0,0 +1,82 @@
+// resolveFloor — which task fills each floor slot (lint, typecheck, test,
+// imports:check, cycles) and, when nothing can, the reason it stays empty.
+//
+// Its own module rather than a section of repo-config so a RULE can ask what
+// the gate would actually run: repo-config imports the rule registry, so a
+// rule importing repo-config back is a cycle that dies at module init.
+// RepoConfig arrives as a TYPE only, which is erased.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import { rawName, routesToShipkit } from './canonical-scripts.ts'
+import type { TaskDef } from './task-runner.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
+
+export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)'
+export type FloorResolution = {
+    tasks: TaskDef[]
+    /** slots disabled by `defaults: { x: false }` — always printed */
+    disabled: string[]
+    /** slots nothing could fill — always printed, never silent */
+    unfilled: { id: string; reason: string }[]
+    /** where each registered slot came from (init prints this) */
+    sources: Record<string, FloorSource>
+}
+
+// zero-config floor (O6): with no script, imports:check/cycles resolve to
+// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc. Returns
+// the task, or the reason the slot stays empty.
+function builtinFloorTask(id: string, root: string): { task: TaskDef; source: FloorSource } | string {
+    if (id === 'imports:check' || id === 'cycles') {
+        let cli: string
+        // shipkit's OWN module, resolved from this file: no dependency to be
+        // out of date with, and no resolution that can fail in a consumer tree
+        cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
+        return {
+            task: { id, cmd: id === 'cycles' ? ['bun', cli, 'cycles'] : ['bun', cli, 'imports', '--check'] },
+            source: 'built-in (shipkit)',
+        }
+    }
+    if (id === 'typecheck') {
+        if (!existsSync(join(root, 'tsconfig.json'))) return `no 'typecheck' script and no tsconfig.json`
+        const local = join(root, 'node_modules/.bin/tsc')
+        const tsc = existsSync(local) ? local : Bun.which('tsc')
+        if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
+        return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+    }
+    return `no package.json '${id}' script`
+}
+
+export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
+    const pkgPath = join(root, 'package.json')
+    let scripts: Record<string, string> = {}
+    if (existsSync(pkgPath)) {
+        // unparseable package.json must NOT silently empty the floor — the
+        // gate would run only `contracts` and report green
+        try { scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
+        catch (e) { throw new Error(`package.json unparseable — floor tasks cannot register: ${String(e).slice(0, 120)}`) }
+    }
+    const tasks: TaskDef[] = []
+    const disabled: string[] = []
+    const unfilled: { id: string; reason: string }[] = []
+    const sources: Record<string, FloorSource> = {}
+    for (const id of FLOOR_IDS) {
+        const override = c.defaults?.[id]
+        if (override === false) { disabled.push(id); continue }
+        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
+        // ONE WAY IN: `<id>` routes to `shipkit ci --only <id>`, so the TOOL
+        // body lives at `<id>:raw` and that is what the gate runs. Running the
+        // routed script here would spawn the gate from inside itself, forever
+        const raw = scripts[rawName(id)]
+        if (raw != null) { tasks.push({ id, cmd: ['bun', 'run', rawName(id)] }); sources[id] = 'package.json script'; continue }
+        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
+        const b = builtinFloorTask(id, root)
+        // a routed script with nothing behind it measures NOTHING, and the
+        // reason must say that rather than `no '<id>' script`, which is false
+        if (typeof b === 'string') unfilled.push({ id, reason: scripts[id] != null ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })
+        else { tasks.push(b.task); sources[id] = b.source }
+    }
+    return { tasks, disabled, unfilled, sources }
+}

package/src/core/motherhome.ts

@@ -10,7 +10,7 @@
 // path no longer exists are pruned on every write. Churn control: a row
 // rewrites only when its DATA changes or its last-seen day is older than
 // 7 days. Never fails the calling command.
-import { existsSync, readFileSync } from 'fs'
+import { existsSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
@@ -46,6 +46,13 @@ function consumptionMode(root: string): string {
     } catch { return '?' }
 }
 
+/** a LINKED worktree, where `.git` is a file pointing at the main checkout
+ *  rather than a directory. Cheap on purpose: this runs on every check pass in
+ *  every repo, and spawning git to learn it would cost more than the write. */
+function isLinkedWorktree(root: string): boolean {
+    try { return statSync(join(root, '.git')).isFile() } catch { return false }
+}
+
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
@@ -57,6 +64,12 @@ export function reportToMotherhome(root: string, config: RepoConfig, today: stri
         if (!base.startsWith('/')) return { wrote: false }
         const page = join(base, 'build/shipkit/local-projects.md')
         if (!existsSync(page)) return { wrote: false }
+        // a gate run inside a linked worktree must not write the MAIN
+        // checkout's tracked page: the row it would add describes a temporary
+        // side checkout, and the write lands as unexplained dirt in a tree
+        // somebody else is working in. The worktree's own runs are covered
+        // when its branch merges.
+        if (isLinkedWorktree(root)) return { wrote: false, note: `motherhome: skipped (${config.name} is a linked worktree — its row belongs to the main checkout)` }
 
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version

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-check.ts

@@ -15,6 +15,8 @@ import { RULES } from '../rules/rule-registry.ts'
 import { runRuleLint } from '../rules/rule.ts'
 import { formatLine, parseWireOutput, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
+import { SHARE_ENV } from '../release/releases-share.ts'
+import { rmSync } from 'fs'
 
 // orchestrator cache for checks WITHOUT their own suite — short on purpose:
 // this layer only absorbs back-to-back runs, real TTLs live in the checks
@@ -42,6 +44,21 @@ export type CheckOpts = {
      *  spends a third-party API call per publish. Undeclared checks are still
      *  collected, because an unclassified check stays fatal. */
     onlyBlocking?: boolean
+    /** the caller narrowed the run to these ids (`ci --only`). Empty or absent
+     *  means everything. A `--only` that narrowed TASKS while every check still
+     *  ran made the flag actively harmful: `ci --only cycles`, a 0.03s task,
+     *  probed every third-party service the repo knows about. One flag, one
+     *  meaning, across all three surfaces. */
+    only?: string[]
+}
+
+/** does this rule or check answer to one of the `--only` ids? Matched against
+ *  every name the surface is known by (a rule's id AND its title, a discovered
+ *  check's name AND its path), because the id an operator types is whichever
+ *  one they last saw on the wire. */
+export function matchesOnly(only: string[] | undefined, ...names: string[]): boolean {
+    if (only == null || only.length === 0) return true
+    return only.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
 }
 
 export type CheckRun = {
@@ -85,26 +102,41 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         t.warned = true
     }
     for (const rule of [...RULES, ...(c.rules ?? [])]) {
+        if (!matchesOnly(o.only, rule.id, rule.title)) continue
         if (o.onlyBlocking === true && !rule.blocking) continue
         suite.addCheck({
+            blocking: rule.blocking,
             name: rule.title,
             remainValidFor: rule.ttl,
             cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
+    // ONE release survey for the whole run: five discovered checks call
+    // collectReports, each in its own subprocess, and the survey is ~4s of
+    // network. The path is per RUN and never reused across runs, so nothing
+    // here can serve a stale answer to a later gate (releases-share.ts).
+    // a caller that already opened one (runCi, which starts the survey next to
+    // the tasks) owns it, cleanup included; otherwise this run owns its own
+    const inherited = process.env[SHARE_ENV]
+    const sharePath = inherited != null && inherited !== '' ? inherited : join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
+        [SHARE_ENV]: sharePath,
         ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path)
         // file wins, then the repo default, then nothing: an unclassified
         // check is an error, never a guess
+        if (!matchesOnly(o.only, d.name, rel)) continue
         const blocking = d.blocking ?? c.checkDefaults?.blocking
         if (blocking == null) undeclared.push(rel)
         if (o.onlyBlocking === true && blocking !== true) continue
         suite.addCheck({
+            // a check about the WORLD may remember a measured negative; one
+            // about this repo never does (check-suite.ts, the rule)
+            blocking: blocking ?? true,
             name: d.name,
             remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
             logic: async (t) => {
@@ -121,6 +153,8 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         })
     }
     const r = await suite.execute()
+    // the survey dies with the run that made it, and only the run that made it
+    if (inherited == null || inherited === '') for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
     // frozen = a release-shaped run: reporting would re-dirty the tree the

package/src/core/run-ci.ts

@@ -13,6 +13,11 @@ import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
+import { rmSync } from 'fs'
+
+import { SHARE_ENV } from '../release/releases-share.ts'
+import { collectReports } from '../release/run-releases.ts'
+import { withContractsScope } from '../contracts/contracts-once.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -54,8 +59,22 @@ export type CiOpts = {
      *  loads of repo.config.ts can disagree, and the release path classifies
      *  rule-vs-probe severity from the config it holds. */
     config?: RepoConfig
+    /** which test tier the run asks the repo's suite for. 'quick' is the
+     *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every task, which
+     *  a suite reads to include the slow, real-world tiers it otherwise skips.
+     *  The release path always asks for 'full': a version published behind a
+     *  partial suite is a green nobody measured. Default reads the env var, so
+     *  `SHIPKIT_TEST_FULL=1 shipkit ci` works with no flag. */
+    tests?: TestTier
 }
 
+export type TestTier = 'quick' | 'full'
+
+/** the env var a repo's own suite reads to widen itself. Named here because
+ *  the gate is what sets it, and a suite that invents its own name is a tier
+ *  the release path cannot reach. */
+export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+
 /** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
  *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
  *  a narrowed run that stamps the full gate's verdict is a green nobody
@@ -71,24 +90,69 @@ function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
 }
 
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
+    // ONE gate run: the `contracts` task evaluates, rule SK002 reads what it
+    // computed instead of evaluating a second time (contracts-once.ts)
+    return await withContractsScope(() => runCiInScope(root, o))
+}
+
+async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
     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
     const skipIds = new Set(o.skipTaskIds ?? [])
-    const tasks = all.tasks.filter((t) => !skipIds.has(t.id))
+    const tier: TestTier = o.tests ?? (process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick')
+    const tasks = all.tasks
+        .filter((t) => !skipIds.has(t.id))
+        // the whole run carries the flag rather than one task id: a repo names
+        // its suites what it likes (`test`, `test:libs`, a prepublish script),
+        // and a gate that guesses which one is the tests will miss one
+        .map((t) => (tier === 'full' ? { ...t, env: { ...t.env, [FULL_TESTS_ENV]: '1' } } : t))
+    // announced BEFORE the run, so a log that died mid-way still says which
+    // tier it was asking for
+    sink(tier === 'full'
+        ? `ok: test tier FULL — every suite, the slow ones included (${FULL_TESTS_ENV}=1)`
+        : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
     for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
     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
+    // is 4s nobody can overlap. Failures are the checks' to report, not this
+    // line's: a survey nobody can run just means the checks do it themselves.
+    const sharePath = join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
+    const priorShare = process.env[SHARE_ENV]
+    process.env[SHARE_ENV] = sharePath
+    // a NARROWED run pre-warms nothing: `--only cycles` asks one question, and
+    // paying a 4s network survey to answer it is the same bug --only was
+    // fixed for
+    const willRunChecks = o.skipChecks !== true && (o.onlyIds ?? []).length === 0
+    const survey = willRunChecks ? collectReports(root, c).catch(() => null) : null
     const summary = await runTasks({
         tasks,
         logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
@@ -100,11 +164,23 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
+    // what the suite ACTUALLY ran, from its own summary line. A flag that was
+    // set proves the intent; the count proves the tests
+    const ranTests = summary.results
+        .map((r) => /Ran (\d+) tests?/.exec(r.lastLine ?? '')?.[1])
+        .find((n) => n != null)
+    if (ranTests != null) sink(`ok: test tier ${tier}: ${ranTests} tests ran`)
     // the checks, in the SAME command. there is no second surface: a check
     // declares whether it blocks, and that is the only question about it.
+    // a narrowed run says what it did NOT look at: a green that only ever
+    // asked one question must not read like the full gate
+    if ((o.onlyIds ?? []).length > 0 && o.skipChecks !== true) sink(`skip: checks not named by --only (${(o.onlyIds ?? []).join(', ')})`)
+    if (survey != null) await survey
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks })
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds })
+    if (priorShare == null) delete process.env[SHARE_ENV]; else process.env[SHARE_ENV] = priorShare
+    for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
     for (const u of checks.undeclared) {

package/src/core/run-fixers.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { runFix } from '../rules/run-fix.ts'
+import { routesToShipkit } from './canonical-scripts.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
@@ -60,8 +61,12 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
         return true
     }
 
-    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null)
+    // `fmt` is the one slot the fix pass invokes BY SCRIPT, so it is the one
+    // name ONE WAY IN deliberately leaves raw: a routed body here would make
+    // the fixer spawn the gate that spawns the fixer
+    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null && !routesToShipkit(scripts[n]!))
     if (fmtName != null) slots.push({ id: 'fmt', cmd: ['bun', 'run', fmtName], source: 'package.json script' })
+    else if (FMT_SCRIPTS.some((n) => scripts[n] != null)) unfilled.push({ id: 'fmt', reason: `the 'fmt' script routes back to shipkit — the fix pass runs it, so it holds the formatter itself` })
     else unfilled.push({ id: 'fmt', reason: `no 'fmt' or 'format' script — formatting stays a manual step` })
 
     if (offByConfig('imports:fix')) { /* the repo said no, in the one place that governs both directions */ }

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