rvlib-shipkit 1.3.0 → 1.5.0

package/src/check.ts

@@ -14,14 +14,14 @@
 //   `cmd`  argv, a subprocess, exit code is truth
 //
 // What a check declares about ITSELF is what every surface reads: `blocking`
-// (can it stop you), how it is remembered (`ttl` or `never`, else a `run`
-// check is keyed on what it read and a `cmd` check on its `inputs`), `when`
-// (where it runs), `deps` (what must pass first). The file's own path joins
-// its cache key automatically, so nothing declares its own code.
+// (can it stop you), `runs` (every context it runs in), `cache` (how its
+// answer is kept), `fix` (which command applies its repair), `applies` (does
+// this repo give it work), `deps` (what must pass first). Every one of them is
+// explicit, with no default (core/runs.ts). The file's own path joins its
+// cache key automatically, so nothing declares its own code.
 import type { CheckCtx } from './core/check-ctx.ts'
-import { parseWhen } from './core/when.ts'
-import { planDeclProblem, type Every, type WhenInactiveDecl } from './plan/cadence.ts'
-import { FOREVER, parseDuration, type Line } from './core/wire.ts'
+import { cacheProblem, combinationProblem, runsProblem, type Applies, type CacheDecl, type FixWhen, type Runs } from './core/runs.ts'
+import { type Line } from './core/wire.ts'
 import type { RepoConfig } from './repo-config.ts'
 
 export { defineScan, mdPages, packageJson, type MdPage, type PackageJson, type Scan } from './scan.ts'
@@ -77,7 +77,7 @@ export type CheckDef = {
      *  gate asks "is my change good" and builds, `shipkit check` asks "is
      *  this repo healthy" and reports, and a tool chain has no business in
      *  the second question. A floor slot derives it, a file declares it, and
-     *  it takes the 600s ceiling rather than the 120s one. `when` stays about
+     *  it takes the 600s ceiling rather than the 120s one. its `runs` say
      *  TIME (always, release, health, off). A build step on `health` is an
      *  opt in one: the gate parks it and `shipkit ci --with <id>` runs it. */
     build?: boolean
@@ -85,74 +85,34 @@ export type CheckDef = {
      *  so a check naming none is a root of it, and a dep doubles as the race
      *  guard between two checks that touch one file. */
     deps?: string[]
-    /** WHERE it runs: `always`, `release`, `health`, `off:<reason>`. The
-     *  repo's `when: {}` map wins over it, so a config can move a check the
-     *  repo does not own (core/when.ts owns the vocabulary). */
-    when?: string
-    /** CONTENT population: the repo-relative paths this check reads, so a
-     *  cached answer is honest while they do not move. For a `cmd` check,
-     *  whose subprocess reads what it likes. A `run` check that declares none
-     *  of `inputs`, `ttl` and `never` is keyed on what it READ through `c`
-     *  instead, the `reads` population (ledger/git-key.ts). A `cmd` check
-     *  that declares none runs every time, which costs speed and never
-     *  correctness. At most one of the three. */
-    inputs?: string[]
-    /** WORLD population: nothing on disk describes the answer, so a clean
-     *  pass keeps for this long, as in '24h'. `'forever'` for a DECIDED fact
-     *  (a repo's visibility, an account that exists): a clean answer never
-     *  expires, it is keyed on the declared value alone (`cacheKey`), and the
-     *  plan runs it only while no answer exists for that key. */
-    ttl?: string
-    /** a DECIDED never-cacheable, with the reason. Says somebody looked and
-     *  no key can describe this, which takes it off the burn-down list. */
-    never?: string
+    /** WHERE IT RUNS, every context explicit, no default (core/runs.ts owns
+     *  the meaning of each key and each value). A repo moves a check it does
+     *  not own OFF with `off` in repo.config.ts, never elsewhere. */
+    runs: Runs
+    /** HOW ITS ANSWER IS KEPT, one variant, every parameter explicit:
+     *  `files` (keyed on these paths), `reads` (keyed on what the body read),
+     *  `ttl` (a world answer that keeps a span), `fact` (a decided value, once
+     *  per key), `never` (with the reason). The file's own path joins every
+     *  key automatically, so nothing declares its own code. */
+    cache: CacheDecl
+    /** which command applies `repair`: `'none'` (no repair), `'ci'` (the
+     *  gate's fix pass and `shipkit check --fix`), `'manual'` (only
+     *  `shipkit check --fix <id>`) */
+    fix: FixWhen
+    /** whether this repo gives the check anything to do: `'always'`, or a
+     *  pure function of { root, config } returning the reason it does not
+     *  (the row is then n/a in every context), or null */
+    applies: Applies
     /** it REWRITES the repo while it runs (updates a dependency, untracks a
      *  file) unless the run is frozen, so a frozen run asks it a different
      *  question: only a check declaring this carries `frozen` in its cache
-     *  key, and every other check shares one answer between a frozen run and
-     *  a normal one. Declared, never guessed from the body. */
+     *  key. Declared, never guessed from the body. */
     writes?: boolean
-    /** WHEN the planner runs it on its own, beside the save that moved what
-     *  it reads: a span since its last run (`'24h'`), a range (`['10h',
-     *  '12h']`, each repo and check on a stable point inside it, so checks
-     *  spread out), a cron expression (`'0 9 * * 1'`), `'once'` (only while
-     *  no answer exists: what `ttl: 'forever'` reads as), or null for on
-     *  change only. Or a PURE function of its last result (`status`, `at`, `streak`
-     *  of that same status) and whether the repo is active, returning any of
-     *  those: `(last) => (last?.status === 'fail' ? '1h' : '7d')`. A lambda
-     *  that throws is an error row on the planned page, and the check runs on
-     *  change only. Absent: its `ttl`, else a build step or a check keyed on
-     *  its files waits for a save. A repo check nothing can key runs about
-     *  once a day until it declares one, and a built-in never may: `shipkit
-     *  keys --burn-down` names both. */
-    every?: Every
-    /** a time of day or week for the rare check that needs one, as five cron
-     *  fields in local time (`'0 9 * * 1'`, Mondays at 9). Never with `every`. */
-    cron?: string
-    /** what a due check does while its repo is inactive (no agent session in
-     *  it, VS Code does not have it open, it is not flagged active): `'wait'`
-     *  turns it late and runs it once the repo is active again, `'run'` runs
-     *  it on time anyway (a credential probe, an api key that must keep
-     *  working). A pure function of the last result may choose. Default
-     *  `'wait'`. */
-    whenInactive?: WhenInactiveDecl
-    /** why this repo gives the check nothing to do on a clock, or null: the
-     *  plan leaves it out there (no row, no timer), and a gate or a health
-     *  pass still runs it. Read at every reload of the repo's checks, so a
-     *  file that gives it work (an ask with a probe, a release unit) plans it
-     *  again. Cheap and pure over the repo's files and config */
-    planOff?: (env: CheckEnv) => string | null
-    /** cache-identity contribution for a `ttl` check whose verdict depends on
-     *  config: a changed key busts the answer instantly instead of serving
-     *  a stale cached assertion for the rest of the TTL. */
-    cacheKey?: (env: CheckEnv) => string
-    /** idempotent auto-repair, never interactive. `shipkit check --fix <id>`
-     *  applies it, then re-runs the check. It gets the same `c` as the body,
-     *  writes with `c.write` and `c.remove`, and is never cached. An `fs`
-     *  import in the check file would keep an undeclared body off its reads
-     *  (core/raw-access.ts). A repair that needs
-     *  judgement stays a FAIL with a pointer. */
-    fix?: (c: CheckCtx) => FixResult | Promise<FixResult>
+    /** idempotent auto-repair, never interactive, required when `fix` is not
+     *  `'none'`. It gets the same `c` as the body, writes with `c.write` and
+     *  `c.remove`, and is never cached. A repair that needs judgement stays a
+     *  FAIL with a pointer. */
+    repair?: (c: CheckCtx) => FixResult | Promise<FixResult>
     /** wall clock ceiling in ms. A `cmd` check is killed with its whole
      *  process tree at the ceiling. */
     timeoutMs?: number
@@ -160,7 +120,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 (cache `ttl`, `fact` 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. */
@@ -197,6 +158,19 @@ export function describeFirst(...candidates: (string | null | undefined)[]): str
     throw new Error(`no description candidate passes the shape: ${candidates.map((d) => JSON.stringify(d)).join(', ')}`)
 }
 
+/** the keys the explicit declaration replaced, and what replaces each */
+const RETIRED_KEYS: Record<string, string> = {
+    when: 'runs (every context explicit)',
+    every: 'runs.onClock { every, inactive }',
+    cron: 'runs.onClock { every: <cron>, inactive }',
+    whenInactive: 'runs.onClock.inactive',
+    planOff: 'applies',
+    inputs: "cache { by: 'files', inputs, key }",
+    ttl: "cache { by: 'ttl', span, key } or { by: 'fact', key }",
+    never: "cache { by: 'never', why }",
+    cacheKey: 'cache.key',
+}
+
 /** THE way a check file declares itself. It validates the shape at import
  *  time, so a malformed check dies when discovery loads it and never mid
  *  gate. The id, the title and the owner are filled in by discovery, which
@@ -207,20 +181,21 @@ export function check(d: CheckDef): CheckDef {
     const bad = descriptionProblem(d.description)
     if (bad != null) throw new Error(`check${name}: ${bad}`)
     if (typeof d.blocking !== 'boolean')
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: blocking is required — true (about this repo, it stops you) or false (about the world, it warns)`)
+        throw new Error(`check${name}: blocking is required — true (about this repo, it stops you) or false (about the world, it warns)`)
     if (has('run') === has('cmd'))
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: declare exactly one body, \`run\` (in process) or \`cmd\` (argv)`)
-    const populations = (['inputs', 'ttl', 'never'] as const).filter((k) => has(k))
-    if (populations.length > 1)
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: ${populations.join(' and ')} contradict each other — a check reads files, or the world, or nothing can describe it`)
-    if (d.ttl != null && d.ttl !== FOREVER)
-        try { parseDuration(d.ttl) } catch { throw new Error(`check${name}: ttl '${d.ttl}' is neither a span ('7d') nor 'forever'`) }
-    const planBad = planDeclProblem({ every: d.every, cron: d.cron, whenInactive: d.whenInactive })
-    if (planBad != null) throw new Error(`check${name}: ${planBad}`)
-    if (d.when != null) {
-        const w = parseWhen(d.when)
-        if (typeof w === 'string') throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: when ${w}`)
-    }
+        throw new Error(`check${name}: declare exactly one body, \`run\` (in process) or \`cmd\` (argv)`)
+    const raw = d as unknown as Record<string, unknown>
+    const retired = Object.keys(RETIRED_KEYS).filter((k) => raw[k] !== undefined)
+    if (retired.length > 0) throw new Error(`check${name}: ${retired.map((k) => `\`${k}\` is retired, declare ${RETIRED_KEYS[k]}`).join('; ')} (build/shipkit/runs.md)`)
+    if (typeof raw.fix === 'function') throw new Error(`check${name}: \`fix\` is now the word 'none' | 'ci' | 'manual', and the function is \`repair\` (build/shipkit/runs.md)`)
+    const runs = runsProblem(d.runs)
+    if (runs != null) throw new Error(`check${name}: ${runs}`)
+    const cache = cacheProblem(d.cache)
+    if (cache != null) throw new Error(`check${name}: ${cache}`)
+    if (d.applies !== 'always' && typeof d.applies !== 'function')
+        throw new Error(`check${name}: applies is required: 'always', or a function of { root, config } returning why this repo gives it nothing to do, or null`)
+    const whole = combinationProblem({ runs: d.runs, cache: d.cache, fix: d.fix, repair: d.repair, build: d.build === true, body: has('run') ? 'run' : 'cmd', blocking: d.blocking })
+    if (whole != null) throw new Error(`check${name}: ${whole}`)
     return d
 }
 
@@ -232,7 +207,7 @@ export function check(d: CheckDef): CheckDef {
 
 export type TaskDef = {
     /** the name every surface uses: the gate line, `--only`, `--skip`, a
-     *  `deps` entry, a `when` key and the ledger row. Unique in the repo. */
+     *  `deps` entry, an `off` key and the ledger row. Unique in the repo. */
     id: string
     /** one line stating what must be true (the shape: descriptionProblem).
      *  A floor slot and a unit test check get theirs from the
@@ -254,7 +229,7 @@ export type TaskDef = {
     /** a label several tasks share, so `--skip <group>` parks all of them at
      *  once (a local bench, a slow integration tier). */
     group?: string
-    /** DEPRECATED, read into `when` as `health`: out of the gate until
+    /** DEPRECATED, read as every gate axis false: out of the gate until
      *  `--with <id>` names it. */
     optIn?: boolean
     /** wall clock ceiling in ms, default 600000 for a build step. One that
@@ -332,13 +307,12 @@ export type Rule = {
 
 // ── running a body, and what every line it prints carries ────────────────
 
-/** the config part of a check's cache identity. Where it RUNS is part of it:
- *  moving one off the gate, or editing the reason it is off, has to ask the
- *  question again rather than serve the cached answer from before the move. */
-export function checkCacheExtra(u: { id: string; cacheKey?: (env: CheckEnv) => string }, env: CheckEnv, at: { at: string; reason: string | null; source: string }): string | undefined {
-    const key = u.cacheKey?.(env)
-    if (at.source === 'default') return key
-    return at.at === 'off' ? `${key ?? ''}|exempt:${at.reason ?? ''}` : `${key ?? ''}|when:${at.at}`
+/** the config part of a check's cache identity: its declared key, and the
+ *  reason it is off. Turning a check off, or editing why, asks the question
+ *  again rather than serving the answer from before. Where it runs is not
+ *  part of it: the answer to one question does not depend on who asks. */
+export function checkCacheExtra(key: string | undefined, off: string | null): string | undefined {
+    return off == null ? key : `${key ?? ''}|exempt:${off}`
 }
 
 /** THE one way to run an in-process body (the check suite and the `--fix`
@@ -373,12 +347,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

@@ -5,7 +5,7 @@
 // what it read: package.json, the probes below, the test file listing, and
 // whatever the floor resolution read.
 //
-// It also enforces the package.json half of ONE WAY IN (build/shipkit.md):
+// It also enforces the package.json half of ONE WAY IN (build/shipkit/one-way-in.md):
 // `test`, `lint` and `typecheck` ROUTE to `shipkit ci --only <id>` and the
 // tool body they used to hold sits at `<id>:raw`. That is what makes a cache
 // worth having: `bun run test` is the reflex, and the reflex has to land in
@@ -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,18 +176,37 @@ 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,
     title: 'package.json',
     description: 'package.json routes lint, typecheck and test through the gate',
     owner: OWNER,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => evaluatePackageJson(c),
     // mechanical repairs only: field flips + scripts whose canonical body the
     // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
     // named in the summary, never invented. rvlib-* roots untouched — their
     // license/private are publish decisions.
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const raw = c.read('package.json')
         if (raw == null) return { changed: false, summary: 'no package.json — nothing to fix' }
         if (rootPublishesNpm(c.config)) return { changed: false, summary: 'published to npm: its package.json is its public contract, never rewritten' }

package/src/checks/SK002-contracts-fulfillness.check.ts

@@ -16,6 +16,10 @@ export const contractsFulfillness = check({
     owner: 'meta/contracts.md',
     // keyed on what the contracts read: each artifact, each detector, and each
     // folder a glob walked through `c.entries`, a gitignored one included
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
     },

package/src/checks/SK003-claude-md-shape.check.ts

@@ -20,6 +20,10 @@ export const claudeMdShape = check({
     owner: 'meta/agent-folder.md',
     // keyed on what it reads: CLAUDE.md and whether agent/index.md exists. The
     // gitignore probe runs git, so an answer that took it is never stored
+    runs: { onPreCommit: { budgetMs: 40 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         const hasAgent = c.exists('agent/index.md')
         const claude = c.read('CLAUDE.md')
@@ -53,7 +57,7 @@ export const claudeMdShape = check({
     // CLAUDE.md would lint green with the base include forever missing,
     // trading a loud FAIL for a permanent silent gap. Creation and prose
     // relocation stay human/machine-local (`shipkit start --include`).
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         if (!c.exists('agent/index.md')) return { changed: false, summary: 'no agent/index.md — nothing mechanical to fix' }
         const cur = c.read('CLAUDE.md')
         if (cur == null) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start <name> writes it), not autofixable' }

package/src/checks/SK004-gitignore-policy.check.ts

@@ -205,11 +205,14 @@ export const gitignorePolicy = check({
     title: '.gitignore',
     description: 'the managed .gitignore block keeps private contract folders out of git',
     owner: 'meta/contracts.md',
-    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
-    // carries and no read set records (the header says why)
-    inputs: ['.'],
     // it untracks generated files (a commit) unless the run is frozen
     writes: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
+    // carries and no read set records (the header says why)
+    cache: { by: 'files', inputs: ['.'], key: null },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         // a generated path still in the index is the half-applied state the
         // managed block cannot fix on its own
@@ -278,7 +281,7 @@ export const gitignorePolicy = check({
         }
         c.ok(`.gitignore policy block current, ${claimed.length + backProbes.size} patterns verified against git`)
     },
-    fix: async (c): Promise<FixResult> => {
+    repair: async (c): Promise<FixResult> => {
         // the move first: it writes the new block itself, before any folder moves
         const moved = process.env.SHIPKIT_FROZEN === '1' ? null : migrateLayout(c.root, { config: c.config, renderGitignore: (t, legacy, cfg) => renderPolicy(t, cfg ?? c.config, legacy) })
         const layout = moved == null ? null

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

@@ -10,7 +10,12 @@
 // Per rvlib-* dep:
 //   link:   → the symlink must resolve (a broken link dies cryptically at
 //             import time otherwise) — nothing to update, code is live
-//   semver  → installed vs npm latest; a BREAKING jump (a new major, or a
+//   semver  → installed vs npm latest. A semver pin whose node_modules
+//             entry is a `bun link` symlink is judged by the PIN's floor
+//             instead: the link carries the source, always the newest, while
+//             a fresh clone installs the pin. Behind, the pin moves through
+//             the same guarded update, and `bun link <name>` restores the
+//             link after it (a link that does not come back FAILs). A BREAKING jump (a new major, or a
 //             new 0.x minor) is never taken by itself
 //             (src/core/update-policy.ts: WARN naming `fleet --update --major`,
 //             package.json untouched); the rvlib-shipkit tree running this
@@ -46,7 +51,7 @@
 import { existsSync, readFileSync } from 'fs'
 import { basename, join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
-import { allowMajor, breakingAdvice, isBreaking } from '../core/update-policy.ts'
+import { allowMajor, breakingAdvice, isBreaking, isLinkedInstall, pinFloor } 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'
@@ -61,6 +66,13 @@ const installedVersion = (root: string, name: string): string | null => {
     try { return (JSON.parse(readFileSync(p, 'utf8')) as Pkg).version ?? null } catch { return null }
 }
 
+const readPin = (root: string, name: string): string | null => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as Pkg
+        return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? null
+    } catch { return null }
+}
+
 async function latestVersion(t: CheckCtx, name: string): Promise<string> {
     const res = await t.fetch(`https://registry.npmjs.org/${name}/latest`)
     if (!res.ok) throw new Error(`registry ${res.status}`)
@@ -74,23 +86,24 @@ export const rvlibVersions = check({
     blocking: true,
     title: 'rvlib versions',
     description: 'the rvlib packages installed here are as new as the published ones',
-    owner: 'build/shipkit.md',
-    ttl: '24h',
+    owner: 'build/shipkit/consuming.md',
     // 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) => {
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: false, onClock: { every: '24h', inactive: 'wait' } },
+    cache: { by: 'ttl', span: '24h', key: (env) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
         return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })
             .filter((n) => n.startsWith('rvlib-'))
             .sort()
-            .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
+            .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}${isLinkedInstall(env.root, n) ? ` pin ${readPin(env.root, n)}` : ''}`)
             .join(',') + (rootPublishesNpm(env.config) ? ' npm' : '')
+    } },
+    fix: 'none',
+    applies: (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'
     },
     run: async (c) => {
         let pkg: Pkg
@@ -100,39 +113,47 @@ export const rvlibVersions = check({
         const pm = detectPackageManager(c.root)
         const manifest = ['package.json', ...(isRefusal(pm) ? LOCK_FILES : pm.locks)]
 
-        const stale: Array<{ name: string; installed: string; latest: string }> = []
+        const stale: Array<{ name: string; installed: string; latest: string; linked: boolean }> = []
         for (const [name, spec] of deps) {
             if (spec.startsWith('link:')) {
                 if (installedVersion(c.root, name) == null) c.fail(`${name} is link: but the symlink does not resolve — re-run \`bun link ${name}\` (a broken link dies cryptically at import time)`)
                 else c.ok(`${name} (linked, live)`)
                 continue
             }
-            const installed = installedVersion(c.root, name)
-            if (installed == null) { c.fail(`${name} declared (${spec}) but not installed — ${isRefusal(pm) ? pm.refused : `run: ${pm.install.join(' ')}`}`); continue }
+            const onDisk = installedVersion(c.root, name)
+            if (onDisk == null) { c.fail(`${name} declared (${spec}) but not installed — ${isRefusal(pm) ? pm.refused : `run: ${pm.install.join(' ')}`}`); continue }
+            const linked = isLinkedInstall(c.root, name)
+            const floor = linked ? pinFloor(spec) : null
+            if (linked && floor == null) { c.ok(`${name} (linked to its source, pin ${spec} names no version to judge)`); continue }
+            const installed = floor ?? onDisk
+            // how the lines below name it: a linked dep is its pin, never the source it links
+            const label = linked ? `${name} pin ${installed}` : `${name} ${installed}`
             let latest: string
             try { latest = await latestVersion(c, name) } catch (e) {
-                c.lines.push({ kind: 'skip', text: `${name} ${installed} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
+                c.lines.push({ kind: 'skip', text: `${label} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
                 continue
             }
             // real semver order, not string difference — a dist-tag pointing
             // BEHIND the installed version (prerelease, unpublish window)
             // must never trigger a silent downgrade
             const cmp = Bun.semver.order(latest, installed)
-            if (cmp === 0) c.ok(`${name} ${installed} (latest)`)
-            else if (cmp < 0) c.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
+            if (cmp === 0) c.ok(`${label} (latest${linked ? ', linked to its source' : ''})`)
+            else if (cmp < 0) c.ok(`${label} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
             else if (isBreaking(installed, latest) && !allowMajor()) c.warn(breakingAdvice(name, latest, basename(c.root)))
-            else if (name === 'rvlib-shipkit' && isRunningCopy(c.root)) {
+            // a linked toolkit moves only its pin: the source tree this process
+            // runs from is never written, so the swap below cannot happen
+            else if (name === 'rvlib-shipkit' && !linked && isRunningCopy(c.root)) {
                 // swapping this tree under the running process is how a run
                 // meets modules of two versions. The startup self-update owns
                 // it: handing it the answer makes the next run update and
                 // restart before any check loads
                 rememberLatest(latest)
                 c.warn(`${name} ${installed} → ${latest} is the toolkit running this check, so it is not swapped mid run: the next shipkit run updates it and restarts before any check`)
-            } else stale.push({ name, installed, latest })
+            } else stale.push({ name, installed, latest, linked })
         }
         if (stale.length === 0) return
 
-        const drift = stale.map((s) => `${s.name} ${s.installed} → ${s.latest}`).join(', ')
+        const drift = stale.map((s) => `${s.name}${s.linked ? ' pin' : ''} ${s.installed} → ${s.latest}`).join(', ')
         const names = stale.map((s) => s.name)
         if (isRefusal(pm)) {
             c.warn(`newer rvlib live: ${drift}, not updating: ${pm.refused}`)
@@ -164,7 +185,11 @@ export const rvlibVersions = check({
         const leased = await withMutateLease(mutateLease(c.root, 'fix'), { label: 'self-update', print: () => {}, escape: 'SHIPKIT_FROZEN=1' }, async () => {
             const again = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
             if (again.code === 0 && again.out.trim() !== '') return null
-            return await c.exec(cmd, { cwd: c.root, timeoutMs: 120_000 })
+            const up = await c.exec(cmd, { cwd: c.root, timeoutMs: 120_000 })
+            // the update may swap a link for the tarball: put every link back,
+            // whatever the update did, inside the same lease
+            for (const s of stale) if (s.linked) await c.exec(['bun', 'link', s.name], { cwd: c.root, timeoutMs: 60_000 })
+            return up
         })
         if (!leased.ok) {
             c.warn(`newer rvlib live: ${drift} — self-update deferred (${leased.warn}); re-run check once that run finishes`)
@@ -188,6 +213,13 @@ export const rvlibVersions = check({
             return
         }
         for (const s of stale) {
+            if (s.linked) {
+                const now = pinFloor(readPin(c.root, s.name) ?? '')
+                if (!isLinkedInstall(c.root, s.name)) c.fail(`${s.name} pin ${s.installed} → ${now ?? 'unreadable'} but node_modules/${s.name} is no longer linked to its source — run: bun link ${s.name}`)
+                else if (now === s.latest) c.warn(`${s.name} pin ${s.installed} → ${now} self-updated, link to the source restored — commit the bump`)
+                else c.warn(`${s.name} updated but its pin reads ${now ?? 'unreadable'} (wanted ${s.latest}) — check package.json`)
+                continue
+            }
             const now = installedVersion(c.root, s.name)
             // WARN on purpose: the run MUTATED the repo and a follow-up
             // (restart watchers, commit) is owed — an ok here would be a

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

@@ -40,6 +40,10 @@ export const npmPublishSafety = check({
     owner: 'meta/rv-conventions/package-json.md',
     // keyed on what it reads: the root package.json and every declared release
     // unit's, at the dirs the config picks
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const json = (rel: string): Pkg | null | 'unparseable' => {
             try { return c.json<Pkg>(rel) } catch { return 'unparseable' }

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

@@ -27,8 +27,10 @@ export const githubVisibility = check({
     title: 'github visibility',
     description: 'the github visibility of this repo matches the one it declares',
     owner: 'meta/contracts.md',
-    ttl: 'forever',
-    cacheKey: (env) => declaredVisibility(env.config),
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: 'once' },
+    cache: { by: 'fact', key: (env) => declaredVisibility(env.config) },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         const declared = declaredVisibility(c.config)
         const skip = (why: string): void => void c.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })

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

@@ -86,15 +86,17 @@ export const reviewerAgent = check({
     title: 'reviewer definition',
     description: 'the declared reviewer agent has its brief, its definition and read only tools',
     owner: 'identity/how-we-work.md',
+    runs: { onPreCommit: { budgetMs: 20 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // 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) => {
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: (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))}`
-    },
+    } },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => {
         const r = c.config.reviewer
         if (r == null) return c.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
@@ -109,7 +111,7 @@ export const reviewerAgent = check({
     // create-if-missing only: an existing definition may carry a repo's own
     // tuned prompt, and silently rewriting that would cost more than the
     // finding it repairs. Violations in a present file stay a loud FAIL.
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const r = c.config.reviewer
         if (r == null) return { changed: false, summary: 'no reviewer declared — nothing to write' }
         const rel = reviewerAgentPath(r.name)