rvlib-shipkit 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## 1.4.0
+
+- **Fix: `shipkit gui` wears the house mark from any directory.** The app took its icon from cwd, so a run outside every house repo rebuilt `Shipkit.app` with no icon. The house now comes from cwd, else from the installed pm agent's `WorkingDirectory` (`installedHouseRoot`, `guiRoot`), and never from cwd itself.
+
+- **Fix: a busy machine never fails a suite as a wait.** The wait verdict judges the wall against `waitAllowance`, twice the budget divided by `1 - share²`, which has no end once the load reaches the core count; `fairWall` is gone. The fair share model failed four suites at 11 to 19s wall with about 1s of CPU at load 20.5 on 8 cores. The FAIL line names the load a wait was judged at instead of "on an idle machine", and `overWords` moved to `judge-suites.ts`.
+- `Answers.busyTimeout()` names the busy timeout sqlite holds on the open handle, so a test asserts a read waits only `READ_BUSY_MS` on a writer instead of timing it.
+- **Fix: a save in a repo nobody looks at costs the daemon nothing.** A hub's warm answers (rows, runs page, wiki graphs) recompute in the background only while a page read them in the last 30s (`WARM_WATCH_MS`), at most once per ten times their last compute (`WARM_SPACING`); the first reader after that waits on one fresh compute. Measured on a live daemon, one file of a large repo touched every 2s: 83.5% cpu before, 5.0% after.
+- **Fix: widgets scan and render only while someone reads them.** No read of `/api/home/widgets.json` for 30s (`WIDGET_WATCH_MS`), and the daemon walks no repo and renders no widget; the first read after that waits on a scan and a render. `Widgets.look(repos)` is the reader's call.
+- **Fix: pm reads the house side again only when it moved.** The `pm-config.ts` child answers with the paths it read and their stamp, and pm stats them every 15s (about 4ms) instead of spawning a child that imports every unit file (about 0.6s of cpu). A dir counts by its subdirs and unit files, so a temp file coming and going in a repo root moves nothing. `repoUnitFiles(root, dirs)` collects the dirs its walk read.
+- **Fix: an ask probe runs with the env the process holds now.** `shipkit asks check` and SK026 spawn each probe with `process.env` named, since bun's default is the env the process started with, blind to a later write such as a caller pointing `HOME` elsewhere.
+- **Fix: the line SK009 asks a foreign commit-msg hook to add works on a clone without `node_modules`.** It reads `if [ -f <cli> ]; then <shipkit> hooks commit-msg "$1" || exit 1; else echo "… attribution gate skipped" >&2; fi`, so a fresh clone skips the gate with a note instead of failing every commit. The bare form and the multi line guarded form both still count as chained.
+- **Fix: the runs page list never moves in.** The `reading the run record…` line sits inside the list box, where the list will be, so the list no longer drops 8px when it arrives (a refresh of the runs tab measured CLS 0.0205, now 0.0019).
+- **The checks page and the asks page are tables.** One line per item on the activity table style instead of a card grid, under group headers that count their lines. A check line: status dot, id, title, age of its last result, duration against its budget, the first finding line (cut, every line on hover), and how it is planned (`on change`, `every 7d`, `once`, `every run`, `health pass`, `every release`, `off`); groups failing, warning, never ran, passing, off, most recent first. An ask line: kind, title, age, what it blocks, `auto close` or `manual`; open asks by what they block then oldest first, done ones after. Passing, off and done fold by default, a header click folds or opens, and the choice is kept per viewer (`hub:table-folds`). The filter input and the `a`, `n`, `r` keys narrow the lines. An ask resource now carries `ask: AskFacts` (kind, created, closed, blocks, probe), and `Ask` gains `closed`.
+- **Every url on the overview opens three ways.** Before the url: open in Chrome, and open as the process's own app (a spinner while it builds). The url itself opens the default browser. The open pick in the url header is gone, and `MachineSt.openProcess` takes the way as its second argument.
+- **The shipkit app finds and inspects.** Cmd-F opens the page's find bar (cmd-G, shift-cmd-G, Esc), alt-cmd-I the Web Inspector (Edit › Find, View › Developer Tools). The zoom keys stay.
+- **Every global process with a url can open as its own app.** One Swift source serves the shipkit window and each process's app: the bundle's Info.plist names it and its start page. The app is built on first use into the declaring repo's `.shipkit/wrapper/<id>.app` (bundle id `dev.shipkit.app.<id>`, its image icon, else the repo's mark), rebuilt only when the source, the icon or the url changed. pm's resource route takes `chrome` (Chrome, else the default browser) beside `open` and `app`, and reports `appBusy` while an app builds.
+- **Fix: no empty band at the bottom of every page.** The daemon or pm not answering is a toast floating over the bottom right corner of the page column, above the dock (`MachineToasts`, replacing `MachineBar`), drawn only while it lasts and taking no room.
+- **The overview's process switches are small icons beside the label.** Play (stop while it runs) and restart sit in their own narrow columns right after the process name, every play under every play, each with a tooltip; open is an open external icon before the url, which stays a link. The new window button and the open choice sit in the url's header. New icons `play`, `stop`, `restart`, `external`.
+- **The runs page opens on its tabs.** The record chart no longer stands over the tabs: it shows only in the `runs` tab, under its list. `test files to fix`, `slowest checks` and `longest runs` draw no chart.
+- **Smaller monitor cards.** The `.wbar` meter is 40px, a meter's value cell takes the class `wv` (11px, tabular figures), and a widget card's padding and line height are tighter.
+- **SK028 names both ways out.** Each finding asks for the screenshot, or for the rule turned off with its reason by the exact key: `when: { SK028: 'off:<why this repo shows no screenshot>' }` in repo.config.ts, which refuses an `off` with no reason.
+- **SK016 says the real refusal condition and offers `--fix` only when it can fix.** The line reads `still read, and refused by the first shipkit release after \`shipkit fleet\` shows no repo below 0.40 and none still carrying a check script`, instead of `read through 0.40, refused after`. Its pointer says `shipkit check --fix SK016 rewrites N of them` while something is mechanical, and that the port is by hand when nothing is. A fix pointer that says `by hand` no longer gets the `· autofix:` suffix, the TODO placeholder warning included.
+- **Fix: the overview never moves when the daemon or pm stops answering.** A process's note or a refused take over is a warn mark after its state words, the words on hover, instead of a line of its own. The daemon, the web or pm not answering reads `no answer` in its own row (row status `silent`, `CoreOpts.silent`), and while pm is silent every global process keeps its line with its state `unknown`. A widget error is a mark on its card's title. The table waits for pm's first answer and the list's order, so a cold load adds no row after its first paint. `bun run home:shift` now also refuses the daemon's and pm's answers in the browser and requires the table's height unchanged.
+- **SK001 asks for `lint` and `fmt` only once the repo has a source file**, like `test` already waits for a test file. A source file is a code file outside installs, build output, dot dirs and `repo.config.ts`, with more in it than an empty `export {}`, or any test file.
+- **Fix: the suite budget verdict is stable.** One continuous rule replaces the step at load == cores: the load is read before the run (never after this run's own parallel phase) and enters as a share of the cores; a suite is charged the smaller of its CPU and its wall, so bun's GC and JIT threads and side by side children are never billed as the suite's time, against a CPU allowance that grows with the load share up to 1.5 times the budget; a wait fails when the wall at a fair share of the machine passes twice the budget. A check's own budget warning (`passed in 12.0s, over its 10s budget`) is no longer printed while the load is at or past the core count, where the wall is the machine's. `SHIPKIT_MACHINE_LOAD=<load1>/<cores>` pins the reading for tests.
+- **Fix: a `never:` check gets the subprocess budget.** A check that declares `never` reads the world like a `ttl` one, so its default budget is 10s instead of the 2s of an in process body: SK026, which runs each ask's own shell probe, no longer warns at 7s.
+- **SK014 soft hits are a note.** With no `prose.baseline`, the soft classes print as one note, `N soft hit(s) need a human read (sentence 900, passive 400, modal 120, …)`, naming every soft class with its count, instead of a warning that named only two of them. Within a declared baseline it stays a note, above it the check fails with the same breakdown.
+- **⌘J opens the picker and ⌘K the overview.** The lines on top of the project list read jump to… ⌘J, overview ⌘K, activity ⌘L, planned ⌘', and the picker lists home, activity and planned in that order.
+- **SK009 checks the hook, not the history.** The commit-msg hook is what refuses AI attribution, so SK009 now checks in every repo that it is armed: `core.hooksPath` at `.shipkit/hooks`, or a foreign dir whose commit-msg chains the shipkit gate, and the finding prints the exact line to add (`<shipkit> hooks commit-msg "$1" || exit 1`). It no longer scans `git log`: what is pushed is accepted as it is. A declared-public repo still needs the `.claude/settings.json` silencer and a clean ref name; a telling branch nobody pushed warns as `local only` instead of failing. `hooks.disable: ['commit-message']` no longer lifts the attribution rule: it runs as its own `ai-attribution` gate, never disabled.
+- **Fix: a gate never writes or commits in another repo.** `shipkit ci` and `check` used to rewrite the docsBase wiki's `local-projects.md` and commit it there ("chore(machine): refresh local-projects row"), so a narrowed gate in one repo landed commits in the house repo. They now file the row in the machine db only. The daemon's hourly sweep (`startSweeps` takes an `also`) runs `landMotherhome`, which writes every filed row into its page and lands it as one scoped commit, at most once a day per page (`LAND_GAP_MS`), with the same churn rule (data change or 7 days) and the same dead path pruning.
+- **SK002 asks each contract only where it means something.** A public surface is a declared venue, `deploy.sh`, a GitHub Pages workflow, a wrangler config, or `visibility: 'public'` (unless an npm package is the repo's only surface). Before one exists the identity contract is silent instead of a warning, and after, it wants favicon, OG image and logo at the dir the deploy serves (a Pages artifact path, a wrangler output dir), overridden by the new `contracts.webRoot`, `public` otherwise; `shipkit assets identity` writes there too. An undeclared `.shipkit/social/` ships only once a post says `status: posted`: a folder of drafts is a note. A `discord` social channel no longer requires the discord server contract. Steam asks for `vdf/` only once `.shipkit/steam/steam_appid.txt` records the appid, and names that blocker before. Contract lines read `steam: …` instead of a double space. New detector `fileMatches(glob, pattern)`.
+- **Fix: a remembered world answer says how old it is, never a clock time frozen into its text.** A `ttl` check's first line carried `(ran at 21:47:51, kept until 22:47:51)` in its stored text, which the next day still read as an expiry to come. The times now ride as data on the line (`Line.stamp`: `at`, `until`, `cached`), and every surface renders them against its own clock: `(ran just now, kept 1h more)`, `(cached, ran 3h ago, kept 57m more)`, `(ran 1d ago, expired 1d ago)`. `formatLine` takes an optional `now`, and `lineText`, `stampWords` and `spanShort` are exported from the wire module. An answer stored by an older build drops its baked times on replay.
+- **Fix: every status surface shows every finding of a check, not the first one.** A failed build step that speaks the wire (the suite runner) keeps the FAIL lines its report closes on, and its headline counts them: `test — FAIL: 3 test(s) failed (+1 more below)`, the budget failure listed under it instead of hidden. The Activity page's hover list and `shipkit activity` list every fail and warn line of each check, the worst weight first (`StatusCheck.lines`), so SK009 shows its 17 attributed commits beside its ref name, and `tts` both of its warnings.
+- **Fix: a non-blocking failure reads orange everywhere, as the gate prints it.** The run record filed a failure of a `blocking: false` check as `fail`, so Activity, the rail's dot and the check feed painted it red while the gate printed WARN and exited 0. The record now files it as `warn`, the status the gate reported.
+- **Fix: SK027 no longer flags a working link.** A link that leaves `agent/` but stays in the repo (`../tools/readme.md`) is checked on disk and fails only when the file is really missing. A link to a folder (`[docs](external-docs/)`, or a backticked `agent/external-docs/`) reaches every page under it. An orphan page still fails. The dangling hint no longer tells anyone to backtick a working link. `scanMd` takes a `boundary`, the dir a ref may leave the scan root for.
+- **SK027 says how to fix an orphan.** The finding asks for a markdown link from the page that should mention it, and names that page when one already names the file (its path, its file name, or a glob like `*_Compte_rendu_*`): `add a markdown link to it from agent/brief.md, which already names it`. Otherwise it points at `agent/index.md or the page of its topic`, and deleting comes second, for a dead page only. An `@./page.md` include now counts as a link.
+
 ## 1.3.0
 
 - **`shipkit ci` prints what the reader acts on, and nothing else.** A green run is one line per check that ran and one verdict line: `ok: test 920 tests (1.4s)` then `ok: 1 check green`, where it used to print nine. A test check carries its count on its own line. The whole gate folds its tier and cache counts into the verdict (`ok: 31 checks green; quick tier; 25 cached, 5 ran, 1 never cached`). A fix pass prints only when it rewrote files, and names them. A green check prints one line, a warned one only its warnings and their `fix:` pointers, a failure prints whole. `--only` says nothing about checks outside its selection (floor gaps, `off` checks, parked checks). `--verbose` restores every line the default leaves out: the clean fix pass, the machine pool, the tier, the cache declarations, the parked checks, the old summary and the cache counts. STATUS.md keeps them all, a release or bump gate still prints them all, and `--json` is unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/asks/asks-queue.ts

@@ -9,7 +9,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFile
 import { atomicWrite, mutateLease, withMutateLease } from '../core/locked-write.ts'
 import { join } from 'path'
 
-export type Ask = { file: string; status: string; kind: string; created: string; blocks: string; check: string | null; title: string }
+export type Ask = { file: string; status: string; kind: string; created: string; closed: string | null; blocks: string; check: string | null; title: string }
 export type CreateOpts = { kind?: string; blocks?: string; check?: string; why?: string }
 
 /** filename slug: kebab, truncated at a WORD boundary (never mid-word — a
@@ -31,6 +31,7 @@ const parse = (dir: string, file: string): Ask => {
         status: fm('status') ?? 'open',
         kind: fm('kind') ?? 'action',
         created: fm('created') ?? '?',
+        closed: fm('closed'),
         blocks: fm('blocks') ?? '-',
         check: fm('check'),
         title: md.match(/^# (.+)$/m)?.[1] ?? file,
@@ -73,7 +74,8 @@ function checkAsksBody(dir: string, print: (line: string) => void): { closed: nu
     for (const a of listAsks(dir)) {
         if (a.status === 'done') { renameSync(join(dir, a.file), join(done, a.file)); print(`archived ${a.file} → done/`); continue }
         if (a.check == null) { print(`still ${a.status.padEnd(8)} ${a.file} (manual — no probe)`); continue }
-        const p = Bun.spawnSync(['bash', '-lc', a.check])
+        // env named: bun's default is the env the process started with, blind to a later process.env write
+        const p = Bun.spawnSync(['bash', '-lc', a.check], { env: process.env })
         if (p.exitCode === 0) {
             const md = readFileSync(join(dir, a.file), 'utf8').replace(/^status:.*$/m, `status: done\nclosed: ${new Date().toISOString().slice(0, 10)}`)
             atomicWrite(join(dir, a.file), md)

package/src/assets/kits/identity-kit.ts

@@ -7,9 +7,9 @@
 //   hook, so picking a logo roll re-renders the whole identity set from the
 //   picked png. Headless `identity` uses the current pick — no pick yet is a
 //   loud FAIL, never a placeholder.
-// Outputs are COMMITTED: public/favicon.png (512² master), public/og.png
-// (1200×630), public/logo.png. Brand data is per-repo and never defaults
-// across repos.
+// Outputs are COMMITTED at the web root (public/ unless the deploy says
+// otherwise): favicon.png (512² master), og.png (1200×630), logo.png. Brand
+// data is per-repo and never defaults across repos.
 import { createCanvas, loadImage, type Image, type SKRSContext2D } from '@napi-rs/canvas'
 import { mkdirSync } from 'fs'
 import { dirname, join } from 'path'
@@ -81,11 +81,13 @@ const defaultOg = (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: numbe
 }
 
 /** THE identity writer — any mark png (canvas draw or picked comfy roll) →
- *  public/logo.png (1024² master) + public/favicon.png (512² resize) +
- *  public/og.png (default card: bg + mark left + name/tagline right). */
-export async function renderIdentityFromMark(brand: Brand, root: string, markPng: Buffer): Promise<string[]> {
+ *  <web>/logo.png (1024² master) + <web>/favicon.png (512² resize) +
+ *  <web>/og.png (default card: bg + mark left + name/tagline right), where
+ *  <web> is the dir the site serves (contracts/web-surface.ts, default public) */
+export async function renderIdentityFromMark(brand: Brand, root: string, markPng: Buffer, webRoot = 'public'): Promise<string[]> {
     const out: string[] = []
-    const write = async (rel: string, buf: Buffer): Promise<void> => {
+    const write = async (name: string, buf: Buffer): Promise<void> => {
+        const rel = webRoot === '.' ? name : `${webRoot}/${name}`
         const path = join(root, rel)
         mkdirSync(dirname(path), { recursive: true })
         await Bun.write(path, buf)
@@ -94,26 +96,26 @@ export async function renderIdentityFromMark(brand: Brand, root: string, markPng
     const logoPng = await sharp(markPng)
         .resize(LOGO_SIZE, LOGO_SIZE, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
         .png().toBuffer()
-    await write('public/logo.png', logoPng)
+    await write('logo.png', logoPng)
     // favicon = logo master resized to 512² (browsers derive the rest)
-    await write('public/favicon.png', await sharp(logoPng).resize(FAVICON_SIZE, FAVICON_SIZE).png().toBuffer())
+    await write('favicon.png', await sharp(logoPng).resize(FAVICON_SIZE, FAVICON_SIZE).png().toBuffer())
     const og = createCanvas(OG_W, OG_H)
     const ctx = og.getContext('2d')
     if (brand.drawOg != null) brand.drawOg(ctx, brand, { w: OG_W, h: OG_H })
     else defaultOg(ctx, brand, { w: OG_W, h: OG_H }, await loadImage(logoPng))
-    await write('public/og.png', og.toBuffer('image/png'))
+    await write('og.png', og.toBuffer('image/png'))
     return out
 }
 
 /** Headless render of the full identity set. Canvas marks draw themselves;
  *  comfy marks need `markFile` = the PICKED roll (the caller resolves the
  *  pick — run-assets does) and FAIL loud without one. */
-export async function renderIdentity(brand: Brand, root: string, opts?: { markFile?: string }): Promise<string[]> {
+export async function renderIdentity(brand: Brand, root: string, opts?: { markFile?: string; webRoot?: string }): Promise<string[]> {
     if (brand.mark.backend === 'canvas') {
         const logo = createCanvas(LOGO_SIZE, LOGO_SIZE)
         await brand.mark.draw(logo.getContext('2d'), { id: 'identity-logo', prompt: '' })
-        return renderIdentityFromMark(brand, root, logo.toBuffer('image/png'))
+        return renderIdentityFromMark(brand, root, logo.toBuffer('image/png'), opts?.webRoot)
     }
     if (opts?.markFile == null) throw new Error(`brand '${brand.name}' uses a comfy mark and no roll is picked — ${NO_PICK_FIX}`)
-    return renderIdentityFromMark(brand, root, await sharp(opts.markFile).png().toBuffer())
+    return renderIdentityFromMark(brand, root, await sharp(opts.markFile).png().toBuffer(), opts.webRoot)
 }

package/src/assets/run-assets.ts

@@ -8,6 +8,9 @@ import { comfyResolver, generateRoll, type ComfyResolver } from './gen/generate-
 import { parentIdsOf, resolveParentContext, topoSort, type ParentContext } from './gen/derived.ts'
 import { allAssets, findAsset, loadKit, type ComfyGen, type ResolvedKit } from './kit-config.ts'
 import { NO_PICK_FIX, renderIdentity, type Brand } from './kits/identity-kit.ts'
+import { webDeploys, webRootOf } from '../contracts/web-surface.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { defineRepo, loadRepoConfig } from '../repo-config.ts'
 import { assetDir, listRolls, readPick, readPromptOverlay } from './roll-workspace.ts'
 
 export type Print = (line: string) => void
@@ -111,6 +114,12 @@ const brandHashPath = (root: string): string => join(root, '.shipkit/identity/br
 const brandHash = async (root: string): Promise<string> =>
     new Bun.CryptoHasher('sha256').update(await Bun.file(join(root, '.shipkit/identity/brand.ts')).text()).digest('hex').slice(0, 16)
 
+/** the dir the identity outputs go to: the same answer SK002 reads */
+async function repoWebRoot(root: string): Promise<string> {
+    const config = existsSync(join(root, 'repo.config.ts')) ? await loadRepoConfig(root) : defineRepo({ name: 'repo' })
+    return webRootOf(config.contracts?.webRoot, webDeploys(CheckCtx.open({ root, config })))
+}
+
 export type IdentityRender = { written: string[] } | { blocked: string }
 
 export async function renderIdentityNow(root: string): Promise<IdentityRender> {
@@ -133,7 +142,7 @@ export async function renderIdentityNow(root: string): Promise<IdentityRender> {
         markFile = join(dir, pick.pick)
         if (!existsSync(markFile)) return { blocked: `picked roll ${pick.pick} vanished from ${dir} — re-pick in the studio` }
     }
-    const written = await renderIdentity(brand, root, { markFile })
+    const written = await renderIdentity(brand, root, { markFile, webRoot: await repoWebRoot(root) })
     await Bun.write(brandHashPath(root), (await brandHash(root)) + '\n')
     return { written }
 }
@@ -142,7 +151,8 @@ export async function renderIdentityNow(root: string): Promise<IdentityRender> {
  *  Returns what happened; 'blocked' = only a human pick can clear it. */
 export async function healIdentity(root: string): Promise<{ state: 'fresh' | 'rendered' | 'blocked' | 'absent'; detail?: string }> {
     if (!existsSync(join(root, '.shipkit/identity/brand.ts'))) return { state: 'absent' }
-    const outputsMissing = ['public/favicon.png', 'public/og.png', 'public/logo.png'].some((p) => !existsSync(join(root, p)))
+    const web = await repoWebRoot(root)
+    const outputsMissing = ['favicon.png', 'og.png', 'logo.png'].some((p) => !existsSync(join(root, web, p)))
     const stored = existsSync(brandHashPath(root)) ? (await Bun.file(brandHashPath(root)).text()).trim() : null
     if (!outputsMissing && stored === (await brandHash(root))) return { state: 'fresh' }
     const r = await renderIdentityNow(root)

package/src/check.ts

@@ -160,7 +160,8 @@ export type CheckDef = {
      *  passes over it prints a WARN and reads yellow, and never blocks.
      *  Judged on the wall time of a run that measured, at the quick tier.
      *  Default 2000 for an in process body, 10000 for a build step, a `cmd`
-     *  or a world probe (core/budget.ts). The repo's `budgets` wins over it. */
+     *  or a world probe (one that declares `ttl` or `never`, core/budget.ts).
+     *  The repo's `budgets` wins over it. */
     budgetMs?: number
     /** a label several checks share, so `--skip <group>` parks all of them
      *  and `--only <group>` runs all of them. */
@@ -373,12 +374,13 @@ export async function runCheckBody(
 }
 
 /** tag every severity line with the check id; a fix pointer of a fixable check
- *  advertises the autofix. Idempotent, since an already-tagged line passes
- *  back through here on a cached suite replay. */
+ *  advertises the autofix, unless it names its own `--fix` or says the repair
+ *  is `by hand`. Idempotent, since an already-tagged line passes back through
+ *  here on a cached suite replay. */
 export function tagCheckLines(u: { id: string; fix?: unknown }, lines: Line[]): Line[] {
     return lines.map((l) => {
         if (l.kind === 'fix-warn' || l.kind === 'fix-fail')
-            return u.fix == null || l.text.includes('--fix ')
+            return u.fix == null || l.text.includes('--fix ') || /\bby hand\b/.test(l.text)
                 ? l
                 : { ...l, text: `${l.text} · autofix: shipkit check --fix ${u.id}` }
         if (l.kind === 'note') return l

package/src/checks/SK001-package-json-shape.check.ts

@@ -107,8 +107,11 @@ export function evaluatePackageJson(t: CheckCtx): void {
 
     // `test` is asked for only once the repo HAS tests: the fixer deliberately
     // refuses to scaffold it before that (a fixer never manufactures a
-    // failure), so nagging for it would be a WARN no machine may clear
-    const baseline = BASELINE.filter((n) => n !== 'test' || hasTestFiles(testFiles(t)))
+    // failure), so nagging for it would be a WARN no machine may clear. For
+    // the same reason `lint` and `fmt` wait for a source file to read
+    const tests = hasTestFiles(testFiles(t))
+    const source = tests || hasSourceFiles(t)
+    const baseline = BASELINE.filter((n) => (n === 'test' ? tests : source))
     const missingBaseline = baseline.filter((n) => !has(n))
     if (missingBaseline.length > 0)
         t.warn(`package.json: missing baseline script(s): ${missingBaseline.join(', ')}`)
@@ -173,6 +176,21 @@ export function hasTestFiles(paths: readonly string[]): boolean {
     })
 }
 
+const SOURCE_GLOB = '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'
+/** an empty module: nothing but `export {}`, semicolons and whitespace */
+const EMPTY_MODULE = /^(?:\s|;|export\s*\{\s*\})*$/
+
+/** a code file with something in it, outside installs, build output, dot dirs
+ *  and the repo config: what lint and fmt would read. Stops at the first */
+function hasSourceFiles(c: CheckCtx): boolean {
+    for (const f of c.list(SOURCE_GLOB)) {
+        const parts = f.split('/')
+        if (f === 'repo.config.ts' || !parts.slice(0, -1).every((d) => !TEST_SKIP.has(d) && !d.startsWith('.'))) continue
+        if (!EMPTY_MODULE.test(c.read(f) ?? '')) return true
+    }
+    return false
+}
+
 export const packageJsonShape = check({
     id: 'SK001',
     blocking: true,

package/src/checks/SK009-commit-ai-tells.check.ts

@@ -1,23 +1,22 @@
-// SK009 — commit AI tells (identity/how-we-commit.md): a repo that will be
-// seen must not read as AI-driven. Prevention lives at the source (the
-// attribution setting + the standing from-commit-one ban, which binds every
-// repo because history follows a repo public and is never rewritten); this
-// rule is the declared-public tripwire: the FULL git log scanned for AI
-// attribution and dash punctuation, plus the tracked settings file that
-// silences attribution. Declared-private repos idle with an ok that RESTATES
-// the ban — a green line must never teach the wrong rule. The remedy for
-// pushed history is the owner's decision, never an automatic rewrite; only
-// an unpushed tip commit may be amended, and the fails say so.
+// SK009 commit AI tells (identity/how-we-commit.md): the commit-msg hook is
+// what refuses AI attribution, in every repo, so this check verifies the hook
+// is ARMED: shipkit's own hooksPath, or a foreign one whose commit-msg chains
+// the shipkit gate. It never scans history: what is pushed is accepted as it
+// is, and only a new commit can still be stopped. A declared-public repo also
+// needs the tracked attribution silencer, and its ref NAMES are checked (a
+// FABLE-checkpoint tag outs the agent like a trailer); a branch nobody pushed
+// is named "local only" and warns.
 import { createHash } from 'crypto'
 import { readFileSync } from 'fs'
-import { join } from 'path'
-import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
+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 { declaredVisibility } from '../core/repo-facts.ts'
+import { hookBinInvocation } from '../hooks/run-hooks.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
 // empty — the harness then never writes the trailer or the PR footer
@@ -30,81 +29,100 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
-/** what the answer depends on: the declared visibility, and for a public
- *  repo the commit HEAD names, every ref name and the silencer. So a commit,
- *  a fetch or a new tag asks again, and nothing else does */
+const readOrNull = (abs: string): string | null => {
+    try {
+        return readFileSync(abs, 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** a commit-msg body that runs the shipkit gate on the message: a live line
+ *  (never a comment) whose failure is not swallowed by `|| true` */
+const chainsShipkit = (body: string): boolean =>
+    body.split('\n').some((l) => !l.trim().startsWith('#') && /\bhooks\s+commit-msg\b/.test(l) && !/\|\|\s*(?:true|:)\b/.test(l))
+
+/** the chain 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): string => {
+    const cli = bin.replace(/^bun\s+/, '')
+    return `if [ -f ${cli} ]; then ${bin} hooks commit-msg "$1" || exit 1; else echo "commit-msg: rvlib-shipkit not installed (run bun install), attribution gate skipped" >&2; fi`
+}
+
+// ref NAMES tell too. bare match only for names with no other meaning;
+// vendor and codename words (cursor, openai, gemini, opus, fable, …) name
+// legitimate branches and features, they only match in a checkpoint/session shape
+const REF_TELL = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
+
+const gitOut = (root: string, args: string[]): { code: number; out: string } => {
+    const p = Bun.spawnSync([gitBin(), ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    return { code: p.exitCode, out: p.stdout.toString() }
+}
+
+/** what the answer depends on: the declared visibility, the hooksPath and the
+ *  commit-msg file it points at, and for a public repo every ref NAME and the
+ *  silencer. A commit moves none of them */
 export function historyKey(env: CheckEnv): string {
-    const declared = declaredVisibility(env.config)
     const nested = nestedIn(env.root)
     if (nested != null) return `nested in ${nested}`
-    if (declared !== 'public') return `declared ${declared}`
-    const git = (args: string[]): string => {
-        const p = Bun.spawnSync([gitBin(), ...args], { cwd: env.root, stdout: 'pipe', stderr: 'pipe' })
-        return p.exitCode === 0 ? p.stdout.toString() : `exit ${p.exitCode}`
-    }
-    const refs = git(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/tags', 'refs/heads', 'refs/remotes'])
-    const head = git(['rev-parse', 'HEAD'])
-    const digest = createHash('sha256').update(head).update('\0').update(refs).digest('hex').slice(0, 16)
-    return `public|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
+    const declared = declaredVisibility(env.config)
+    const hooksPath = gitOut(env.root, ['config', 'core.hooksPath'])
+    const dir = hooksPath.code === 0 ? hooksPath.out.trim() : ''
+    const hook = `hooks=${dir}|msg=${dir === '' ? 'none' : fileStamp(isAbsolute(dir) ? join(dir, 'commit-msg') : join(env.root, dir, 'commit-msg'))}`
+    if (declared !== 'public') return `declared ${declared}|${hook}`
+    const refs = gitOut(env.root, ['for-each-ref', '--format=%(refname)', 'refs/tags', 'refs/heads', 'refs/remotes']).out
+    const digest = createHash('sha256').update(refs).digest('hex').slice(0, 16)
+    return `public|${hook}|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
 }
 
 export const commitAiTells = check({
     id: 'SK009',
     blocking: true,
     title: 'commit ai tells',
-    description: 'the history of a public repo carries no AI attribution and no dash punctuation',
+    description: 'the commit-msg hook that refuses AI attribution is armed, and no ref name tells',
     owner: 'identity/how-we-commit.md',
-    // it scans the full `git log` and every ref name, which no tree id
-    // describes, so the refs themselves are the key
+    // git config and ref names, which no tree id describes, so they are the key
     inputs: [CONFIG_FILE],
     cacheKey: historyKey,
     run: async (c) => {
         const nested = nestedIn(c.root)
-        if (nested != null)
-            return void c.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
-        const declared = declaredVisibility(c.config)
-        if (declared !== 'public')
-            return c.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
-        // %x1f separates hash from body, %x1e terminates the record — commit
-        // bodies are free text, so only unprintable separators are safe
-        const log = await c.exec(['git', 'log', '--format=%h%x1f%B%x1e'], { cwd: c.root, timeoutMs: 30_000 })
-        if (log.code !== 0) {
-            const first = log.out.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? `exit ${log.code}`
-            return void c.lines.push({ kind: 'skip', text: `commit history unverifiable — git says: ${first}` })
+        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() : ''
+        const chain = guardedChain(hookBinInvocation(c.root))
+        if (dir === '' && process.env['CI'] != null && process.env['CI'] !== '') {
+            c.lines.push({ kind: 'skip', text: 'commit-msg hook not armed in this CI checkout: a CI run makes no commit, and the fix pass arms hooks on a machine only' })
+        } else if (dir === '') {
+            c.fail('the commit-msg hook is not armed, so nothing refuses an AI attribution trailer: run `shipkit hooks install` (`shipkit ci` arms it too)')
+        } else {
+            const body = isAbsolute(dir) ? readOrNull(join(dir, 'commit-msg')) : c.read(`${dir}/commit-msg`)
+            const own = dir === LAYOUT.hooks
+            if (body == null)
+                c.fail(`core.hooksPath=${dir} has no ${dir}/commit-msg, so nothing refuses an AI attribution trailer: ${own ? 'run `shipkit hooks install`' : `add one that runs \`${chain}\``}`)
+            else if (!chainsShipkit(body))
+                c.fail(`core.hooksPath=${dir}: its commit-msg (${body.split('\n').find((l) => l.trim() !== '' && !l.startsWith('#'))?.trim().slice(0, 80) ?? 'empty'}) does not run the shipkit gate, so nothing refuses AI attribution: add \`${chain}\` above its last line`)
+            else c.ok(`the commit-msg hook refuses AI attribution (${own ? dir : `${dir}, chained to the shipkit gate`})`)
         }
-        const commits = log.out
-            .split('\x1e')
-            .map((r) => r.trim())
-            .filter((r) => r !== '')
-            .map((r) => {
-                const cut = r.indexOf('\x1f')
-                return { hash: r.slice(0, cut), body: r.slice(cut + 1) }
-            })
-        if (commits.length === 0) return void c.lines.push({ kind: 'skip', text: 'commit history unverifiable — no commits yet' })
-        const remedy = 'an unpushed TIP commit may be amended; anything deeper is the owner\'s decision (history is never rewritten as a side effect)'
-        const sample = (hits: { hash: string }[]): string => hits.slice(0, 5).map((h) => h.hash).join(' ') + (hits.length > 5 ? ' …' : '')
-        const attributed = commits.filter((m) => hasAiAttribution(m.body))
-        const dashed = commits.filter((m) => hasDashPunctuation(m.body))
-        // ref NAMES tell too (a FABLE-checkpoint-3 tag outs the agent as
-        // loudly as a trailer). bare match only for names with no other
-        // meaning; vendor and codename words (cursor, openai, gemini, opus,
-        // fable, …) name legitimate branches and features, they only match in
-        // a checkpoint/session shape
-        const refTell = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
-        const refs = await c.exec(['git', 'for-each-ref', '--format=%(refname:short)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: c.root, timeoutMs: 30_000 })
-        if (refs.code !== 0) c.lines.push({ kind: 'skip', text: `ref names unverifiable — git for-each-ref exit ${refs.code}` })
-        const tellRefs = refs.code === 0 ? refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '' && refTell.test(r)) : []
-        if (tellRefs.length > 0)
-            c.fail(`${tellRefs.length} ref name(s) carry an AI tell in a declared-public repo (${tellRefs.slice(0, 5).join(' ')}${tellRefs.length > 5 ? ' …' : ''}) — rename or delete the refs before the flip; a pushed tag also needs the remote delete`)
-        if (attributed.length > 0)
-            c.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / a session trailer or claude.ai url / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
-        if (dashed.length > 0)
-            c.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
-        const silenced = attributionSilenced(c.root)
-        if (!silenced)
-            c.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
-        if (attributed.length === 0 && dashed.length === 0 && tellRefs.length === 0 && silenced)
-            c.ok(`${commits.length} commits + ${refs.code === 0 ? refs.out.split('\n').filter((r) => r.trim() !== '').length : 0} ref names scanned, attribution silenced in .claude/settings.json — no AI tells`)
+
+        if (declaredVisibility(c.config) !== 'public') return
+        if (!attributionSilenced(c.root))
+            c.fail(`.claude/settings.json does not silence AI attribution: track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
+        const refs = await c.exec(['git', 'for-each-ref', '--format=%(refname)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: c.root, timeoutMs: 30_000 })
+        if (refs.code !== 0) return void c.lines.push({ kind: 'skip', text: `ref names unverifiable: git for-each-ref exit ${refs.code}` })
+        const all = refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '')
+        const remote = new Set(all.filter((r) => r.startsWith('refs/remotes/')).map((r) => r.split('/').slice(3).join('/')))
+        const tells = all.filter((r) => REF_TELL.test(r.replace(/^refs\/(?:heads|tags|remotes)\//, '')))
+        const shown = (r: string): string => r.replace(/^refs\/(?:heads|tags|remotes)\//, '')
+        const local = tells.filter((r) => r.startsWith('refs/heads/') && !remote.has(shown(r)))
+        const out = tells.filter((r) => !local.includes(r) && !(r.startsWith('refs/heads/') && remote.has(shown(r))))
+        const list = (rs: string[], suffix = ''): string => rs.slice(0, 5).map((r) => `${shown(r)}${suffix}`).join(' ') + (rs.length > 5 ? ' …' : '')
+        if (out.length > 0)
+            c.fail(`${out.length} ref name(s) carry an AI tell in a declared-public repo (${list(out)}): rename or delete them, a pushed one on the remote too, then \`git fetch --prune\` so a remote ref deleted there leaves this clone`)
+        if (local.length > 0)
+            c.warn(`${local.length} branch name(s) carry an AI tell (${list(local, ' (local only)')}): never push them under this name, rename or delete them`)
     },
 })
 

package/src/checks/SK014-prose-ste.check.ts

@@ -7,16 +7,17 @@
 //
 // The tier split is the whole design. `fix` and `hard` hits BLOCK: they are
 // mechanical, and a machine reporting them is never guessing. `soft` hits
-// (sentence length, passive voice) need a human read, so they WARN, and only
-// a declared `baseline` makes them blocking, as a ratchet that can only go
-// down.
+// (sentence length, passive voice, modals, semicolons, …) need a human read,
+// so they are a note, never an attention item, and only a declared
+// `baseline` makes them blocking, as a ratchet that can only go down.
 //
 // It carries NO `fix()` on purpose. `shipkit ci` runs `--fix-rules` by
 // default, so a rule with a fixer rewrites tracked files unattended, and
 // prose is not repo shape: a wrong package.json line is a config, a wrong
 // sentence is content. The rewrite lives behind an explicit `shipkit prose
 // --fix` that a human ran and can read the diff of.
-import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
+import { classSummary, proseLines, runProseCheck, type ProseReport } from '../prose/run-prose.ts'
+import { tierOf, type ProseClass } from '../prose/ste.ts'
 import { check } from '../check.ts'
 
 const OWNER = 'identity/writing-voice.md'
@@ -53,12 +54,21 @@ export const proseSte = check({
                 `${blocking} STE violation(s) across ${r.byFile.length}/${r.files} file(s) — ${classSummary(r)}`,
                 r.fixable > 0 ? `shipkit prose --fix rewrites ${r.fixable} of them` : undefined,
             )
+        const soft = softSummary(r)
         if (cfg.baseline != null && r.byTier.soft > cfg.baseline)
-            c.fail(`${r.byTier.soft} soft hits (sentence length, passive voice), above the declared baseline of ${cfg.baseline} — the ratchet only goes down`)
+            c.fail(`${r.byTier.soft} soft hits (${soft}), above the declared baseline of ${cfg.baseline}: the ratchet only goes down`)
         else if (r.byTier.soft > 0)
-            c.warn(`${r.byTier.soft} soft hit(s): sentence length and passive voice need a human read${cfg.baseline != null ? ` (baseline ${cfg.baseline})` : ''}`)
+            c.note(`${r.byTier.soft} soft hit(s) need a human read (${soft})${cfg.baseline != null ? `, within the baseline of ${cfg.baseline}` : ''}: \`shipkit prose\` lists them`)
         if (!c.failed && blocking === 0) c.ok(`${r.files} file(s) STE-clean on the mechanical rules`)
     }
 })
 
+/** every soft class with its count, most first */
+const softSummary = (r: ProseReport): string =>
+    Object.entries(r.byClass)
+        .filter(([cls]) => tierOf(cls as ProseClass) === 'soft')
+        .sort((a, b) => b[1] - a[1])
+        .map(([cls, n]) => `${cls} ${n}`)
+        .join(', ')
+
 export default proseSte

package/src/checks/SK016-legacy-check-shapes.check.ts

@@ -1,8 +1,9 @@
 // SK016 — the shapes the check file replaced, and the machine that
 // rewrites them (build/shipkit/writing-a-check.md owns the shape itself).
 //
-// The window: every shape below is READ through 0.40, named once per run, and
-// refused at the first release after `shipkit fleet` shows no repo below 0.40.
+// The window: every shape below is still READ, named once per run, and
+// refused at the first release after `shipkit fleet` shows no repo below 0.40
+// and none still carrying a check script.
 // So a repo on an old declaration keeps working, learns what to write instead
 // on every gate, and is carried across by one command, save what only a
 // reader can port: a check script's body, a rule, a task whose body is code.
@@ -60,7 +61,7 @@ export const legacyCheckShapes = check({
         if (s.placeholders.length > 0)
             c.warn(
                 `${s.placeholders.length} check file(s) still open with the TODO description the migration wrote: ${s.placeholders.join(', ')}`,
-                'replace each TODO with one line stating what must be true',
+                'by hand: replace each TODO with one line stating what must be true',
             )
         if (s.count === 0) return
         // one WARN per shape, never a bare line: the gate promises every line
@@ -78,9 +79,14 @@ export const legacyCheckShapes = check({
         }
         if (s.rules.length > 0) c.warn(`${s.rules.length} \`rules: []\` entr(ies): ${s.rules.join(', ')} — each one is a *.check.ts file whose \`run\` is its \`lint\``)
         if (s.ruleExempt.length > 0) c.warn(`ruleExempt names ${s.ruleExempt.join(', ')} — the spelling is \`when: { id: 'off:<why>' }\``)
+        // what the fixer rewrites without guessing: the exemptions, the tasks
+        // once all of them are data, checkDefaults once no script leans on it
+        const mechanical = s.ruleExempt.length + (s.tasks.every((x) => x.data) ? s.tasks.length : 0) + (s.checkDefaults && s.checkFiles.length === 0 ? 1 : 0)
         c.warn(
-            `${s.count} declaration(s) in a shape the check file replaced — read through 0.40, refused after`,
-            'shipkit check --fix SK016 rewrites what is mechanical and names the rest',
+            `${s.count} declaration(s) in a shape the check file replaced: still read, and refused by the first shipkit release after \`shipkit fleet\` shows no repo below 0.40 and none still carrying a check script`,
+            mechanical > 0
+                ? `shipkit check --fix SK016 rewrites ${mechanical} of them and names the rest`
+                : `nothing left is mechanical, so the port is by hand: each line above becomes a *.check.ts file (${OWNER})`,
         )
     },
     fix: async (c) => await fixLegacyShapes(c),