rvlib-shipkit 1.5.0 → 1.7.0

package/src/cli/cmd_Insights.ts

@@ -0,0 +1,78 @@
+// shipkit insights: the insights page in the console. The boxes come from
+// insightsOf, the one computation the daemon's route serves the page; this
+// file only renders them as text. It reads the manifests directly and needs no
+// daemon.
+import { homedir } from 'os'
+import { Command, Option } from 'clipanion'
+import { devRepos, insightsOf, placeWords, rowMatches, SCOPES, tagsOf, type InsightsAnswer, type Scope } from '../home/insights.ts'
+
+/** the boxes as text: a heading per box, then its rows, top `top` of each */
+export function renderInsights(a: InsightsAnswer, o: { tag?: string | null; query?: string; top: number; uses: boolean }): string[] {
+    const out: string[] = []
+    for (const b of a.boxes) {
+        if (o.tag != null && !b.tags.includes(o.tag)) continue
+        const rows = b.rows.filter((r) => rowMatches(b, r, o.query ?? ''))
+        out.push(`${b.title}  [${b.tags.join(', ')}]  ${rows.length} ${b.noun}${rows.length === 1 ? '' : 's'}`)
+        const width = Math.max(0, ...rows.slice(0, o.top).map((r) => r.key.length))
+        for (const r of rows.slice(0, o.top)) {
+            out.push(`  ${r.key.padEnd(width)}  ${String(r.repos).padStart(3)} repos  ${r.values.slice(0, 3).join('  ')}${r.values.length > 3 ? `  +${r.values.length - 3}` : ''}`)
+            if (o.uses) for (const u of r.uses) out.push(`      ${placeWords(u)}  ${u.value}${u.dev ? '  (dev)' : ''}`)
+        }
+        if (rows.length > o.top) out.push(`  … ${rows.length - o.top} more`)
+        out.push('')
+    }
+    out.push(`${a.repos} repos, ${a.files} package.json, read in ${a.ms}ms`)
+    for (const e of a.errors) out.push(`WARN ${e}`)
+    return out
+}
+
+export class InsightsCommand extends Command {
+    static override paths = [['insights']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the insights page as text: boxes about every repo, like which packages they use and by how many',
+        details: 'every package.json the house repos track (or every folder of ~/dev with --scope dev), turned into boxes: dependency usage sorted by how many repos use each package, version drift, script names. The same computation the page reads, no daemon needed',
+        examples: [
+            ['every box, the house repos', 'sk insights'],
+            ['every repo of ~/dev', 'sk insights --scope dev'],
+            ['where a package is used, and at which range', 'sk insights --scope dev --tag deps --query zod --uses'],
+            ['the whole list of one tag', 'sk insights --tag deps --top 1000'],
+            ['the route\'s exact payload', 'sk insights --json'],
+        ],
+    })
+
+    scope = Option.String('--scope', 'house', { description: 'house (the project list) or dev (every folder of ~/dev)' })
+    tag = Option.String('--tag', { required: false, description: 'only the boxes carrying this tag' })
+    query = Option.String('--query', { required: false, description: 'only the rows whose key or a value holds this text' })
+    top = Option.String('--top', '20', { description: 'rows shown per box' })
+    uses = Option.Boolean('--uses', false, { description: 'list every use under each row' })
+    json = Option.Boolean('--json', false, { description: 'the daemon route\'s exact payload: { now, scope, repos, files, boxes, errors, ms }' })
+
+    async execute(): Promise<number> {
+        if (!(SCOPES as readonly string[]).includes(this.scope)) {
+            this.context.stderr.write(`--scope must be one of ${SCOPES.join(', ')}, got ${JSON.stringify(this.scope)}\n`)
+            return 2
+        }
+        const scope = this.scope as Scope
+        const top = Number(this.top)
+        if (!(top >= 1)) {
+            this.context.stderr.write(`--top must be a number from 1, got ${JSON.stringify(this.top)}\n`)
+            return 2
+        }
+        const home = process.env.HOME || homedir()
+        // the hub route module draws app icons, so it loads only when this runs
+        const repos = scope === 'dev' ? devRepos(home) : (await import('../serve/project-gutter-route.ts')).railRepos(process.cwd(), home)
+        const a = await insightsOf(repos, scope)
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        if (this.tag != null && !tagsOf(a.boxes).includes(this.tag)) {
+            this.context.stderr.write(`--tag must be one of ${tagsOf(a.boxes).join(', ')}, got ${JSON.stringify(this.tag)}\n`)
+            return 2
+        }
+        for (const l of renderInsights(a, { tag: this.tag ?? null, query: this.query, top, uses: this.uses })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Keys.ts

@@ -75,6 +75,14 @@ export class KeysCommand extends Command {
                 return 0
             }
             out(`      key ${k.key}`)
+            // a lib hash names nothing by itself: the files behind it are what
+            // an edit has to touch to move this key
+            const lib = k.libFiles ?? []
+            if (lib.length > 0) {
+                out(`      toolkit files in its lib components: ${lib.length}`)
+                for (const f of lib.slice(0, 12)) out(`        ${f}`)
+                if (lib.length > 12) out(`        … ${lib.length - 12} more (shipkit keys --json)`)
+            }
             if (k.population === 'reads') {
                 for (const comp of k.components) out(`      ${comp}`)
                 // the rest of its identity is what it READ, stored with the
@@ -89,12 +97,15 @@ export class KeysCommand extends Command {
                 const lists = Object.entries(set.lists)
                 const dirs = Object.entries(set.dirs ?? {})
                 const links = Object.entries(set.links ?? {})
-                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}`)
+                // outside the repo a traced read is keyed on stat alone
+                const outside = Object.keys(set.sigs ?? {}).filter((p) => !(p in set.files))
+                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}${outside.length > 0 ? `, ${outside.length} file(s) outside the repo, by stat` : ''}`)
                 for (const [p, oid] of files) out(`        read ${p}=${oid ?? 'absent'}`)
                 for (const [p, kind] of exists) out(`        exists ${p}=${kind ?? 'absent'}`)
                 for (const [g, h] of lists) out(`        list ${g}=${h}`)
                 for (const [d, h] of dirs) out(`        entries ${d}=${h ?? 'absent'}`)
                 for (const [p, is] of links) out(`        link ${p}=${is ? 'yes' : 'no'}`)
+                for (const p of outside) out(`        stat ${p}=${set.sigs![p]}`)
                 return 0
             }
             // the excluded block is 44 lines here and it buries the component

package/src/cli/cmd_Overview.ts

@@ -88,7 +88,7 @@ export class OverviewCommand extends Command {
     json = Option.Boolean('--json', false, { description: 'the answers as json: { now, pm, daemon, processes, widgets }, processes as `shipkit gp --json`, widgets the daemon route\'s payload' })
 
     async execute(): Promise<number> {
-        const a = await overviewAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
+        const a = await overviewAnswer({ ...(await localProcessDeps(process.cwd())), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
             return 0

package/src/cli/cmd_Serve.ts

@@ -1,7 +1,6 @@
 // shipkit serve — the ONE hub server per repo (one vscode folder-open task,
 // clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
 import { Command, Option } from 'clipanion'
-import { runServe } from '../serve/run-serve.ts'
 
 export class ServeCommand extends Command {
     static override paths = [['serve']]
@@ -27,6 +26,8 @@ export class ServeCommand extends Command {
                 return 1
             }
         }
+        // the hub runtime carries the image tools: loaded when it serves
+        const { runServe } = await import('../serve/run-serve.ts')
         return runServe(process.cwd(), {
             print: (l) => this.context.stdout.write(`${l}\n`),
             printErr: (l) => this.context.stderr.write(`${l}\n`),

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

@@ -13,6 +13,7 @@ import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
 import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
+import { InsightsCommand } from './cli/cmd_Insights.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
@@ -30,6 +31,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'
@@ -97,9 +100,12 @@ export function buildCli(): Cli {
     cli.register(GlobalProcessRestartCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
+    cli.register(InsightsCommand)
     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 => {