rvlib-shipkit 0.35.6 → 0.35.8

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.35.8
+
+- **`release.requireHealthy` had become a no-op for exactly the checks it exists for.** `runCi` hardcoded `gateOnly: true` on its checks call, and `requireHealthy` is implemented one layer up as `onlyBlockingChecks: false` plus `failOnAdvisory: true`. The gate filter runs before severity is considered, so a repo that asked for a missing publish credential to stop its release had that request silently dropped the moment its cred check declared `gate = false`. Reproduced through `runCi` with the exact option shape the release path builds, against a check exiting 1 with a FAIL line: the line never appeared and the gate returned 0. `gateOnly` now yields to `failOnAdvisory`, so `requireHealthy` re-arms every opted-out check. Two tests, one per option shape.
+- **`--only <check>` ran the check and then exited 1 saying it did not exist.** `selectTasks` validates the flag against the TASK list alone, so naming a discovered check or a rule ran it and still printed `unknown task id`. The flag addresses three surfaces, so the task runner is now handed the ids owned by the other two (rule ids, rule titles, check names, check paths). This is what makes the opt-out safe to use: a check taken off the gate stays reachable by name.
+- The `run-check.ts` comment on the release-survey share path no longer describes a pre-warm `runCi` deleted, and says who the single owner is.
+
+## 0.35.7
+
+- **`shipkit ci` no longer pre-warms a release survey nothing in the gate reads.** `runCi` started `collectReports` next to the tasks and awaited it before the checks, to hide ~3s of npm registry and `gh` network behind the task DAG. Its only consumer was ever the lib-drift probe, which asks what is PUBLISHED and therefore belongs to `shipkit releases` and the bump gate rather than to a gate that asks whether this change is good. Measured on a repo whose drift checks had left the gate: warm no-op 4.3s with the pre-warm, 1.2s without. Deleted rather than made conditional, because nothing is left to condition it on and a second mechanism guessing which check wants a survey is exactly the source-sniffing this scanner already retired. `collectChecks` creates, shares and cleans up the share path when it was not handed one, so the checks that DO want a survey still pay for exactly one between them, and `shipkit check` is unchanged. Honest cost: a repo that keeps a lib-drift check inside its gate loses the overlap and is up to 3s slower there.
+- **`export const gate = false` was parsed, filtered on, and never honoured** (the fix itself shipped in 0.35.6, which carried no note for it). The CLI declares `--only` as `Option.Array('--only', [])`, so a plain `shipkit ci` hands the check filter an EMPTY ARRAY and never `undefined`. The guard tested `only == null`, which is false for `[]`, so every gate run read as a narrowed one and no check ever opted out: a repo could declare fifteen world probes off-gate and watch all fifteen run anyway. `matchesOnly`, two hundred lines up in the same file, already used the right predicate, and the `only` field's own doc comment already said "Empty or absent means everything". Both readers of the CHECK filter now call one exported `isNarrowed`. `--only` also names rules and discovered checks, so the task runner is handed those ids too rather than answering `unknown task id` for a check it was never asked to run. Pinned by three tests that call `collectChecks` the way the CLI calls it: the gate skips a `gate = false` check, `shipkit check` still runs it, and naming it in `--only` still reaches it.
+- **The adopt path writes `.vscode/tasks.json` alone, and derives what goes in it.** 0.35.6 wrote `settings.json` too, which turns eslint off and hands formatting to an oxc extension: landing that in a repo that lints with eslint silences the linter that repo chose, and that is an answer only its own author gets to give. It also wrote a canned `👁  TSC` watcher pointed at `tsconfig.json`. Against a solution config (`files: []` plus `references`) that watcher needs `--build`, type checks ZERO files without it, and reports a clean problems pane forever, which is worse than no task at all. The TSC subtask is now written only when the root tsconfig resolves inputs, `build/vscode-tasks.md` stays the owner of the per-project analysis for every other watcher, and `init` names that page in its output rather than implying the file is finished.
+- **A symlinked `.vscode/` is left alone.** It is a dotfiles pattern pointing at a SHARED directory, and writing through it landed files outside the repo being wired.
+- **A `repo.config.ts` with no `name` no longer kills `init` with an opaque `TypeError`.** The config loader validates nothing and hands back the raw default export, and the port arithmetic iterates the name it is given. That resolution now sits inside the same guard as the write, falls back to the directory name, and a failure there costs one WARN after everything else has already landed.
+- **`shipkit start` advertises the port the hub will actually listen on.** The scaffold derived it from `package.json` while `init` names the config from the CALLER first, so a dir found holding a forked manifest got a tasks file pointing at a port nothing answers on. The caller now passes the port it resolved.
+
 ## 0.35.6
 
 - **`shipkit init` furnishes an adopted repo with the folder-open half of the scaffold.** The day-one shape was written only for a dir with no commit history, so every repo wired AFTER it already existed got `repo.config.ts` and the scripts and no `.vscode/` at all: opening the folder started no watcher, and the hub the config advertises had no way in. `init` now writes `.vscode/settings.json` and `.vscode/tasks.json` on both its paths, the wiring run and the re-run, through the same writers and the same templates the start scaffold uses. The split it holds: a file that changes no output of any command lands on adopt, and anything saying what the repo IS (`tsconfig.json`, `src/index.ts`) or what an agent may DO in it (the verify skill, the `.claude/` policy files, the `agent/` wiki, the `.rv-reflections/` seed) still needs an explicit caller, because a repo with a history of its own already answered those. Create only, so a `.vscode/` a repo was forked with survives byte for byte, and a second run writes nothing and says so. The advertised port is resolved from `repo.config.ts` (`serve.port`, else derived from the config name), which is where the hub reads it, rather than from the folder name or a stale `package.json`. A `.vscode` path that cannot hold the two files (a read only tree, a path that is a file) costs one WARN naming the errno: this write runs after `repo.config.ts` is on disk and before the publish chain, and it is the least important thing the verb does, so it never kills the run.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.35.6",
+    "version": "0.35.8",
     "funding": "https://github.com/sponsors/rvion",
     "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",

package/src/core/run-check.ts

@@ -78,15 +78,25 @@ export type CheckOpts = {
  *  one they last saw on the wire. */
 export function matchesOnly(only: string[] | undefined, ...names: string[]): boolean {
     if (!isNarrowed(only)) return true
-    return only!.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
+    return only.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
 }
 
 /** did the operator narrow this run? The ONE reading of `--only` everywhere: an
  *  empty list is not a selection, it is the absence of one. */
-export function isNarrowed(only: string[] | undefined): boolean {
+export function isNarrowed(only: string[] | undefined): only is string[] {
     return only != null && only.length > 0
 }
 
+/** every id `--only` can name that is NOT a task: rule ids, rule titles,
+ *  discovered check names and their repo-relative paths. `--only` addresses all
+ *  three surfaces, so the task runner has to be told which ids belong to the
+ *  other two, or it answers `unknown task id` for a check that does run. */
+export function checkSideIds(root: string, c: RepoConfig): string[] {
+    const ids = [...RULES, ...(c.rules ?? [])].flatMap((r) => [r.id, r.title])
+    for (const d of discoverChecks(root)) ids.push(d.name, relative(root, d.path))
+    return ids
+}
+
 export type CheckRun = {
     /** wire lines, with non-blocking failures already downgraded to warnings */
     lines: Line[]
@@ -194,12 +204,13 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
-    // ONE release survey for the whole run: five discovered checks call
-    // collectReports, each in its own subprocess, and the survey is ~4s of
+    // ONE release survey for the whole run: several discovered checks call
+    // collectReports, each in its own subprocess, and the survey is ~3s of
     // network. The path is per RUN and never reused across runs, so nothing
     // here can serve a stale answer to a later gate (releases-share.ts).
-    // a caller that already opened one (runCi, which starts the survey next to
-    // the tasks) owns it, cleanup included; otherwise this run owns its own
+    // This is the ONLY owner: nothing else in shipkit sets the variable, and an
+    // inherited one can only come from a caller outside the binary, which then
+    // owns its own cleanup.
     const inherited = process.env[SHARE_ENV]
     const sharePath = inherited != null && inherited !== '' ? inherited : join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
     const childEnv: Record<string, string | undefined> = {

package/src/core/run-ci.ts

@@ -8,15 +8,11 @@
 import { join } from 'path'
 import { allTasks, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
-import { collectChecks } from './run-check.ts'
+import { checkSideIds, collectChecks } from './run-check.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
-import { rmSync } from 'fs'
-
-import { SHARE_ENV } from '../release/releases-share.ts'
-import { collectReports } from '../release/run-releases.ts'
 import { withContractsScope } from '../contracts/contracts-once.ts'
 import { envTier, FULL_TESTS_ENV, gateUnits, type TestTier } from '../ledger/gate-units.ts'
 import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
@@ -178,23 +174,15 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         if ((o.onlyIds ?? []).includes(u.id))
             sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
     }
-    // the release survey is ~4s of network that five discovered checks need
-    // and the TASKS do not. Started HERE it overlaps lint/typecheck/test and
-    // costs the run nothing; started inside the first check that wants it, it
-    // is 4s nobody can overlap. Failures are the checks' to report, not this
-    // line's: a survey nobody can run just means the checks do it themselves.
-    const sharePath = join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
-    const priorShare = process.env[SHARE_ENV]
-    process.env[SHARE_ENV] = sharePath
-    // a NARROWED run pre-warms nothing: `--only cycles` asks one question, and
-    // paying a 4s network survey to answer it is the same bug --only was
-    // fixed for
-    const willRunChecks = o.skipChecks !== true && (o.onlyIds ?? []).length === 0
     // REPLAY, before the DAG sees the list. A replayed task is removed from
     // the run entirely, which is also what makes its dependents correct: the
     // runner treats a filtered dep as satisfied, and only a GREEN is ever
     // stored, so a dependent can never start on the back of a red nobody saw.
-    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [] }).selected.map((t) => t.id))
+    // --only addresses tasks, rules and checks alike, so the task runner is
+    // told which ids belong to the other two surfaces rather than answering
+    // `unknown task id` for a check it was never asked to run
+    const otherIds = checkSideIds(root, c)
+    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [], otherIds }).selected.map((t) => t.id))
     const replayedTasks = new Map<string, UnitOutcome>()
     const toRun = tasks
         .filter((t) => {
@@ -212,11 +200,6 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         // this is the same "a filtered dep counts as satisfied" the runner
         // already applies to --skip and opt-in tasks.
         .map((t) => (t.deps?.some((d) => replayedTasks.has(d)) === true ? { ...t, deps: t.deps.filter((d) => !replayedTasks.has(d)) } : t))
-    // the pre-warm exists to hide the survey behind the TASKS. When every task
-    // replayed there is nothing to hide it behind, and starting it anyway is a
-    // 4s network call the run may never need: the five checks that want it
-    // fetch it themselves, and when they replay too, nobody pays for it at all.
-    const survey = willRunChecks && toRun.length > 0 ? collectReports(root, c).catch(() => null) : null
     // a NAMED task that replayed leaves the list, so its name has to leave the
     // filters with it: the runner validates `--only`/`--with` against the list
     // it was handed and answers `unknown task id`. `bun run typecheck` and
@@ -240,6 +223,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         skipGroups: o.skipGroups ?? [],
         withIds,
         onlyIds,
+        otherIds,
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
@@ -268,12 +252,18 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // a narrowed run says what it did NOT look at: a green that only ever
     // asked one question must not read like the full gate
     if ((o.onlyIds ?? []).length > 0 && o.skipChecks !== true) sink(`skip: checks not named by --only (${(o.onlyIds ?? []).join(', ')})`)
-    if (survey != null) await survey
+    // no release survey is pre-warmed here. It is ~3s of registry and `gh`
+    // network, and the only thing that ever read it is the lib-drift probe,
+    // which asks what is PUBLISHED and so has no business in a gate that asks
+    // whether this change is good. collectChecks owns the share path, so the
+    // checks that do want it still pay for exactly one survey between them.
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false, gateOnly: true })
-    if (priorShare == null) delete process.env[SHARE_ENV]; else process.env[SHARE_ENV] = priorShare
-    for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
+        // `gate = false` opts a check out of the EVERYDAY gate. failOnAdvisory
+        // is release.requireHealthy, a repo saying it wants a missing cred to
+        // stop its publish, so it re-arms them: the opt-out must not silently
+        // drop the one request that asks for exactly these probes.
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false, gateOnly: o.failOnAdvisory !== true })
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
     for (const u of checks.undeclared) {

package/src/core/task-runner.ts

@@ -78,6 +78,10 @@ export type RunOpts = {
     skipGroups?: string[]
     onlyIds?: string[]
     withIds?: string[]
+    /** ids `--only` may name that are NOT tasks: discovered checks and rules.
+     *  The flag addresses all three surfaces, so a check name must not come
+     *  back as `unknown task id` from the one surface that does not own it. */
+    otherIds?: string[]
     /** print sink — tests capture, production defaults to console.log */
     print?: (line: string) => void
     color?: boolean
@@ -115,7 +119,9 @@ export function selectTasks(o: RunOpts): { selected: TaskDef[]; errors: string[]
         if ((t.cmd == null) === (t.logic == null)) errors.push(`task ${t.id}: exactly one of cmd/logic required`)
         for (const d of t.deps ?? []) if (!ids.has(d)) errors.push(`task ${t.id}: unknown dep '${d}'`)
     }
-    for (const id of [...(o.onlyIds ?? []), ...(o.withIds ?? [])]) if (!ids.has(id)) errors.push(`unknown task id '${id}'`)
+    const elsewhere = new Set((o.otherIds ?? []).map((i) => i.toLowerCase()))
+    for (const id of [...(o.onlyIds ?? []), ...(o.withIds ?? [])])
+        if (!ids.has(id) && !elsewhere.has(id.toLowerCase())) errors.push(`unknown task id '${id}'`)
     // cycle check — a dep cycle must die loud at select time, not hang the loop
     const state = new Map<string, 0 | 1>()
     const byId = new Map(o.tasks.map((t) => [t.id, t]))

package/src/init-repo.ts

@@ -96,7 +96,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
         await repairOneWayIn(root, cfg, p)
-        furnishEditor(root, cfg.name, cfg.serve?.port ?? defaultHubPort(cfg.name), p)
+        furnishEditor(root, cfg, p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -130,7 +130,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
-    furnishEditor(root, name, defaultHubPort(name), p)
+    furnishEditor(root, { name }, p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -170,17 +170,20 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
  *  files are the only half of that scaffold an adopted repo can be handed
  *  unasked, because they change no output of any command (project-scaffold.ts
  *  owns the line). Create-only, so a .vscode/ the repo brought with it wins. */
-function furnishEditor(root: string, name: string, port: number, p: (line: string) => void): void {
+function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: number } }, p: (line: string) => void): void {
     // the least important thing init does, and it runs AFTER repo.config.ts is
-    // on disk: an unwritable .vscode (a read-only tree, a path that is a file)
-    // must not abort the run before the publish chain, and must not pass in
-    // silence either
+    // on disk: an unwritable .vscode (a read-only tree, a path that is a file),
+    // or a config with no name at all, must not abort the run before the
+    // publish chain, and must not pass in silence either. The port resolution
+    // is INSIDE the try for that reason: it reads a config nothing validates
     try {
-        const wrote = editorErgonomics(root, { name, port })
-        if (wrote.length > 0) p(`ok: ${wrote.join(' + ')} written — opening the folder starts the watchers and the hub on ${port}`)
-        else p('ok: .vscode/ already yours, left untouched')
+        const name = repoName(root, undefined, cfg.name)
+        const port = cfg.serve?.port ?? defaultHubPort(name)
+        if (editorErgonomics(root, { name, port }).length === 0) return void p('ok: .vscode/ is this repo\'s own, left untouched')
+        p(`ok: .vscode/tasks.json written — opening the folder starts the hub on ${port}`)
+        p('      next: add this stack\'s own watchers (dev server, css, tests) — build/vscode-tasks.md carries the shapes')
     } catch (e) {
-        p(`WARN no .vscode/ here: ${e instanceof Error ? e.message : String(e)} — opening the folder starts nothing, everything else landed`)
+        p(`WARN no .vscode/tasks.json here: ${e instanceof Error ? e.message : String(e)} — opening the folder starts nothing, everything else landed`)
     }
 }
 

package/src/scaffold/project-scaffold.ts

@@ -10,7 +10,7 @@
 // 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 { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { defaultHubPort } from '../serve/hub-port.ts'
 
@@ -23,6 +23,10 @@ export type ScaffoldOpts = {
     print?: (line: string) => void
     /** the changelog's first dated entry — injected so callers stay testable */
     today?: string
+    /** the hub port the caller resolved for the config it is about to wire.
+     *  Absent falls back to the manifest name, which is only right when this
+     *  run wrote the manifest too */
+    port?: number
     /** 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
@@ -99,10 +103,6 @@ function put(root: string, rel: string, body: string): boolean {
     return true
 }
 
-/** the ERGONOMIC half of the day-one shape: the two files that decide what
- *  happens when the folder is opened in vscode, and nothing else. */
-export const ERGONOMIC_FILES = ['.vscode/settings.json', '.vscode/tasks.json'] as const
-
 export type ErgonomicsOpts = {
     /** repo name, substituted into the templates */
     name: string
@@ -112,35 +112,83 @@ export type ErgonomicsOpts = {
     port: number
 }
 
-/** the folder-open half of the scaffold, split out because it is the ONLY
- *  half an ADOPTED repo can be given unasked.
+/** 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.
  *
- *  Everything else the day-one shape writes says what the repo IS (a tsconfig,
- *  a src/index.ts) or what an agent may DO in it (the verify skill, the
- *  .claude/ policy files), and a repo with a history of its own already
- *  answered those. A tasks file and an editor settings file change no output
- *  of any command: they decide what vscode starts when the folder opens, and
- *  a repo where that starts nothing has no folder-open story at all.
+ *  What lands INSIDE it is DERIVED, never assumed. `build/vscode-tasks.md` owns
+ *  this artifact and its method is per-project analysis, so the only subtasks
+ *  written here are the ones true of every wired repo (the hub, whose script
+ *  `init` writes) plus a TSC watcher when this repo actually has a project for
+ *  one. A canned watcher pointed at a solution tsconfig (`files: []` plus
+ *  `references`) type checks ZERO files and reports a clean problems pane
+ *  forever, which is worse than no task. Every other watcher a stack earns
+ *  (a dev server, css, tests) stays the analysis step the owner page describes,
+ *  and the caller says so out loud.
  *
- *  Create-only, like every other writer here: an adopted repo often carries a
- *  .vscode/ from whatever it was forked from, and that one wins byte for
- *  byte. Returns the paths it wrote, so a caller can say "already current"
- *  when it wrote none. */
+ *  Create-only: an adopted repo often carries a `.vscode/` from whatever it was
+ *  forked from, and that one wins byte for byte. Returns the paths it wrote. */
 export function editorErgonomics(root: string, opts: ErgonomicsOpts): string[] {
-    const vars = { NAME: opts.name, PORT: String(opts.port), DATE: '' }
-    const written: string[] = []
-    if (put(root, '.vscode/settings.json', template('vscode-settings.json', vars))) written.push('.vscode/settings.json')
-    if (put(root, '.vscode/tasks.json', template('vscode-tasks.json', vars))) written.push('.vscode/tasks.json')
-    return written
+    // 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) }, typecheckableProject(root))
+    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 with the TSC subtask REMOVED when this repo has no
+ *  project it would check. One template, one subtraction: forking the file
+ *  would put two copies of the house task shape in the tree. */
+export function tasksTemplate(vars: Record<string, string>, withTsc: boolean): string {
+    const body = template('vscode-tasks.json', vars)
+    if (withTsc) return body
+    const parsed = JSON.parse(body.replace(/^\s*\/\/.*$/gm, '')) as { version: string; tasks: Array<Record<string, unknown>> }
+    parsed.tasks = parsed.tasks.filter((t) => t['label'] !== TSC_LABEL)
+    for (const t of parsed.tasks) {
+        const deps = t['dependsOn']
+        if (Array.isArray(deps)) t['dependsOn'] = deps.filter((d) => d !== TSC_LABEL)
+    }
+    return JSON.stringify(parsed, null, 3) + '\n'
+}
+
+const TSC_LABEL = '👁  TSC'
+
+/** whether `tsc --project tsconfig.json` here would check anything at all. A
+ *  solution config (`files: []` plus `references`) needs `--build`, which the
+ *  house watcher does not pass, and answers zero files without it. */
+export function typecheckableProject(root: string): boolean {
+    try {
+        const raw = readFileSync(join(root, 'tsconfig.json'), 'utf8')
+        const cfg = JSON.parse(raw.replace(/^\s*\/\/.*$/gm, '')) as { files?: unknown[]; include?: unknown[]; references?: unknown[] }
+        if ((cfg.references ?? []).length === 0) return true
+        return (cfg.files ?? []).length > 0 || (cfg.include ?? []).length > 0
+    } catch {
+        return false
+    }
 }
 
 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 port = defaultHubPort(configName)
+    // 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
+    // knows the name it is about to wire passes the port it resolves
+    const port = opts.port ?? defaultHubPort(packageName(root) ?? opts.name)
     const vars = {
         NAME: opts.name,
         PORT: String(port),
@@ -152,8 +200,12 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
 
     write('src/index.ts', 'export {}\n')
     write('tsconfig.json', template('tsconfig.json', vars))
-    for (const rel of editorErgonomics(root, { name: opts.name, port })) written.push(rel)
-    for (const rel of ERGONOMIC_FILES) if (!written.includes(rel)) skipped.push(rel)
+    // tasks AFTER the tsconfig, so the TSC subtask is derived from the project
+    // this run just wrote rather than from the empty dir it found
+    ;(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('.vscode/settings.json', template('vscode-settings.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

package/src/start-repo.ts

@@ -10,6 +10,7 @@ import { join } from 'path'
 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'
+import { defaultHubPort } from './serve/hub-port.ts'
 
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
@@ -115,7 +116,11 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
             // 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 }) }
+            // the port comes from the name being WIRED, which is the one on the
+            // command line: init takes the caller's name over the manifest's,
+            // and a dir found holding a forked package.json carries a name
+            // nothing will listen on
+            try { scaffoldProject(dir, { name, port: defaultHubPort(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