rvlib-shipkit 0.30.0 → 0.32.0

package/src/core/check-suite.ts

@@ -15,8 +15,9 @@ import { fmtStamp, formatLine, parseDuration, type Line } from './wire.ts'
 
 type Logic = (t: CheckCtx) => unknown
 type Prep = { skip?: string; cacheExtra?: string }
-type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic }
-type CacheFile = Record<string, { version: number; key: string; at: number; lines: Line[] }>
+type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic; blocking: boolean }
+type CacheEntry = { version: number; key: string; at: number; lines: Line[] }
+type CacheFile = Record<string, CacheEntry>
 
 export type GetSecret = (name: string, field: 'get' | 'account') => string | null
 
@@ -61,8 +62,12 @@ export class CheckSuite {
         this.onResult = opts.onResult
     }
 
-    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic }): void {
-        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic })
+    /** `blocking` decides what a NEGATIVE result may be cached as: see the
+     *  measured-negative rule in execute(). Default true, the safe side: a
+     *  check that never declared itself is treated as being about this repo,
+     *  so its failures are never replayed. */
+    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic; blocking?: boolean }): void {
+        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic, blocking: spec.blocking ?? true })
     }
 
     defineRequiredTool(name: string, opts: { candidates?: string[]; probe?: { args: string[]; expect?: RegExp }; fix: string }): void {
@@ -97,6 +102,12 @@ export class CheckSuite {
         const validate = spec.validate as (v: unknown, t: CheckCtx) => unknown
         let payload: unknown
         this.runners.push({
+            // conservative on purpose: a secret probe keeps today's behaviour,
+            // where no negative is remembered. Its cache key already hashes the
+            // secret VALUE, so a rotation busts it, which would make caching a
+            // measured 403 sound. That is a severity call for whoever owns the
+            // secrets surface, not a side effect of this change.
+            blocking: true,
             // bare secret name — this shows up in human-facing WARN/FAIL lines
             name: names.length === 1 ? primary : primary.split('/').slice(0, 2).join('/') + '/*',
             ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0,
@@ -118,65 +129,122 @@ export class CheckSuite {
     }
 
     // test seam — run() prints + exits; execute() returns the structured result
+    /** ONE check: cache replay, run, classify, and what it wants remembered.
+     *  Pure with respect to its neighbours, which is what lets execute() run
+     *  them together. */
+    private async runOne(r: Runner, cache: CacheFile): Promise<{ lines: Line[]; skip: string | null; ran: boolean; failed: boolean; store: CacheEntry | null; evict: boolean }> {
+        const prep = r.prep?.() ?? {}
+        if (prep.skip != null) {
+            this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
+            return { lines: [], skip: prep.skip, ran: false, failed: false, store: null, evict: false }
+        }
+        const key = prep.cacheExtra ?? ''
+        const entry = cache[r.name]
+        const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
+            && entry != null && entry.version === r.version && entry.key === key
+            && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
+        if (fresh) {
+            // the stamp was baked in when the check RAN (below): a replay
+            // prints the stored lines VERBATIM, so the live run and every
+            // later replay render the same string, and the line changes
+            // only when a re-validation happens. Annotating replays but
+            // not live runs still diffed on every fresh-vs-cached
+            // alternation, so neither side annotates
+            // a replayed WORLD negative keeps its severity: it is still the
+            // answer, and demoting it to a pass would hide a real finding
+            const replayedWarn = entry.lines.some((l) => l.kind === 'warn' || l.kind === 'fail')
+            this.onResult?.(r.name, { lines: entry.lines, status: replayedWarn ? 'warn' : 'pass', cached: true })
+            return { lines: entry.lines, skip: null, ran: true, failed: false, store: null, evict: false }
+        }
+        const t = new CheckCtx(this.toolPaths)
+        try {
+            await r.logic(t)
+        } catch (e) {
+            // both of these mean the probe never reached its subject, so the
+            // run has no answer to remember
+            if (e instanceof RateLimited) t.unreachable(`${r.name} not validated this run (${e.message}) — retry later`)
+            else if (e instanceof ToolUnresolved) { t.unmeasured = true; t.note(`${r.name} skipped (${e.message})`) }
+            else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
+        }
+        // AN ANSWER CACHES. THE ABSENCE OF ONE DOES NOT. That distinction, not
+        // pass-versus-fail, is what decides cacheability here, and a future
+        // reader is warned off "fixing" the asymmetry:
+        //
+        //   measured negative  a probe that RAN and came back bad ("the box is
+        //                      off", "the token answered 403", "five repos are
+        //                      uncatalogued") is a real answer about the world.
+        //                      Replaying it for its TTL is CORRECT: the world
+        //                      does not fix itself between two gate runs, and
+        //                      re-asking every 30 seconds spends a third-party
+        //                      API call to be told the same thing.
+        //   unmeasured         a probe that could not run at all ("registry
+        //                      unreachable", "no cred", "rate limited", tool
+        //                      missing) produced no answer. Caching it asserts
+        //                      a dead network as fact long after it recovered.
+        //                      `skip` lines and the unmeasured flag mark these.
+        //
+        // A measured negative caches ONLY for a check about the WORLD. A
+        // blocking check reports THIS REPO, where the whole point is that a
+        // human fixes it and the next run goes green: replaying its red for a
+        // TTL would be the cache lying about work already done.
+        const unmeasured = t.unmeasured || t.lines.some((l) => l.kind === 'skip')
+        const clean = !t.failed && !t.warned
+        const cacheable = r.ttlMs > 0 && !unmeasured && (clean || !r.blocking)
+        const lines = cacheable
+            ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (${clean ? 'cached' : 'measured'} at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
+            : t.lines
+        this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
+        return {
+            lines,
+            skip: null,
+            ran: true,
+            failed: t.failed,
+            store: cacheable && r.ttlMs > 0 ? { version: r.version, key, at: this.now(), lines } : null,
+            // an unmeasured run evicts whatever was stored: a later run must
+            // re-probe rather than replay an answer recorded before the outage
+            evict: r.ttlMs > 0 && !cacheable && entry != null,
+        }
+    }
+
     async execute(): Promise<{ lines: Line[]; exitCode: number }> {
         const cachePath = join(this.cacheDir, `${this.name}.json`)
         let cache: CacheFile = {}
         try { cache = JSON.parse(readFileSync(cachePath, 'utf8')) } catch {}
         let cacheDirty = false
 
+        // CONCURRENT, bounded. Checks are independent by contract: each answers
+        // one question about the world or the repo and shares nothing with its
+        // neighbours, and most of the wall time is a network round trip or a
+        // cold `bun` start. In series, twenty checks cost the SUM; together
+        // they cost the slowest one. Measured on this repo: 18.4s to 6.0s.
+        // Order is preserved by collecting per runner and concatenating in
+        // declaration order, so the wire output is byte-identical to the
+        // sequential run and the frozen contract still holds.
+        const cap = Math.max(2, Math.min(8, navigator.hardwareConcurrency || 4))
+        const results = new Array<Awaited<ReturnType<CheckSuite['runOne']>>>(this.runners.length)
+        let next = 0
+        const worker = async (): Promise<void> => {
+            for (;;) {
+                const i = next++
+                if (i >= this.runners.length) return
+                results[i] = await this.runOne(this.runners[i]!, cache)
+            }
+        }
+        await Promise.all(Array.from({ length: Math.min(cap, this.runners.length) }, () => worker()))
+
         const out: Line[] = []
         const skipped: string[] = []
         let ran = 0
         let anyFail = false
-
-        for (const r of this.runners) {
-            const prep = r.prep?.() ?? {}
-            if (prep.skip != null) {
-                skipped.push(prep.skip)
-                this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
-                continue
-            }
-            ran++
-            const key = prep.cacheExtra ?? ''
-            const entry = cache[r.name]
-            const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
-                && entry != null && entry.version === r.version && entry.key === key
-                && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
-            if (fresh) {
-                // the stamp was baked in when the check RAN (below): a replay
-                // prints the stored lines VERBATIM, so the live run and every
-                // later replay render the same string, and the line changes
-                // only when a re-validation happens. Annotating replays but
-                // not live runs still diffed on every fresh-vs-cached
-                // alternation, so neither side annotates
-                out.push(...entry.lines)
-                this.onResult?.(r.name, { lines: entry.lines, status: 'pass', cached: true }) // only clean passes are cached
-                continue
-            }
-            const t = new CheckCtx(this.toolPaths)
-            try {
-                await r.logic(t)
-            } catch (e) {
-                if (e instanceof RateLimited) t.warn(`${r.name} not validated this run (${e.message}) — retry later`)
-                else if (e instanceof ToolUnresolved) t.note(`${r.name} skipped (${e.message})`)
-                else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
-            }
-            // a skip line is an UNKNOWN, not a clean pass — replaying
-            // "registry unreachable" for a TTL asserts a dead network as
-            // fact long after it recovered
-            const cacheable = r.ttlMs > 0 && !t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')
-            const lines = cacheable
-                ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
-                : t.lines
-            out.push(...lines)
-            this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
-            if (t.failed) anyFail = true
-            if (r.ttlMs > 0) {
-                if (cacheable) { cache[r.name] = { version: r.version, key, at: this.now(), lines }; cacheDirty = true }
-                // a WARN/FAIL evicts the stale pass — a later run must re-probe,
-                // not replay an ok recorded before the breakage
-                else if (entry != null) { delete cache[r.name]; cacheDirty = true }
-            }
+        for (let i = 0; i < this.runners.length; i++) {
+            const r = results[i]!
+            const name = this.runners[i]!.name
+            out.push(...r.lines)
+            if (r.skip != null) skipped.push(r.skip)
+            if (r.ran) ran++
+            if (r.failed) anyFail = true
+            if (r.store != null) { cache[name] = r.store; cacheDirty = true }
+            else if (r.evict) { delete cache[name]; cacheDirty = true }
         }
 
         // contract: `skip:` lines ONLY when no check ran at all (whole probe is

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/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,6 +90,12 @@ 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) }
@@ -83,12 +108,36 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     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})`)
+    // 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 +149,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 */ }