rvlib-shipkit 0.30.0 → 0.32.0

package/src/rules/SK001-package-json-shape.ts

@@ -2,11 +2,17 @@
 // private:true, no license, capability-required script names FAIL, banned
 // aliases + missing baseline scripts WARN. Blocking, so it runs in `shipkit
 // ci` like every other rule. Pure local fs, no TTL.
+//
+// It also enforces the package.json half of ONE WAY IN (build/shipkit.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
+// shipkit rather than beside it.
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { canonicalBodies, conditionalBodies, inferBin } from '../core/canonical-scripts.ts'
+import { canonicalBodies, conditionalBodies, inferBin, ROUTED_SCRIPTS, rawName, routedBody, routesToShipkit } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
-import type { RepoConfig } from '../repo-config.ts'
+import { resolveFloor, type RepoConfig } from '../repo-config.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
 
 type Pkg = { name?: string; private?: boolean; license?: string; scripts?: Record<string, string> }
@@ -68,6 +74,23 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
     const missing = required.filter((r) => !has(r.name))
     for (const m of missing) t.fail(`package.json: missing script '${m.name}' (${m.why})`)
 
+    // ONE WAY IN — a governed script that runs the tool directly is the whole
+    // reason a cache gets bypassed: an agent types `bun run test` and shipkit
+    // never hears about it. A slot the repo turned off has no shipkit task to
+    // route to, so it is not governed.
+    const floor = resolveFloor(c, root)
+    for (const id of ROUTED_SCRIPTS) {
+        if (routedExempt(c).has(id) || c.defaults?.[id] === false) continue
+        const body = scripts[id]
+        if (body == null) continue
+        if (!routesToShipkit(body)) {
+            t.fail(`package.json: script '${id}' runs the tool directly — route it to \`${routedBody(id, { bin: inferBin(scripts) })}\` and move the body to '${rawName(id)}', so \`bun run ${id}\` gets the cache instead of bypassing it`)
+            continue
+        }
+        const gap = floor.unfilled.find((u) => u.id === id)
+        if (gap != null) t.fail(`package.json: ${gap.reason} — \`bun run ${id}\` would measure nothing`)
+    }
+
     // `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
@@ -96,6 +119,29 @@ function requiredScripts(root: string, _c: RepoConfig): Array<{ name: string; wh
     return required
 }
 
+/** rebuild the script map with `key` inserted directly after `after`, so a
+ *  routed pair reads as two adjacent lines instead of the tool body landing at
+ *  the bottom of the file, far from the name it belongs to */
+function insertAfter(scripts: Record<string, string>, after: string, key: string, value: string): Record<string, string> {
+    const out: Record<string, string> = {}
+    for (const [k, v] of Object.entries(scripts)) {
+        if (k === key) continue
+        out[k] = v
+        if (k === after) out[key] = value
+    }
+    if (out[key] == null) out[key] = value
+    return out
+}
+
+/** governed names this repo keeps as a direct tool call. Declared per NAME in
+ *  repo.config, never as a list of banned binaries: the invariant is about
+ *  which VERBS an agent reaches for, and a binary blocklist goes stale the day
+ *  a repo changes runner. `defineRepo` rejects a name outside ROUTED_SCRIPTS,
+ *  so a typo can never silently un-govern a script. */
+function routedExempt(c: RepoConfig): Set<string> {
+    return new Set(c.oneWayIn?.exempt ?? [])
+}
+
 const TEST_SKIP = new Set(['node_modules', 'dist', 'tmp', 'references', 'coverage'])
 
 /** any `*.test.ts` in the repo, so the test script is only scaffolded once it
@@ -164,6 +210,23 @@ export const packageJsonShape: Rule = {
         // none, so scaffolding this into a repo without any turns the gate red
         // on work the fixer itself did. a fixer must never manufacture a failure.
         if (pkg.scripts['test'] == null && hasTestFiles(env.root)) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        // ONE WAY IN, last so it also routes whatever this pass just added:
+        // the tool body slides to `<id>:raw` and `<id>` becomes the shipkit
+        // call. Both keys keep their place in the file, so the diff a human
+        // reads is the two lines that changed and not a reordered block
+        for (const id of ROUTED_SCRIPTS) {
+            if (routedExempt(env.config).has(id) || env.config.defaults?.[id] === false) continue
+            const body = pkg.scripts[id]
+            if (body == null || routesToShipkit(body)) continue
+            const raw = rawName(id)
+            const held = pkg.scripts[raw]
+            // a `<id>:raw` that already says something else is a repo's own
+            // answer, and overwriting it would delete a body nobody can recover
+            if (held != null && held !== body) { notes.push(`'${id}' left as it is — '${raw}' already holds a different body`); continue }
+            pkg.scripts = insertAfter(pkg.scripts, id, raw, body)
+            pkg.scripts[id] = routedBody(id, { bin })
+            changes.push(`script '${id}' routed through shipkit ('${raw}' holds the tool)`)
+        }
         if (changes.length > 0) {
             const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
             writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')

package/src/rules/SK002-contracts-fulfillness.ts

@@ -6,7 +6,7 @@
 // `shipkit contracts`, the ci `contracts` task) tags with this id via
 // contracts/apply-contracts.ts.
 import { activeContracts, applyContractsResult, contractsConfigFrom } from '../contracts/apply-contracts.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { evaluateContractsOnce } from '../contracts/contracts-once.ts'
 import type { Rule } from './rule.ts'
 
 export const contractsFulfillness: Rule = {
@@ -15,6 +15,6 @@ export const contractsFulfillness: Rule = {
     title: 'contracts',
     owner: 'meta/contracts.md',
     lint: async (t, env) => {
-        applyContractsResult(t, await evaluateContracts(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
+        applyContractsResult(t, await evaluateContractsOnce(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
     },
 }

package/src/rules/SK004-gitignore-policy.ts

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
+import { GENERATED_IGNORE_LINES, trackedGeneratedPaths, untrackGenerated } from './untrack-generated.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
 
 const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit outside only'
@@ -37,6 +38,10 @@ const POLICY_LINES = [
     // so every consumer repo needs both ignored before its first commit
     '.comfy-ts/',
     '*.loras.local.txt',
+    // shipkit's own per-run output. Ignoring is only half of it: the fixer
+    // also removes these from the index, because .gitignore does nothing to a
+    // file already tracked (untrack-generated.ts owns the pair)
+    ...GENERATED_IGNORE_LINES,
 ]
 
 export function expectedBlock(config: RepoConfig): string {
@@ -96,6 +101,13 @@ export const gitignorePolicy: Rule = {
     title: '.gitignore',
     owner: 'meta/contracts.md',
     lint: (t, env) => {
+        // a generated path still in the index is the half-applied state the
+        // managed block cannot fix on its own
+        const tracked = trackedGeneratedPaths(env.root)
+        if (tracked.length > 0) {
+            t.fail(`${tracked.join(', ')} generated on every run but TRACKED — gitignore does not apply to a tracked file, so it dirties every tree`)
+            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) untracks it in one commit, the file stays on disk' })
+        }
         const s = blockState(env.root, env.config)
         switch (s) {
             case 'missing-file': return t.fail('.gitignore missing — the contract git policy is unenforced')
@@ -107,8 +119,20 @@ export const gitignorePolicy: Rule = {
     },
     fix: (env: RuleEnv): FixResult => {
         const before = blockState(env.root, env.config)
-        if (before === 'current') return { changed: false, summary: 'policy block already current' }
-        writeBlock(env.root, env.config)
-        return { changed: true, summary: before === 'missing-file' ? '.gitignore created with the policy block' : before === 'missing-block' ? 'policy block appended (repo lines untouched)' : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)' : 'policy block rewritten in place (repo lines untouched)' }
+        const blockSummary = before === 'current'
+            ? null
+            : before === 'missing-file' ? '.gitignore created with the policy block'
+            : before === 'missing-block' ? 'policy block appended (repo lines untouched)'
+            : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)'
+            : 'policy block rewritten in place (repo lines untouched)'
+        if (blockSummary != null) writeBlock(env.root, env.config)
+        // the block must be written FIRST: untracking a path the ignore list
+        // does not yet carry leaves it staged for re-add on the next `git add`
+        const un = untrackGenerated(env.root, { enabled: env.config.untrackGenerated })
+        const parts = [blockSummary]
+        if (un.did === 'untracked') parts.push(`untracked ${un.paths.join(', ')} (generated, now gitignored, committed as ${un.commit})`)
+        if (un.did === 'refused') parts.push(`left ${trackedGeneratedPaths(env.root).join(', ')} tracked: ${un.why}`)
+        const summary = parts.filter((x): x is string => x != null).join(' · ')
+        return { changed: blockSummary != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
     },
 }

package/src/rules/SK012-config-barrel-import.ts

@@ -0,0 +1,60 @@
+// SK012 — `repo.config.ts` must import from the NARROW module, never from the
+// package barrel.
+//
+// THE COST, measured on this tree: `import { defineRepo } from 'rvlib-shipkit'`
+// pulls the whole toolkit, 405ms of module load. The same symbol from
+// `rvlib-shipkit/src/repo-config.ts` is 7ms. Every shipkit invocation in every
+// repo loads this file first, the ~1s pre-commit hook included, so the barrel
+// is a fixed tax on every gate run, every hook, every hub boot.
+//
+// A barrel is a fine PUBLIC surface and a terrible one to import from a config
+// file that exists to be read before anything else happens. This rule is
+// narrow on purpose: it is about repo.config.ts, not about barrels in general.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const CONFIG = 'repo.config.ts'
+const BARREL = /(^|\n)(\s*import\s+(?:type\s+)?\{[^}]*\}\s+from\s+)['"]rvlib-shipkit['"]/
+const NARROW = 'rvlib-shipkit/src/repo-config.ts'
+
+/** the symbols a config file can legitimately want, all of which the narrow
+ *  module already exports. A config reaching for anything else is asking the
+ *  barrel for a reason, and the rule says so rather than rewriting it. */
+const CONFIG_SYMBOLS = new Set(['defineRepo', 'RepoConfig', 'TaskDef', 'ServeConfig', 'FloorSource', 'FloorResolution', 'loadRepoConfig', 'resolveFloor', 'allTasks'])
+
+const importedSymbols = (line: string): string[] =>
+    (/\{([^}]*)\}/.exec(line)?.[1] ?? '').split(',').map((s) => s.replace(/^\s*type\s+/, '').trim()).filter((s) => s !== '')
+
+export const configBarrelImport: Rule = {
+    id: 'SK012',
+    blocking: true,
+    title: 'config import path',
+    owner: 'build/shipkit.md',
+    lint: (t, env) => {
+        const p = join(env.root, CONFIG)
+        if (!existsSync(p)) return void t.ok(`${CONFIG} absent — nothing to narrow`)
+        const src = readFileSync(p, 'utf8')
+        if (!BARREL.test(src)) return void t.ok(`${CONFIG} imports the narrow config module`)
+        const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
+        const symbols = importedSymbols(line)
+        const strays = symbols.filter((s) => !CONFIG_SYMBOLS.has(s))
+        if (strays.length > 0) {
+            t.fail(`${CONFIG} imports ${strays.join(', ')} from the package barrel, which costs ~400ms of module load on every shipkit run`)
+            return void t.lines.push({ kind: 'fix-fail', text: `move ${strays.join(', ')} to their own module, then import from ${NARROW}` })
+        }
+        t.fail(`${CONFIG} imports from the package barrel (~400ms of module load on every shipkit run, the pre-commit hook included)`)
+    },
+    fix: (env: RuleEnv): FixResult => {
+        const p = join(env.root, CONFIG)
+        if (!existsSync(p)) return { changed: false, summary: `${CONFIG} absent` }
+        const src = readFileSync(p, 'utf8')
+        if (!BARREL.test(src)) return { changed: false, summary: 'already narrow' }
+        const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
+        // only rewrite what the narrow module actually exports: silently
+        // repointing an import it cannot serve turns a slow gate into a broken one
+        if (importedSymbols(line).some((s) => !CONFIG_SYMBOLS.has(s))) return { changed: false, summary: 'imports symbols the narrow module does not export — move them by hand' }
+        writeFileSync(p, src.replace(BARREL, `$1$2'${NARROW}'`))
+        return { changed: true, summary: `${CONFIG} now imports ${NARROW} (~400ms saved per run)` }
+    },
+}

package/src/rules/rule-registry.ts

@@ -14,6 +14,7 @@ import { reviewerAgent } from './SK008-reviewer-agent.ts'
 import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
+import { configBarrelImport } from './SK012-config-barrel-import.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -27,6 +28,7 @@ export const RULES: readonly Rule[] = [
     commitAiTells,
     undeclaredReleaseUnit,
     siblingUnitRanges,
+    configBarrelImport,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/rules/untrack-generated.ts

@@ -0,0 +1,117 @@
+// paths shipkit GENERATES on every run, and the one operation that makes a
+// declaration like that actually hold.
+//
+// THE CONTRADICTION THIS RESOLVES: `.gitignore` does not apply to a file that
+// is already tracked. So a path shipkit ignores but leaves in the index keeps
+// dirtying every tree forever, and rides into unrelated commits as a mystery
+// diff. Ignoring and untracking are therefore ONE operation, never two, and
+// any path declared machine-generated gets both.
+//
+// STATUS.md is the first customer and the reason: 141 of this repo's 625
+// commits carried it, 125 of them as an unrelated rider inside someone else's
+// diff, in a repo whose commits ARE the session-resume mechanism. It is
+// nondeterministic by construction (minute-resolution header, task lines in
+// DAG completion order, per-worktree cache stamps that move backwards), and
+// nothing on this disk ever reads a past version: the hub reads it off disk,
+// the TUI renders live, the tests assert the writer.
+//
+// WHY THIS ONE FIXER COMMITS, when shipkit otherwise never does: `git rm
+// --cached` leaves a STAGED DELETION in the index, which the next agent's
+// unrelated commit sweeps up as an unexplained deletion. That is strictly
+// worse than the disease. The commit is a one-time migration per path, it
+// goes through the hooks like any other, and it refuses in every state where
+// it could surprise someone.
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+/** rendered into the SK004 managed block. A glob is fine HERE: ignoring is
+ *  not destructive. */
+export const GENERATED_IGNORE_LINES = [
+    '# shipkit writes these on every run — ignored AND untracked (untrack-generated.ts)',
+    'STATUS.md',
+    'STATUS.md.lock',
+    '.STATUS.md.tmp-*',
+]
+
+/** the LITERAL subset an autofix may remove from the index. Never a glob and
+ *  never derived from a pattern: `git rm --cached` driven by a wildcard is how
+ *  a fixer eats source it was never pointed at. A future entry is added HERE,
+ *  by hand, spelled out. */
+export const GENERATED_TRACKED_PATHS = ['STATUS.md', 'STATUS.md.lock'] as const
+
+export type UntrackOutcome =
+    | { did: 'nothing' }
+    | { did: 'refused'; why: string }
+    | { did: 'untracked'; paths: string[]; commit: string }
+
+const git = (root: string, args: string[]): { code: number; out: string } => {
+    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
+}
+
+/** every declared path this repo still carries in its index. ONE git spawn,
+ *  not one per path: this runs inside the SK004 lint, which runs on every
+ *  `shipkit check` in every repo, and a process start is ~10ms of it. */
+export function trackedGeneratedPaths(root: string): string[] {
+    if (!existsSync(join(root, '.git'))) return []
+    const r = git(root, ['ls-files', '-z', '--', ...GENERATED_TRACKED_PATHS])
+    if (r.code !== 0) return []
+    const listed = new Set(r.out.split('\0').filter((l) => l !== ''))
+    return GENERATED_TRACKED_PATHS.filter((p) => listed.has(p))
+}
+
+/** a state where an automated commit would surprise someone, or land on the
+ *  wrong ref. Named rather than boolean so the refusal says which one. */
+function unsafeState(root: string): string | null {
+    const gitDir = git(root, ['rev-parse', '--git-dir'])
+    if (gitDir.code !== 0) return 'not a git work tree'
+    const d = join(root, gitDir.out)
+    if (existsSync(join(d, 'MERGE_HEAD'))) return 'a merge is in progress'
+    if (existsSync(join(d, 'rebase-merge')) || existsSync(join(d, 'rebase-apply'))) return 'a rebase is in progress'
+    if (git(root, ['symbolic-ref', '-q', 'HEAD']).code !== 0) return 'HEAD is detached'
+    if (git(root, ['rev-parse', '--verify', '-q', 'HEAD']).code !== 0) return 'the repo has no commit yet'
+    // the commit below stages nothing but our own removal, so ANY other staged
+    // change would ride along in it. A one-time migration can wait for a run
+    // where the index is the fixer's alone
+    const staged = git(root, ['diff', '--cached', '--name-only'])
+    if (staged.code === 0 && staged.out !== '') return `something else is already staged (${staged.out.split('\n')[0]})`
+    return null
+}
+
+const message = (paths: string[]): string =>
+    [
+        `chore(machine): untrack ${paths.join(', ')}`,
+        '',
+        `shipkit rewrites ${paths.length === 1 ? 'this path' : 'these paths'} on every run, so ${paths.length === 1 ? 'it was' : 'they were'} never source.`,
+        'Tracked, it dirtied every tree and rode into unrelated commits as a',
+        'mystery diff. Gitignore alone cannot fix that: it does not apply to a',
+        'file already in the index, so the two halves land together.',
+        '',
+        'The file stays on disk. Nothing reads a past version of it.',
+    ].join('\n')
+
+/**
+ * ignore AND untrack, in one operation. Loud when it acts, loud when it
+ * refuses, silent when there is nothing to do.
+ *
+ * `frozen` is the release-shaped run: report only, touch nothing.
+ */
+export function untrackGenerated(root: string, o: { frozen?: boolean; enabled?: boolean } = {}): UntrackOutcome {
+    if (o.enabled === false) return { did: 'nothing' }
+    if (o.frozen === true || process.env.SHIPKIT_FROZEN === '1') return { did: 'nothing' }
+    const paths = trackedGeneratedPaths(root)
+    if (paths.length === 0) return { did: 'nothing' }
+    const unsafe = unsafeState(root)
+    if (unsafe != null) return { did: 'refused', why: unsafe }
+
+    const rm = git(root, ['rm', '--cached', '--quiet', '--', ...paths])
+    if (rm.code !== 0) return { did: 'refused', why: `git rm --cached failed: ${rm.out.slice(0, 120)}` }
+    // through the hooks, never --no-verify. A rejected commit must not leave
+    // the staged deletion behind: that IS the failure mode this exists to stop
+    const commit = git(root, ['commit', '-m', message(paths)])
+    if (commit.code !== 0) {
+        git(root, ['reset', '--quiet', '--', ...paths])
+        return { did: 'refused', why: `the commit was rejected, index restored: ${commit.out.slice(0, 160)}` }
+    }
+    return { did: 'untracked', paths, commit: git(root, ['rev-parse', '--short', 'HEAD']).out }
+}

package/src/scaffold/project-scaffold.ts

@@ -12,7 +12,7 @@
 // none of them may name a machine-local tool or a private path.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
-import { defaultHubPort } from '../serve/run-serve.ts'
+import { defaultHubPort } from '../serve/hub-port.ts'
 
 const FILES = join(import.meta.dir, 'files')
 

package/src/serve/hub-port.ts

@@ -0,0 +1,17 @@
+// the hub's default port, alone in its own module ON PURPOSE.
+//
+// It is four lines of arithmetic that several places need BEFORE any server
+// exists: the repo scaffold writes it into .vscode/tasks.json, `init` prints
+// it, the config resolver defaults to it. Importing it from run-serve.ts drags
+// the whole hub (react, the markdown renderer, the sanitiser, every panel)
+// into a caller that only wanted a number, which measured 393ms of module
+// load in the scaffold alone.
+//
+// A port derived from the repo NAME rather than assigned means two repos open
+// side by side almost never collide, and the same repo always reopens on the
+// same port, which is what makes a folder-open task able to advertise a URL.
+export function defaultHubPort(name: string): number {
+    let h = 0
+    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
+    return 4800 + (h % 180)
+}

package/src/serve/run-serve.ts

@@ -1,12 +1,14 @@
 // shipkit serve — resolve the repo's toolbox and run the hub. What mounts
 // comes from convention + repo.config's `serve` block: the wiki graph is
 // always on (custom provider via serve.wikiGraph, else the generic md
-// scan), agent/ graph when the dir exists, the studio when .rv-assets/
+// scan), the base-context wiki when a CLAUDE.md include names one, agent/
+// graph when the dir exists, the studio when .rv-assets/
 // kit.ts loads. Port: --port > serve.port > a deterministic house-range
 // default (4800-4979, hashed from the repo name — stable across launches;
 // pin serve.port when two repos collide).
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { homedir } from 'os'
+import { basename, dirname, join, resolve, sep } from 'path'
 import { fileURLToPath } from 'url'
 import { loadKit, type ResolvedKit } from '../assets/kit-config.ts'
 import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
@@ -15,30 +17,63 @@ import { graphsCollection } from '../collections/graphs.ts'
 import { pingTick } from '../collections/pings.ts'
 import { buildCollections } from '../collections/providers.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import { scanMdGraph } from '../wiki/scan-md.ts'
 import { serveHub, type HubDeps } from './serve-hub.ts'
+import { defaultHubPort } from './hub-port.ts'
+export { defaultHubPort }
 
 export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
 
-export function defaultHubPort(name: string): number {
-    let h = 0
-    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
-    return 4800 + (h % 180)
+
+// the BASE-CONTEXT wiki: the shared wiki this repo's CLAUDE.md include chain
+// points at (`@~/dev/<other-repo>/wiki/index.md`). It lives in ANOTHER repo and
+// binds every agent working here, so the hub makes it browsable. Never linted
+// from here. The local-include forms (`@./agent/index.md`,
+// `@./CLAUDE.local.md`) and any index inside this repo are skipped: those are
+// already their own mounts.
+export function baseWikiRoot(root: string): string | null {
+    const abs = resolve(root)
+    for (const f of ['CLAUDE.md', 'CLAUDE.local.md', 'CLAUDE.private.md']) {
+        const p = join(abs, f)
+        if (!existsSync(p)) continue
+        for (const line of readFileSync(p, 'utf8').split('\n')) {
+            const m = line.trim().match(/^@(\S+\.md)$/)
+            if (m == null) continue
+            const raw = m[1]!
+            const target = resolve(abs, raw.startsWith('~/') ? join(homedir(), raw.slice(2)) : raw)
+            const dir = dirname(target)
+            if (!existsSync(target)) continue
+            if (dir === abs || dir.startsWith(abs + sep)) continue
+            return dir
+        }
+    }
+    return null
 }
 
+// `~/dev/<repo>/wiki` reads as "<repo> wiki" — a dir literally named wiki says
+// nothing on its own, so the owning repo names the card
+const wikiLabel = (dir: string): string => (basename(dir) === 'wiki' ? `${basename(dirname(dir))} wiki` : basename(dir))
+
 export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
-    // the default wiki graph exists only when the repo HAS a wiki dir: a
-    // game repo's hub advertising a wiki route was startup noise
-    // 2026-08-05). A config-declared wikiGraph always mounts.
-    const wikiGraph = c.serve?.wikiGraph != null
-        ? { title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load }
-        : existsSync(join(root, 'wiki'))
-            ? { title: `${c.name} wiki`, load: () => scanMdGraph({ root }) }
-            : null
+    // ONE list: the routes, the /hub.json tools and the graphs section all
+    // read it, so nothing can advertise a graph the server does not serve.
+    // The repo's OWN wiki mounts when it has one (a game repo's hub
+    // advertising an empty wiki route was startup noise), a config-declared
+    // provider always mounts, and the base-context wiki (the shared one named
+    // by the CLAUDE.md include chain) mounts wherever it is reachable: an
+    // agent working here obeys that wiki, so a reader can open it.
+    const graphs: GraphMount[] = []
+    if (c.serve?.wikiGraph != null)
+        graphs.push({ id: 'wiki', label: 'wiki graph', title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, lint: null, note: 'repo-owned lint' })
+    else if (existsSync(join(root, 'wiki')))
+        graphs.push({ id: 'wiki', label: 'wiki graph', title: `${c.name} wiki`, load: () => scanMdGraph({ root }), lint: { root } })
+    const baseWiki = baseWikiRoot(root)
+    if (baseWiki != null)
+        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), lint: null })
     const agentRoot = join(root, 'agent')
-    const agentGraph = existsSync(agentRoot)
-        ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
-        : null
+    if (existsSync(agentRoot))
+        graphs.push({ id: 'agent', label: 'agent graph', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), lint: { root: agentRoot, index: c.serve?.agentIndex } })
     // ONE page for every repo: the studio ALWAYS
     // mounts — kit-less repos get an empty media section, never a second
     // page. A broken kit degrades to the same empty kit, loudly.
@@ -60,15 +95,14 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     const cli = fileURLToPath(new URL('../cli.ts', import.meta.url))
     const allCollections = () => [
         ...buildCollections(root, c, kit, { bootVersion: BOOT_VERSION, libVersion }),
-        graphsCollection(root, { customWiki: c.serve?.wikiGraph != null, agentIndex: c.serve?.agentIndex }),
+        graphsCollection(graphs),
     ]
     const port = o?.port ?? c.serve?.port ?? defaultHubPort(c.name)
     return {
         root,
         name: c.name,
         port,
-        wikiGraph,
-        agentGraph,
+        graphs,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
         needs: () => projectNeeds(allCollections()),

package/src/serve/serve-hub.ts

@@ -6,23 +6,21 @@
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
-import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 import type { StudioRoutes } from '../assets/server/studio-server.ts'
 import { appendAskRemark, appendAssetNote, appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
 import type { Collection, Instance, NeedItem } from '../collections/collection-types.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import hubIndex from './hub-app/index.html'
 
-export type HubGraph = { title: string; load: () => MdGraph }
 export type HubTool = { path: string; label: string; desc: string }
 export type HubDeps = {
     root: string
     name: string
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
-    /** null = this repo has no wiki to graph — the route stays unmounted */
-    wikiGraph: HubGraph | null
-    /** null = no agent/ dir */
-    agentGraph: HubGraph | null
+    /** every md graph this hub serves, in card order: /graph/<id>. run-serve
+     *  resolves the list, the routes AND the graphs section read it */
+    graphs: GraphMount[]
     /** the media API (mounted under /media/*); null only if the route
      *  table failed to build — the page shows the WARN, never a second page */
     studio: StudioRoutes | null
@@ -43,11 +41,11 @@ export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop
 
 // the toolbox as data — stdout ok: lines and /hub.json render THIS list,
 // so they can never disagree
-export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph'>): HubTool[] {
-    const tools: HubTool[] = [{ path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' }]
-    if (d.wikiGraph != null) tools.push({ path: '/graph/wiki', label: 'wiki graph', desc: d.wikiGraph.title })
-    if (d.agentGraph != null) tools.push({ path: '/graph/agent', label: 'agent graph', desc: d.agentGraph.title })
-    return tools
+export function hubTools(d: Pick<HubDeps, 'graphs'>): HubTool[] {
+    return [
+        { path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' },
+        ...d.graphs.map((g) => ({ path: `/graph/${g.id}`, label: g.label, desc: g.title })),
+    ]
 }
 
 // drill-down pages (graph canvases) get one fixed home link back to THE page
@@ -125,10 +123,10 @@ export function serveHub(d: HubDeps): Hub {
                 return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
             }
             const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
-            if (d.wikiGraph != null && path === '/graph/wiki') return page(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
-            if (d.wikiGraph != null && path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
-            if (d.agentGraph != null && path === '/graph/agent') return page(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
-            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
+            for (const g of d.graphs) {
+                if (path === `/graph/${g.id}`) return page(graphHtml(g.load(), { title: g.title }))
+                if (path === `/graph/${g.id}/graph.json`) return Response.json(g.load())
+            }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
             // stale bookmarks (/assets/, /status, …) land here — name the way home

package/src/shipkit.ts

@@ -5,8 +5,9 @@ export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './re
 export { contractsConfigFrom, activeContracts, applyContractsResult } from './contracts/apply-contracts.ts'
 // the hub (`shipkit serve`): one server, one port, every tool a click away
 export { serveHub, hubTools } from './serve/serve-hub.ts'
-export type { Hub, HubDeps, HubGraph, HubTool } from './serve/serve-hub.ts'
-export { runServe, resolveHubDeps, defaultHubPort } from './serve/run-serve.ts'
+export type { Hub, HubDeps, HubTool } from './serve/serve-hub.ts'
+export type { GraphMount } from './wiki/graph-mount.ts'
+export { runServe, resolveHubDeps, defaultHubPort, baseWikiRoot } from './serve/run-serve.ts'
 export { projectNeeds, redCount } from './collections/collection-types.ts'
 export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
 export { buildCollections } from './collections/providers.ts'

package/src/wiki/graph-mount.ts

@@ -0,0 +1,21 @@
+// one MOUNTED md graph, as the hub serves it and as the graphs section shows
+// it. ONE list per repo (serve/run-serve builds it): the route, the card and
+// the lint verdict all read the same entries, so a card can never link at a
+// route that is not served.
+import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+export type GraphMount = {
+    /** route + card id: /graph/<id>, instance graph:<id> */
+    id: string
+    /** card text and tool label, e.g. `wiki graph`, `<repo> wiki` */
+    label: string
+    /** graph page title */
+    title: string
+    load: () => MdGraph
+    /** null = someone else owns this graph's lint (a repo-owned provider, or a
+     *  wiki living in another repo): the card links, it never judges */
+    lint: { root: string; index?: string } | null
+    /** parenthesized on the CARD only, never in the terminal banner: why this
+     *  graph carries no verdict here */
+    note?: string
+}