@skitterbyte/skitterspec 22.5.0 → 23.0.1

package/MIGRATION.md

@@ -1,5 +1,41 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v22 → v23 (the engine runs the worktree bootstrap)
+
+### Breaking change — `spec-env up` no longer prints the worktree steps
+
+`spec-env up` (and `spec-env nospec`) used to end with a
+`then, in the worktree, run:` block of shell commands: one per seeded file, the
+env-file write, each `setup` command, and `docker compose … up -d`. They now end
+with one line instead:
+
+```
+  then, run:
+    skitterspec spec-env bootstrap <name>
+```
+
+**`spec-env bootstrap [<spec>]` runs those steps itself**, with the worktree
+as its cwd: it seeds the gitignored files, writes `docker.envFile`, runs `setup`
+and brings the stack up, in that order. The behaviour is the same as before: it
+is idempotent, prints `seeded …` / `exists — skipped` / `not in main — skipped`
+per seed, refuses to write through a symlinked env file, and stops at the first
+failing step, naming it. `--docs` seeds only. `--plan` describes the steps
+without running them, and `--json` reports each step and its outcome.
+
+**Why.** The printed commands had to be copied word for word, and agents did
+not copy them faithfully. A project's secrets hook refused any Bash call naming
+a `.env` file, so every rewritten seed command was blocked and bootstrap stopped
+half-way. The new command line names no file.
+
+**What to change.** The shipped skills already call `bootstrap`; run
+`skitterspec update` to take them. Anything of your own that ran the printed
+block (a script, or a skill you edited) should run
+`skitterspec spec-env bootstrap <name>` after the `git worktree add` instead.
+Nothing in `env.config.json` changes.
+
+**If you added a secrets-hook exception for the printed seed commands**, you
+can remove it now. Nothing shipped prints them any more.
+
 ## `@skitterbyte/skitterspec` v21 → v22 (a review port per repo, and every render serves)
 
 ### Breaking change 1 — `review.serveOnRemote` is now `review.serve`
@@ -127,6 +163,12 @@ can run it.
 committed file, so it changes for everyone who pulls and leaves that tree dirty.
 The engine says so when it does.
 
+## `@skitterbyte/skitterspec-linear` v17 → v18 (the engine runs the worktree bootstrap)
+
+The same change as `@skitterbyte/skitterspec` v22 → v23 above — this
+distribution composes the same engine. Read that entry; nothing here is
+Linear-specific.
+
 ## `@skitterbyte/skitterspec-linear` v16 → v17 (a review port per repo, and every render serves)
 
 The same two changes as `@skitterbyte/skitterspec` v21 → v22 above — this

package/assets/core/env.config.md

@@ -5,7 +5,7 @@ stack + host dev servers + a front-door proxy per in-progress spec).
 Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
 `/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
 is `/spec-diff`; the `skitterspec spec-env
-<up|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
+<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
 the engine beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-start` gives
@@ -90,8 +90,9 @@ through to a documented conservative default; see the field notes below.
     "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
     "portBase": 3000,          // first port of slot 0's block
     "portsPerSpec": 10,        // block width; slot n → portBase + n*portsPerSpec
-    // Written into the worktree, and passed to compose as `--env-file`. A
-    // Docker spec's worktree steps run in this order: seedFiles, this env file
+    // Written into the worktree by `spec-env bootstrap`, and passed to compose
+    // as `--env-file`. A Docker spec's worktree steps run in this order:
+    // seedFiles, this env file
     // (COMPOSE_PROJECT_NAME and PORT_OFFSET appended only where missing, so a
     // value `setup` or you put there is kept), `setup`, then
     // `docker compose … up -d` — all from inside the worktree, so the stack
@@ -106,7 +107,7 @@ through to a documented conservative default; see the field notes below.
   },
 
   // Gitignored files seeded from the primary checkout into a fresh worktree by
-  // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
+  // `spec-env bootstrap`, after `git worktree add` and BEFORE `setup` runs — so a
   // fresh linked worktree (which starts with none of the repo's gitignored files)
   // has the .env / local secret overrides / local config that setup steps and
   // git hooks depend on. Without this any setup step that reads .env — a schema
@@ -116,9 +117,9 @@ through to a documented conservative default; see the field notes below.
   //          stays in sync; "copy" makes an independent copy.
   //   files  repo-relative paths to seed. A source absent in main is a printed
   //          no-op (not an error); a target that already exists is left untouched
-  //          (idempotent — safe when `spec-env up` re-attaches an existing
-  //          worktree). The main checkout is resolved robustly at run time via
-  //          `git rev-parse --git-common-dir` — no hardcoded repo name or path.
+  //          (idempotent — safe to re-run `spec-env bootstrap` over an existing
+  //          worktree). Seeding is done by the engine itself, never printed as
+  //          shell, so no command line ever names one of these files.
   // Shorthand: `"seedFiles": [".env", …]` == `{ "mode": "symlink", "files": […] }`.
   // `.env` is an ILLUSTRATION, not an expectation — skitterspec never reads any
   // of these files, it only links or copies them. Name whatever your stack keeps
@@ -134,12 +135,12 @@ through to a documented conservative default; see the field notes below.
     "files": [".env"]
   },
 
-  // Bootstrap commands `spec-env up <spec>` runs IN the worktree, right after
-  // `git worktree add` (before Docker/dev), on every provision including
+  // Bootstrap commands `spec-env bootstrap <spec>` runs IN the worktree, after
+  // the seeds and the env file and before the stack, on every provision including
   // re-attach — so a fresh worktree's dependencies exist and git hooks,
   // typechecks, builds and tests work immediately instead of failing on a
-  // missing node_modules. An array, run in order; [] = none. Each string is a
-  // shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
+  // missing node_modules. An array, run in order, stopping at the first that
+  // exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
   // expand (the cwd is already the worktree, so {worktreePath} is usually
   // redundant). Example: ["pnpm install --frozen-lockfile"].
   "setup": [],

package/assets/hooks/main-guard.cjs

@@ -107,19 +107,36 @@ function findEngine(projectDir) {
 // skills carry the rule for everything this matcher cannot see.
 const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
 
+// The path a write tool names: `file_path` for Edit, Write and MultiEdit,
+// `notebook_path` for NotebookEdit. Anything else is no path at all.
+function writeTarget(input) {
+  if (!input || typeof input !== 'object') return null
+  for (const key of ['file_path', 'notebook_path']) {
+    if (typeof input[key] === 'string' && input[key]) return input[key]
+  }
+  return null
+}
+
 function main() {
   const payload = readPayload()
   if (!payload) allow()
 
   if (!WRITE_TOOLS.has(payload.tool_name)) allow()
 
-  // The write's own directory decides the answer — a worktree is its own
-  // checkout, and only the primary one is this guard's business.
+  // A worktree is its own checkout, and only the primary one is this guard's
+  // business. `cwd` is where the session stands; the target below is where the
+  // write lands, and the engine prefers it.
   const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
   const session = typeof payload.session_id === 'string' ? payload.session_id : ''
 
   const argv = ['spec-env', 'main', 'check', '--dir', cwd]
   if (session) argv.push('--session', session)
+  // The FILE decides where the write lands, not the session's directory. Judged
+  // on `cwd` alone, a session on the base branch was refused its own scratchpad
+  // under /tmp, and a session in a worktree could write into the primary
+  // checkout unseen. No path in the payload → the engine judges `cwd`, as before.
+  const target = writeTarget(payload.tool_input)
+  if (target) argv.push('--path', target)
 
   const result = spawnSync(findEngine(cwd), argv, { cwd, encoding: 'utf8', timeout: 8000 })
 
@@ -142,4 +159,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { findEngine, WRITE_TOOLS }
+module.exports = { findEngine, WRITE_TOOLS, writeTarget }

package/assets/rules/spec-planning.md

@@ -178,8 +178,11 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
-engine. **Omit the spec name anywhere and it uses the worktree you are standing in**,
+<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
+engine. `up` plans the fork;
+**`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
+the command a skill runs names no file, and a secrets hook that refuses any
+`.env` path has nothing to refuse. **Omit the spec name anywhere and it uses the worktree you are standing in**,
 else the sole provisioned spec — with no exceptions left: a bare
 `/spec-connect` connects, and a bare `/spec-live` takes, where both once meant
 `main`. Teardown drops

package/assets/skills/no-spec/SKILL.md

@@ -46,9 +46,24 @@ skitterspec spec-env nospec <name>
 ```
 
 It records the name as a **specless branch** and prints the plan. Run the
-commands it prints, then move this session into the worktree with a plain `cd`
-— the Bash working directory persists between calls, so from here on the work
-happens on its own branch.
+`git worktree add` it prints, then move this session into the worktree with a
+plain `cd` and run the `then, run:` line where there is one:
+
+```
+cd "<worktreePath>" && skitterspec spec-env bootstrap <name>
+```
+
+That seeds the project's gitignored files into the worktree, then runs its
+`setup`, and stops at the first failing step, naming it. There is no stack: a
+specless branch never gets an env file or Docker. The Bash working directory persists between calls, so from
+here on the work happens on its own branch.
+
+**The worktree steps are the engine's to run, never yours.** Seeding the
+gitignored files, the env file, `setup` and the stack all happen inside
+`skitterspec spec-env bootstrap <name>` — one call that names no file. Do not
+reconstruct them as shell: they used to be printed that way, an agent's copy was
+never faithful, and a project's secrets hook refused every rewrite that named a
+`.env` path. `bootstrap --plan` says what it would do, for reading only.
 
 **Confirm the move landed** rather than reading silence as success
 (`.claude/rules/negative-checks.md` rule 1): `skitterspec spec-env resolve` with

package/assets/skills/spec/SKILL.md

@@ -87,9 +87,11 @@ a worktree costs nothing to obtain and everything is still ahead of it:
 skitterspec spec-env up <name> --docs
 ```
 
-Run the commands it prints, then move this session into the worktree with a
-plain `cd` — the Bash working directory persists between calls, so from here on
-the spec is written on its own branch. Confirm the move landed rather than
+Run the commands it prints under `to provision, run:`, and the
+`skitterspec spec-env bootstrap <name> --docs` under `then, run:` where there is
+one (it seeds the gitignored files, nothing more). Then move this session into
+the worktree with a plain `cd` — the Bash working directory persists between
+calls, so from here on the spec is written on its own branch. Confirm the move landed rather than
 reading silence as success (`.claude/rules/negative-checks.md` rule 1):
 `skitterspec spec-env resolve` with no argument must name this spec. If it does
 not, say so and write the spec where you are standing instead; a spec in the
@@ -378,7 +380,7 @@ get the land through.
 
 **The worktree lifetime follows the verdict, and the asymmetry is deliberate.**
 `commit-start` keeps it because you are carrying straight on, and `/spec-start`
-re-runs `up` over it without `--docs` — which is where the setup commands
+re-runs `up` and `bootstrap` over it without `--docs`, which is where the setup commands
 Phase B skipped finally run. Plain `commit` tears it down with
 `skitterspec spec-env down <name>`, because a spec parked in the backlog should
 hold no worktree and no `node_modules`; `/spec-start` provisions from scratch

package/assets/skills/spec-bug/SKILL.md

@@ -59,8 +59,9 @@ skitterspec spec-env up bug-<name> --docs
 **The spec does not exist yet, and that is the lane.** `up` opens its authoring
 branch on exactly three signals — a spec it could not find, `--docs`, and a name
 shaped `bug-<something>` — records the branch so the name resolves from here on,
-and prints a `git worktree add … -b bug/<name>` forked from `main`. Run what it
-prints, then move this session into the worktree with a plain `cd`; the Bash
+and prints a `git worktree add … -b bug/<name>` forked from `main`. Run it, and
+the `skitterspec spec-env bootstrap bug-<name> --docs` under `then, run:` where
+there is one, then move this session into the worktree with a plain `cd`; the Bash
 working directory persists between calls, so from here on the test, the fix and
 the spec are all written on the bug's own branch. Confirm the move landed rather
 than reading silence as success (`.claude/rules/negative-checks.md` rule 1):
@@ -80,7 +81,15 @@ tree *runnable* — because provisioning somewhere to write markdown should cost
 steps from here, in this same tree, and
 **a tree that cannot run the suite cannot go red**.
 The flagless re-run re-attaches the worktree that now exists
-(no second `-b` fork) and prints the bootstrap steps the flag deferred.
+(no second `-b` fork) and prints `skitterspec spec-env bootstrap bug-<name>` —
+run it, and it runs the steps the flag deferred.
+
+**The worktree steps are the engine's to run, never yours.** Seeding the
+gitignored files, the env file, `setup` and the stack all happen inside
+`skitterspec spec-env bootstrap <name>` — one call that names no file. Do not
+reconstruct them as shell: they used to be printed that way, an agent's copy was
+never faithful, and a project's secrets hook refused every rewrite that named a
+`.env` path. `bootstrap --plan` says what it would do, for reading only.
 
 **Why the stub is no longer seeded on the base branch.** This step used to open
 by writing `specs/in-progress/bug-<name>/00-overview.md` in the primary checkout

package/assets/skills/spec-hotfix/SKILL.md

@@ -79,7 +79,9 @@ through to `git worktree add`, which refuses far more loudly than a planner
 guessing from an absence.
 
 Run what it prints — the `git worktree add … -b hotfix/<slug> <tag>` is checked
-out **at the tag**, not at `main` — then move this session into the worktree
+out **at the tag**, not at `main`, and the
+`skitterspec spec-env bootstrap hotfix-<name> --docs` under `then, run:` where
+there is one — then move this session into the worktree
 with a plain `cd`; the Bash working directory persists between calls, so from
 here on the test, the fix and the spec are all written on the hotfix's own
 branch. Confirm the move landed rather than reading silence as success
@@ -100,7 +102,15 @@ to: §4 runs the project's suite in this same tree, and
 **a tree that cannot run the suite cannot go red**.
 The flagless re-run re-attaches the worktree that now exists (no second `-b`
 fork, and no fork point — the branch is already on the tag's line) and prints
-the bootstrap steps the flag deferred.
+`skitterspec spec-env bootstrap hotfix-<name>` — run it, and it runs the steps
+the flag deferred.
+
+**The worktree steps are the engine's to run, never yours.** Seeding the
+gitignored files, the env file, `setup` and the stack all happen inside
+`skitterspec spec-env bootstrap <name>` — one call that names no file. Do not
+reconstruct them as shell: they used to be printed that way, an agent's copy was
+never faithful, and a project's secrets hook refused every rewrite that named a
+`.env` path. `bootstrap --plan` says what it would do, for reading only.
 
 **Why nothing is seeded on the base branch, and nothing is moved.** This step
 used to write `specs/in-progress/hotfix-<name>/00-overview.md` in the primary

package/assets/skills/spec-start/SKILL.md

@@ -82,10 +82,11 @@ nothing to commit" as a sign something was skipped: it means the landing worked.
 
 **And the worktree may already exist**, because `Commit & Start` keeps it. That
 is a re-attach, not a clash: `spec-env up` plans the attach form rather than a
-second `-b` fork, and its `then, in the worktree, run:` step is where the
-`setup` commands `--docs` deliberately skipped finally run. So run the plan as
-printed — the install belongs to this moment, the first at which the tree is
-used for code — and report a re-attach rather than a fresh provision.
+second `-b` fork, and its `then, run:` line — `spec-env bootstrap <name>`,
+without `--docs` — is where the `setup` commands `--docs` deliberately skipped
+finally run. So run it — the install belongs to this moment, the first at which
+the tree is used for code — and report a re-attach rather than a fresh
+provision.
 
 ## 2. Identify the spec
 
@@ -164,12 +165,22 @@ render says so. On **`--plan`** this step does not run at all.
    spec on its own:
 
    ```
-   cd "<worktreePath>" && <the planner's "then, in the worktree, run:" steps>
+   cd "<worktreePath>" && skitterspec spec-env bootstrap <name>
    ```
 
-   Run the seeding steps before `setup`: a fresh worktree has no dependencies and
-   none of the repo's gitignored files, so hooks, typechecks and tests fail until
-   both have happened.
+   That is the planner's `then, run:` line, with the `cd` in front. It seeds
+   the gitignored files before `setup` itself — a fresh worktree has neither, so
+   hooks, typechecks and tests fail until both have happened — and stops at the
+   first step that fails, naming it. Relay its step lines; a non-zero exit is a
+   failure to report at the moment it happens, not a reason to run the steps by
+   hand.
+
+   **The worktree steps are the engine's to run, never yours.** Seeding the
+   gitignored files, the env file, `setup` and the stack all happen inside
+   `skitterspec spec-env bootstrap <name>` — one call that names no file. Do not
+   reconstruct them as shell: they used to be printed that way, an agent's copy was
+   never faithful, and a project's secrets hook refused every rewrite that named a
+   `.env` path. `bootstrap --plan` says what it would do, for reading only.
 
    **Then confirm the move landed — never assume it.** Ask for a positive signal
    rather than reading silence as success (`.claude/rules/negative-checks.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.5.0",
+  "version": "23.0.1",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -29,6 +29,7 @@ const ENV_CONFIG_LABEL = 'env.config.json'
 // their own lines below.
 const SPEC_ENV_VERBS = Object.freeze([
   'up',
+  'bootstrap',
   'down',
   'prune',
   'dev',
@@ -147,7 +148,8 @@ const {
   cacheHit,
   asCached,
 } = require('./env/reviewers.js')
-const { planUp, planCheckoutUp, worktreeCd, resolveStack } = require('./env/provision.js')
+const { planUp, planCheckoutUp, resolveStack, worktreeSteps } = require('./env/provision.js')
+const { runBootstrap, describeStep } = require('./env/bootstrap.js')
 const { classifyDirtyTree, dirtyPaths, specDocsIn } = require('./env/classify.js')
 const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
@@ -213,6 +215,10 @@ Usage:
                                                   Docker stack (prints commands; creates nothing)
                                                   --docs: a tree to write documents in — no
                                                   setup commands, no Docker
+                                bootstrap [spec]  run the worktree's seeds, env file, setup
+                                                  and stack itself, in the worktree — after
+                                                  \`up\`'s worktree add (--docs: seeds only;
+                                                  --plan: describe, run nothing; --json)
                                 nospec <name>     record a branch with no spec document
                                                   (/no-spec work) and print its plan
                                 main <check|allow|status>
@@ -669,8 +675,17 @@ function specEnvMain(dir, config, positional, flags = {}, present = true, invoke
     // checkout before it runs, so asking `dir` whether it is the primary
     // checkout always answers yes — and the guard would fire on a write inside
     // somebody's worktree, which is the one place it must never fire.
+    //
+    // `--path` is the file being written, and where it is given it decides: a
+    // write outside the primary checkout is none of this guard's business,
+    // whichever directory the session happens to be standing in.
     const from = invokedFrom || dir
-    const verdict = checkMainWrite(from, config, gitReader(from), { sessionId, present })
+    const verdict = checkMainWrite(from, config, gitReader(from), {
+      sessionId,
+      present,
+      target: flags.path ? path.resolve(from, flags.path) : null,
+      gitAt: gitReader,
+    })
     if (!verdict.refuse) return
     process.stdout.write(`spec-env main: ${verdict.reason}\n`)
     process.exitCode = 1
@@ -805,9 +820,6 @@ function specEnvNospec(dir, config, name, flags = {}) {
   const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
   const attached = fs.existsSync(spec.worktreePath)
 
-  const guard = worktreeCd(spec.worktreePath)
-  const setupCommands = (config.setup || []).map((cmd) => `${guard}; ${cmd}`)
-
   const out = [
     `spec-env nospec: ${name} ` +
       (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
@@ -835,11 +847,8 @@ function specEnvNospec(dir, config, name, flags = {}) {
       ? `    git worktree add ${spec.worktreePath} ${spec.branch}`
       : `    git worktree add ${spec.worktreePath} -b ${spec.branch}`,
   )
-  if (setupCommands.length) {
-    out.push('')
-    out.push('  then, in the worktree, run:')
-    for (const cmd of setupCommands) out.push(`    ${cmd}`)
-  }
+  const seeds = (config.seedFiles && config.seedFiles.files) || []
+  if (seeds.length || (config.setup || []).length) out.push(...bootstrapLines(name))
   if (flags.json) {
     process.stdout.write(
       JSON.stringify(
@@ -1100,21 +1109,191 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  // Everything after the fork runs in the worktree, under one heading, in the
-  // order each step depends on the last: seeds (the env file may be one), the
-  // env file, setup (which may derive values into it), and only then the stack.
-  const worktreeSteps = [
-    ...plan.seedCommands,
-    ...(plan.envCommands || []),
-    ...plan.setupCommands,
-    ...(plan.dockerCommands || []),
+  // Everything after the fork runs in the worktree, and the engine runs it: one
+  // line naming the verb, never the steps as shell (see `specEnvBootstrap`).
+  if (plan.steps.length) out.push(...bootstrapLines(spec.folder, { docs }))
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+/**
+ * `spec-env bootstrap [<spec>]` — bring a provisioned worktree to ready.
+ *
+ * Runs the steps `up` once printed as shell for the caller to copy —
+ * seeds, the env file, `setup`, the stack — itself, with the worktree as cwd.
+ * The caller's command line is `skitterspec spec-env bootstrap <name>` and
+ * nothing more, so no `.env` path ever appears in it: there is nothing for a
+ * secrets hook to refuse, and nothing for an agent to rewrite on the way.
+ *
+ * IT DOES NOT FORK. `git worktree add` and the spec's own commit stay `up`'s,
+ * printed and run as before; this verb starts where they finish, so re-running
+ * one step later — `setup` after a lockfile change — costs no re-plan.
+ *
+ * Refuses BEFORE ACTING, non-zero, when there is nothing to bootstrap yet: no
+ * worktree on disk, or a docker spec with no registry slot (its port block
+ * would be derived from nothing). Both name `spec-env up`.
+ *
+ * Specless (`/no-spec`) work runs `setup` only — `nospec` has never seeded and
+ * still does not. Checkout mode has no worktree and says so, exit 0: the
+ * primary checkout already has its dependencies.
+ */
+function specEnvBootstrap(dir, config, specArg, flags = {}) {
+  const docs = flags.docs === true
+  const json = flags.json === true
+  const say = (line) => process.stdout.write(line + '\n')
+  const refuse = (msg) => {
+    if (json) say(JSON.stringify({ ok: false, refused: msg }, null, 2))
+    else say(`spec-env bootstrap: ${msg}`)
+    process.exitCode = 1
+  }
+
+  if (config.mode === 'checkout') {
+    say(
+      'spec-env bootstrap: checkout mode has no worktree to bootstrap — the primary ' +
+        'checkout already has its dependencies.',
+    )
+    return
+  }
+
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+  const name = spec.folder
+
+  if (!fs.existsSync(spec.worktreePath)) {
+    refuse(
+      `no worktree at ${spec.worktreePath} — run \`skitterspec spec-env up ${name}\` ` +
+        'and the worktree add it prints first.',
+    )
+    return
+  }
+  // The primary checkout answering as the worktree would seed every file onto
+  // itself and report `exists — skipped`, indistinguishable from a healthy
+  // re-run, while `setup` ran against the base branch.
+  if (sameDir(spec.worktreePath, dir)) {
+    refuse(`${spec.worktreePath} is the primary checkout, not ${name}'s worktree.`)
+    return
+  }
+
+  let steps
+  // A `/no-spec` record — not the authoring record `up --docs` writes for a
+  // spec not yet on disk, which is a spec and plans like one. It seeds and runs
+  // `setup` exactly as a spec does, since a `setup` that reads a seeded `.env`
+  // fails without it; what it never has is a stack, so no slot is consulted.
+  if (spec.specless && !spec.unwritten) {
+    steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false })
+  } else {
+    const compose = composeFilePresent(dir, config)
+    const { wantsDocker } = resolveStack(spec, config, { docs, composeFilePresent: compose })
+    let offset = null
+    if (wantsDocker) {
+      const slots = readRegistry(dir, config).slots || {}
+      if (!Object.prototype.hasOwnProperty.call(slots, name)) {
+        refuse(
+          `${name} wants a Docker stack and has no slot yet — run ` +
+            `\`skitterspec spec-env up ${name}\` first.`,
+        )
+        return
+      }
+      offset = portOffset(slots[name], config)
+    }
+    steps = worktreeSteps(spec, offset, config, {
+      docs,
+      wantsDocker,
+      composeFilePresent: compose,
+    })
+  }
+
+  if (flags.plan) {
+    if (json) {
+      say(
+        JSON.stringify(
+          { spec: name, worktree: spec.worktreePath, docs, planned: true, steps },
+          null,
+          2,
+        ),
+      )
+      return
+    }
+    say(`spec-env bootstrap: ${name} (plan — nothing run)`)
+    say('')
+    say(`  worktree:  ${spec.worktreePath}`)
+    if (!steps.length) say('  steps:     none — nothing configured to run')
+    else steps.forEach((st, i) => say(`  ${i + 1}. ${describeStep(st)}`))
+    return
+  }
+
+  if (!json) {
+    say(`spec-env bootstrap: ${name}`)
+    say(`  worktree:  ${spec.worktreePath}`)
+  }
+  const result = runBootstrap(steps, {
+    cwd: spec.worktreePath,
+    mainRoot: dir,
+    // Report lines go to stdout as plain text; under --json they are carried in
+    // the payload instead, and spawned output is moved to stderr with them.
+    write: json ? () => {} : (line) => say(`  ${line}`),
+    childStdout: json ? process.stderr : 'inherit',
+  })
+
+  if (json) {
+    say(
+      JSON.stringify(
+        {
+          spec: name,
+          worktree: spec.worktreePath,
+          docs,
+          planned: false,
+          ok: result.ok,
+          failedAt: result.failedAt,
+          steps: result.results.map((r) => ({ ...r.step, outcome: r.outcome, line: r.line })),
+          remaining: steps.slice(result.results.length),
+        },
+        null,
+        2,
+      ),
+    )
+  } else if (result.ok) {
+    say(
+      steps.length
+        ? `spec-env bootstrap: ${name} ready (${steps.length} step${steps.length === 1 ? '' : 's'})`
+        : `spec-env bootstrap: ${name} — nothing to do (no seedFiles, setup or stack configured)`,
+    )
+  } else {
+    const failed = result.results[result.results.length - 1]
+    process.stderr.write(`  ${failed.line}\n`)
+    say(
+      `spec-env bootstrap: stopped at step ${result.failedAt} of ${steps.length} ` +
+        `(${describeStep(failed.step)}) — nothing after it ran.`,
+    )
+  }
+  if (!result.ok) process.exitCode = 1
+}
+
+/**
+ * The hand-off from a planner to `spec-env bootstrap`: the one command a caller
+ * runs once the worktree exists.
+ *
+ * ONE LINE, AND NO SHELL. The worktree steps used to be printed here as
+ * POSIX-sh one-liners, and an agent copying them rewrote them — merged two seeds
+ * into a loop, reworded the echo text — at which point a consumer's secrets hook
+ * refused the `.env` paths in the rewrite. This line names no file at all, so it
+ * has nothing to rewrite and nothing to refuse. `bootstrap --plan` is where the
+ * steps can still be read.
+ */
+function bootstrapLines(name, { docs = false } = {}) {
+  return [
+    '',
+    '  then, run:',
+    `    skitterspec spec-env bootstrap ${name}${docs ? ' --docs' : ''}`,
   ]
-  if (worktreeSteps.length) {
-    out.push('')
-    out.push('  then, in the worktree, run:')
-    for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
+}
+
+// Two spellings of one directory — `/tmp` and `/private/tmp` on macOS — are
+// the same directory. Cannot-tell (either missing) is "not the same".
+function sameDir(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b)
+  } catch {
+    return false
   }
-  process.stdout.write(out.join('\n') + '\n')
 }
 
 /**
@@ -5164,8 +5343,10 @@ async function specEnv(rest) {
     else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
     else if (args[i] === '--docs') flags.docs = true
+    else if (args[i] === '--plan') flags.plan = true
     else if (args[i] === '--from') flags.from = args[++i]
     else if (args[i] === '--session') flags.session = args[++i]
+    else if (args[i] === '--path') flags.path = args[++i]
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
   }
@@ -5238,6 +5419,9 @@ async function specEnv(rest) {
     case 'up':
       specEnvUp(dir, config, positional[0], flags)
       break
+    case 'bootstrap':
+      specEnvBootstrap(dir, config, positional[0], flags)
+      break
     case 'nospec':
       specEnvNospec(dir, config, positional[0], flags)
       break

package/src/env/bootstrap.js

@@ -0,0 +1,188 @@
+'use strict'
+
+/**
+ * Run a worktree's bootstrap steps — the engine half of `spec-env bootstrap`.
+ *
+ * `planUp` decides WHAT a fresh worktree needs (`worktreeSteps`); this module
+ * does it. Seeds and the env file are plain filesystem work, done here with
+ * `fs` and no shell at all. `setup` commands and the stack are spawned with the
+ * worktree as their cwd.
+ *
+ * WHY THE ENGINE RUNS THEM. These steps used to be printed as shell for the
+ * agent to run, and an agent does not copy shell faithfully. A consumer's
+ * secrets hook refuses any Bash call naming a `.env` file, with one exception
+ * for the exact printed shape — so every rewrite was refused, and the retry was
+ * refused again by auto mode as a workaround. The call that replaces them,
+ * `skitterspec spec-env bootstrap <name>`, names no file at all.
+ *
+ * Behaviour is the printed commands' behaviour, kept exactly: idempotent, one
+ * `seeded …` / `… — skipped` line per seed, a seed missing from the primary
+ * checkout is skipped rather than failed, a symlinked env file is refused before
+ * anything is written through it, and the run stops at the first failing step.
+ *
+ * Every side effect goes through `io`, so the tests drive it with a real temp
+ * directory and a fake spawn — no docker, no package manager.
+ */
+
+const realFs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+/** One line describing a step, for `--plan` and for the failure report. */
+function describeStep(step) {
+  switch (step.kind) {
+    case 'seed':
+      return `seed ${step.file} (${step.mode} from the primary checkout)`
+    case 'envFile':
+      return `env file ${step.file} (COMPOSE_PROJECT_NAME, PORT_OFFSET)`
+    case 'setup':
+      return `setup: ${step.command}`
+    case 'docker':
+      return `docker: ${step.argv.join(' ')}`
+    default:
+      return `unknown step ${step.kind}`
+  }
+}
+
+// `lstat` that answers null for a missing path rather than throwing.
+function lstatOrNull(fs, p) {
+  try {
+    return fs.lstatSync(p)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Seed one gitignored file from the primary checkout.
+ *
+ * The source is tested with `existsSync`, which follows links — a dangling
+ * link in the primary checkout is "not in main", exactly as `[ -e ]` read it.
+ * The target is tested with `lstat`, which does not: an existing link, even a
+ * dangling one, is somebody's deliberate state and is left alone.
+ */
+function runSeed(step, { cwd, mainRoot, fs }) {
+  const src = path.join(mainRoot, step.file)
+  const dst = path.join(cwd, step.file)
+  if (!fs.existsSync(src)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: not in main — skipped` }
+  }
+  if (lstatOrNull(fs, dst)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
+  }
+  fs.mkdirSync(path.dirname(dst), { recursive: true })
+  if (step.mode === 'copy') fs.copyFileSync(src, dst)
+  else fs.symlinkSync(src, dst)
+  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
+}
+
+/**
+ * Make sure the spec's env file sets its project name and port block.
+ *
+ * Additive: a key is appended only when no line already sets it, so a re-run
+ * writes nothing and a file `setup` already wrote to keeps every value it holds
+ * — a deliberate `PORT_OFFSET` of its own included.
+ *
+ * A SYMLINK IS REFUSED, before anything is written. Seeding links gitignored
+ * files from the primary checkout, so a seeded env file IS the primary
+ * checkout's own, and appending through it would write this spec's port block
+ * into the main stack's configuration. The fix is a `docker.envFile` naming a
+ * file of its own.
+ */
+function runEnvFile(step, { cwd, fs }) {
+  const p = path.join(cwd, step.file)
+  const st = lstatOrNull(fs, p)
+  if (st && st.isSymbolicLink()) {
+    return {
+      outcome: 'refused',
+      line:
+        `env file ${step.file} is a symlink — docker.envFile must name a file of its own, ` +
+        "not a seeded one; refusing to write this spec's port block through it",
+    }
+  }
+  const before = st ? fs.readFileSync(p, 'utf8') : ''
+  let add = ''
+  // A file without a trailing newline would glue the first appended key onto
+  // its last line.
+  const sep = before.length && !before.endsWith('\n') ? '\n' : ''
+  for (const [key, value] of [
+    ['COMPOSE_PROJECT_NAME', step.projectName],
+    ['PORT_OFFSET', step.offset],
+  ]) {
+    if (!new RegExp(`^${key}=`, 'm').test(before)) add += `${key}=${value}\n`
+  }
+  if (!st || add) {
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, before + (add ? sep + add : ''))
+  }
+  return { outcome: add ? 'written' : 'skipped', line: `env file ${step.file}: ready` }
+}
+
+/**
+ * Spawn a setup command (through the shell — it is the project's own command
+ * line) or the stack (an argv, no shell).
+ *
+ * `stdout` is where the child's own output goes: inherited normally, so an
+ * install streams as it runs, and moved to stderr under `--json` so the payload
+ * on stdout stays parseable.
+ */
+function runSpawned(step, { cwd, spawn, childStdout }) {
+  const stdio = ['ignore', childStdout, 'inherit']
+  const res =
+    step.kind === 'setup'
+      ? spawn(step.command, { cwd, shell: true, stdio })
+      : spawn(step.argv[0], step.argv.slice(1), { cwd, stdio })
+  if (res.error) {
+    return { outcome: 'failed', line: `${describeStep(step)} — ${res.error.message}` }
+  }
+  if (res.status !== 0) {
+    const why = res.status === null ? `killed by ${res.signal || 'a signal'}` : `exit ${res.status}`
+    return { outcome: 'failed', line: `${describeStep(step)} — ${why}` }
+  }
+  return { outcome: 'ran', line: null }
+}
+
+/**
+ * Run `steps` in order in `cwd`, stopping at the first that fails.
+ *
+ * io: { cwd, mainRoot, fs?, spawn?, write?, childStdout? }
+ *   - `write(line)` receives every report line as it happens
+ *   - `childStdout` is the stdio slot for spawned output ('inherit' default)
+ *
+ * Returns { ok, results: [{ step, outcome, line }], failedAt } — `failedAt` is
+ * the 1-based index of the step that stopped the run, or null.
+ */
+function runBootstrap(steps, io) {
+  const ctx = {
+    cwd: io.cwd,
+    mainRoot: io.mainRoot,
+    fs: io.fs || realFs,
+    spawn: io.spawn || spawnSync,
+    childStdout: io.childStdout || 'inherit',
+  }
+  const write = io.write || (() => {})
+  const results = []
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]
+    // A spawned step announces itself BEFORE it runs, so the streamed output
+    // that follows has a heading.
+    if (step.kind === 'setup' || step.kind === 'docker') write(describeStep(step))
+    let r
+    try {
+      if (step.kind === 'seed') r = runSeed(step, ctx)
+      else if (step.kind === 'envFile') r = runEnvFile(step, ctx)
+      else if (step.kind === 'setup' || step.kind === 'docker') r = runSpawned(step, ctx)
+      else r = { outcome: 'failed', line: describeStep(step) }
+    } catch (err) {
+      r = { outcome: 'failed', line: `${describeStep(step)} — ${err.message}` }
+    }
+    results.push({ step, ...r })
+    if (r.line && r.outcome !== 'failed' && r.outcome !== 'refused') write(r.line)
+    if (r.outcome === 'failed' || r.outcome === 'refused') {
+      return { ok: false, results, failedAt: i + 1 }
+    }
+  }
+  return { ok: true, results, failedAt: null }
+}
+
+module.exports = { runBootstrap, describeStep }

package/src/env/mainguard.js

@@ -139,12 +139,61 @@ function judgeMainWrite(ctx) {
   }
 }
 
+/**
+ * The checkout a path lives in: the `--show-toplevel` of its nearest existing
+ * ancestor, or null when that is in no git repo at all.
+ *
+ * NEAREST EXISTING ANCESTOR, because a `Write` usually creates its file and
+ * often its folder too — `git -C` on a directory that does not exist yet fails,
+ * and reading that failure as "not in a repo" would wave through exactly the
+ * new file the guard exists for.
+ */
+function checkoutOf(target, gitAt) {
+  let at = path.resolve(target)
+  while (!fs.existsSync(at)) {
+    const up = path.dirname(at)
+    if (up === at) return null
+    at = up
+  }
+  if (!fs.statSync(at).isDirectory()) at = path.dirname(at)
+  return gitAt(at)(['rev-parse', '--show-toplevel'])
+}
+
+// Two spellings of one directory — `/tmp` and `/private/tmp` on macOS — are
+// the same directory. Cannot-tell is "not the same", the branch that allows.
+function sameDir(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b)
+  } catch {
+    return false
+  }
+}
+
+const ALLOWS = { refuse: false, reason: null, branch: null, baseBranch: null }
+
 /**
  * Gather the facts and judge. The only IO in the module's hot path.
  *
  * `git` is an injected reader, as everywhere in this package: the caller owns
  * the child-process boundary, which is what keeps `judgeMainWrite` testable
  * without one.
+ *
+ * `opts.target` is the path being written, and when it is given IT decides
+ * where the write lands — not `dir`, which is only where the session stands.
+ * Judging the session's directory refused every write a session on the base
+ * branch made anywhere, its own scratchpad under /tmp included, while a session
+ * standing in a worktree could write into the primary checkout unseen
+ * (bug-main-guard-judges-cwd). `opts.gitAt(dir)` makes a reader for another
+ * directory; it is required alongside `target`.
+ *
+ * This reads the write's LOCATION, never its name, so it is not the exception
+ * list `judgeMainWrite` refuses to grow: a path inside the primary checkout is
+ * judged exactly as before, whatever it is called.
+ *
+ * WHAT WOULD FOOL THIS: a target in ANOTHER configured repo is judged against
+ * this session's repo, so it is allowed — that repo's guard is its own sessions'
+ * business. And without `target` (an older hook, a tool with no path) the
+ * session's directory is judged as it always was.
  */
 function checkMainWrite(dir, config, git, opts = {}) {
   // `present` from `loadEnvConfig` — the caller has it and this module must not
@@ -159,27 +208,37 @@ function checkMainWrite(dir, config, git, opts = {}) {
   // looking for the absence of a worktree marker.
   let isPrimary = false
   let primary = null
+  // Which checkout's HEAD decides "on the base branch". With a target that is
+  // the primary checkout's own, wherever the session is standing.
+  let branchGit = git
   try {
     primary = resolvePrimaryCheckout(dir, git)
-    isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+    if (opts.target && typeof opts.gitAt === 'function') {
+      const top = checkoutOf(opts.target, opts.gitAt)
+      isPrimary = Boolean(top) && Boolean(primary) && sameDir(top, primary)
+      if (!isPrimary) return ALLOWS
+      branchGit = opts.gitAt(primary)
+    } else {
+      isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+    }
   } catch {
     // Not a git repo, or git unreadable. Cannot tell → allow.
-    return { refuse: false, reason: null, branch: null, baseBranch: null }
+    return ALLOWS
   }
 
   let onBase = false
   let branch = null
   let baseBranch = null
   try {
-    const state = assertPrimaryOnMain(config, git)
+    const state = assertPrimaryOnMain(config, branchGit)
     onBase = state.onBase
     branch = state.branch
     baseBranch = state.baseBranch
   } catch {
-    return { refuse: false, reason: null, branch: null, baseBranch: null }
+    return ALLOWS
   }
 
-  const root = isPrimary ? dir : primary || dir
+  const root = primary || dir
   const verdict = judgeMainWrite({
     configured,
     enabled,

package/src/env/provision.js

@@ -3,10 +3,10 @@
 /**
  * Pure provisioning planner for `spec-env up`.
  *
- * Given a resolved spec and its allocated slot, `planUp` returns the exact
- * side-effecting commands the `/spec-env` skill runs (`git worktree add`, the
- * env file, `docker compose up`) and the rendered `.env` contents — but performs no side
- * effects itself. The caller (the CLI) reads/allocates the
+ * Given a resolved spec and its allocated slot, `planUp` returns the commands
+ * the caller runs from the primary checkout (the spec commit, `git worktree
+ * add`) and the worktree steps `spec-env bootstrap` runs afterwards (seeds, the
+ * env file, `setup`, the stack) — but performs no side effects itself. The caller (the CLI) reads/allocates the
  * registry and passes the slot; this stays deterministic and unit-testable with
  * no live git/docker.
  */
@@ -16,107 +16,6 @@ const { portOffset } = require('./registry.js')
 const { renderEnvFile } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
 
-/**
- * Build the POSIX-sh prefix that puts a command in the spec's worktree, or stops.
- *
- * Every command under the "then, in the worktree, run:" heading carries this.
- * Without it those commands stay silent when run from the wrong place: in the
- * primary checkout `$m` resolves to the checkout itself, so a seed's source and
- * target are the same path and it prints `exists — skipped` — indistinguishable
- * from a correctly-provisioned re-run — while a setup command like an install
- * runs against the main checkout and "succeeds" too. Three layers then agree that
- * nothing is wrong, and the caller carries on committing to `main`.
- *
- * A `cd` is deliberately chosen over comparing `git rev-parse --show-toplevel`
- * against `worktreePath`: the planned path is a lexical `path.resolve` while git
- * reports the symlink-resolved one (`/tmp` vs `/private/tmp` on macOS), so a
- * string compare would refuse a perfectly good worktree. `cd` sidesteps that, and
- * does better than refusing — it *positions* the command, so a caller who is in
- * the wrong directory still gets correct behaviour. When the worktree was never
- * created — the reported case — the `cd` fails and takes the whole command with
- * it, non-zero and loud.
- *
- * Per-command, not once at the top of the block: a single leading `cd` only
- * protects the sequence if the caller chains it with `&&`, and the reported
- * failure is precisely a caller that ran the steps as separate statements.
- */
-function worktreeCd(worktreePath) {
-  return (
-    `cd "${worktreePath}" 2>/dev/null || ` +
-    `{ echo "no worktree at ${worktreePath} — run the provisioning commands first"; exit 1; }`
-  )
-}
-
-/**
- * Build one idempotent POSIX-sh command that seeds a gitignored file from the
- * main checkout into the current worktree (the cwd when the skill runs it).
- *
- * The main checkout is resolved at run time from inside the worktree via
- * `git rev-parse --git-common-dir` (absolute `<main>/.git` in a linked worktree)
- * and its dirname — never a hardcoded repo name or a `../..` hop. The command is
- * safe to re-run: a source absent in main is a printed no-op, an already-seeded
- * target (real file or symlink) is left untouched, and only a genuinely missing
- * target is created. `mode` is 'symlink' (points at main, stays in sync) or
- * 'copy' (an independent copy). Output mirrors the setup style: `seeded <f> → …`.
- */
-function seedCommandFor(file, mode) {
-  const op =
-    mode === 'copy'
-      ? `cp "$m/${file}" "${file}"`
-      : `ln -s "$m/${file}" "${file}"`
-  return (
-    'm="$(dirname "$(git rev-parse --git-common-dir)")"; ' +
-    `if [ ! -e "$m/${file}" ]; then echo "seed ${file}: not in main — skipped"; ` +
-    `elif [ -e "${file}" ] || [ -L "${file}" ]; then echo "seed ${file}: exists — skipped"; ` +
-    `else mkdir -p "$(dirname "${file}")" && ${op} && echo "seeded ${file} → $m/${file}"; fi`
-  )
-}
-
-
-// Single-quote a value for POSIX sh: the only character that needs escaping
-// inside single quotes is the single quote itself.
-function shq(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`
-}
-
-/**
- * Build one idempotent POSIX-sh command that writes the spec's env file in the
- * current worktree (the cwd when the skill runs it).
- *
- * It was prose once — "write <envFile> in the worktree:" — which left the write
- * to whoever read the plan, and a secrets guard that blocks any tool call naming
- * `.env` refused it. As a command it is one more step the plan runs.
- *
- * Idempotent and additive: it `touch`es the file and appends each key only when
- * no line already sets it, so a re-run changes nothing and a file `setup` has
- * already written to keeps every value it holds — including a deliberate
- * `PORT_OFFSET` of its own.
- *
- * A SYMLINK IS REFUSED, loudly. Seeding links gitignored files from the primary
- * checkout, so a seeded env file is the primary checkout's own; appending
- * through it would write this spec's port block into the main stack's
- * configuration. It runs after the seeds precisely so that collision is caught
- * rather than hidden. The fix is a `docker.envFile` naming a file of its own.
- */
-function envFileCommandFor(envFile, projectName, offset) {
-  const f = shq(envFile)
-  const ensure = (key, value) =>
-    `{ grep -q '^${key}=' ${f} || echo ${shq(`${key}=${value}`)} >> ${f}; }`
-  return (
-    `if [ -L ${f} ]; then echo ${shq(
-      `env file ${envFile} is a symlink — docker.envFile must name a file of its ` +
-        "own, not a seeded one; refusing to write this spec's port block through it",
-    )} >&2; exit 1; fi; ` +
-    `touch ${f} && ` +
-    // A file without a trailing newline would glue the first appended key onto
-    // its last line.
-    `{ [ ! -s ${f} ] || [ -z "$(tail -c 1 ${f})" ] || echo >> ${f}; } && ` +
-    `${ensure('COMPOSE_PROJECT_NAME', projectName)} && ` +
-    `${ensure('PORT_OFFSET', offset)} && ` +
-    `echo ${shq(`env file ${envFile}: ready`)}`
-  )
-}
-
 // Cap a path list in a message: enough to recognise, not a wall of text.
 function listPaths(paths) {
   const shown = paths.slice(0, 5).join(', ')
@@ -328,6 +227,71 @@ function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
   return { stack, wantsDocker: stack === 'docker' && config.docker.enabled && !docs }
 }
 
+/**
+ * The steps that bring a fresh worktree to ready, as data — the list
+ * `spec-env bootstrap` runs. In the order each depends on the last: seeds (the
+ * env file may be one), the env file, `setup` (which may derive values into
+ * it), and only then the stack.
+ *
+ * DATA AND NOT SHELL, and that is the reason the verb exists. These steps were
+ * printed as POSIX-sh one-liners for the agent to copy, and the copy was never
+ * faithful: merged into a loop, its echo text reworded, two steps glued into one
+ * call. A consumer's secrets hook — which refuses any Bash call naming a `.env`
+ * file and makes an exception only for the exact printed shape — then refused
+ * the rewrite, and bootstrap stopped with the user running it by hand. A step
+ * the engine runs itself has no text for anything to rewrite or refuse.
+ *
+ * `setup` entries stay shell strings: they are the project's own commands,
+ * written by the project. The docker step is an argv, run without a shell.
+ *
+ * Pure: `offset` is the spec's port offset (null without a stack), and every
+ * filesystem fact arrives in `opts`.
+ */
+function worktreeSteps(spec, offset, config, opts = {}) {
+  const { docs = false, wantsDocker = false, composeFilePresent: compose } = opts
+  const seed = config.seedFiles || { mode: 'symlink', files: [] }
+  const mode = seed.mode === 'copy' ? 'copy' : 'symlink'
+  const tokens = {
+    worktreePath: spec.worktreePath,
+    slug: spec.slug,
+    branch: spec.branch,
+    projectName: spec.projectName,
+    portOffset: offset === null || offset === undefined ? '' : String(offset),
+  }
+  const envFile = (config.docker && config.docker.envFile) || '.env'
+  const steps = (seed.files || []).map((file) => ({ kind: 'seed', file, mode }))
+  if (wantsDocker) {
+    steps.push({ kind: 'envFile', file: envFile, projectName: spec.projectName, offset })
+  }
+  // Documents mode drops `setup` and nothing else: seeding is cheap and a spec
+  // author may well want the gitignored files present, while `setup` is the
+  // expensive half that exists to make the tree run. `wantsDocker` is already
+  // false under `--docs` (`resolveStack`), so the stack drops with it.
+  if (!docs) {
+    for (const cmd of config.setup || []) {
+      steps.push({ kind: 'setup', command: expandTokens(cmd, tokens) })
+    }
+  }
+  if (wantsDocker) {
+    const file = composeFileArg(config, compose).trim().split(/\s+/).filter(Boolean)
+    steps.push({
+      kind: 'docker',
+      argv: [
+        'docker',
+        'compose',
+        ...file,
+        '--env-file',
+        envFile,
+        '--project-name',
+        spec.projectName,
+        'up',
+        '-d',
+      ],
+    })
+  }
+  return steps
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -338,10 +302,10 @@ function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
  * @param {object} config normalised env config.
  * @param {object} opts  { docs } — documents mode (see below). Optional.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
- *                     envContents, commands, seedCommands, envCommands,
- *                     setupCommands, dockerCommands, docs, attached }
+ *                     envContents, commands, steps, docs, attached }
  *
- * The worktree steps run in that order: seeds, env file, setup, compose.
+ * `commands` run from the primary checkout (the spec commit, the fork); `steps`
+ * are what `spec-env bootstrap` runs in the worktree afterwards.
  */
 function planUp(spec, alloc, config, ctx, opts = {}) {
   const { slot, attached } = alloc
@@ -374,33 +338,13 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
     ? renderEnvFile({ projectName: spec.projectName, portOffset: offset })
     : null
 
-  const tokens = {
-    worktreePath: spec.worktreePath,
-    slug: spec.slug,
-    branch: spec.branch,
-    projectName: spec.projectName,
-    portOffset: offset === null ? '' : String(offset),
-  }
-
-
-  // File seeding runs *in the worktree* after `git worktree add`, before the
-  // setup commands (which may depend on the seeded .env). Each entry becomes an
-  // idempotent shell command resolving the main checkout at run time. Absent
-  // config ⇒ no commands ⇒ current behaviour.
-  const seed = config.seedFiles || { mode: 'symlink', files: [] }
-  const seedMode = seed.mode === 'copy' ? 'copy' : 'symlink'
-  const guard = worktreeCd(spec.worktreePath)
-  const seedCommands = (seed.files || []).map(
-    (file) => `${guard}; ${seedCommandFor(file, seedMode)}`,
-  )
-
-  // Bootstrap commands run *in the worktree* after `git worktree add` (before
-  // Docker/dev), on every provision including re-attach — deps must exist for
-  // the worktree to be usable. Kept separate from `commands` (run from the
-  // primary checkout root); the CLI prints them under an "in the worktree" head.
-  const setupCommands = (config.setup || []).map(
-    (cmd) => `${guard}; ${expandTokens(cmd, tokens)}`,
-  )
+  // Everything after the fork runs in the worktree, and `spec-env bootstrap`
+  // runs it — the steps are data, not shell for a caller to copy.
+  const steps = worktreeSteps(spec, offset, config, {
+    docs,
+    wantsDocker,
+    composeFilePresent: ctx ? ctx.composeFilePresent : undefined,
+  })
 
   const commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
@@ -413,25 +357,6 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
       : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
-  // The stack comes up LAST, in the worktree: after the seeds, after the env
-  // file, after `setup` — which may derive values into that file. It once ran
-  // from the primary checkout before the worktree existed, so compose read the
-  // primary checkout's env file, fell back to its defaults and collided with the
-  // main stack. `--env-file` is always passed: with the default `.env` it is what
-  // compose would have found anyway, and with any other name it is the only way
-  // compose finds it.
-  const envFile = (config.docker && config.docker.envFile) || '.env'
-  const envCommands = wantsDocker
-    ? [`${guard}; ${envFileCommandFor(envFile, spec.projectName, offset)}`]
-    : []
-  const dockerCommands = wantsDocker
-    ? [
-        `${guard}; docker compose` +
-          composeFileArg(config, ctx ? ctx.composeFilePresent : undefined) +
-          ` --env-file ${shq(envFile)} --project-name ${spec.projectName} up -d`,
-      ]
-    : []
-
   // The tree gate. A worktree forks from the base branch's tree, so an
   // uncommitted spec would produce a branch missing the spec it is for — this is
   // where that gets committed, or refused. Worktree mode had NO clean gate before
@@ -455,18 +380,13 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
     portOffset: offset,
     envContents,
     commands: gate.blocked ? [] : [...gate.commands, ...commands],
-    seedCommands: gate.blocked ? [] : seedCommands,
-    envCommands: gate.blocked ? [] : envCommands,
-    // Documents mode drops these, and keeps the seed commands above. The two are
-    // not the same kind of thing: seeding links the gitignored files a worktree
-    // has none of — cheap, and a spec author may well want `.env` present —
-    // while `setup` is the expensive half that exists to make the tree run.
-    setupCommands: gate.blocked || docs ? [] : setupCommands,
-    dockerCommands: gate.blocked ? [] : dockerCommands,
+    // The worktree steps, in the order `spec-env bootstrap` runs them. Documents
+    // mode drops `setup` and the stack and keeps the seeds (`worktreeSteps`).
+    steps: gate.blocked ? [] : steps,
     // Reported so a caller reading `--json` can tell a documents worktree from a
-    // full one POSITIVELY, rather than inferring it from what is missing. An
-    // empty `setupCommands` also describes a project that configured no setup
-    // at all, and those two must not read alike.
+    // full one POSITIVELY, rather than inferring it from what is missing. A step
+    // list with no `setup` also describes a project that configured none, and
+    // those two must not read alike.
     docs,
     attached,
   }
@@ -540,9 +460,7 @@ module.exports = {
   planUp,
   planCheckoutUp,
   planSpecCommit,
-  seedCommandFor,
-  envFileCommandFor,
-  worktreeCd,
+  worktreeSteps,
   resolveStack,
   composeFileArg,
 }