rvlib-shipkit 1.8.0 → 2.0.0

package/src/release/run-release.ts

@@ -12,7 +12,7 @@ import { runCi } from '../core/run-ci.ts'
 import { extractChangelogSection } from './changelog.ts'
 import { deriveRemote, dirtyPaths, git, remoteTagState, tagExistsLocally, type RemoteTagState } from './git-facts.ts'
 import { releaseScope } from './release-scope.ts'
-import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
+import { publishCommand, unitBlockers, type Publisher } from './unit-gate.ts'
 import { formatUnitError, resolveUnits, unitById, unknownUnit, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { nestedIn, nestedRefusal } from '../core/nesting.ts'
@@ -37,6 +37,10 @@ export type ReleaseConfig = {
      *  Absent = rely on ambient npm auth. Never put a token in config.
      *  Repo-wide: one account publishes every unit. */
     npmTokenCommand?: string[]
+    /** the tool that packs and publishes every npm unit (default 'npm'). A
+     *  repo that tests its tarball with `bun pm pack` publishes with 'bun', so
+     *  the packer it tests is the packer that ships. */
+    publisher?: Publisher
     /** cut a GitHub release for the ROOT unit with `gh` (default true) */
     githubRelease?: boolean
     /** make a NON-blocking check failure block the release too. Blocking
@@ -113,7 +117,7 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
     return await runCi(root, {
         fix: o.fix ?? false,
         // a check's repair never runs on the release path (runs.onRelease):
-        // only the mechanical slots (the formatter) may, when bump asks
+        // only the mechanical slots (the import fixer) may, when bump asks
         fixRules: false,
         // the rows declaring onRelease, whatever the tier
         release: true,
@@ -239,13 +243,7 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
     const remoteName0 = 'remote' in remote ? remote.remote : null
     const tagExists = (): boolean => tagExistsLocally(root, tag)
     const remoteState: RemoteTagState = remoteName0 == null ? { state: 'unreadable', error: 'no remote' } : remoteTagState(root, remoteName0, tag)
-    if (remoteName0 != null && remoteState.state === 'unreadable')
-        blockers.push(`cannot read tags on '${remoteName0}' (${remoteState.error}) — the push would be a guess`)
-    // a tag NAME the remote already carries at another commit is not a
-    // resumable release: this version would describe a tree that shipped as
-    // something else, and git refuses the push anyway
-    if (remoteState.state === 'different')
-        blockers.push(`tag ${tag} already on '${remoteName0 ?? ''}' at ${remoteState.remoteOid.slice(0, 8)}, ${remoteState.localOid == null ? 'and not here at all' : `not ${remoteState.localOid.slice(0, 8)} as here`} — that version number is burnt, bump a new one`)
+    blockers.push(...tagBlockers(remoteName0, remoteState, tag))
     const ghReleaseExists = (): boolean =>
         wantGh && Bun.which('gh') != null && Bun.spawnSync(['gh', 'release', 'view', tag], { cwd: root }).exitCode === 0
     const fullyShipped = tagExists() && remoteState.state === 'same' && (!wantGh || ghReleaseExists()) && (!wantNpm || alreadyPublished)
@@ -301,18 +299,23 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
         if (wantNpm && !alreadyPublished) {
             const env: Record<string, string> = { ...process.env as Record<string, string> }
             const argv = rc.npmTokenCommand
+            const publisher = rc.publisher ?? 'npm'
             let npmrc: string | null = null
+            let token: string | null = null
             if (argv != null && argv[0] != null) {
                 const t = Bun.spawnSync(argv)
-                const token = t.exitCode === 0 ? t.stdout.toString().trim() : ''
+                token = t.exitCode === 0 ? t.stdout.toString().trim() : ''
                 if (token === '') { print(`FAIL: release.npmTokenCommand produced no token (exit ${t.exitCode})`); return 1 }
-                // token via a throwaway userconfig, never argv, never a
-                // committed .npmrc, never a line in a log
-                npmrc = join(work, 'npmrc')
-                writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600 })
+                // token via a throwaway userconfig (npm) or the env (bun),
+                // never argv, never a committed .npmrc, never a line in a log
+                if (publisher === 'npm') {
+                    npmrc = join(work, 'npmrc')
+                    writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600 })
+                }
             }
-            const p = Bun.spawnSync(npmPublishArgv({ npmrc }), { cwd: unit.dir, env, stdout: 'inherit', stderr: 'inherit' })
-            if (p.exitCode !== 0) { print(`FAIL: npm publish failed for ${unit.id} (exit ${p.exitCode})`); return 1 }
+            const cmd = publishCommand({ publisher, npmrc, token })
+            const p = Bun.spawnSync(cmd.argv, { cwd: unit.dir, env: { ...env, ...cmd.env }, stdout: 'inherit', stderr: 'inherit' })
+            if (p.exitCode !== 0) { print(`FAIL: ${publisher} publish failed for ${unit.id} (exit ${p.exitCode})`); return 1 }
             print(`ok: published ${name}@${version}`)
         }
 
@@ -356,3 +359,14 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
         rmSync(work, { recursive: true, force: true })
     }
 }
+
+/** what the remote's view of the tag forbids: a remote nobody can read makes
+ *  the push a guess, and a tag NAME it already carries at another commit is not
+ *  a resumable release (this version would describe a tree that shipped as
+ *  something else, and git refuses the push anyway) */
+export function tagBlockers(remote: string | null, state: RemoteTagState, tag: string): string[] {
+    if (remote != null && state.state === 'unreadable') return [`cannot read tags on '${remote}' (${state.error}) — the push would be a guess`]
+    if (state.state === 'different')
+        return [`tag ${tag} already on '${remote ?? ''}' at ${state.remoteOid.slice(0, 8)}, ${state.localOid == null ? 'and not here at all' : `not ${state.localOid.slice(0, 8)} as here`} — that version number is burnt, bump a new one`]
+    return []
+}

package/src/release/unit-gate.ts

@@ -9,11 +9,18 @@ import { dirtyPaths } from './git-facts.ts'
 import type { ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
-/** the publish argv. `--access public` is not a default: npm restricts a
- *  scoped package unless it is asked, and a restricted publish looks
- *  successful right up until a consumer cannot install it. */
-export function npmPublishArgv(o: { npmrc?: string | null } = {}): string[] {
-    return ['npm', 'publish', '--access', 'public', ...(o.npmrc != null ? ['--userconfig', o.npmrc] : [])]
+/** the tool that packs and publishes an npm unit (`release.publisher`) */
+export const PUBLISHERS = ['npm', 'bun'] as const
+export type Publisher = (typeof PUBLISHERS)[number]
+
+/** the publish argv and the env its token rides in. `--access public` is not
+ *  a default: npm restricts a scoped package unless it is asked, and a
+ *  restricted publish looks successful right up until a consumer cannot
+ *  install it. npm reads the token from a throwaway userconfig; `bun publish`
+ *  has no `--userconfig` and reads NPM_CONFIG_TOKEN instead. */
+export function publishCommand(o: { publisher?: Publisher; npmrc?: string | null; token?: string | null } = {}): { argv: string[]; env: Record<string, string> } {
+    if (o.publisher === 'bun') return { argv: ['bun', 'publish', '--access', 'public'], env: o.token != null ? { NPM_CONFIG_TOKEN: o.token } : {} }
+    return { argv: ['npm', 'publish', '--access', 'public', ...(o.npmrc != null ? ['--userconfig', o.npmrc] : [])], env: {} }
 }
 
 /** everything that must hold for this unit, checked before anything is

package/src/repo-config.ts

@@ -5,26 +5,27 @@
 // (lint/typecheck/test/imports:check/cycles): a package.json script wins;
 // with no script, imports:check/cycles fill from shipkit's own
 // rvlib-ts-tools dep and typecheck from the repo's tsc (O6 zero-config);
-// a slot that can't fill emits a visible reason, disabling via
-// `defaults: { x: false }` prints a skipped-by-config line — never silence.
+// a slot that can't fill emits a visible reason, and one turned off with
+// `off: { x: '<why>' }` prints a skipped-by-config line, never silence.
 // The `contracts` task is always present when any contract applies.
-import { existsSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
 import { ROUTED_SCRIPTS } from './core/canonical-scripts.ts'
 import { FLOOR_IDS } from './core/floor.ts'
 export { resolveFloor, type FloorResolution, type FloorSource } from './core/floor.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
-import type { ProseConfig } from './prose/run-prose.ts'
-import { proseWordsProblems } from './prose/ste.ts'
 import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { RULE_ID_RE, validateRules } from './rules/rule.ts'
 import { builtinCheckIds } from './core/discover-checks.ts'
+import { RETIRED_CHECK_IDS } from './core/retired-checks.ts'
 import { parseWhen } from './core/when.ts'
+import { normalizeVendored, vendoredOfText, vendoredProblem } from './core/vendored.ts'
 import { budgetValueProblem } from './core/budget.ts'
 import type { Rule } from './check.ts'
 import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
+import { PUBLISHERS } from './release/unit-gate.ts'
 import { TEST_ONLY_UNIT_KEYS, UNIT_DECL_KEYS, type UnitDecl } from './release/unit-resolve.ts'
 import { TASK_DEF_KEYS, type TaskDef } from './check.ts'
 import { testsConfigProblems, type TestsConfig } from './suite/judge-suites.ts'
@@ -41,6 +42,10 @@ export type ServeConfig = {
      *  its own port — house range 5800+, default = the hub port plus 1000
      *  (build/comfyui.md owns that surface) */
     comfyPort?: number
+    /** false hides the asset kit from the hub page (no asset rows, an empty
+     *  studio) and from `shipkit needs`, for a repo whose own tool mounts
+     *  `studioRoutes` and owns the picking. Default true */
+    assets?: boolean
     /** custom wiki-graph provider for repos with their own link semantics.
      *  Default: a generic md scan of the repo root. */
     wikiGraph?: {
@@ -75,12 +80,13 @@ export type RepoConfig = {
     social?: string[]
     /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
     docsBase?: string
-    /** a floor slot: `false` disables it (always visible), a def with a
-     *  `cmd` or `logic` REPLACES it, and a def with neither DECORATES whatever
-     *  fills it. The decoration is how a repo declares what its own `test`
-     *  script reads (`{ test: { inputs: ['tests', 'src'] } }`) without
-     *  restating the command: the read set is repo knowledge, the command is
-     *  already in package.json, and restating it is a second source of truth. */
+    /** a floor slot: a def with a `cmd` or `logic` REPLACES it, and a def
+     *  with neither DECORATES whatever fills it. The decoration is how a repo
+     *  declares what its own `test` script reads (`{ test: { inputs:
+     *  ['tests', 'src'] } }`) without restating the command: the read set is
+     *  repo knowledge, the command is already in package.json, and restating
+     *  it is a second source of truth. A slot set to `false` is RETIRED, read
+     *  as `off` while SK029 ports it there: a slot turns off like any check */
     defaults?: Record<string, Partial<TaskDef> | false>
     /** DEPRECATED, read through 0.40 and rewritten by `shipkit check --fix
      *  SK016`: a build step is a `<name>.check.ts` file with `build: true` */
@@ -162,10 +168,10 @@ export type RepoConfig = {
      *  folder only: it never commits, untracks, tags or pushes on the parent's
      *  history. Rule SK015 fails when this and the disk disagree (core/nesting.ts) */
     nested?: boolean
-    /** THE CHECKS THIS REPO TURNS OFF, check id → why. The one thing a repo
-     *  says about a check it does not own: where a check runs is its own
-     *  declaration (build/shipkit/runs.md), and an off check runs in no
-     *  context. `defineRepo` throws on a blank reason and on a rule id no
+    /** THE CHECKS THIS REPO TURNS OFF, check id → why, for a whole check it
+     *  does not own (one false finding is waived at its site instead): where
+     *  a check runs is its own declaration (build/shipkit/runs.md), and an
+     *  off check runs in no context. `defineRepo` throws on a blank reason and on a rule id no
      *  check carries. The hub writes this map through the managed block in
      *  this file (core/when-block.ts). */
     off?: Record<string, string>
@@ -246,6 +252,18 @@ export type RepoConfig = {
      *  repo root is refused outright: a single line that excuses everything
      *  would turn a blocking rule into a false green. */
     notReleasable?: string[]
+    /** repo-relative dirs of THIRD PARTY code (a git subtree, a copied
+     *  library) that must stay byte identical to upstream. Every tool that
+     *  treats the tree as the repo's own source leaves them out: the import
+     *  fixer and its package discovery, imports:check, cycles, the fix pass
+     *  (a fixer that rewrites a file under one gets it put back, with a
+     *  WARN naming it), bun lint, the checks' file
+     *  listings, check discovery, the md scan and `shipkit mv`. Cache keys
+     *  and watchers still read them, because they are still inputs, and the
+     *  leak guard still scans what a commit stages there. Write it
+     *  as a literal array of strings: the tools that never load this file
+     *  read it as text. One entry is one dir, never a glob */
+    vendored?: string[]
     /** git-hook gates: built-in leak guard + commit-message predicate, plus the
      *  repo's own commands. `shipkit hooks list` enumerates them, so what blocks
      *  a commit is answerable without reading shell. hooks/run-hooks.ts */
@@ -258,12 +276,6 @@ export type RepoConfig = {
         /** what a `*.check.ts` with no `export const blocking` means here */
         blocking?: boolean
     }
-    /** house prose in STE (identity/writing-voice.md), gated by rule SK014.
-     *  `include` is what makes the rule run at all: a repo that declares no
-     *  scope is skipped rather than failed, because STE binds the prose an
-     *  agent WRITES and no repo can be opted in from the outside.
-     *  prose/run-prose.ts */
-    prose?: ProseConfig
     /** `shipkit smoke`: the deployed url, the routes a read only browser pass
      *  visits after a deploy, and how it logs in. The password is a secret
      *  NAME: the value never sits in config, argv or env. smoke/run-smoke.ts */
@@ -295,7 +307,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'ignoredInputs', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'ignoredInputs', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'vendored', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -319,7 +331,9 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))
         if (!KNOWN_KEYS.has(k))
-            throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : k === 'home' ? ` — home.resources was removed; declare each one in a <name>.shipkit.ts file as \`export default globalProcess({...})\`` : ''}`)
+            throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : k === 'home' ? ` — home.resources was removed; declare each one in a <name>.shipkit.ts file as \`export default globalProcess({...})\`` : k === 'prose' ? ` — prose was removed with rule SK014: delete the key` : ''}`)
+    if (c.release?.publisher != null && !(PUBLISHERS as readonly string[]).includes(c.release.publisher))
+        throw new Error(`defineRepo: release.publisher '${String(c.release.publisher)}' is not a publisher (${PUBLISHERS.join(', ')})`)
     // a typo'd unit key would silently drop a target and release the wrong shape
     for (const u of c.units ?? []) {
         if (typeof u.dir !== 'string' || u.dir === '') throw new Error(`defineRepo: every units[] entry needs a 'dir'`)
@@ -341,6 +355,11 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (isAbsolute(d) || rel === '.' || rel === '' || rel === '..' || rel.startsWith('../'))
             throw new Error(`defineRepo: notReleasable '${d}' is the repo root or outside it, and would excuse every package at once — name one package dir per entry`)
     }
+    if (c.vendored != null && !Array.isArray(c.vendored)) throw new Error(`defineRepo: vendored is a list of repo-relative dirs`)
+    for (const d of c.vendored ?? []) {
+        const bad = vendoredProblem(d)
+        if (bad != null) throw new Error(`defineRepo: vendored '${String(d)}' ${bad}`)
+    }
     for (const [k, slot] of Object.entries(c.defaults ?? {})) {
         if (!(FLOOR_IDS as readonly string[]).includes(k))
             throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
@@ -378,6 +397,7 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     for (const [id, reason] of Object.entries(c.off ?? {})) {
         if (id.trim() === '') throw new Error(`defineRepo: off has an entry with no check id`)
         if (typeof reason !== 'string' || reason.trim() === '') throw new Error(`defineRepo: off.${id} needs a reason: a check nobody can explain is a silenced gate`)
+        if (RETIRED_CHECK_IDS[id] != null) throw new Error(`defineRepo: off.${id} names a retired rule (${RETIRED_CHECK_IDS[id]}): delete the entry`)
         if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
             throw new Error(`defineRepo: off.${id} names no rule, the ids are in \`shipkit checks\``)
     }
@@ -396,15 +416,12 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     }
     // an exemption silences a gate, so it names a rule that exists and says why
     for (const [id, reason] of Object.entries(c.ruleExempt ?? {})) {
+        if (RETIRED_CHECK_IDS[id] != null) throw new Error(`defineRepo: ruleExempt.${id} names a retired rule (${RETIRED_CHECK_IDS[id]}): delete the entry`)
         if (!builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
             throw new Error(`defineRepo: ruleExempt.${id} names no rule, the ids are in \`shipkit checks\``)
         if (typeof reason !== 'string' || reason.trim() === '')
             throw new Error(`defineRepo: ruleExempt.${id} needs a reason, an exemption nobody can explain is a silenced gate`)
     }
-    // a word list entry silences or adds gate hits, so a malformed one dies
-    // here rather than matching nothing
-    const words = proseWordsProblems(c.prose?.words)
-    if (words.length > 0) throw new Error(`defineRepo: ${words[0]}`)
     // a smoke typo would land as a run that visits nothing and exits 0
     if (c.smoke != null) validateSmokeConfig(c.smoke)
     // a leak-guard waiver is the one config row that can make a gate quieter,
@@ -432,5 +449,12 @@ export async function loadRepoConfig(root: string, o: { fresh?: boolean } = {}):
     if (!existsSync(path)) throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
     const mod = (await import(o.fresh === true ? `${path}?v=${Date.now()}-${Math.random().toString(36).slice(2)}` : path)) as { default?: RepoConfig }
     if (mod.default == null) throw new Error(`${path}: must default-export defineRepo({...})`)
+    // the tools that never load the config read `vendored` off the text, so
+    // a value the text cannot show would omit one set of dirs here and
+    // another there
+    const loaded = (mod.default.vendored ?? []).map(normalizeVendored)
+    const read = vendoredOfText(readFileSync(path, 'utf8'))
+    if (loaded.join('\0') !== read.join('\0'))
+        throw new Error(`${path}: \`vendored\` must be a literal array of strings, the tools that never load the config read it as text (they read [${read.join(', ')}], the config says [${loaded.join(', ')}])`)
     return mod.default
 }

package/src/scaffold/files/bunfig.toml

@@ -0,0 +1,11 @@
+# `bun lint` is the house linter, and `sk ci` runs it once [lint] is declared.
+# [fmt] is the house style for a manual `bun fmt`: nothing formats in the gate.
+[fmt]
+semi = false
+singleQuote = true
+printWidth = 140
+tabWidth = 4
+# code only: prose keeps its own shape, and package.json belongs to its fixers
+ignorePatterns = ["*.md", "*.json", "*.jsonc", "*.yaml", "*.yml", "*.toml"]
+
+[lint]

package/src/scaffold/files/vscode-settings.json

@@ -33,8 +33,7 @@
    "js/ts.tsserver.automaticTypeAcquisition.enabled": false,
    "js/ts.tsserver.checkNpmIsInstalled": false,
 
-   // oxc lints in-editor; eslint off; formatter owns formatting, not tsserver
-   "oxc.enable": true,
+   // eslint off, and no formatter on save: formatting is a manual `bun fmt`
    "eslint.enable": false,
    "js/ts.format.enabled": false
 }

package/src/scaffold/jsonc-spans.ts

@@ -111,3 +111,19 @@ export function removalSpan(text: string, arr: Extract<Node, { kind: 'array' }>,
     }
     return [item.start, item.end]
 }
+
+/** the spans that take several items out of one array at once, disjoint so
+ *  they apply in any order. An item with a kept one after it goes with its own
+ *  comma, and the removed run after the last kept item goes as one span from
+ *  that item's end, so no comma is left dangling */
+export function removalSpans(text: string, arr: Extract<Node, { kind: 'array' }>, idxs: Iterable<number>): [number, number][] {
+    const gone = new Set(idxs)
+    if (gone.size === 0) return []
+    const kept = arr.items.flatMap((_, i) => (gone.has(i) ? [] : [i]))
+    const lastKept = kept.at(-1) ?? -1
+    const spans: [number, number][] = []
+    for (const i of [...gone].sort((a, b) => a - b)) if (i < lastKept) spans.push(removalSpan(text, arr, i))
+    const tail = [...gone].filter((i) => i > lastKept).sort((a, b) => a - b)
+    if (tail.length > 0) spans.push([lastKept < 0 ? arr.items[tail[0]!]!.start : arr.items[lastKept]!.end, arr.items[tail.at(-1)!]!.end])
+    return spans
+}

package/src/scaffold/project-scaffold.ts

@@ -10,10 +10,9 @@
 // package.json rewrite reformats the file it edits.
 // Templates live beside this file in files/ and ship in the npm tarball, so
 // none of them may name a machine-local tool or a private path.
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { defaultHubPort } from '../serve/hub-port.ts'
-import { hubProblemMatcher } from '../problems/problem-line.ts'
 
 const FILES = join(import.meta.dir, 'files')
 
@@ -36,15 +35,14 @@ export type ScaffoldOpts = {
     claudePolicy?: boolean
 }
 
-/** every dep the house toolchain needs for the scripts below to run */
-export const TOOLCHAIN = ['typescript', 'oxlint', 'oxfmt', '@types/bun'] as const
+/** every dep the house toolchain needs for the scripts below to run. The
+ *  linter and the formatter are bun's own, declared in bunfig.toml */
+export const TOOLCHAIN = ['typescript', '@types/bun'] as const
 
 /** script bodies for a fresh repo whose only source dir is src/. A stack
- *  scaffold (vite, hono) adds dev/build on top; these three are the floor
- *  rule SK001 asks every repo for */
+ *  scaffold (vite, hono) adds dev/build on top. No `lint` or `fmt`: a script
+ *  of either name would shadow `bun lint` and `bun fmt` */
 const SCRIPTS: Record<string, string> = {
-    lint: 'oxlint src/',
-    fmt: 'oxfmt src/',
     typecheck: 'tsc --noEmit',
 }
 
@@ -104,64 +102,12 @@ function put(root: string, rel: string, body: string): boolean {
     return true
 }
 
-export type ErgonomicsOpts = {
-    /** repo name, substituted into the templates */
-    name: string
-    /** the port the hub actually listens on, resolved by the caller from the
-     *  repo config (`serve.port`, else the name-derived default), so the task
-     *  advertises a url something answers on */
-    port: number
-}
-
-/** the folder-open story, and the ONE file of it a repo shipkit did not create
- *  can be handed unasked.
- *
- *  What lands is `tasks.json` alone. `settings.json` turns eslint off and hands
- *  formatting to an oxc extension, so writing it into a repo that lints with
- *  eslint silences the linter that repo chose: that is an answer about what the
- *  repo IS, and a repo with a history of its own already gave it. A tasks file
- *  is the opposite: with no `folderOpen` task nothing starts at all, so there
- *  is no existing answer to overrule.
- *
- *  What lands INSIDE it is only what is true of every wired repo: the hub,
- *  whose script `init` writes, carrying the problem matcher that turns every
- *  check's findings into the problems pane. There is no type checker task, the
- *  hub runs `typecheck` like any other check. Every watcher a stack earns (a
- *  dev server, css) stays the analysis step `build/vscode-tasks.md` describes,
- *  and the caller says so out loud.
- *
- *  Create-only: an adopted repo often carries a `.vscode/` from whatever it was
- *  forked from, and that one wins byte for byte (rule SK017 then repairs its
- *  hub task in place). Returns the paths it wrote. */
-export function editorErgonomics(root: string, opts: ErgonomicsOpts): string[] {
-    // a symlinked .vscode is a dotfiles pattern pointing at a SHARED dir, and
-    // writing through it lands files outside the repo being wired
-    if (isLink(join(root, '.vscode'))) return []
-    const body = tasksTemplate({ NAME: opts.name, PORT: String(opts.port) })
-    return put(root, '.vscode/tasks.json', body) ? ['.vscode/tasks.json'] : []
-}
-
-const isLink = (path: string): boolean => {
-    try {
-        return lstatSync(path).isSymbolicLink()
-    } catch {
-        return false
-    }
-}
-
-/** the tasks template, the hub's problem matcher rendered in from the one
- *  module the hub prints through, so the two can never disagree */
-export function tasksTemplate(vars: Record<string, string>): string {
-    return template('vscode-tasks.json', vars).replace(/^(\s*)(.*)\{\{HUB_PROBLEM_MATCHER\}\}/m, (_all, indent: string, head: string) =>
-        `${indent}${head}${JSON.stringify(hubProblemMatcher(), null, 3).split('\n').join(`\n${indent}`)}`)
-}
-
 export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     const p = opts.print ?? console.log
     // the hub resolves its port from repo.config, whose name `init` takes from
     // the CALLER first and the manifest only after (init-repo.ts repoName). A
-    // dir that arrived holding a forked package.json would otherwise get a
-    // tasks.json advertising a port nothing listens on, so the caller that
+    // dir that arrived holding a forked package.json would otherwise get an
+    // agent index advertising a port nothing listens on, so the caller that
     // knows the name it is about to wire passes the port it resolves
     const port = opts.port ?? defaultHubPort(packageName(root) ?? opts.name)
     const vars = {
@@ -175,15 +121,32 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
 
     write('src/index.ts', 'export {}\n')
     write('tsconfig.json', template('tsconfig.json', vars))
-    ;(editorErgonomics(root, { name: opts.name, port }).length > 0 ? written : skipped).push('.vscode/tasks.json')
-    // settings.json only here: it turns eslint off and hands formatting to an
-    // oxc extension, which is a decision only the repo's creator gets to make
+    write('bunfig.toml', template('bunfig.toml', vars))
+    // settings.json only here: it turns eslint off and keeps tsserver from
+    // formatting, which is a decision only the repo's creator gets to make
     write('.vscode/settings.json', template('vscode-settings.json', vars))
     write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
+    writeHouseFiles(write, vars, opts.claudePolicy === true, written, p)
+
+    addScripts(root, written, p)
+    addIgnoreLines(root, written)
+
+    if (written.length > 0) p(`ok: scaffolded ${written.length} file(s): ${written.slice(0, 6).join(', ')}${written.length > 6 ? `, +${written.length - 6} more` : ''}`)
+    // the skips are the interesting half on a half-built dir: a pre-existing
+    // .claude/settings.json means no attribution silencer, and that one only
+    // counts from the first commit on
+    if (skipped.length > 0) p(`skip: ${skipped.length} file(s) already present, left untouched: ${skipped.join(', ')}`)
+    return written
+}
+
+/** the half of the day-one shape a house brings, whatever the repo already
+ *  is: the agent wiki its CLAUDE.md routes at, the reflections folder, and
+ *  for a caller that declared a house the .claude/ policy files. Create-only */
+function writeHouseFiles(write: (rel: string, body: string) => void, vars: Record<string, string>, claudePolicy: boolean, written: string[], p: (line: string) => void): void {
     // a permission grant and a git-history policy are decisions about someone
     // else's repo, so they land only for a caller that declared a house, and
     // the grant is named out loud the one time it is written
-    if (opts.claudePolicy === true) {
+    if (claudePolicy) {
         write('.claude/settings.json', template('claude-settings.json', vars))
         write('.claude/settings.local.json', template('claude-settings-local.json', vars))
         if (written.includes('.claude/settings.local.json')) p(`ok: .claude/ policy written — agents are pre-approved for ${grantSummary()} in this repo, and the harness writes no attribution trailer`)
@@ -197,15 +160,18 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     // gitignored by policy, so it never ships: it exists so an agent hitting
     // friction with the toolchain finds the place to write it down
     write('.shipkit/reflections/README.md', REFLECTIONS_README)
+}
 
-    addScripts(root, written, p)
-    addIgnoreLines(root, written)
-
-    if (written.length > 0) p(`ok: scaffolded ${written.length} file(s): ${written.slice(0, 6).join(', ')}${written.length > 6 ? `, +${written.length - 6} more` : ''}`)
-    // the skips are the interesting half on a half-built dir: a pre-existing
-    // .claude/settings.json means no attribution silencer, and that one only
-    // counts from the first commit on
-    if (skipped.length > 0) p(`skip: ${skipped.length} file(s) already present, left untouched: ${skipped.join(', ')}`)
+/** an ADOPTED repo (one with history) whose start declares a house: the
+ *  include lines pull it into the house contract, so it gets the house half
+ *  of the day-one shape and nothing that says what the repo IS. Create-only,
+ *  so every file the repo already holds wins. Returns the paths it wrote */
+export function adoptHouse(root: string, opts: { name: string; today?: string; print?: (line: string) => void }): string[] {
+    const p = opts.print ?? console.log
+    const vars = { NAME: opts.name, PORT: String(defaultHubPort(opts.name)), DATE: opts.today ?? new Date().toISOString().slice(0, 10) }
+    const written: string[] = []
+    writeHouseFiles((rel, body) => { if (put(root, rel, body)) written.push(rel) }, vars, true, written, p)
+    if (written.length > 0) p(`ok: adopted into the house, ${written.length} file(s) seeded: ${written.join(', ')}`)
     return written
 }
 
@@ -227,14 +193,14 @@ What broke, which page or lib, what you expected. Gitignored on purpose,
 transient by design: it is harvested, then deleted.
 `
 
-/** the three baseline scripts, added only where the key is free */
+/** the baseline scripts, added only where the key is free */
 function addScripts(root: string, written: string[], p: (line: string) => void): void {
     const path = join(root, 'package.json')
-    if (!existsSync(path)) return void p('WARN no package.json here — the lint/fmt/typecheck scripts were not written')
+    if (!existsSync(path)) return void p('WARN no package.json here — the typecheck script was not written')
     const raw = readFileSync(path, 'utf8')
     let pkg: { scripts?: Record<string, string> }
     try { pkg = JSON.parse(raw) as { scripts?: Record<string, string> } }
-    catch (e) { return void p(`WARN package.json is unparseable (${String(e).slice(0, 80)}) — the lint/fmt/typecheck scripts were not written, repair it then re-run`) }
+    catch (e) { return void p(`WARN package.json is unparseable (${String(e).slice(0, 80)}) — the typecheck script was not written, repair it then re-run`) }
     pkg.scripts ??= {}
     let added = 0
     for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }

package/src/serve/hub-app/check-view.tsx

@@ -13,7 +13,6 @@ import type { RepoSt } from './repo-st.ts'
 import type { SlowSuite, CheckFacts, RecentRun } from './hub-types.ts'
 import { renderMd, renderMdInline } from './md.ts'
 import { nextRun } from './next-run.ts'
-import { ProseHits } from './prose-hits-view.tsx'
 import { stampWords, TimeAgo, TimeAhead } from './time-ago.tsx'
 import { checkName, commandOf, docPath, editorHref, lastRun, rememberedFact, repoPath, whatFacts, type ShortPath } from './check-words.ts'
 
@@ -23,8 +22,9 @@ const SOURCE_CHIP: Record<CheckFacts['whenSource'], string> = {
     off: 'repo.config.ts',
     when: 'when (retired)',
     ruleExempt: 'ruleExempt (retired)',
+    'hooks.disable': 'hooks.disable (retired)',
     'check-file': 'the check file',
-    defaults: 'defaults',
+    defaults: 'defaults (retired)',
     default: 'derived',
 }
 
@@ -33,7 +33,8 @@ const SOURCE_WORD: Record<CheckFacts['whenSource'], string> = {
     when: 'turned off by the retired `when` key, which `shipkit ci` ports to `off` (SK029)',
     ruleExempt: 'turned off by the retired `ruleExempt` key, which `shipkit ci` ports to `off` (SK029)',
     'check-file': 'declared by the check file itself: every context it runs in, no default',
-    defaults: 'from the `defaults` block, which removes the floor slot entirely',
+    'hooks.disable': 'turned off by the retired `hooks.disable` key, which `shipkit ci` ports to `off` (SK029)',
+    defaults: 'turned off by the retired `defaults: { <slot>: false }`, which `shipkit ci` ports to `off` (SK029)',
     default: 'a row with no file of its own: the code that derives it writes every context',
 }
 
@@ -359,7 +360,6 @@ export const CheckCard = observer(({ app, id }: { app: RepoSt; id: string }) =>
             </div>
             <WhereItRuns app={app} u={u} />
             {u.build && u.checkId === 'test' ? <SlowSuites app={app} /> : null}
-            {u.checkId === 'SK014' ? <ProseHits app={app} /> : null}
             <LastOutput app={app} lines={u.lastLines} />
         </div>
     )

package/src/serve/hub-app/check-words.ts

@@ -19,6 +19,7 @@ const CADENCE: Record<WhenAt, string> = {
     always: 'on every run',
     release: 'on every release run',
     health: 'each time the plan runs it',
+    commit: 'on every commit, in a git hook',
     off: 'nowhere, it is off',
 }
 

package/src/serve/hub-app/checks-svc.ts

@@ -100,8 +100,7 @@ export class ChecksSvc {
         }
     }
 
-    /** ONE write path for the switch, the slow suite form and the prose word
-     *  lists alike: it edits repo.config.ts in place and leaves it dirty to be
+    /** ONE write path for the switch and the slow suite form alike: it edits repo.config.ts in place and leaves it dirty to be
      *  reviewed. Resolves true when the server took the edit */
     async writeGate(edit: Record<string, unknown>, said: string): Promise<boolean> {
         if (this.gateBusy) return false

package/src/serve/hub-app/home.html

@@ -6,7 +6,6 @@
   <title>home</title>
   <link rel="stylesheet" href="./hub.css" />
   <link rel="stylesheet" href="./project-list.css" />
-  <link rel="stylesheet" href="./prose-hits.css" />
   <link rel="stylesheet" href="./home-strip.css" />
   <link rel="stylesheet" href="./planned.css" />
   <link rel="stylesheet" href="./when.css" />

package/src/serve/hub-app/hub-types.ts

@@ -145,8 +145,6 @@ export type GateBlock = {
     tests: { budgetMs?: number; slow?: SlowSuite[]; serial?: { file: string; why: string }[] }
     declaredOutside: boolean
     dirty: boolean
-    /** the prose words block inside `prose: {` (core/when-block.ts) */
-    wordsState?: 'missing-file' | 'missing-block' | 'stale' | 'current' | 'no-prose'
 }
 
 /** one check finishing, as the run stream sends it */

package/src/serve/hub-app/index.html

@@ -6,7 +6,6 @@
   <title>hub</title>
   <link rel="stylesheet" href="./hub.css" />
   <link rel="stylesheet" href="./project-list.css" />
-  <link rel="stylesheet" href="./prose-hits.css" />
   <link rel="stylesheet" href="./home-strip.css" />
   <link rel="stylesheet" href="./planned.css" />
   <link rel="stylesheet" href="./when.css" />

package/src/serve/hub-app/project-list.css

@@ -1,5 +1,4 @@
-/* the project list, the page's left panel. Its classes are pj*: another
-   sheet of the page already styles .plist (prose-hits.css). It fills its
+/* the project list, the page's left panel. Its classes are pj*. It fills its
    panel (hub-app.tsx, react-resizable-panels), whose width is the only one:
    this sheet sizes the rows and never the list. Colours are hub.css tokens only, spacing is its scale:
    tests/hub-css-invariants.test.ts reads this sheet too. Every icon is 18px