rvlib-shipkit 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.28.0
+
+- **The `.claude/` policy files are OPT-IN.** 0.27.0 wrote a pre-approved shell allowlist (`curl *`, `git push*`, `./deploy.sh`) and an attribution silencer into every started repo, gitignored and therefore invisible to review. Those are decisions about what an agent can do in a repo and what its git history says, so they now require the caller to declare a house (`claudePolicy`, which `start` enables when it seeds CLAUDE.md include lines), and the grant prints once by name when it lands. The verify skill still lands for everyone.
+- **The scaffolded verify skill points at `shipkit ci`.** It shipped a gate of `bunx tsc && bun test && bun run build`: scripts a started repo does not have, contradicting the coding page written beside it.
+- **The `.gitignore` baseline is appended line by line, by ONE writer.** It was written only when the file was absent, so a dir arriving with any `.gitignore` at all (a downloaded template, one stray line) skipped it: the install then wrote `node_modules/` and the first commit refused over thousands of staged files. A `.env` in a started dir is now ignored rather than blocking the commit outright, so the secret stays out AND the work gets backed up.
+- **A scaffold write error no longer aborts the start.** It is wrapped like every other step, warns, and the chain still commits and pushes.
+- **Smaller repairs**: an unparseable `package.json` warns instead of silently skipping the scripts · files the scaffold SKIPPED are reported, because on a half-built dir the skipped one is the interesting one · delivered templates get their "copy me somewhere" comment blocks stripped, true on the page they twin and nonsense in the repo they land in · the hub port in `tasks.json` derives from the package name, matching what `init` writes into `repo.config.ts`.
+
+## 0.27.0
+
+- **`shipkit start` writes the whole day-one shape, not just a repo.** A started dir was a repo you still had to furnish: no tsconfig, no editor tasks, no agent wiki behind CLAUDE.md's own include, no verify skill, no attribution silencer, and two baseline scripts the rules then warned about. One scaffold pass now writes all of it (`src/scaffold/project-scaffold.ts`), installs the toolchain, and the result passes its OWN `shipkit ci` with nothing left but the identity assets a human has to choose. Every file is CREATE-ONLY, so running it over a half-built dir never destroys work.
+- **The scaffolded tsconfig drops the root `*.ts` glob.** That glob picks up `repo.config.ts`, whose `rvlib-shipkit` import is raw TypeScript, so `tsc --noEmit` walked into the dependency and typechecked the entire library (`skipLibCheck` covers `.d.ts` only). A fresh repo's typecheck failed on someone else's code, which no user can fix. List a root config file by name when one earns checking, the way a vite repo lists `vite.config.ts`.
+- **The baseline `.gitignore` is written before anything else can create one.** The scaffold's own ignore lines landed first, so the `node_modules/` baseline was skipped and the first commit refused on 7700 staged dependency files.
+- **`start` says how to land in the dir it made.** A child process cannot cd its parent shell, so the path goes to stdout for a sourced wrapper and, when none is in play, the last line names the `cd`. `SHIPKIT_CD=1` silences it for a wrapper that does the move.
+
 ## 0.26.0
 
 - **start means START: the full bootstrap runs on any dir with no commit history.** 0.25.0 widened the scaffold to empty dirs and commitless husks, and the very next field run hit the remaining wall: a folder holding one stray readme was still refused. The gate is now commit history alone: no commits means the dir is startable, and loose files simply ride in the first commit as the repo's first backup. What start still refuses is structural: a repo with real history is never scaffolded or pushed over, a subdirectory of another work tree gets nothing, a temp dir never mints a github repo, and the risky-file refusal still blocks a first commit carrying a `.env` or `node_modules` anywhere in the tree.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.26.0",
+    "version": "0.28.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/cli/cmd_Start.ts

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in: ensures the dir, seeds CLAUDE.md include lines, scaffolds a minimal package.json + src/index.ts + the rvlib-shipkit dev dep on any dir with no commit history (loose files ride in the first commit), wires shipkit (repo.config.ts via init), then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Only a repo with real history is left as it is. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .rv-reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. Seeding CLAUDE.md include lines also opts the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer). Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],

package/src/git-bootstrap.ts

@@ -14,7 +14,7 @@
 // identity), it never touches a history that already has commits, and every
 // unverifiable path (no gh, not authenticated, offline) is a WARN that
 // leaves the local repo wired and names the next move.
-import { existsSync, realpathSync } from 'fs'
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { basename, join } from 'path'
 import { spawnWithTimeout } from './core/spawn-timeout.ts'
@@ -261,13 +261,15 @@ async function firstCommit(root: string, git: Run, p: (line: string) => void): P
         p('skip: first commit — nothing in this dir yet')
         return false
     }
-    // a repo with no .gitignore at all gets the baseline: the very first
-    // commit is the one nobody reviews, and it is the one that ships a .env
-    // to github. A repo that HAS one keeps its own answer, whatever it says.
-    // rule SK004 stays the only writer of its managed block, with the repo's
-    // real config: rewriting it from a synthetic one here DELETED the lines
-    // repo.config.ts contributed, seconds before staging what they covered
-    if (!existsSync(join(root, '.gitignore'))) await Bun.write(join(root, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+    // the baseline lands before the very first commit, the one nobody
+    // reviews and the one that ships a .env to github. Every MISSING line is
+    // appended, because a repo that arrived with a one-line .gitignore is
+    // exactly as exposed as one with none. Repo-owned lines are never
+    // touched, and rule SK004 stays the only writer of its managed block,
+    // with the repo's real config: rewriting it from a synthetic one here
+    // DELETED the lines repo.config.ts contributed, seconds before staging
+    // what they covered
+    ensureIgnoreBaseline(root)
     const status = await git(['status', '--porcelain', '-uall'])
     if (status.code !== 0) {
         p(`WARN no first commit: ${firstGhLine(status.out)}`)
@@ -300,6 +302,19 @@ async function firstCommit(root: string, git: Run, p: (line: string) => void): P
     return true
 }
 
+/** append whichever baseline lines this repo's .gitignore does not already
+ *  carry. ONE writer of this fact, called by the first commit and by the
+ *  start scaffold (which runs before the dep install, so node_modules can
+ *  never reach the staging area) */
+export function ensureIgnoreBaseline(root: string): void {
+    const path = join(root, '.gitignore')
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const have = new Set(cur.split('\n').map((l) => l.trim()))
+    const missing = IGNORE_BASELINE.filter((l) => !have.has(l))
+    if (missing.length === 0) return
+    writeFileSync(path, `${cur}${cur === '' || cur.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`)
+}
+
 /** never in a first commit, wherever it sits in the tree. `.env.example` and
  *  friends are documentation and belong in the repo */
 function isRisky(f: string): boolean {

package/src/scaffold/files/agent-changelog.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Newest first. Each entry narrates WHAT changed and WHY, for the next
+session that arrives with no context.
+
+## {{DATE}}
+
+- Repo scaffolded: package.json, tsconfig, vscode tasks, agent/ wiki,
+  shipkit wiring, first commit.

package/src/scaffold/files/agent-coding.md

@@ -0,0 +1,35 @@
+# Coding standards — {{NAME}}
+
+The always-loaded page. Keep it to hard gates plus a screen of standards.
+Once it grows past that, split the gates into `process.md`, make that the
+always-loaded one, and route the rest by surface.
+
+## Gates
+
+- **Spec-first**: the `agent/` page changes BEFORE the code it describes.
+- **`shipkit ci` is the verification.** Run it, not the linter, the
+  typechecker and the tests one at a time.
+- **Repro before fix**: write the failing test, then fix, then re-run it.
+- One code path per concern. Delete the redundant mechanism rather than
+  keeping two.
+
+## TypeScript
+
+- `strict`, `noUncheckedIndexedAccess`, `noUnusedLocals`,
+  `noUnusedParameters`, `noFallthroughCasesInSwitch`: all on, always.
+- No `as any`, no `@ts-ignore`. A cast that survives review is listed here
+  with the reason it is safe.
+- Imports are absolute (`src/...`), never `../..` chains.
+
+## Comments
+
+- The default is NO comment. Write one only for what the code cannot say:
+  a constraint, an invariant, a performance reason, a workaround.
+- Never narrate the edit, the date, or who asked for it. That is what git
+  and the changelog are for.
+- Lowercase, no dash punctuation, matching the density of the file.
+
+## Layout
+
+- A file past ~600 lines is a smell; carve it at ~800.
+- Anti-patterns: <fill as the project teaches them>.

package/src/scaffold/files/agent-index.md

@@ -0,0 +1,25 @@
+# {{NAME}}
+
+<One paragraph: what this project is, who it is for, and the stack.>
+
+## Quick start
+
+- `bun run hub` → the repo toolbox at http://localhost:{{PORT}}
+- `shipkit ci` → THE gate: run it to check your work, never the parts
+
+This folder is the project's internal wiki and its SPEC. Update the page
+BEFORE the change it describes.
+
+**Always loaded every session:**
+
+@coding.md
+
+Read the matching page before touching a surface:
+
+| read when touching… | page |
+|---|---|
+| any source file | `agent/coding.md` |
+| recent changes and why | `agent/changelog.md` |
+
+Grow this table: a subsystem, a service, a runbook each earn their own page,
+cross-linked from here.

package/src/scaffold/files/claude-settings-local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(shipkit *)",
+      "Bash(bun run *)",
+      "Bash(bun test*)",
+      "Bash(bun install*)",
+      "Bash(bun add *)",
+      "Bash(bunx tsc*)",
+      "Bash(bunx wrangler*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add *)",
+      "Bash(git commit*)",
+      "Bash(git push*)",
+      "Bash(curl *)",
+      "Bash(oxlint*)",
+      "Bash(./deploy.sh)"
+    ],
+    "deny": []
+  }
+}

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

@@ -0,0 +1,6 @@
+{
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  }
+}

package/src/scaffold/files/tsconfig.json

@@ -0,0 +1,48 @@
+{
+   // ONE tsconfig at the repo root — copy as-is (replaces whatever
+   // `bun init` generated), adjust include/paths to the repo's dirs.
+   "compilerOptions": {
+      // real node resolution, no bundler hand-waving — what tsc resolves is
+      // what bun resolves at runtime (bun follows tsconfig paths)
+      "module": "nodenext",
+      "moduleResolution": "nodenext",
+
+      // the pair that legalizes `from 'src/foo/Bar.ts'` — extensions are part
+      // of the exact-path search key; tsc only typechecks, bun/vite emit
+      "allowImportingTsExtensions": true,
+      "noEmit": true,
+
+      // THE mapping that makes 'src/...' specifiers resolve. No baseUrl —
+      // explicit paths only, so bare specifiers can't collide with packages.
+      // paths doubles as an escape hatch for deps with broken "exports"
+      // (map the submodule) — but bun follows these at RUNTIME too, so
+      // runtime-loaded packages need "exports" patches instead, or bun
+      // resolves a .d.ts where it needs a .js.
+      "paths": {
+         "src/*": ["./src/*"],
+         "scripts/*": ["./scripts/*"]
+      },
+
+      // every file is a module even with no import/export (standalone scripts)
+      "moduleDetection": "force",
+
+      // the house TS standard is all five, always on (meta/rv-conventions):
+      // strict alone leaves dead locals and fallthrough bugs in the codebase
+      "strict": true,
+      "noUncheckedIndexedAccess": true,
+      "noUnusedLocals": true,
+      "noUnusedParameters": true,
+      "noFallthroughCasesInSwitch": true,
+      "isolatedModules": true,
+      "skipLibCheck": true,
+      "incremental": true,
+      "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+   },
+   // NO root `*.ts` glob: it picks up a config file like repo.config.ts,
+   // and a dependency imported from there whose package points at raw .ts
+   // (rvlib-shipkit does) gets walked and typechecked in full, since
+   // skipLibCheck covers .d.ts only. The repo then fails on code its owner
+   // cannot edit. List a root file BY NAME when it earns checking, the way
+   // a vite repo lists vite.config.ts
+   "include": ["src", "scripts"]
+}

package/src/scaffold/files/verify-skill.md

@@ -0,0 +1,32 @@
+---
+name: verify
+description: Prove a change in THIS project actually works — drive the real flow end to end, never trust green checks or self-reports. Use before committing any nontrivial change.
+---
+
+# verify — how to PROVE a change works here
+
+<!-- Template: copy to .claude/skills/verify/SKILL.md at project start, fill the
+     placeholders, then GROW it — every gotcha discovered in this repo gets
+     encoded here the same day. -->
+
+## The rules (house-wide)
+- Failing repro test BEFORE the fix. Green checks ≠ verification.
+- Logic → fast headless `bun test` (tiny ~10-line test files reusing fixtures).
+- Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
+- Verify as the end user would: drive the real flow, observe the real signal.
+
+## This project
+- Full gate: `shipkit ci` — THE command, never the linter, the typechecker
+  and the tests one at a time.
+- TODO, fill these in once the stack exists: the dev server command and its
+  port (check it is not already running: `curl -s localhost:PORT >/dev/null
+  && echo up`), and the live URL after deploy (curl 200 + drive the flow).
+
+## Browser verification (only when a browser is truly needed)
+Playwright with explicit `executablePath`, `deviceScaleFactor: 2`, localStorage
+reset between runs, `page.evaluate` probes for state, collect `pageerror`
+("none" is evidence). Screenshots are for LOOKS, never for "does it fit".
+
+## Gotchas discovered in this repo
+<!-- append as found — this list is the reason this file exists -->
+- (none yet)

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

@@ -0,0 +1,40 @@
+// merge into .vscode/settings.json — the convention only sticks if the editor
+// produces it by default. Load-bearing keys for the absolute-import style.
+// NOTE: `js/ts.*` is the unified prefix (recent VSCode); on older builds
+// expand each to its `typescript.*` + `javascript.*` twins
+// (e.g. typescript.preferences.importModuleSpecifier, typescript.tsdk).
+{
+   // THE key pair: auto-import inserts 'src/...' absolute specifiers, never
+   // './relative'. Modern tsserver respects this reliably.
+   // the ONE key that makes auto-import write `src/foo/Bar.ts`, not
+   // `../foo/Bar`. It is the only real id in that family (`…Ending` aside);
+   // vscode ignores unknown keys in silence, so an invented name looks like
+   // it works
+   "js/ts.preferences.importModuleSpecifier": "non-relative",
+
+   // use the workspace typescript (native ts7 compiler), not vscode's bundled one
+   "js/ts.tsdk.path": "node_modules/typescript/lib",
+
+   // auto-imports emit `import type` — saves don't fight the lint's
+   // consistent-type-imports rule
+   "js/ts.preferences.preferTypeOnlyAutoImports": true,
+
+   // kill junk suggestions: only tsserver speaks, no word-soup completions
+   "editor.suggest.showWords": false,
+   "editor.wordBasedSuggestions": "off",
+   "js/ts.preferences.includePackageJsonAutoImports": "off",
+
+   // rename the real symbol, not an import alias; rename both jsx tags
+   "js/ts.preferences.useAliasesForRenames": false,
+   "js/ts.preferences.renameMatchingJsxTags": true,
+
+   // big-repo hygiene: more tsserver memory, no npm probing, no auto type acquisition
+   "js/ts.tsserver.maxMemory": 6144,
+   "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.enable": false,
+   "js/ts.format.enabled": false
+}

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

@@ -0,0 +1,45 @@
+{
+   // one master task with runOn folderOpen, every dev process as a subtask.
+   // Opening the folder in vscode starts them all. Add a subtask per
+   // long-running watcher the stack earns (dev server, css, tests), never
+   // for a one-off script.
+   "version": "2.0.0",
+   "tasks": [
+      {
+         "label": "starts everything",
+         "dependsOn": ["👁  TSC", "🚀  shipkit"],
+         "group": { "kind": "build", "isDefault": true },
+         "runOptions": { "runOn": "folderOpen", "instanceLimit": 1 },
+         "problemMatcher": []
+      },
+      {
+         "label": "👁  TSC",
+         "detail": "Get all typescript errors in problems pane",
+         "type": "process",
+         "command": "${workspaceFolder}/node_modules/.bin/tsc",
+         "args": ["--noEmit", "--incremental", "--watch", "--project", "tsconfig.json"],
+         "options": {
+            "cwd": "${workspaceFolder}",
+            "env": { "NODE_OPTIONS": "--max-old-space-size=8192" }
+         },
+         "isBackground": true,
+         "presentation": { "reveal": "never", "clear": true },
+         "group": "build",
+         "runOptions": { "instanceLimit": 1 },
+         "problemMatcher": []
+      },
+      {
+         "label": "🚀  shipkit",
+         "detail": "The shipkit hub at http://localhost:{{PORT}} — clickable URLs: the page, /graph/wiki, /graph/agent",
+         "type": "process",
+         "command": "bun",
+         "args": ["run", "hub"],
+         "options": { "cwd": "${workspaceFolder}" },
+         "isBackground": true,
+         "presentation": { "reveal": "always", "close": false },
+         "group": "build",
+         "runOptions": { "instanceLimit": 1 },
+         "problemMatcher": []
+      }
+   ]
+}

package/src/scaffold/project-scaffold.ts

@@ -0,0 +1,202 @@
+// the day-one shape of a repo, written by `shipkit start` for a dir with no
+// commit history. The bar: opening the folder in vscode starts the watchers,
+// an agent lands on a wiki that routes it, and `shipkit ci` is green with no
+// warning a machine could have cleared.
+//
+// Writes are CREATE-ONLY for files (a path that exists is left exactly as it
+// is) and ADDITIVE for package.json scripts and .gitignore (a free key or a
+// missing line is filled, an existing one is never touched), so the scaffold
+// can run over a half-built dir without ever destroying work. Note that the
+// 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, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { defaultHubPort } from '../serve/run-serve.ts'
+
+const FILES = join(import.meta.dir, 'files')
+
+export type ScaffoldOpts = {
+    /** repo name, substituted into the templates */
+    name: string
+    /** report sink */
+    print?: (line: string) => void
+    /** the changelog's first dated entry — injected so callers stay testable */
+    today?: string
+    /** write the .claude/ POLICY files: a pre-approved permission list and an
+     *  attribution silencer. Both are decisions about what agents may do in
+     *  someone's repo and what its git history says, so they are opt-in: only
+     *  a caller that declares a house (start seeds include lines) turns them
+     *  on, and the grant is printed the one time it lands */
+    claudePolicy?: boolean
+}
+
+/** every dep the house toolchain needs for the scripts below to run */
+export const TOOLCHAIN = ['typescript', 'oxlint', 'oxfmt', '@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 */
+const SCRIPTS: Record<string, string> = {
+    lint: 'oxlint src/',
+    fmt: 'oxfmt src/',
+    typecheck: 'tsc --noEmit',
+}
+
+/** repo-owned ignore lines, written OUTSIDE rule SK004's managed block so its
+ *  fixer never rewrites them */
+const IGNORE_EXTRA = ['backups/', '.claude/settings.local.json']
+
+/** a line telling a READER to copy this file somewhere. True in the wiki page
+ *  the template is a twin of, nonsense in the repo it just landed in */
+const COPY_INSTRUCTION = /copy (?:as-is|to|this)|merge into|^\s*<!-- Template:/i
+
+const template = (file: string, vars: Record<string, string>): string => {
+    let out = readFileSync(join(FILES, file), 'utf8')
+    for (const [k, v] of Object.entries(vars)) out = out.replaceAll(`{{${k}}}`, v)
+    return stripCopyInstructions(out)
+}
+
+/** drop whole COMMENT BLOCKS that address a copier, never a structural line:
+ *  a template's own "copy me somewhere" line is true on the wiki page it
+ *  twins and nonsense in the repo it just landed in. Comments explaining the
+ *  CONTENT are the point of these files and stay */
+export function stripCopyInstructions(body: string): string {
+    const lines = body.split('\n')
+    const drop = new Set<number>()
+    const blockSpeaksToACopier = (from: number, to: number): boolean => COPY_INSTRUCTION.test(lines.slice(from, to + 1).join('\n'))
+    for (let i = 0; i < lines.length; i++) {
+        if (drop.has(i)) continue
+        const line = lines[i]!
+        // an html comment block, possibly spanning lines
+        if (/^\s*<!--/.test(line)) {
+            let end = i
+            while (end < lines.length && !/-->/.test(lines[end]!)) end++
+            if (end < lines.length && blockSpeaksToACopier(i, end)) for (let k = i; k <= end; k++) drop.add(k)
+            i = end
+            continue
+        }
+        // a run of consecutive // lines is one block
+        if (/^\s*\/\//.test(line)) {
+            let end = i
+            while (end + 1 < lines.length && /^\s*\/\//.test(lines[end + 1]!)) end++
+            if (blockSpeaksToACopier(i, end)) for (let k = i; k <= end; k++) drop.add(k)
+            i = end
+        }
+    }
+    if (drop.size === 0) return body
+    const kept = lines.filter((_, i) => !drop.has(i))
+    while (kept.length > 0 && kept[0]!.trim() === '') kept.shift()
+    return kept.join('\n')
+}
+
+/** write only when the path is free. Returns whether it wrote */
+function put(root: string, rel: string, body: string): boolean {
+    const path = join(root, rel)
+    if (existsSync(path)) return false
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, body)
+    return true
+}
+
+export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
+    const p = opts.print ?? console.log
+    // the hub resolves its port from the CONFIG name, which init takes from
+    // package.json — a dir whose folder name differs would otherwise get a
+    // tasks.json advertising a port nothing listens on
+    const configName = packageName(root) ?? opts.name
+    const vars = {
+        NAME: opts.name,
+        PORT: String(defaultHubPort(configName)),
+        DATE: opts.today ?? new Date().toISOString().slice(0, 10),
+    }
+    const written: string[] = []
+    const skipped: string[] = []
+    const write = (rel: string, body: string): void => { (put(root, rel, body) ? written : skipped).push(rel) }
+
+    write('src/index.ts', 'export {}\n')
+    write('tsconfig.json', template('tsconfig.json', vars))
+    write('.vscode/settings.json', template('vscode-settings.json', vars))
+    write('.vscode/tasks.json', template('vscode-tasks.json', vars))
+    write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
+    // 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) {
+        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`)
+    }
+    // the project's own docs wiki. A repo whose CLAUDE.md routes at
+    // agent/index.md (rule SK003) needs the file to exist, and a repo with no
+    // CLAUDE.md at all still gets a place for its docs to live
+    write('agent/index.md', template('agent-index.md', vars))
+    write('agent/coding.md', template('agent-coding.md', vars))
+    write('agent/changelog.md', template('agent-changelog.md', vars))
+    // 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('.rv-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(', ')}`)
+    return written
+}
+
+/** what the pre-approved permission list actually allows, in one phrase */
+function grantSummary(): string {
+    try {
+        const s = JSON.parse(readFileSync(join(FILES, 'claude-settings-local.json'), 'utf8')) as { permissions?: { allow?: string[] } }
+        const allow = s.permissions?.allow ?? []
+        return `${allow.length} shell patterns incl. ${allow.filter((a) => /curl|push|deploy/.test(a)).join(', ') || 'none network-facing'}`
+    } catch {
+        return 'a shell allowlist'
+    }
+}
+
+const REFLECTIONS_README = `# .rv-reflections
+
+One file per friction with the shared toolchain: \`YYYYMMDD-<slug>.md\`.
+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 */
+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')
+    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`) }
+    pkg.scripts ??= {}
+    let added = 0
+    for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+    if (added === 0) return
+    const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
+    writeFileSync(path, JSON.stringify(pkg, null, indent) + '\n')
+    written.push(`package.json (${added} script(s))`)
+}
+
+function packageName(root: string): string | null {
+    try {
+        return (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string }).name ?? null
+    } catch {
+        return null
+    }
+}
+
+function addIgnoreLines(root: string, written: string[]): void {
+    const path = join(root, '.gitignore')
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const have = new Set(cur.split('\n').map((l) => l.trim()))
+    const missing = IGNORE_EXTRA.filter((l) => !have.has(l))
+    if (missing.length === 0) return
+    writeFileSync(path, `${cur}${cur === '' || cur.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`)
+    written.push('.gitignore')
+}

package/src/start-repo.ts

@@ -7,8 +7,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { ensureGitRepo, firstGhLine, IGNORE_BASELINE, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
+import { ensureGitRepo, ensureIgnoreBaseline, firstGhLine, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
+import { scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
 
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
@@ -94,33 +95,44 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         // and the risky-file commit refusal downstream still guards .env and
         // node_modules
         const startable = wired && (await runner('git', dir, 120_000)(['rev-parse', '--verify', 'HEAD'])).code !== 0
-        if (startable && !existsSync(join(dir, 'package.json')) && !existsSync(join(dir, 'repo.config.ts'))) {
-            const pkg = { name, version: '0.0.0', private: true, type: 'module', scripts: {} }
-            writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
-            // the first source file, so the ci gate is green from commit one:
-            // an imports gate over zero files fails loud on purpose
-            mkdirSync(join(dir, 'src'), { recursive: true })
-            writeFileSync(join(dir, 'src', 'index.ts'), 'export {}\n')
-            console.error('ok: package.json + src/index.ts scaffolded (private, type module)')
-            // the install below creates node_modules/ BEFORE the first
-            // commit, so the baseline ignore must exist first (SK004's block,
-            // written by init, does not carry node_modules)
-            if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
-            // the scripts init wires call node_modules/rvlib-shipkit — a
-            // scaffold whose scripts exit 127 is not a started repo. Skips
-            // mirror the github half's guards: an injected runner wins, the
-            // env switch turns it off machine-wide, a temp dir is a rehearsal
-            // that must not pull the network. init owns the fix line for
-            // every not-installed outcome
+        if (startable && !existsSync(join(dir, 'repo.config.ts'))) {
+            if (!existsSync(join(dir, 'package.json'))) {
+                const pkg = { name, version: '0.0.0', private: true, type: 'module', scripts: {} }
+                writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
+                console.error('ok: package.json created (private, type module)')
+            }
+            // the baseline ignore goes FIRST, before anything else creates a
+            // .gitignore, and every MISSING line is appended rather than the
+            // file being written only when absent: the install below writes
+            // node_modules/, neither SK004's block nor the scaffold's own
+            // lines carry it, and a dir that arrived with any .gitignore at
+            // all (a downloaded template, one stray line) otherwise skipped
+            // the baseline and refused the first commit over 7000 dep files
+            ensureIgnoreBaseline(dir)
+            // the day-one shape: tsconfig, vscode tasks, the agent wiki, the
+            // verify skill. Create-only, so a dir that already holds any of
+            // them keeps its own. The .claude/ policy files ride on the
+            // include lines: a caller that declares a house gets the house
+            // defaults, a bare `shipkit start` never has its agent
+            // permissions widened by a scaffold
+            try { scaffoldProject(dir, { name, print, claudePolicy: (opts.include ?? []).length > 0 }) }
+            catch (e) { console.error(`WARN scaffold incomplete in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+            // the wired scripts call node_modules binaries, so a scaffold
+            // whose scripts exit 127 is not a started repo. Skips mirror the
+            // github half's guards: an injected runner wins, the env switch
+            // turns it off machine-wide, a temp dir is a rehearsal that must
+            // not pull the network. init owns the fix line for every
+            // not-installed outcome
             let bun: Run | null
             if (opts.bun !== undefined) bun = opts.bun
-            else if ((process.env.SHIPKIT_NO_INSTALL ?? '') !== '') { console.error('skip: rvlib-shipkit install — SHIPKIT_NO_INSTALL is set'); bun = null }
-            else if (isScratch(dir)) { console.error(`skip: rvlib-shipkit install — ${dir} is a temp dir`); bun = null }
-            else bun = Bun.which('bun') == null ? null : runner('bun', dir, 180_000)
+            else if ((process.env.SHIPKIT_NO_INSTALL ?? '') !== '') { console.error('skip: dependency install — SHIPKIT_NO_INSTALL is set'); bun = null }
+            else if (isScratch(dir)) { console.error(`skip: dependency install — ${dir} is a temp dir`); bun = null }
+            else bun = Bun.which('bun') == null ? null : runner('bun', dir, 300_000)
             if (bun != null) {
-                const r = await bun(['add', '-d', 'rvlib-shipkit'])
-                if (r.code === 0) console.error('ok: rvlib-shipkit installed (dev dep)')
-                else console.error(`WARN rvlib-shipkit install failed: ${firstGhLine(r.out)}`)
+                const deps = ['rvlib-shipkit', ...TOOLCHAIN]
+                const r = await bun(['add', '-d', ...deps])
+                if (r.code === 0) console.error(`ok: installed ${deps.join(', ')}`)
+                else console.error(`WARN dependency install failed: ${firstGhLine(r.out)}`)
             }
         }
         let unscaffolded = false
@@ -137,6 +149,11 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         // last line, so what to do next is the last thing read
         if (unscaffolded) console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
     }
+    // a child process cannot cd its parent shell, so the dir goes to stdout
+    // and a sourced wrapper does the move. Without one, say the move out
+    // loud: a verb that lands you nowhere reads as a verb that did nothing.
+    // A wrapper sets SHIPKIT_CD to silence this
+    if ((process.env.SHIPKIT_CD ?? '') === '') console.error(`next: cd ${dir}   (a sourced shell function running \`cd "$(shipkit start <name>)"\` does this for you)`)
     console.log(dir)
     return 0
 }