rvlib-shipkit 1.8.0 → 2.0.0

package/src/checks/SK017-vscode-hub-task.check.ts

@@ -1,26 +1,24 @@
-// SK017 vscode hub task (build/vscode-tasks.md): the folder-open hub task
-// carries the problem matcher the hub prints for, it opens with the folder
-// itself when nothing else does, and no `👁  TSC` watcher runs beside a gate
-// that already runs `typecheck`.
+// SK017 vscode hub task (build/vscode-tasks.md): no folder-open task starts
+// the shipkit hub (it runs in the home, and VS Code needs no task for it), and
+// no `👁  TSC` watcher runs beside a gate that already runs `typecheck`.
 //
-// the file is hand-written jsonc, so the fixer edits spans: it removes the TSC
-// task, a wrapper that only starts the hub, and their dependsOn entries, and
-// writes the hub's matcher and folder-open run option. Every other byte stays
-// as its author left it.
+// the file is hand-written jsonc, so the fixer edits spans: it removes the hub
+// task, the TSC task, a wrapper left starting nothing, and their dependsOn
+// entries, and folds a wrapper left starting ONE task into it. Every other
+// byte stays, except a dependsOn array it edits, which is rewritten inline.
+// A file left holding nothing but an empty task list is deleted.
 import { basename } from 'path'
 import { check } from '../check.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
 import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { repoOff } from '../core/when.ts'
-import { hubProblemMatcher } from '../problems/problem-line.ts'
-import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
+import { indentAt, parseSpans, plain, removalSpans, type Node } from '../scaffold/jsonc-spans.ts'
 
 export const TSC_LABEL = '👁  TSC'
 const TASKS = '.vscode/tasks.json'
 
 type Obj = Extract<Node, { kind: 'object' }>
-type Arr = Extract<Node, { kind: 'array' }>
 
 const prop = (o: Obj, key: string): Node | undefined => o.props.find((p) => p.key === key)?.value
 
@@ -35,12 +33,17 @@ function isTscWatcher(t: Record<string, unknown>): boolean {
     return t['label'] === TSC_LABEL && TSC_BINS.has(basename(cmd)) && args.includes('--watch')
 }
 
-/** the hub task: `bun run hub`, or the house label */
+/** the hub task: `bun run hub` or `sk serve` (args or one shell string), or the house label */
 function isHub(t: Record<string, unknown>): boolean {
-    const args = Array.isArray(t['args']) ? t['args'] : []
-    return (t['command'] === 'bun' && args[0] === 'run' && args[1] === 'hub') || (typeof t['label'] === 'string' && /^🚀\s+shipkit\b/.test(t['label']))
+    const args = Array.isArray(t['args']) ? t['args'].map(String) : []
+    const line = [typeof t['command'] === 'string' ? t['command'] : '', ...args].join(' ')
+    return /(?:^|\s)(?:bun run hub|(?:sk|shipkit) serve)(?:\s|$)/.test(line) || (typeof t['label'] === 'string' && /^🚀\s+shipkit\b/.test(t['label']))
 }
 
+/** the comment the old scaffold wrote above its hub task, byte for byte, any
+ *  indent: it describes the hub task, so it goes with it */
+const SCAFFOLD_HEADER = /^[ \t]*\/\/ the hub is the one process every wired repo starts, so it opens with the\n[ \t]*\/\/ folder itself\. It runs every check after each save and its problem\n[ \t]*\/\/ matcher fills the problems pane, so there is no type checker task\. A\n[ \t]*\/\/ stack that earns more long-running watchers \(dev server, css\) adds a\n[ \t]*\/\/ master task with runOn folderOpen whose dependsOn lists them all, the hub\n[ \t]*\/\/ included, and moves runOn off the hub\.\n/m
+
 /** a task that only starts other tasks: no command of its own */
 const isWrapper = (t: Record<string, unknown>): boolean => t['command'] == null && t['type'] == null && t['dependsOn'] != null
 
@@ -50,112 +53,111 @@ export type RepairOpts = {
     typecheckOn: boolean
 }
 
-/** what this file needs, applied: the text to write, one line per change, and
- *  one line per thing it deliberately left. No change means the text comes
- *  back byte for byte */
-export function repairTasks(text: string, o: RepairOpts): { text: string; changes: string[]; kept: string[] } {
+/** what this file needs, applied: the text to write, one line per change,
+ *  one line per thing it deliberately left, and whether any task is left. No
+ *  change means the text comes back byte for byte */
+export function repairTasks(text: string, o: RepairOpts): { text: string; changes: string[]; kept: string[]; empty: boolean } {
     const root = parseSpans(text)
     if (root.kind !== 'object') throw new Error('tasks.json is not an object')
     const tasks = prop(root, 'tasks')
-    if (tasks == null || tasks.kind !== 'array') return { text, changes: [], kept: [] }
-    const edits: { start: number; end: number; body: string }[] = []
+    if (tasks == null || tasks.kind !== 'array') return { text, changes: [], kept: [], empty: false }
     const changes: string[] = []
     const kept: string[] = []
     const record = (t: Node): Record<string, unknown> => plain(text, t) as Record<string, unknown>
     const labelOf = (t: Node): string => String(record(t)['label'] ?? '?')
-    const items = tasks.items.filter((n): n is Obj => n.kind === 'object')
-    const hubs = items.filter((t) => isHub(record(t)))
-
-    const tscAt = tasks.items.flatMap((n, i) => (n.kind === 'object' && isTscWatcher(record(n)) ? [i] : []))
-    const dropTsc = tscAt.length > 0 && o.typecheckOn
-    if (tscAt.length > 0 && !o.typecheckOn) kept.push(`kept the '${TSC_LABEL}' task: this repo's gate has no enabled typecheck check, so it is the only type checker here`)
-    if (dropTsc) for (const i of tscAt) {
-        const [start, end] = removalSpan(text, tasks, i)
-        edits.push({ start, end, body: '' })
-        changes.push(`removed the '${TSC_LABEL}' task`)
+    const at = (pred: (t: Record<string, unknown>) => boolean): number[] => tasks.items.flatMap((n, i) => (n.kind === 'object' && pred(record(n)) ? [i] : []))
+
+    const remove = new Set<number>()
+    const gone = new Set<string>()
+    const drop = (i: number, why: string): void => {
+        remove.add(i)
+        gone.add(labelOf(tasks.items[i]!))
+        changes.push(why)
     }
+    for (const i of at(isHub)) drop(i, `removed the '${labelOf(tasks.items[i]!)}' hub task: the hub runs in the home, not in VS Code`)
+    const tscAt = at(isTscWatcher)
+    if (tscAt.length > 0 && !o.typecheckOn) kept.push(`kept the '${TSC_LABEL}' task: this repo's gate has no enabled typecheck check, so it is the only type checker here`)
+    if (o.typecheckOn) for (const i of tscAt) drop(i, `removed the '${TSC_LABEL}' task`)
 
-    // a folder-open wrapper whose only job is starting the hub is a second
-    // task on screen for nothing: the hub opens with the folder itself
-    const hub = hubs.length === 1 ? hubs[0]! : null
-    const hubLabel = hub == null ? null : labelOf(hub)
     const depsOf = (t: Node): string[] => {
         const d = record(t)['dependsOn']
-        const list = Array.isArray(d) ? d.map(String) : [String(d)]
-        return dropTsc ? list.filter((x) => x !== TSC_LABEL) : list
+        return d == null ? [] : Array.isArray(d) ? d.map(String) : [String(d)]
     }
-    const wrapperAt = hub == null ? -1 : tasks.items.findIndex((n) => n.kind === 'object' && isWrapper(record(n)) && depsOf(n).length === 1 && depsOf(n)[0] === hubLabel)
-    const wrapper = wrapperAt < 0 ? null : (tasks.items[wrapperAt] as Obj)
-    if (wrapper != null) {
-        const [start, end] = removalSpan(text, tasks, wrapperAt)
-        edits.push({ start, end, body: '' })
-        changes.push(`folded the '${labelOf(wrapper)}' wrapper into '${hubLabel}', which now opens with the folder`)
-        if (/\/\/.*(master task|subtask)/i.test(text)) changes.push('a comment still describes a master task with subtasks: rewrite it by hand')
-    }
-
-    // a wrapper that started only the TSC task starts nothing once it goes
-    const emptied = !dropTsc ? [] : tasks.items.flatMap((n, i) => (n !== wrapper && n.kind === 'object' && isWrapper(record(n)) && depsOf(n).length === 0 ? [i] : []))
-    for (const i of emptied) {
-        const [start, end] = removalSpan(text, tasks, i)
-        edits.push({ start, end, body: '' })
-        changes.push(`removed the '${labelOf(tasks.items[i]!)}' wrapper, which started nothing else`)
+    // a wrapper that started only what went starts nothing, and so on up
+    for (let moved = true; moved;) {
+        moved = false
+        tasks.items.forEach((n, i) => {
+            if (remove.has(i) || n.kind !== 'object' || !isWrapper(record(n))) return
+            const deps = depsOf(n)
+            if (deps.length > 0 && deps.every((x) => gone.has(x))) { drop(i, `removed the '${labelOf(n)}' wrapper, which started nothing else`); moved = true }
+        })
     }
 
-    if (dropTsc) {
-        for (const t of items) {
-            if (t === wrapper || emptied.some((i) => tasks.items[i] === t)) continue
-            const d = prop(t, 'dependsOn')
-            if (d?.kind === 'array') {
-                const idx = d.items.findIndex((x) => x.kind === 'scalar' && x.value === TSC_LABEL)
-                if (idx < 0) continue
-                const [start, end] = removalSpan(text, d as Arr, idx)
-                edits.push({ start, end, body: '' })
-                changes.push(`dropped '${TSC_LABEL}' from the dependsOn of '${labelOf(t)}'`)
-            } else if (d?.kind === 'scalar' && d.value === TSC_LABEL) {
-                edits.push({ start: d.start, end: d.end, body: '[]' })
-                changes.push(`dropped '${TSC_LABEL}' from a dependsOn`)
-            }
-        }
-    }
-
-    const want = hubProblemMatcher()
-    for (const h of hubs) {
-        const first = h.props[0]
-        const hubIndent = indentAt(text, h.start)
-        const propIndent = first != null ? indentAt(text, first.keyStart) : `${hubIndent}   `
-        const unit = propIndent.length > hubIndent.length ? propIndent.slice(hubIndent.length) : '   '
-        const render = (v: unknown): string => JSON.stringify(v, null, unit).split('\n').join(`\n${propIndent}`)
+    const edits: { start: number; end: number; body: string }[] = []
+    // a wrapper this pass cut down to ONE task is two tasks on screen for one
+    // process: it folds into that task, which takes the wrapper's own runOn
+    // and group, and every dependsOn naming the wrapper names the task instead
+    const alias = new Map<string, string>()
+    const folds = new Map<Obj, Obj[]>()
+    tasks.items.forEach((n, i) => {
+        if (remove.has(i) || n.kind !== 'object' || !isWrapper(record(n))) return
+        const deps = depsOf(n)
+        const left = deps.filter((x) => !gone.has(x))
+        if (left.length !== 1 || left.length === deps.length) return
+        const into = tasks.items.findIndex((t, j) => !remove.has(j) && t.kind === 'object' && labelOf(t) === left[0])
+        if (into < 0) return
+        remove.add(i)
+        alias.set(labelOf(n), left[0]!)
+        folds.set(tasks.items[into] as Obj, [...(folds.get(tasks.items[into] as Obj) ?? []), n])
+        const opens = (record(n)['runOptions'] as Record<string, unknown> | undefined)?.['runOn'] === 'folderOpen'
+        changes.push(`folded the '${labelOf(n)}' wrapper into '${left[0]}'${opens ? ', which now opens with the folder' : ''}`)
+    })
+    tasks.items.forEach((n, i) => {
+        if (remove.has(i) || n.kind !== 'object') return
+        const d = prop(n, 'dependsOn')
+        const deps = depsOf(n)
+        const next = [...new Set(deps.map((x) => alias.get(x) ?? x).filter((x) => !gone.has(x) && x !== labelOf(n)))]
+        if (d == null || JSON.stringify(next) === JSON.stringify(deps)) return
+        edits.push({ start: d.start, end: d.end, body: JSON.stringify(next).replace(/","/g, '", "') })
+        changes.push(`dropped ${deps.filter((x) => !next.includes(x)).map((x) => `'${x}'`).join(', ')} from the dependsOn of '${labelOf(n)}'`)
+    })
+    for (const [start, end] of removalSpans(text, tasks, remove)) edits.push({ start, end, body: '' })
+    // the default build group a removed hub held moves with the fold too
+    const hubGroup = at(isHub).map((i) => prop(tasks.items[i] as Obj, 'group')).find((g) => g != null && /"isDefault"\s*:\s*true/.test(text.slice(g.start, g.end)))
+    for (const [task, wrappers] of folds) {
+        const first = task.props[0]
+        const taskIndent = indentAt(text, task.start)
+        const propIndent = first != null ? indentAt(text, first.keyStart) : `${taskIndent}   `
         const added: string[] = []
-        const current = prop(h, 'problemMatcher')
-        if (current == null || JSON.stringify(plain(text, current)) !== JSON.stringify(want)) {
-            if (current != null) edits.push({ start: current.start, end: current.end, body: render(want) })
-            else added.push(`"problemMatcher": ${render(want)}`)
-            changes.push(`wrote the shipkit problem matcher on '${labelOf(h)}'`)
-        }
-        if (h === hub && wrapper != null) {
-            const ro = prop(h, 'runOptions')
+        const runOn = wrappers.map((w) => record(w)['runOptions'] as Record<string, unknown> | undefined).find((r) => r?.['runOn'] != null)?.['runOn']
+        if (runOn != null) {
+            const ro = prop(task, 'runOptions')
             const was = ro != null && ro.kind === 'object' ? record(ro) : {}
-            const inline = `{ ${Object.entries(Object.assign({ runOn: 'folderOpen', instanceLimit: 1 }, was, { runOn: 'folderOpen' })).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(', ')} }`
+            const inline = `{ ${Object.entries({ ...was, runOn, instanceLimit: was['instanceLimit'] ?? 1 }).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(', ')} }`
             if (ro != null) edits.push({ start: ro.start, end: ro.end, body: inline })
             else added.push(`"runOptions": ${inline}`)
-            const wg = prop(wrapper, 'group')
-            if (wg != null) {
-                const body = text.slice(wg.start, wg.end)
-                const g = prop(h, 'group')
-                if (g != null) edits.push({ start: g.start, end: g.end, body })
-                else added.push(`"group": ${body}`)
-            }
         }
-        if (added.length === 0) continue
-        const last = h.props.at(-1)
-        const joined = added.join(`,\n${propIndent}`)
-        if (last == null) edits.push({ start: h.start + 1, end: h.start + 1, body: `\n${propIndent}${joined}\n${hubIndent}` })
-        else edits.push({ start: last.value.end, end: last.value.end, body: `,\n${propIndent}${joined}` })
+        const wg = wrappers.map((w) => prop(w, 'group')).find((g) => g != null) ?? hubGroup
+        if (wg != null) {
+            const body = text.slice(wg.start, wg.end)
+            const g = prop(task, 'group')
+            if (g != null) edits.push({ start: g.start, end: g.end, body })
+            else added.push(`"group": ${body}`)
+        }
+        const last = task.props.at(-1)
+        if (added.length > 0 && last != null) edits.push({ start: last.value.end, end: last.value.end, body: `,\n${propIndent}${added.join(`,\n${propIndent}`)}` })
     }
 
+    const header = gone.size > 0 ? SCAFFOLD_HEADER.exec(text) : null
+    if (header != null) {
+        edits.push({ start: header.index, end: header.index + header[0].length, body: '' })
+        changes.push('removed the old scaffold comment that described the hub task')
+    }
     let out = text
     for (const e of edits.sort((a, b) => b.start - a.start)) out = out.slice(0, e.start) + e.body + out.slice(e.end)
-    return { text: out, changes, kept }
+    // empty only when nothing else lives in the file either (`inputs`, a key of its own)
+    const onlyTasks = root.props.every((x) => x.key === 'version' || x.key === 'tasks')
+    return { text: out, changes, kept, empty: onlyTasks && tasks.items.length > 0 && remove.size === tasks.items.length }
 }
 
 /** whether this repo's gate runs a typecheck: a floor slot or a task that
@@ -184,26 +186,26 @@ const PUBLIC_SKIP = `the root unit publishes to npm: ${TASKS} belongs to every c
 export const vscodeHubTask = check({
     id: 'SK017',
     // a stale editor file is behind, not broken: it warns, and the fix pass
-    // repairs it
+    // of every gate repairs it
     blocking: false,
     title: 'vscode hub task',
-    description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
+    description: 'no vscode task starts the shipkit hub, and no extra tsc watcher runs',
     owner: 'build/vscode-tasks.md',
-    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
     cache: { by: 'reads' },
-    fix: 'manual',
+    fix: 'ci',
     applies: 'always',
     run: (c) => {
         if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const own = ownTasks(c)
-        if (own === 'none') return c.ok(`no ${TASKS}, so there is no hub task to wire`)
+        if (own === 'none') return c.ok(`no ${TASKS}, so no task starts the hub`)
         if (own === 'linked') return c.ok(`.vscode/ is a link to a shared dir, left alone`)
         let r: { changes: string[]; kept: string[] }
         try { r = repairTasks(own.text, { typecheckOn: typecheckOn(c) }) }
         catch (e) { return c.warn(`${TASKS} does not parse (${(e as Error).message}), so the hub task was not checked`) }
         for (const k of r.kept) c.note(`${TASKS}: ${k}`)
-        if (r.changes.length === 0) return c.ok(`${TASKS}: the hub task feeds the problems pane`)
-        for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
+        if (r.changes.length === 0) return c.ok(`${TASKS}: no task starts the hub`)
+        for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop')}`)
     },
     repair: (c) => {
         if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
@@ -211,8 +213,9 @@ export const vscodeHubTask = check({
         if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }
         const r = repairTasks(own.text, { typecheckOn: typecheckOn(c) })
         if (r.changes.length === 0) return { changed: false, summary: `${TASKS} already current` }
-        c.write(TASKS, r.text)
-        return { changed: true, summary: `${TASKS}: ${r.changes.join(', ')}` }
+        if (r.empty) c.remove(TASKS)
+        else c.write(TASKS, r.text)
+        return { changed: true, summary: `${TASKS}: ${r.changes.join(', ')}${r.empty ? ', and deleted the file, which held no other task' : ''}` }
     },
 })
 

package/src/checks/SK019-tests-run-in-units.check.ts

@@ -15,6 +15,7 @@ import { check } from '../check.ts'
 import { repoCheckSources } from '../core/legacy-shapes.ts'
 import { argvRunsTests, commandRunsTests, sourceRunsTests, type ScriptReader } from '../suite/runner-shapes.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
+import { repoOff } from '../core/when.ts'
 
 /** the scripts of the package.json in `dir` (repo relative), then the root's */
 const scriptsIn = (c: CheckCtx, dir: string): ScriptReader => {
@@ -67,7 +68,7 @@ export const testsRunInUnits = check({
         }
         // a slot the package.json fills: its raw body, else its own script
         for (const id of OTHER_SLOTS) {
-            if (defaults[id] === false || (defaults[id] as { cmd?: unknown } | undefined)?.cmd != null) continue
+            if (repoOff(c.config, id) != null || (defaults[id] as { cmd?: unknown } | undefined)?.cmd != null) continue
             const name = root(`${id}:raw`) != null ? `${id}:raw` : id
             const body = root(name)
             const how = body == null ? null : commandRunsTests(body, (n) => (n === name ? null : root(n)))

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -30,9 +30,12 @@ export const agentWikiLinks = check({
         for (const f of orphans) {
             const by = namingPage(c.root, f, linked)
             const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
-            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)
+            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`, { at: { file: `agent/${f}` } })
+        }
+        for (const d of lint.dangling) {
+            const file = `agent/${d.from}`
+            c.fail(`${file}:${d.line}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`, { at: { file, line: d.line } })
         }
-        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`)
         if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
     },
 })

package/src/checks/SK029-explicit-check-files.check.ts

@@ -5,28 +5,44 @@
 // keys resolved to (core/port-check-file.ts), so the check keeps running
 // where it ran, and the ci fix pass applies it before the gate reads the
 // files: a repo carried across by its first `shipkit ci`. The same holds for
-// the config: a retired `when` (only its `off:<why>` entries still load) and
-// `ruleExempt` become `off` entries in the managed block.
+// the config: a retired `when` (only its `off:<why>` entries still load),
+// `ruleExempt`, `hooks.disable` and a `defaults` slot set to false become
+// `off` entries in the managed block.
 import { join } from 'path'
 import { check, type FixResult } from '../check.ts'
 import { unportedCheckFiles } from '../core/port-check-files.ts'
 import type { PortRun } from '../core/port-check-cli.ts'
 import type { ConfigPlan, ConfigRewrite } from '../core/config-rewrite.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { legacyOffReason } from '../core/when.ts'
 
 /** the write half, run as its own process: it walks import closures on disk */
 const PORT_CLI = join(import.meta.dir, '../core/port-check-cli.ts')
 /** the config half, run as its own process: it loads repo.config.ts */
 const CONFIG_REWRITE = join(import.meta.dir, '../core/config-rewrite.ts')
 
-/** the retired config keys this repo still carries, and the `off` entries
- *  they become. defineRepo already refused every `when` word but `off:<why>` */
-export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string> } {
+/** the retired config spellings this repo still carries, and the `off`
+ *  entries they become. defineRepo already refused every `when` word but
+ *  `off:<why>`. `hooks.disable` and a `defaults` slot set to false never said
+ *  why, so they are lifted with the comment above them, else with a reason
+ *  that says none was recorded (core/when.ts legacyOffReason) */
+export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string>; lift: NonNullable<ConfigPlan['lift']> } {
     const off: Record<string, string> = {}
     for (const [id, raw] of Object.entries(c.when ?? {})) off[id] = raw.trim().replace(/^off:?/, '').trim()
     for (const [id, why] of Object.entries(c.ruleExempt ?? {})) off[id] ??= why
-    const keys = [...(c.when != null ? ['when'] : []), ...(c.ruleExempt != null ? ['ruleExempt'] : [])]
-    return { keys, off }
+    const lift: NonNullable<ConfigPlan['lift']> = []
+    const disable = c.hooks?.disable ?? []
+    if (c.hooks?.disable != null)
+        lift.push({ parent: 'hooks', entry: 'disable', value: '\\[[^\\]\\[]*\\]', ids: disable, reason: Object.fromEntries(disable.map((id) => [id, legacyOffReason('hooks.disable', id)])) })
+    const slots = Object.entries(c.defaults ?? {}).filter(([, d]) => d === false).map(([id]) => id)
+    for (const id of slots) lift.push({ parent: 'defaults', entry: id, value: 'false', ids: [id], reason: { [id]: legacyOffReason('defaults', id) } })
+    const keys = [
+        ...(c.when != null ? ['when'] : []),
+        ...(c.ruleExempt != null ? ['ruleExempt'] : []),
+        ...(c.hooks?.disable != null ? ['hooks.disable'] : []),
+        ...slots.map((id) => `defaults.${id}: false`),
+    ]
+    return { keys, off, lift }
 }
 
 export const explicitCheckFiles = check({
@@ -76,6 +92,7 @@ export const explicitCheckFiles = check({
                     ...(c.config.ruleExempt != null ? [{ key: 'ruleExempt', why: 'its exemptions are `off` now', phase: 'afterOff' as const }] : []),
                 ],
                 name: c.config.name,
+                lift: cfg.lift,
             }
             const r = await c.exec([process.execPath, CONFIG_REWRITE, c.root, JSON.stringify(plan)], { cwd: c.root, timeoutMs: 60_000 })
             try {
@@ -84,7 +101,7 @@ export const explicitCheckFiles = check({
                 hand.push(...out.hand)
                 if (out.restored != null) hand.push(`repo.config.ts was left as it was: ${out.restored}`)
             } catch {
-                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify(cfg.off)} by hand and drop ${cfg.keys.join(', ')}`)
+                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify({ ...Object.assign({}, ...cfg.lift.map((l) => l.reason)), ...cfg.off })} by hand and drop ${cfg.keys.join(', ')}`)
             }
         }
         const summary = [did.length > 0 ? did.join('; ') : 'nothing ported', ...(hand.length > 0 ? [`${hand.length} by hand: ${hand.join(' | ')}`] : [])].join('. ')

package/src/checks/SK034-commit-gates-armed.check.ts

@@ -0,0 +1,90 @@
+// SK034 commit gates armed (build/shipkit/commit-gates.md): the leak guard and
+// the message gate run only from git's hooks, so a repo whose hooksPath is
+// unset, or points at a foreign dir that never calls shipkit, commits with
+// both dark and nothing says so. `sk ci` arms an unset path; a foreign one is
+// the repo's own, so the check names the line to chain into it.
+import { readFileSync } from 'fs'
+import { isAbsolute, join } from 'path'
+import { nestedIn } from '../core/nesting.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
+import { LAYOUT } from '../core/layout.ts'
+import { check, type CheckEnv } from '../check.ts'
+import { hookBinInvocation } from '../hooks/run-hooks.ts'
+
+const HOOKS = [
+    { name: 'pre-commit', arg: '', guards: 'the leak guard' },
+    { name: 'commit-msg', arg: ' "$1"', guards: 'the message gate' },
+] as const
+
+const readOrNull = (abs: string): string | null => {
+    try {
+        return readFileSync(abs, 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** a hook body that runs the shipkit gate: a live line (never a comment)
+ *  whose failure is not swallowed by `|| true` */
+export const chainsShipkit = (body: string, hook: string): boolean =>
+    body.split('\n').some((l) => !l.trim().startsWith('#') && new RegExp(`\\bhooks\\s+${hook}\\b`).test(l) && !/\|\|\s*(?:true|:)\b/.test(l))
+
+/** the line to paste into a foreign hook: a clone with no install skips the
+ *  gate with a note, rather than failing every commit */
+export const guardedChain = (bin: string, hook: string, arg: string): string => {
+    const cli = bin.replace(/^bun\s+/, '')
+    return `if [ -f ${cli} ]; then ${bin} hooks ${hook}${arg} || exit 1; else echo "${hook}: rvlib-shipkit not installed (run bun install), shipkit gate skipped" >&2; fi`
+}
+
+const hooksDir = (root: string): string => {
+    const p = Bun.spawnSync([gitBin(), 'config', 'core.hooksPath'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    return p.exitCode === 0 ? p.stdout.toString().trim() : ''
+}
+
+/** the hooksPath and the two hook files it points at. A commit moves none */
+export function gatesKey(env: CheckEnv): string {
+    const nested = nestedIn(env.root)
+    if (nested != null) return `nested in ${nested}`
+    const dir = hooksDir(env.root)
+    if (dir === '') return 'hooks='
+    const at = (h: string): string => fileStamp(isAbsolute(dir) ? join(dir, h) : join(env.root, dir, h))
+    return `hooks=${dir}|${HOOKS.map((h) => `${h.name}=${at(h.name)}`).join('|')}`
+}
+
+export const commitGatesArmed = check({
+    id: 'SK034',
+    blocking: true,
+    title: 'commit gates armed',
+    description: 'git runs the shipkit pre-commit and commit-msg gates on every commit',
+    owner: 'build/shipkit/commit-gates.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // git config and hook files outside any tree id, so they are the key
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: gatesKey },
+    fix: 'none',
+    applies: 'always',
+    run: async (c) => {
+        const nested = nestedIn(c.root)
+        if (nested != null) return void c.lines.push({ kind: 'skip', text: `commit gates not checked, nested in ${nested}: the parent repo owns them` })
+        const top = await c.exec(['git', 'rev-parse', '--show-toplevel'], { cwd: c.root })
+        if (top.code !== 0) return void c.lines.push({ kind: 'skip', text: 'not a git repo: no commit to guard yet' })
+        const hp = await c.exec(['git', 'config', 'core.hooksPath'], { cwd: c.root })
+        const dir = hp.code === 0 ? hp.out.trim() : ''
+        if (dir === '' && process.env['CI'] != null && process.env['CI'] !== '')
+            return void c.lines.push({ kind: 'skip', text: 'commit gates not armed in this CI checkout: a CI run makes no commit, and the fix pass arms hooks on a machine only' })
+        if (dir === '') return void c.fail('the commit gates are not armed, so a commit runs no leak guard and no message gate: run `shipkit hooks install` (`shipkit ci` arms them too)')
+        const own = dir === LAYOUT.hooks
+        const bin = hookBinInvocation(c.root)
+        for (const h of HOOKS) {
+            const body = isAbsolute(dir) ? readOrNull(join(dir, h.name)) : c.read(`${dir}/${h.name}`)
+            if (body == null)
+                c.fail(`core.hooksPath=${dir} has no ${h.name}, so ${h.guards} never runs: ${own ? 'run `shipkit hooks install`' : `add one that runs \`${guardedChain(bin, h.name, h.arg)}\``}`)
+            else if (!chainsShipkit(body, h.name))
+                c.fail(`core.hooksPath=${dir}: its ${h.name} does not run the shipkit gate, so ${h.guards} never runs: add \`${guardedChain(bin, h.name, h.arg)}\` above its last line`)
+        }
+        if (!c.failed) c.ok(`git runs the shipkit commit gates (${own ? dir : `${dir}, chained to shipkit`})`)
+    },
+})
+
+export default commitGatesArmed

package/src/cli/cmd_Ci.ts

@@ -14,13 +14,14 @@ export class CiCommand extends Command {
     static override usage = Command.Usage({
         category: 'Gate',
         description: 'THE gate: repairs what a machine can, then runs every check. Run this, not the parts',
-        details: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
+        details: 'THE command. Repairs what a machine can (imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
             ['full gate, mechanical fixes applied', 'sk ci'],
             ['gate without the repair pass (checks can still write)', 'sk ci --no-fix'],
             ['leave repo config files alone', 'sk ci --no-fix-rules'],
             ['stop at the first failure', 'sk ci --bail'],
-            ['one check + its dep closure', 'sk ci --only typecheck'],
+            ['one check + its dep closure, the tree left alone', 'sk ci --only typecheck'],
+            ['one check, its own repair first', 'sk ci --only SK004 --fix'],
             ['every check declaring one group', 'sk ci --only wiki'],
             ['run everything, take nothing from the cache', 'sk ci --fresh'],
             ['include an opt in check', 'sk ci --with up:itch'],
@@ -31,12 +32,12 @@ export class CiCommand extends Command {
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
-    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fix = Option.Boolean('--fix', { description: 'repair before gating. Default on for a whole gate and off for a --only run, which leaves the tree alone unless --fix is named, and then repairs only what the named checks own. Nothing ever formats. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
     fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural autofixes of the built-in checks too. Default on. --no-fix-rules leaves repo config alone' })
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining checks: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
     skip = Option.Array('--skip', [], { description: 'skip a check group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include a check the quick gate leaves out (repeatable)' })
-    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group' })
+    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group. No repair pass unless --fix is named' })
     fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
@@ -68,7 +69,7 @@ export class CiCommand extends Command {
         return [
             ...(this.bail ? ['--bail'] : []),
             ...(this.json ? ['--json'] : []),
-            ...(this.fix ? [] : ['--no-fix']),
+            ...(this.fix === true ? ['--fix'] : this.fix === false ? ['--no-fix'] : []),
             ...(this.fixRules ? [] : ['--no-fix-rules']),
             ...(this.frozen ? ['--frozen'] : []),
             ...this.skip.flatMap((v) => ['--skip', v]),

package/src/cli/cmd_Commands.ts

@@ -71,6 +71,20 @@ export function renderMarkdown(rows: CommandRow[]): string {
     return out.join('\n').trim()
 }
 
+/** the eager form: one line per command, its positional arguments and its
+ *  description. Flags and examples are `sk <command> --help`, so a page every
+ *  session loads costs a line per command, not a screen */
+export function renderCompact(rows: CommandRow[]): string {
+    const out: string[] = []
+    let cat = ''
+    for (const r of rows) {
+        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
+        const sig = r.usage.replace(/^\$0/, 'sk').replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `sk ${r.path}`
+        out.push(`- \`${sig}\` — ${r.description}`)
+    }
+    return out.join('\n').trim()
+}
+
 export const BEGIN = '<!-- shipkit:commands -->'
 export const END = '<!-- /shipkit:commands -->'
 
@@ -89,14 +103,16 @@ export class CommandsCommand extends Command {
         examples: [
             ['markdown index', 'sk commands'],
             ['machine-readable', 'sk commands --json'],
-            ['write into a docs page between the markers', 'sk commands --out wiki/build/shipkit-cli.md'],
-            ['fail if that page is stale (lint mode)', 'sk commands --out wiki/build/shipkit-cli.md --check'],
+            ['write into a docs page between the markers', 'sk commands --out docs/commands.md'],
+            ['one line per command, for a page every session loads', 'sk commands --compact --out wiki/build/shipkit-cli.md'],
+            ['fail if that page is stale (lint mode)', 'sk commands --compact --out wiki/build/shipkit-cli.md --check'],
         ],
     })
 
     json = Option.Boolean('--json', false, { description: 'machine-readable [{path, category, description}]' })
     out = Option.String('--out', { description: 'host file carrying the shipkit:commands markers. The block between them is rewritten' })
     check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
+    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `sk <command> --help`)' })
 
     async execute(): Promise<number> {
         const rows = commandRows(
@@ -104,18 +120,18 @@ export class CommandsCommand extends Command {
             (this.cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }),
         )
         if (this.out == null) {
-            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${renderMarkdown(rows)}\n`)
+            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows)}\n`)
             return 0
         }
         const { existsSync, readFileSync, writeFileSync } = await import('fs')
         if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
         const host = readFileSync(this.out, 'utf8')
-        const next = spliceBlock(host, renderMarkdown(rows))
+        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows))
         if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
         if (next === host) { this.context.stdout.write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return 0 }
         if (this.check) {
             this.context.stdout.write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
-            this.context.stdout.write(`      fix: shipkit commands --out ${this.out}\n`)
+            this.context.stdout.write(`      fix: shipkit commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
             return 1
         }
         writeFileSync(this.out, next)