rvlib-shipkit 1.5.0 → 1.6.0

package/src/cli/cmd_TraceAudit.ts

@@ -0,0 +1,62 @@
+// sk trace-audit — which gitignored paths each gate task reads that its key
+// cannot see, found by running the task once under the tracer, and with
+// --fix written into repo.config.ts (core/trace-audit.ts).
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { applyAudit, traceAudit } from '../core/trace-audit.ts'
+import { describeByTask } from '../core/audit-report.ts'
+import { setTraceEnabled } from '../trace/tracer.ts'
+
+export class TraceAuditCommand extends Command {
+    static override paths = [['trace-audit']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'gitignored paths a gate task reads that its key misses, found by tracing it once',
+        details: 'Runs each gate task once under the tracer (on by default: --disable for this machine, or SHIPKIT_TRACE=0 for one run) and lists the gitignored paths it read that neither the tracked tree nor repo.config ignoredInputs covers. The answer is kept for about a day under the git common dir, where every worktree reads it, and each finding joins the key of the task that read it at once. --fix writes the findings into the managed block of repo.config.ts, per task, without tracing again. Exit 1 when a key misses something.',
+        examples: [
+            ['audit, reusing a recent answer', 'sk trace-audit'],
+            ['trace again now', 'sk trace-audit --fresh'],
+            ['write the proposals into repo.config.ts', 'sk trace-audit --fix'],
+            ['machine-readable', 'sk trace-audit --json'],
+            ['stop tracing on this machine', 'sk trace-audit --disable'],
+            ['trace again, the default', 'sk trace-audit --enable'],
+        ],
+    })
+
+    fresh = Option.Boolean('--fresh', false, { description: 'trace again even when a recent answer is kept' })
+    fix = Option.Boolean('--fix', false, { description: 'write the kept proposals into repo.config.ts ignoredInputs' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable report' })
+    enable = Option.Boolean('--enable', false, { description: 'turn tracing back on for this machine, the default: the daemon\'s health pass audits about daily (SK031)' })
+    disable = Option.Boolean('--disable', false, { description: 'stop tracing on this machine: nothing audits here until --enable' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const out = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+        if (this.enable || this.disable) {
+            setTraceEnabled(this.enable)
+            out(this.enable ? 'ok: tracing is on for this machine: the health pass audits each repo about daily (SK031)' : 'ok: tracing is off for this machine')
+            return 0
+        }
+        if (this.fix) {
+            let r: Awaited<ReturnType<typeof applyAudit>>
+            // a config the block writer refuses (a hand edit, a key declared
+            // outside the markers) is an answer for a human, never a crash
+            try { r = await applyAudit(root) } catch (e) { out(`FAIL: ${(e as Error).message}`); return 1 }
+            if (r.note != null) out(`skip: ${r.note}`)
+            else out(Object.keys(r.added).length === 0 ? 'ok: repo.config.ts ignoredInputs already covers every path the audit found' : `ok: repo.config.ts ignoredInputs gained ${describeByTask(r.added)}`)
+            return 0
+        }
+        const r = await traceAudit(root, await loadRepoConfig(root), { fresh: this.fresh })
+        const missing = r.tasks.filter((t) => t.uncovered.length > 0)
+        if (this.json) { out(JSON.stringify(r)); return missing.length > 0 ? 1 : 0 }
+        if (r.skipped != null) { out(`skip: nothing traced: ${r.skipped}`); return 0 }
+        for (const t of r.tasks) {
+            if (t.status === 'unaudited') out(`WARN ${t.id} could not be audited: ${t.why}`)
+            else if (t.uncovered.length > 0) out(`FAIL: ${t.id} reads ${t.uncovered.length} gitignored path(s) its key misses: ${t.uncovered.slice(0, 5).join(', ')}${t.uncovered.length > 5 ? ', …' : ''}`)
+            else out(`ok: ${t.id}: its key covers every gitignored path it read`)
+        }
+        if (missing.length > 0) out(`      fix: sk trace-audit --fix adds ${describeByTask(Object.fromEntries(missing.map((t) => [t.id, t.propose])))} to repo.config.ts ignoredInputs`)
+        return missing.length > 0 ? 1 : 0
+    }
+}

package/src/cli.ts

@@ -30,6 +30,8 @@ import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
 import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
 import { WhenCommand } from './cli/cmd_When.ts'
+import { CacheAuditCommand } from './cli/cmd_CacheAudit.ts'
+import { TraceAuditCommand } from './cli/cmd_TraceAudit.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
@@ -100,6 +102,8 @@ export function buildCli(): Cli {
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
     cli.register(WhenCommand)
+    cli.register(CacheAuditCommand)
+    cli.register(TraceAuditCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(ConfigKeysCommand)

package/src/collections/collection-types.ts

@@ -228,6 +228,9 @@ export type Instance = {
      *  kind, a secret present or missing, a post its venue, an asset its roll
      *  count. Absent = this kind has nothing to say there */
     slot?: string
+    /** the group it sits in on the tree, under its section: an asset's kit
+     *  category. Absent = directly under the section */
+    group?: string
     type: ResourceType
     /** a slash path. Where a truth file exists this IS its repo-relative
      *  path; otherwise a VIRTUAL path under a root named for the type, and

package/src/collections/providers.ts

@@ -321,6 +321,8 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
                 const base: Instance = {
                     id: `media:${f.asset.id}`,
                     text: f.asset.id,
+                    label: f.asset.label ?? f.asset.id,
+                    group: f.kind.category,
                     // the roll count is the one fact a row of assets is read for
                     slot: rolls.length > 0 ? `${rolls.length} roll${rolls.length === 1 ? '' : 's'}` : manual ? 'manual' : undefined,
                     type: 'asset',
@@ -343,11 +345,11 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
                 const said: Partial<Instance> = manual && rolls.length === 0
                     // the brief IS the paste-ready artifact ("I don't even
                     // know what to paste" — the tile hands him the prompt)
-                    ? { text: `${f.asset.id} — manual, nothing uploaded`, label: f.asset.id, verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined }
+                    ? { text: `${f.asset.id} — manual, nothing uploaded`, verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined }
                     : rolls.length > 0 && !picked
-                        ? { text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, label: f.asset.id, verbs: ['pick'] }
+                        ? { text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, verbs: ['pick'] }
                         : stale
-                            ? { text: `${f.asset.id} — stale (a parent was re-picked)`, label: f.asset.id, verbs: ['pick'] }
+                            ? { text: `${f.asset.id} — stale (a parent was re-picked)`, verbs: ['pick'] }
                             : {}
                 out.push({ ...base, ...said, ...colour })
             }

package/src/core/app-icon.ts

@@ -0,0 +1,154 @@
+// a repo's app icon, drawn from its mark: the mark's transparent margin is
+// cut away, and what is left sits on a rounded plate in the repo's identity
+// colour, on the macOS icon grid (an 824 plate on a 1024 canvas). A mark that
+// already fills its box (a photo, a square tile) becomes the plate itself.
+// The app build and the page's preview both draw through appIconPngs.
+import { createCanvas, Image, type Canvas } from '@napi-rs/canvas'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { identityOfName, identityOfText, type Identity } from './identity-color.ts'
+import { configName, CONFIG_FILE } from './identity.ts'
+import { LAYOUT } from './layout.ts'
+
+/** the mark an app wears: the repo's own, largest first. Rasters only */
+export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
+
+export function appIconOf(root: string): string | null {
+    for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
+    return null
+}
+
+export const ICON_PX = 1024
+const PLATE = 824
+const RADIUS = 185
+/** the mark's longest side, as a share of the plate */
+const MARK = 0.7
+/** an alpha at or under this is margin, and is dropped: a generated image
+ *  often carries faint noise over its whole canvas, which would widen the box
+ *  to the full image and haze the plate */
+const NOISE = 48
+/** a mark whose box is this full is a tile already: it fills the plate */
+const TILE = 0.85
+
+export type Box = { x: number; y: number; w: number; h: number; fill: number }
+
+/** the box of the pixels that are not margin, and how full it is; null for a
+ *  mark with no such pixel */
+export function markBox(rgba: Uint8Array | Uint8ClampedArray, w: number, h: number): Box | null {
+    let x0 = w, y0 = h, x1 = -1, y1 = -1
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++)
+            if (rgba[(y * w + x) * 4 + 3]! > NOISE) {
+                if (x < x0) x0 = x
+                if (x > x1) x1 = x
+                if (y < y0) y0 = y
+                if (y > y1) y1 = y
+            }
+    if (x1 < 0) return null
+    let solid = 0
+    for (let y = y0; y <= y1; y++) for (let x = x0; x <= x1; x++) if (rgba[(y * w + x) * 4 + 3]! > 250) solid++
+    const bw = x1 - x0 + 1
+    const bh = y1 - y0 + 1
+    return { x: x0, y: y0, w: bw, h: bh, fill: solid / (bw * bh) }
+}
+
+const lum = (r: number, g: number, b: number): number => (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
+
+/** the mean lightness of the mark's own pixels, alpha weighted */
+function markLum(rgba: Uint8Array | Uint8ClampedArray): number {
+    let sum = 0, weight = 0
+    for (let i = 0; i < rgba.length; i += 4) {
+        const a = rgba[i + 3]! / 255
+        sum += a * lum(rgba[i]!, rgba[i + 1]!, rgba[i + 2]!)
+        weight += a
+    }
+    return weight === 0 ? 0.5 : sum / weight
+}
+
+const hexLum = (hex: string): number => {
+    const n = Number.parseInt(hex.slice(1), 16)
+    return lum((n >> 16) & 255, (n >> 8) & 255, n & 255)
+}
+
+/** of the two identity colours, the one the mark stands out on most */
+export function plateOf(id: Identity, markLightness: number): string {
+    return Math.abs(hexLum(id.colorLight) - markLightness) >= Math.abs(hexLum(id.colorDark) - markLightness) ? id.colorLight : id.colorDark
+}
+
+const towardWhite = (hex: string, t: number): string => {
+    const n = Number.parseInt(hex.slice(1), 16)
+    const c = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => Math.round(v + (255 - v) * t))
+    return `#${c.map((v) => v.toString(16).padStart(2, '0')).join('')}`
+}
+
+async function decode(bytes: Uint8Array): Promise<Image> {
+    const img = new Image()
+    img.src = Buffer.from(bytes)
+    // the pixels land on decode: drawn before it, the image is empty
+    await img.decode().catch(() => {})
+    if (img.width === 0) throw new Error('not an image the icon renderer reads')
+    return img
+}
+
+function plate(ctx: ReturnType<Canvas['getContext']>, o: number): void {
+    ctx.beginPath()
+    ctx.roundRect(o, o, PLATE, PLATE, RADIUS)
+}
+
+/** the icon at 1024px, and the plate colour it used (null: the mark is the plate) */
+export async function drawAppIcon(bytes: Uint8Array, id: Identity): Promise<{ canvas: Canvas; plate: string | null }> {
+    const img = await decode(bytes)
+    const src = createCanvas(img.width, img.height)
+    const sctx = src.getContext('2d')
+    sctx.drawImage(img, 0, 0)
+    const data = sctx.getImageData(0, 0, img.width, img.height)
+    const px = data.data
+    for (let i = 3; i < px.length; i += 4) if (px[i]! <= NOISE) px[i] = 0
+    sctx.putImageData(data, 0, 0)
+    const box = markBox(px, img.width, img.height) ?? { x: 0, y: 0, w: img.width, h: img.height, fill: 0 }
+    const out = createCanvas(ICON_PX, ICON_PX)
+    const ctx = out.getContext('2d')
+    ctx.imageSmoothingQuality = 'high'
+    const o = (ICON_PX - PLATE) / 2
+    if (box.fill >= TILE) {
+        // a tile: cover the plate with it, clipped to the plate's corners
+        const s = Math.max(PLATE / box.w, PLATE / box.h)
+        ctx.save()
+        plate(ctx, o)
+        ctx.clip()
+        ctx.drawImage(src, box.x, box.y, box.w, box.h, ICON_PX / 2 - (box.w * s) / 2, ICON_PX / 2 - (box.h * s) / 2, box.w * s, box.h * s)
+        ctx.restore()
+        return { canvas: out, plate: null }
+    }
+    const colour = plateOf(id, markLum(px))
+    const g = ctx.createLinearGradient(0, o, 0, o + PLATE)
+    // a lighter top edge, the way a native icon catches light
+    g.addColorStop(0, towardWhite(colour, 0.14))
+    g.addColorStop(1, colour)
+    ctx.fillStyle = g
+    plate(ctx, o)
+    ctx.fill()
+    const s = (PLATE * MARK) / Math.max(box.w, box.h)
+    ctx.drawImage(src, box.x, box.y, box.w, box.h, ICON_PX / 2 - (box.w * s) / 2, ICON_PX / 2 - (box.h * s) / 2, box.w * s, box.h * s)
+    return { canvas: out, plate: colour }
+}
+
+/** the icon as pngs, one per size asked, drawn once */
+export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX]): Promise<Buffer[]> {
+    const { canvas } = await drawAppIcon(bytes, id)
+    return sizes.map((px) => {
+        if (px === ICON_PX) return canvas.toBuffer('image/png')
+        const small = createCanvas(px, px)
+        const ctx = small.getContext('2d')
+        ctx.imageSmoothingQuality = 'high'
+        ctx.drawImage(canvas, 0, 0, px, px)
+        return small.toBuffer('image/png')
+    })
+}
+
+/** the identity a repo's config declares, else the one its name hashes to */
+export function identityOfRoot(root: string): Identity {
+    const path = join(root, CONFIG_FILE)
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    return identityOfText(text) ?? identityOfName(configName(text, root))
+}

package/src/core/audit-report.ts

@@ -0,0 +1,21 @@
+// THE KEPT AUDIT: what the last traced audit (core/trace-audit.ts) found, per
+// task. It lives under the git common dir, beside the ledger, so every
+// worktree of the repo on this machine reads the same one. The keys read it
+// (ledger/gate-checks.ts): a finding covers the task that read it before any
+// config write lands. The shape and the pure helpers: core/ignored-inputs.ts.
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { shipkitRoot } from './git-root.ts'
+import type { AuditReport } from './ignored-inputs.ts'
+
+export type { AuditReport, AuditTask, IgnoredInputs } from './ignored-inputs.ts'
+export { auditedExtras, describeByTask, ignoredFor, pendingByTask } from './ignored-inputs.ts'
+
+/** its name under the repo's shipkit state dir (CheckCtx.state reads it) */
+export const AUDIT_FILE = 'trace-audit.json'
+
+export const auditReportPath = (root: string): string => join(shipkitRoot(root), AUDIT_FILE)
+
+export function readAuditReport(root: string): AuditReport | null {
+    try { return JSON.parse(readFileSync(auditReportPath(root), 'utf8')) as AuditReport } catch { return null }
+}

package/src/core/cache-audit.ts

@@ -0,0 +1,72 @@
+// THE CACHE AUDIT: is a cached green still what a fresh run says? A check
+// keyed on files is only as honest as the paths it declares: a path it reads
+// and never declared cannot move its key, so an edit there serves the old
+// green. Nothing sees that while it happens. This re-runs a small sample of
+// the checks the cache would answer right now, fresh, and compares.
+//
+// the one constraint a reader breaks first: only a green is ever stored, so
+// a fresh FAIL under a key that replays a green is the whole finding. A
+// fresh green where the stored one warned, or the reverse, is reported too.
+import { composeChecks } from '../ledger/gate-checks.ts'
+import { Ledger } from '../ledger/ledger.ts'
+import { gateBinary } from '../ledger/toolchain-identity.ts'
+import { populationOf } from '../problems/problem-line.ts'
+import { runCheckPass } from './run-check.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type AuditRow = {
+    id: string
+    /** what the cache holds for the current key */
+    cached: 'pass' | 'warn'
+    /** what a fresh run said */
+    fresh: 'pass' | 'warn' | 'fail' | 'skip'
+    /** how the check is keyed: files (declared paths) or reads (recorded) */
+    keyedOn: 'files' | 'reads'
+    ms: number
+}
+
+export type AuditResult = {
+    /** checks the cache would answer now, the pool the sample came from */
+    pool: number
+    rows: AuditRow[]
+    /** the rows whose fresh verdict is not the cached one */
+    stale: AuditRow[]
+}
+
+/** the sample: `n` checks of the pool, a different stable set each day, so
+ *  every check is audited over time and two runs on one day agree */
+export function sampleOf(ids: string[], n: number, day: number): string[] {
+    const rank = (id: string): bigint => BigInt(Bun.hash(`${day}:${id}`))
+    return [...ids].sort((a, b) => (rank(a) < rank(b) ? -1 : rank(a) > rank(b) ? 1 : 0)).slice(0, n)
+}
+
+export async function auditCache(root: string, config: RepoConfig, o: { sample: number; only?: string[]; now?: number }): Promise<AuditResult> {
+    const composed = await composeChecks(root, config, { tier: 'quick' })
+    const ledger = Ledger.open(root, composed.map((g) => g.row.decl), { cliEntry: gateBinary(), read: true })
+    // what the cache would answer right now, keyed on the repo's own files
+    const pool: { id: string; cached: 'pass' | 'warn'; keyedOn: 'files' | 'reads' }[] = []
+    for (const g of composed) {
+        if (g.row.runs.off != null) continue
+        const pop = populationOf(g.row.decl)
+        if (pop !== 'content' && pop !== 'reads') continue
+        if (o.only != null && !o.only.includes(g.row.decl.id)) continue
+        const hit = ledger.replay(g.row.decl.id)
+        if (hit != null) pool.push({ id: g.row.decl.id, cached: hit.status, keyedOn: pop === 'content' ? 'files' : 'reads' })
+    }
+    const day = Math.floor((o.now ?? Date.now()) / 86_400_000)
+    const picked = new Set(o.only != null ? pool.map((p) => p.id) : sampleOf(pool.map((p) => p.id), o.sample, day))
+    const rows: AuditRow[] = []
+    for (const p of pool.filter((x) => picked.has(x.id))) {
+        const t = performance.now()
+        // fresh: nothing comes from the cache. A green it finds is stored, a
+        // failure is not, which is why a stale entry is forgotten below
+        const run = await runCheckPass(root, { config, composed, audience: 'health', only: [p.id], fresh: true, frozen: true, status: false, print: () => {}, detail: () => {} })
+        const r = run.results.find((x) => x.id === p.id)
+        rows.push({ id: p.id, cached: p.cached, fresh: r?.status ?? 'skip', keyedOn: p.keyedOn, ms: Math.round(performance.now() - t) })
+    }
+    const stale = rows.filter((r) => r.fresh !== 'skip' && r.fresh !== r.cached)
+    // a fresh failure is never stored, so without this the stale green would
+    // keep being served under the same key
+    for (const r of stale) ledger.forget(r.id)
+    return { pool: pool.length, rows, stale }
+}

package/src/core/canonical-scripts.ts

@@ -22,7 +22,7 @@ export function canonicalBodies(opts: ScriptStyle = {}): Record<string, string>
 }
 
 // conditional canon (bodies stated by the vocabulary page) — keyed by the
-// SK001 requirement name; a requirement with no canonical body (comfy:up) is
+// SK001 requirement name; a requirement with no canonical body is
 // deliberately absent: a fixer must not invent one
 export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, string> {
     return {

package/src/core/check-ctx.ts

@@ -18,12 +18,13 @@
 // A context with no pass reports and reaches the world, and a repo read there
 // throws rather than guess a root.
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
-import { dirname, join } from 'path'
+import { basename, dirname, isAbsolute, join } from 'path'
 import { atomicWrite } from './locked-write.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 import { blobOid, dirEntries, entriesHash, isLinkAt, kindOf, listingHash, Reads, type DirEntry } from './read-set.ts'
 import { CheckPass } from './check-pass.ts'
 import { normalizeInput, WHOLE_TREE } from '../ledger/git-scan.ts'
+import { shipkitRoot } from './git-root.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Scan } from '../scan.ts'
 import type { Line } from './wire.ts'
@@ -123,17 +124,25 @@ export class CheckCtx {
         if (p === WHOLE_TREE) throw new Error(`'${path}' is the repo root, not a file`)
         return p
     }
-    /** the text of a repo-relative file, null when there is none */
+    /** the text of a repo-relative file, null when there is none. An
+     *  absolute path reads a file outside the work tree (the kept audit under
+     *  the git common dir), recorded by that path */
     read(path: string): string | null {
         return this.bytes(path)?.toString('utf8') ?? null
     }
+    /** the text of a file under the repo's shipkit state dir (the git common
+     *  dir, shared by every worktree), null when there is none. Recorded by
+     *  its absolute path, like any read */
+    state(name: string): string | null {
+        return this.read(join(shipkitRoot(this.root), name))
+    }
     /** the raw bytes of a repo-relative file (an image, a binary), null when
      *  there is none. Recorded exactly like `read` */
     bytes(path: string): Buffer | null {
-        const p = this.rel(path)
+        const p = isAbsolute(path) ? path : this.rel(path)
         let bytes: Buffer
         try {
-            bytes = readFileSync(join(this.repo('read').root, p))
+            bytes = readFileSync(isAbsolute(p) ? p : join(this.repo('read').root, p))
         } catch (e) {
             const code = (e as { code?: string }).code
             if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'EISDIR') throw e
@@ -245,7 +254,7 @@ export class CheckCtx {
     // spawn without the Bun.spawn throw-on-missing-binary gotcha; SIGTERM at
     // timeoutMs, SIGKILL 2s later (one code path: core/spawn-timeout.ts)
     async exec(cmd: string[], opts?: { env?: Record<string, string | undefined>; cwd?: string; timeoutMs?: number }): Promise<{ code: number; out: string; timedOut: boolean }> {
-        this.world('exec')
+        this.world(`\`${cmd.slice(0, 3).map((a) => basename(a)).join(' ')}\``)
         // the environment as it stands NOW: left out, Bun hands the child the
         // one it started with, and a variable set since (a test seam, a flag
         // the gate set) never reaches it

package/src/core/check-runner.ts

@@ -442,6 +442,8 @@ type Live = RunnableCheck & CheckResult & {
     /** what an in process body read, null when it reached the world or ran
      *  as a subprocess */
     reads: ReadSet | null
+    /** why its answer cannot be stored on its reads, in its own words */
+    untracked: string | null
     /** it printed nothing of its own, so its one line is the headline below */
     synthetic: boolean
     /** what the headline carries after the id: a failure's last line, or the
@@ -498,7 +500,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const runDir = openRunDir(o.logDir)
     const checks: Live[] = sel.selected.map((u) => ({
         ...u,
-        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, synthetic: false, tail: '', extra: [],
+        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, untracked: null, synthetic: false, tail: '', extra: [],
         logPath: u.body.cmd != null ? join(runDir, `${u.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
     }))
     const selectedIds = new Set(checks.map((u) => u.id))
@@ -629,6 +631,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             // id, every line is tagged, and a failure carries a fix pointer
             await runCheckBody({ id: u.id, title: u.title, owner: u.owner, run: u.body.run, fix: u.fix }, t)
             u.reads = t.untracked == null ? t.reads.snapshot() : null
+            u.untracked = t.untracked
             u.lines = t.lines
             u.problems = findings(u, t.lines)
             u.unmeasured = t.unmeasured
@@ -785,7 +788,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             await measureAndKeep(u)
             return { value: answerOf(u), share: !killed.has(u.id) && !u.unmeasured }
         })
-        if (r.kind === 'attached') { o.ledger?.noteAttached(); adopt(u, r.value, r.pid) }
+        if (r.kind === 'attached') { o.ledger?.noteAttached(u.id); adopt(u, r.value, r.pid) }
         else if (r.kind === 'aborted') { u.status = 'skip'; u.note = bailed ? 'bailed' : 'interrupted'; u.lines = [] }
         else if (r.kind === 'overlapped') emit({ kind: 'warn', text: `${u.id} ran again beside another run: ${r.warn}` })
     }
@@ -828,7 +831,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             })
         }
         if (o.ledger != null && keep)
-            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads)
+            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads, u.untracked)
     }
 
     const start = (u: Live): void => {

package/src/core/floor-resolve.ts

@@ -201,9 +201,9 @@ function builtinFloorTask(id: string, root: string, io: FloorReader): { task: Ta
     return `no package.json '${id}' script`
 }
 
-// NOTHING here declares a read set on a repo's behalf, and that is a decision
-// rather than an omission. A floor slot with no `inputs` is measured every run,
-// which costs speed and never correctness (ledger/git-key.ts owns that default).
+// NOTHING here declares a read set on a repo's behalf. The composer keys a
+// floor slot with no `inputs` on the whole work tree plus the repo's
+// `ignoredInputs` (ledger/gate-checks.ts), and the traced audit fills those.
 //
 // The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
 // under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
@@ -214,10 +214,8 @@ function builtinFloorTask(id: string, root: string, io: FloorReader): { task: Ta
 // gate print `ok: test (replayed)` over a suite that exits 1
 // (tests/floor-cache-safety.test.ts holds the repro).
 //
-// Speed here is bought by a REPO saying what its own tasks read, in
-// `defaults`, which is the only declaration with a real hit rate anyway.
-// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
-// still undeclared, and the gate prints the cost of it once per run.
+// A narrower key is bought by a REPO saying what its own tasks read, in
+// `defaults`.
 
 export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): FloorResolution {
     const pkg = io.text('package.json')

package/src/core/git-root.ts

@@ -8,6 +8,7 @@
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'fs'
 import { dirname, join, resolve } from 'path'
 import { gitBin } from './git-bin.ts'
+import { LAYOUT } from './layout.ts'
 
 export type GitRoot = {
     /** absolute git dir of this work tree (per worktree) */
@@ -130,3 +131,15 @@ export const gitRoot = (dir: string): GitRoot | null => probeGitRoot(dir).root
 export function isLinkedWorktree(root: string): boolean {
     try { return statSync(join(root, '.git')).isFile() } catch { return false }
 }
+
+/** the one dir everything this repo remembers hangs off.
+ *
+ *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
+ *  git dir but shares the common one, and that sharing is safe because every
+ *  key component is content or a version string. A tree that is not a git
+ *  repo at all still gets one, under `.shipkit/cache/`, because a scaffold in
+ *  progress must not crash on it. */
+export function shipkitRoot(root: string): string {
+    const dir = gitRoot(root)?.commonDir
+    return dir == null ? join(root, LAYOUT.cache) : join(dir, 'shipkit')
+}

package/src/core/ignored-block.ts

@@ -0,0 +1,94 @@
+// THE IGNORED INPUTS BLOCK in `repo.config.ts`: the one place the traced
+// audit (core/trace-audit.ts) writes the gitignored paths each task reads.
+//
+// Its own markers, apart from the gate block (core/when-block.ts), so a repo
+// that writes `off` or `tests` by hand, with its comments, keeps them exactly
+// as they are. The same paranoia as the gate block:
+//   1. `ignoredInputs` declared OUTSIDE the markers is refused, because a
+//      second declaration is a duplicate key rather than a merge
+//   2. a block that no longer renders what the config loads was hand edited,
+//      and is refused rather than overwritten
+//   3. the result is read back through the loader the cli uses, and the
+//      previous bytes go back when it does not round trip
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { atomicWrite } from './locked-write.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import type { IgnoredInputs } from './audit-report.ts'
+
+export const IGNORED_BEGIN = '// >>> shipkit ignored inputs — managed block, the traced audit writes it, edit outside the markers'
+export const IGNORED_END = '// <<< shipkit ignored inputs'
+
+const isBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit ignored inputs')
+const isEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit ignored inputs')
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+const key = (s: string): string => (/^[A-Za-z_$][\w$]*$/.test(s) ? s : q(s))
+
+/** the same map, tasks and paths sorted, empty tasks dropped */
+export function normalizeIgnored(ii: IgnoredInputs): IgnoredInputs {
+    const out: IgnoredInputs = {}
+    for (const t of Object.keys(ii).sort()) if ((ii[t] ?? []).length > 0) out[t] = [...new Set(ii[t])].sort()
+    return out
+}
+
+/** the bytes between the markers, markers included */
+export function renderIgnoredBlock(ii: IgnoredInputs, pad: string): string[] {
+    const n = normalizeIgnored(ii)
+    return [
+        `${pad}${IGNORED_BEGIN}`,
+        `${pad}ignoredInputs: {`,
+        ...Object.entries(n).flatMap(([t, ps]) => [`${pad}${pad}${key(t)}: [`, ...ps.map((p) => `${pad}${pad}${pad}${q(p)},`), `${pad}${pad}],`]),
+        `${pad}},`,
+        `${pad}${IGNORED_END}`,
+    ]
+}
+
+function indentOf(lines: string[]): string {
+    for (const l of lines) {
+        const m = /^([ \t]+)\S/.exec(l)
+        if (m != null) return m[1]!
+    }
+    return '    '
+}
+
+export const validIgnoredInput = (p: unknown): p is string => typeof p === 'string' && p !== '' && !p.startsWith('/') && !p.split('/').includes('..')
+
+/** add `add` (task id → paths) to the repo's ignoredInputs, through the
+ *  managed block; the map after the write */
+export async function addIgnoredInputs(root: string, add: IgnoredInputs): Promise<IgnoredInputs> {
+    const file = join(root, 'repo.config.ts')
+    if (!existsSync(file)) throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
+    for (const p of Object.values(add).flat()) if (!validIgnoredInput(p)) throw new Error(`ignoredInputs '${String(p)}' must be a repo-relative path inside the repo`)
+    const text = readFileSync(file, 'utf8')
+    const lines = text.split('\n')
+    const c = await loadRepoConfig(root, { fresh: true })
+    const have = c.ignoredInputs ?? {}
+    const b = lines.findIndex(isBegin)
+    const e = lines.findIndex(isEnd)
+    if (b === -1 || e === -1 || e < b) {
+        if (Object.keys(have).length > 0) throw new Error('repo.config.ts declares `ignoredInputs` outside the managed block — move it between the markers first, or the audit would write a duplicate key')
+    } else {
+        const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
+        if (lines.slice(b, e + 1).join('\n') !== renderIgnoredBlock(have, pad).join('\n'))
+            throw new Error('the shipkit ignored inputs block in repo.config.ts no longer matches what the config loads, so it was hand edited — reconcile it by hand, then run the audit fix again')
+    }
+    const merged: IgnoredInputs = { ...have }
+    for (const [t, ps] of Object.entries(add)) merged[t] = [...(merged[t] ?? []), ...ps]
+    const next = normalizeIgnored(merged)
+    let out: string[]
+    if (b !== -1 && e > b) out = [...lines.slice(0, b), ...renderIgnoredBlock(next, /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''), ...lines.slice(e + 1)]
+    else {
+        const anchor = lines.findIndex((l) => /defineRepo\(\s*\{\s*$/.test(l))
+        if (anchor === -1) throw new Error(`repo.config.ts has no \`defineRepo({\` line to write into — paste this block inside the config object by hand:\n${renderIgnoredBlock(next, indentOf(lines)).join('\n')}`)
+        out = [...lines.slice(0, anchor + 1), ...renderIgnoredBlock(next, indentOf(lines)), ...lines.slice(anchor + 1)]
+    }
+    atomicWrite(file, out.join('\n'))
+    try {
+        const after = await loadRepoConfig(root, { fresh: true })
+        if (JSON.stringify(normalizeIgnored(after.ignoredInputs ?? {})) !== JSON.stringify(next)) throw new Error(`the loader read ignoredInputs ${JSON.stringify(after.ignoredInputs ?? {})}`)
+    } catch (err) {
+        atomicWrite(file, text)
+        throw new Error(`repo.config.ts was left as it was: ${(err as Error).message}`)
+    }
+    return next
+}