rvlib-shipkit 1.2.0 → 1.4.0

package/src/checks/SK005-rvlib-versions.check.ts

@@ -48,6 +48,7 @@ import { basename, join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { allowMajor, breakingAdvice, isBreaking } from '../core/update-policy.ts'
 import { isRunningCopy, rememberLatest } from '../core/self-update.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { mutateLease, withMutateLease } from '../core/locked-write.ts'
 import { detectPackageManager, isRefusal, LOCK_FILES } from '../core/package-manager.ts'
 import { check, type CheckEnv } from '../check.ts'
@@ -77,6 +78,11 @@ export const rvlibVersions = check({
     ttl: '24h',
     // it updates the rvlib deps unless the run is frozen
     writes: true,
+    planOff: (env) => {
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'no readable package.json' }
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).some((n) => n.startsWith('rvlib-')) ? null : 'no rvlib-* dependency'
+    },
     cacheKey: (env) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
@@ -84,7 +90,7 @@ export const rvlibVersions = check({
             .filter((n) => n.startsWith('rvlib-'))
             .sort()
             .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
-            .join(',')
+            .join(',') + (rootPublishesNpm(env.config) ? ' npm' : '')
     },
     run: async (c) => {
         let pkg: Pkg
@@ -137,6 +143,12 @@ export const rvlibVersions = check({
             c.warn(`newer rvlib live: ${drift} (frozen — apply with: ${cmd.join(' ')})`)
             return
         }
+        // a package published to npm: its package.json is its public
+        // contract, so the bump is a release decision, named and never made
+        if (rootPublishesNpm(c.config)) {
+            c.warn(`newer rvlib live: ${drift} (published to npm, never updated by a check — apply with: ${cmd.join(' ')})`)
+            return
+        }
         const dirty = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
         if (dirty.code !== 0 || dirty.out.trim() !== '') {
             c.warn(`newer rvlib live: ${drift} — self-update deferred (${dirty.code !== 0 ? `git says: ${dirty.out.trim().split('\n')[0] ?? `exit ${dirty.code}`}` : 'package.json/lockfile dirty'}); commit first, then re-run check`)

package/src/checks/SK006-npm-publish-safety.check.ts

@@ -15,6 +15,7 @@
 import { join, relative } from 'path'
 import { checkUnitReader, resolveUnits } from '../release/unit-resolve.ts'
 import { check } from '../check.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 
 type Pkg = {
     name?: string
@@ -65,6 +66,10 @@ export const npmPublishSafety = check({
             if (localHits.length === 0) c.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
             return
         }
+        if (rootPublishesNpm(c.config)) {
+            if (localHits.length === 0) c.ok('the root unit declares release.npm: publishes by design, no local dependency protocol in any releasing unit')
+            return
+        }
         if (pkg.private !== true) return c.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')

package/src/checks/SK007-github-visibility.check.ts

@@ -8,8 +8,9 @@
 // own base-repo resolution prefers `upstream`, which in a fork-shaped
 // checkout would confidently validate the WRONG repository. Flipping a
 // repo public stays a human act behind the pre-public audit; this rule is
-// the standing tripwire if it ever happens out of band. Clean passes cache
-// 7d, keyed on the declared value (a flip re-probes immediately); every
+// the standing tripwire if it ever happens out of band. A decided fact: a
+// clean pass is kept forever, keyed on the declared value (a flip re-probes
+// immediately, and the plan asks only while no answer exists); every
 // unverifiable path (no git, no remote, non-github remote, gh missing or
 // erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
 // never cached.
@@ -17,20 +18,19 @@ import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
 import { probeGitRoot } from '../core/git-root.ts'
 import { nestedIn } from '../core/nesting.ts'
 import { check } from '../check.ts'
+import { declaredVisibility } from '../core/repo-facts.ts'
 
 export const githubVisibility = check({
     id: 'SK007',
-    // blocking despite being measured over the network: the fact is about THIS
-    // REPO (it is public while it declares itself private), and every
-    // unverifiable path above is a skip, so an offline machine never goes red
-    blocking: true,
+    // a gate block does not un-leak a repo: the red shows on the needs surface
+    blocking: false,
     title: 'github visibility',
     description: 'the github visibility of this repo matches the one it declares',
     owner: 'meta/contracts.md',
-    ttl: '7d',
-    cacheKey: (env) => env.config.visibility ?? 'private',
+    ttl: 'forever',
+    cacheKey: (env) => declaredVisibility(env.config),
     run: async (c) => {
-        const declared = c.config.visibility ?? 'private'
+        const declared = declaredVisibility(c.config)
         const skip = (why: string): void => void c.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
         const firstLine = firstGhLine
         const repo = probeGitRoot(c.root)

package/src/checks/SK008-reviewer-agent.check.ts

@@ -8,12 +8,13 @@
 // harness then inherits every tool. The brief itself must exist. No
 // declaration = not a reviewer repo, and the rule passes silently.
 import { existsSync, mkdirSync, readFileSync } from 'fs'
-import { homedir } from 'os'
-import { dirname, isAbsolute, join } from 'path'
+import { dirname, join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type FixResult, type CheckEnv } from '../check.ts'
 import { LAYOUT } from '../core/layout.ts'
 import { atomicWrite } from '../core/locked-write.ts'
+import { configPath, fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
 
 /** where a review lands when its caller named no output file:
  *  `YYYYMMDD-HHMMSS-<review-name>.md`, local time, gitignored */
@@ -48,8 +49,7 @@ export function reviewerAgentIssues(text: string, reviewer: NonNullable<RepoConf
 /** the brief must EXIST: a reviewer whose mandated first action is reading a
  *  missing file flounders silently, which is the one thing this rule prevents */
 export function briefMissing(root: string, brief: string): boolean {
-    const p = brief.startsWith('~/') ? join(homedir(), brief.slice(2)) : isAbsolute(brief) ? brief : join(root, brief)
-    return !existsSync(p)
+    return !existsSync(configPath(root, brief))
 }
 
 function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
@@ -83,12 +83,18 @@ That brief overrides any habit of reviewing a diff for correctness alone.
 export const reviewerAgent = check({
     id: 'SK008',
     blocking: true,
-    title: 'reviewer agent',
+    title: 'reviewer definition',
     description: 'the declared reviewer agent has its brief, its definition and read only tools',
     owner: 'identity/how-we-work.md',
-    // the brief is a CONFIG path, and a `~/...` or absolute one puts it
-    // outside the repo, where no tree id can see whether it still exists
-    never: 'the reviewer brief may live outside the repo, where no tree id reaches it',
+    // the answer is the config, the definition file and the brief. The brief
+    // is a CONFIG path that may sit outside the repo, so both files enter the
+    // key by content, wherever they live
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => {
+        const r = env.config.reviewer
+        if (r == null) return 'no reviewer'
+        return `${r.name}|${(r.tools ?? REVIEWER_TOOLS).join(',')}|def=${fileStamp(join(env.root, reviewerAgentPath(r.name)))}|${r.brief}=${fileStamp(configPath(env.root, r.brief))}`
+    },
     run: (c) => {
         const r = c.config.reviewer
         if (r == null) return c.ok('no reviewer agent declared (repo.config reviewer:) — skipped')

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

@@ -1,18 +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 { check } from '../check.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
@@ -25,62 +29,100 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
+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 nested = nestedIn(env.root)
+    if (nested != null) return `nested in ${nested}`
+    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. History and refs are not
-    // work-tree content, so nothing a scan can produce describes this answer
-    never: 'reads the full commit history and every ref name, neither of which is work-tree content',
+    // 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 = c.config.visibility ?? 'private'
-        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/SK013-one-way-in-policy.check.ts

@@ -15,6 +15,7 @@
 import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type CheckCtx, type FixResult } from '../check.ts'
 
@@ -95,8 +96,8 @@ async function guardScriptMissing(d: Disk, command: string): Promise<string | nu
     return null // a form this rule cannot resolve is not a form it may condemn
 }
 
-/** the guard the fixer writes: the cli path the scripts run when a guard sits
- *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
+/** the guard the fixer writes: the shipkit cli path the scripts run when a
+ *  guard sits beside it, else the
  *  repo's own dependency, else the copy of shipkit doing the fixing, which is
  *  the one the launcher falls back to in a repo that has none */
 export async function guardCommandFor(d: Disk): Promise<string> {
@@ -109,6 +110,11 @@ export async function guardCommandFor(d: Disk): Promise<string> {
     return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
+/** a package published to npm is worked on by strangers: this file binds
+ *  their agents, and a deny list with a hook would tie them to a toolkit they
+ *  never installed */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${SETTINGS_PATH} belongs to every contributor, so it is never written`
+
 export const oneWayInPolicy = check({
     id: 'SK013',
     blocking: true,
@@ -119,6 +125,7 @@ export const oneWayInPolicy = check({
     // the declared guard script resolves. A guard at an absolute path lives
     // outside the repo, so an answer that probed one is never stored
     run: async (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return c.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
@@ -165,6 +172,7 @@ export const oneWayInPolicy = check({
     // a repo's own allow list and its own hooks, and clobbering those to fix a
     // deny list would cost more than the finding it repairs
     fix: async (c): Promise<FixResult> => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }

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/SK015-nested-repo.check.ts

@@ -3,6 +3,7 @@
 // sites that write history refuse on the disk fact either way (core/nesting.ts),
 // so this rule is about the declaration telling the truth to the next reader.
 import { nestedIn } from '../core/nesting.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
 import { check } from '../check.ts'
 
 export const nestedRepo = check({
@@ -11,7 +12,10 @@ export const nestedRepo = check({
     title: 'nested repo',
     description: 'a config inside a larger work tree declares `nested: true`, and only there',
     owner: 'build/shipkit/config-keys.md',
-    never: 'reads where the git work tree root sits, which no content inside the repo describes',
+    // the declaration, and where the git work tree root sits, which no tree
+    // id describes, so its path is the rest of the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `nested=${env.config.nested === true}|top=${nestedIn(env.root) ?? 'root'}`,
     run: (c) => {
         const top = nestedIn(c.root)
         const declared = c.config.nested === true

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),

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

@@ -11,6 +11,7 @@ import { basename } from 'path'
 import { check } from '../check.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { whenOfTask } from '../core/when.ts'
 import { hubProblemMatcher } from '../problems/problem-line.ts'
 import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
@@ -165,6 +166,10 @@ function ownTasks(c: CheckCtx): { text: string } | 'none' | 'linked' {
     return text == null ? 'none' : { text }
 }
 
+/** a package published to npm is worked on by strangers, whose editor
+ *  runs these tasks */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${TASKS} belongs to every contributor, so it is never rewritten`
+
 export const vscodeHubTask = check({
     id: 'SK017',
     // a stale editor file is behind, not broken: it warns, and the fix pass
@@ -174,6 +179,7 @@ export const vscodeHubTask = check({
     description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
     owner: 'build/vscode-tasks.md',
     run: (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const own = ownTasks(c)
         if (own === 'none') return c.ok(`no ${TASKS}, so there is no hub task to wire`)
         if (own === 'linked') return c.ok(`.vscode/ is a link to a shared dir, left alone`)
@@ -185,6 +191,7 @@ export const vscodeHubTask = check({
         for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
     },
     fix: (c) => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const own = ownTasks(c)
         if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }
         const r = repairTasks(own.text, { typecheckOn: typecheckOn(c) })

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -3,7 +3,9 @@
 // rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
 // newer than the one this process runs: a rule or an api that pin relies on
 // is absent here until the house copy catches up.
+import { join } from 'path'
 import { LIB_VERSION } from '../core/lib-version.ts'
+import { fileStamp } from '../core/file-stamp.ts'
 import { check } from '../check.ts'
 
 type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -23,8 +25,10 @@ export const machineRunsThePin = check({
     title: 'machine runs the pin',
     description: 'the shipkit this machine runs is at least the version this repo pins',
     owner: 'build/shipkit.md',
-    // the running version is no file of the repo
-    cacheKey: () => LIB_VERSION,
+    // the pin, the install (gitignored) and the version this machine runs,
+    // which is no file of the repo
+    inputs: ['package.json'],
+    cacheKey: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}`,
     run: (c) => {
         const pkg = c.json<Pkg>('package.json')
         const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]

package/src/checks/SK024-identity-colors.check.ts

@@ -3,7 +3,9 @@
 // surface that shows the repo (the home page header, its rail tile) draws it
 // in its own colour. The fix derives them from the repo icon, or from a hue
 // hashed from the name, and writes that one key, every other byte kept.
+import { join } from 'path'
 import { check } from '../check.ts'
+import { fileStamp } from '../core/file-stamp.ts'
 import { configName, CONFIG_FILE, deriveIdentity, identityRefusal, INSTALLED_CONFIG_SRC } from '../core/identity.ts'
 import { declaresIdentity, identityOfText, identityProblem, setIdentityText } from '../core/identity-color.ts'
 
@@ -16,6 +18,9 @@ export const identityColors = check({
     title: 'identity colors',
     description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
     owner: 'build/shipkit/built-in-checks.md',
+    // the config, and the installed lib that says whether it knows the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}`,
     run: (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return c.note(`no ${CONFIG_FILE}`)