@skitterbyte/skitterspec 22.3.1 → 22.4.0

package/assets/core/env.config.md

@@ -90,7 +90,17 @@ 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
-    "envFile": ".env",         // written into the worktree
+    // 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
+    // (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
+    // reads this spec's values and not the primary checkout's.
+    // It must be a file of its OWN: if it is also in `seedFiles` as a symlink,
+    // the write is refused rather than send this spec's port block into the
+    // primary checkout's file. Name a different file here (".worktree.env")
+    // and have your compose file read the values from it.
+    "envFile": ".env",
     "backupCommand": ""        // optional pre-teardown backup (e.g. pg_dump);
                               // empty = no backup, volumes dropped directly.
   },
@@ -116,6 +126,8 @@ through to a documented conservative default; see the field notes below.
   // `local.settings.json`, `config/local.yml`.
   // Seeded files are gitignored, so they never make the worktree "dirty" and
   // never block teardown; they vanish with the worktree at `spec-env down`.
+  // On a Docker project, do not seed `docker.envFile` as a symlink — the env
+  // file step refuses to write through one (see `envFile` above).
   // [] (or absent) = seed nothing (current behaviour).
   "seedFiles": {
     "mode": "symlink",

package/assets/review/page.html

@@ -1044,10 +1044,43 @@ a.ticket:hover { border-color: var(--accent); }
     return bands
   }
 
+  // --- one order, for both columns -----------------------------------------
+  // The sidebar and the panes are two views of one list, and they must be the
+  // SAME list in the same order — a reader scrolling the panes watches the
+  // current-file mark walk the sidebar, and a mark that walks backwards is the
+  // whole reason this exists.
+  //
+  // The emitted order cannot be it. `review.js` collects tracked changes and
+  // untracked files in two passes, so a new file is appended after everything
+  // else however its path sorts; git's own order is not the tree's either.
+  //
+  // So the tree's order is the one order, settled here and used by both. It is
+  // expressed as a comparator rather than derived from the built tree because
+  // the panes are built long before the tree is, and a second traversal that
+  // had to agree with the first is the thing that went wrong.
+  function treeOrder(a, b) {
+    var A = a.split('/')
+    var B = b.split('/')
+    var n = Math.min(A.length, B.length)
+    for (var i = 0; i < n; i++) {
+      // A segment with anything after it is a directory. `renderTree` walks
+      // every directory at a level — label and subtree — before that level's
+      // files, so a directory sorts ahead of a file it ties with by name.
+      var aDir = i < A.length - 1
+      var bDir = i < B.length - 1
+      if (aDir !== bDir) return aDir ? -1 : 1
+      if (A[i] !== B[i]) return A[i].localeCompare(B[i])
+    }
+    return 0
+  }
+
+  // A copy: `data` is the emitted review, and the page is a view of it.
+  var files = data.files.slice().sort(function (a, b) { return treeOrder(a.path, b.path) })
+
   // --- per-file page state -------------------------------------------------
   // Band state lives HERE, never in the emitted data: the page is a view of an
   // immutable review, and expanding context is a property of this reading of it.
-  var state = data.files.map(function (f) {
+  var state = files.map(function (f) {
     var rows = parsePatch(f.patch)
     var st = {
       file: f,
@@ -1717,7 +1750,16 @@ a.ticket:hover { border-color: var(--accent); }
   function renderTree(node) {
     var ul = el('ul')
     ;(function walk(n, depth) {
-      Object.keys(n.dirs).sort().forEach(function (name) {
+      // `treeOrder` above is the authority and these two sorts must match it,
+      // which is why the directories sort by `localeCompare` rather than by the
+      // default `.sort()`: that compares UTF-16 code units, so it puts every
+      // capitalised name ahead of every lowercase one and the panes would drift
+      // from the sidebar again on the first `README/` in a diff.
+      //
+      // Insertion order would be free — the list arrives sorted — but a key
+      // that looks like an array index (`2024/`) is enumerated first whatever
+      // order it was inserted in, and a dated directory is not exotic.
+      Object.keys(n.dirs).sort(function (a, b) { return a.localeCompare(b) }).forEach(function (name) {
         var li = el('li')
         li.appendChild(indent(el('span', 'dir', name + '/'), depth, 0.6))
         ul.appendChild(li)
@@ -1750,9 +1792,9 @@ a.ticket:hover { border-color: var(--accent); }
   }
 
   var tree = document.getElementById('tree')
-  tree.appendChild(renderTree(buildTree(data.files)))
+  tree.appendChild(renderTree(buildTree(files)))
   document.getElementById('tree-summary').textContent =
-    'Files (' + data.files.length + ')'
+    'Files (' + files.length + ')'
   if (window.matchMedia && !window.matchMedia('(min-width: 60rem)').matches) {
     document.getElementById('tree-wrap').open = false
   }

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

@@ -47,21 +47,49 @@ bug's **own branch**, never directly on `main`. Provision the worktree **now**,
 before the failing test, so the test, the fix, and the spec all land together and
 arrive as one reviewable PR.
 
-The engine resolves a spec by its folder, so seed a **minimal stub** for it to
-provision from — you'll flesh it out in §4:
-
-- From the base branch (`main`), create
-  `specs/in-progress/bug-<name>/00-overview.md` with just the header block and the
-  `## Symptom` you established above.
-- Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
-  the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
-  the worktree path, and any `in the worktree, run:` bootstrap steps.
-- Run the printed commands in order. The plan **commits the stub first** — the
-  worktree forks from `main`'s last commit, so the stub has to be in it — and
-  then adds the worktree. Nothing to move afterwards: the spec is already there.
-  The commit is planned, not silent; it appears in the printed plan above the
-  `git worktree add`, and `spec-env up` refuses outright if anything *other* than
-  this spec is uncommitted.
+**Provision before you write, not after.** §1 put nothing on disk and the bug's
+name is settled by the end of it, so this is the one moment where a worktree
+costs nothing to obtain and everything — the red test, the fix, the spec — is
+still ahead of it:
+
+```
+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
+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):
+`skitterspec spec-env resolve` with no argument must name this spec. If it does
+not, say so and stop rather than writing into a tree you cannot name.
+
+**Then run `up` again, without the flag:**
+
+```
+skitterspec spec-env up bug-<name>
+```
+
+`--docs` skips the `setup` commands — everything whose only purpose is making a
+tree *runnable* — because provisioning somewhere to write markdown should cost a
+`git worktree add` and nothing else. `/spec` leaves them to `/spec-start`, but
+**there is no `/spec-start` in a bug's life**: §3 runs the project's suite three
+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.
+
+**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
+for the engine to resolve, and `main` is where work **lands**, not where it
+happens: where the project installs `.claude/hooks/main-guard.cjs` that write is
+refused, and the skill's documented first instruction becomes the one thing the
+repo will not do. Nothing is seeded and nothing is moved now — the spec is
+written in the worktree, at §4, on the branch it belongs to.
+
 - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
@@ -71,9 +99,10 @@ provision from — you'll flesh it out in §4:
   — run `/add-dir <trusted root>` before editing into the worktree, or the first
   edits will prompt.
 - **Do everything below in the worktree**, on the branch — the red test, the fix,
-  and the rest of the spec. Act on the worktree with absolute paths /
-  `git -C <worktreePath>`, or open a session rooted at the printed path. `main`
-  changes only when the branch merges (at `/spec-complete`).
+  and the rest of the spec. The `cd` above is what makes that the default rather
+  than something to remember; where a step has to reach out of the tree, use an
+  absolute path or `git -C <worktreePath>`. `main` changes only when the branch
+  merges (at `/spec-complete`).
 
 ## 3. Write the failing test FIRST (RED) — mandatory
 
@@ -89,8 +118,10 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
 
 ## 4. Write the Bug spec
 
-Fill in the spec's entry point `00-overview.md`. **When isolated**, you already
-seeded this stub in §2 and moved it into the worktree — flesh it out there.
+Write the spec's entry point `00-overview.md`. **When isolated**, you are already
+standing in this spec's own worktree — §2 provisioned it and moved you there, so
+create the folder and write it here, on the bug's branch. Nothing was seeded
+ahead of it and nothing is moved across.
 **When not isolated**, create the spec **folder**
 `specs/in-progress/bug-<kebab-name>/` with its entry point `00-overview.md` now
 (every spec is a folder — never a bare file). A bug is

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

@@ -55,39 +55,69 @@ Hotfixes are concrete — confirm, don't over-grill. Establish:
 - **Root cause:** read the code **at the base tag** and trace it to `file:line`.
   The fix belongs on the tag's line, so reason about that code, not `main`'s.
 
-## 3. Seed the stub, then provision the worktree from the tag
-
-The engine forks the worktree from the spec's `Base version`, so the stub — with
-that header — must exist **before** `spec-env up`:
-
-- From the base branch (`main`), create
-  `specs/in-progress/hotfix-<name>/00-overview.md` with the header block
-  (including `> **Type:** Hotfix` and `> **Base version:** <tag>`) and the
-  `## Symptom` you established. It starts in `in-progress` — work begins now.
-- Run `skitterspec spec-env up hotfix-<name>`. It prints a `git worktree add …
-  -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
-  `main`), the worktree path, and any `in the worktree, run:` bootstrap steps.
-- Run the printed `git worktree add`, then **move the stub across yourself.**
-  This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
-  that skill's worktree forks from `main`, so committing the stub puts it there,
-  while **this worktree is checked out at the tag** — a commit on `main` is not in
-  it and never will be. The move is not redundant here; keep it.
-  **Create the destination bucket first:**
-
-  ```
-  mkdir -p <worktreePath>/specs/in-progress
-  mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/
-  ```
-
-  The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
-  `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an
-  **old release tag**, where it is absent more often than not. `mv` into a
-  missing destination renames your spec folder **to** `specs/in-progress`,
-  silently: the spec's files end up one level too high, `00-overview.md` sits
-  where the bucket should be, and every later step still appears to work until
-  something cannot find the spec. Confirm the result before carrying on — you
-  want `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`. - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+## 3. Provision the worktree from the tag, then write in it
+
+**Provision before you write, not after.** §1 settled the tag and the name and
+§2 put nothing on disk, so this is the one moment where a worktree costs nothing
+to obtain and everything — the red test, the fix, the spec — is still ahead of
+it:
+
+```
+skitterspec spec-env up hotfix-<name> --docs --from <tag>
+```
+
+**`--from` is how the tag reaches the engine, and it is not the header twice.**
+Everywhere else `up` forks a hotfix from the spec's own
+`> **Base version:**` line — but here the spec that would carry it does not
+exist yet, which is the whole of what this lane is for. Without the flag the
+branch would fork from `main`: the fix gets written against code prod is not
+running, while the tag and the cherry-pick downstream go on believing it is on
+the release line, and nothing says otherwise until someone asks why the patch
+did not take. The engine refuses a ref git does not know rather than forking
+from somewhere else quietly; where git cannot answer at all it passes the ref
+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
+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
+(`.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 stop rather than
+writing into a tree you cannot name.
+
+**Then run `up` again, without the flags:**
+
+```
+skitterspec spec-env up hotfix-<name>
+```
+
+`--docs` skips the `setup` commands — everything whose only purpose is making a
+tree *runnable* — because provisioning somewhere to write markdown should cost a
+`git worktree add` and nothing else. A hotfix has no `/spec-start` to leave them
+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.
+
+**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
+checkout for the engine to resolve, and then `mv` the folder across into a
+worktree checked out at a tag — a move with a hazard paragraph of its own, since
+`specs/in-progress/` is usually absent at an old release tag. Both halves are
+gone. `main` is where work **lands**, not where it happens: where the project
+installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
+and a step whose documented opening the repo will not perform is not a step. The
+spec is written in the worktree at §5, on the branch it belongs to.
+
+**§5 records the same tag you passed to `--from`**, on the spec's
+`> **Base version:**` header. That is not bookkeeping: `/spec-complete` tags the
+new patch and cherry-picks off the header, so a worktree forked from one ref and
+a header naming another is this whole bug again with the halves swapped.
+
+- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
   anything else.
@@ -96,8 +126,9 @@ that header — must exist **before** `spec-env up`:
   — run `/add-dir <trusted root>` before editing into the worktree, or the first
   edits will prompt.
 - **Do everything below in the worktree**, on the `hotfix/<slug>` branch — the red
-  test, the fix, and the rest of the spec. Act with absolute paths /
-  `git -C <worktreePath>`, or open a fresh session rooted there. `main` changes
+  test, the fix, and the rest of the spec. The `cd` above is what makes that the
+  default rather than something to remember; where a step has to reach out of
+  the tree, use an absolute path or `git -C <worktreePath>`. `main` changes
   only at `/spec-complete` (via cherry-pick, not merge).
 
 ## 4. Write the failing test FIRST (RED) — mandatory
@@ -114,7 +145,8 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
 
 ## 5. Write the Hotfix spec
 
-Flesh out `00-overview.md` in the worktree (you seeded the stub in §3). A hotfix
+Write `00-overview.md` in the worktree — §3 provisioned it at the tag and moved
+you there, so create the folder and write it here. A hotfix
 is usually a single-pass fix, so the `## Fix` block can live directly in
 `00-overview.md`. Keep it lean:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.3.1",
+  "version": "22.4.0",
   "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

@@ -863,6 +863,9 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
   // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
   // phase 2), so the name resolves to nothing at exactly the moment this runs.
+  // `/spec-bug` takes the same lane and then re-runs `up` WITHOUT the flag for
+  // the `setup` commands it skipped — it has no `/spec-start` to defer them to,
+  // and its next step runs the suite in that tree.
   // It opens only on a positive signal, all three parts: the not-found refusal
   // itself (by code, never by message), `--docs`, and a spec-shaped name — so a
   // typo'd `up` without the flag, or with a name no spec could have, refuses
@@ -883,6 +886,19 @@ function specEnvUp(dir, config, specArg, flags = {}) {
     // a caller that runs the printed commands must never own a worktree the
     // engine cannot name. `spec: true` is what makes the record resolve with
     // the spec's own type and slug rather than as `/no-spec` work.
+    // `--from <ref>` is the fork point for a spec whose own header cannot yet
+    // supply one. `/spec-hotfix` is the caller: its worktree belongs on the
+    // released line, and `> **Base version:**` is written INSIDE that tree.
+    // Everywhere else `spec.baseRef` comes off the spec and stays the
+    // authority — which is why passing this to a spec that resolves refuses
+    // below rather than quietly losing to the header.
+    if (flags.from !== undefined) {
+      const bad = badForkRef(dir, flags.from)
+      if (bad) {
+        process.stdout.write(bad)
+        return
+      }
+    }
     const beforeAuth = readRegistry(dir, config)
     const resolved = resolveSpecless(specArg, dir, config, { spec: true })
     writeRegistry(
@@ -891,9 +907,23 @@ function specEnvUp(dir, config, specArg, flags = {}) {
       recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
     )
     spec = resolved
+    if (flags.from !== undefined) spec.baseRef = flags.from
     authoring = true
   }
 
+  // A flag that cannot be honoured is refused, never ignored. The operator
+  // typed a fork point; silently forking from base instead would build a hotfix
+  // against `main`'s code while everything downstream believes it is on the
+  // release line — the exact silent failure this flag exists to prevent.
+  if (flags.from !== undefined && !authoring) {
+    process.stdout.write(
+      `spec-env up: --from applies to a spec that is not written yet. ` +
+        `${specArg} already exists, and its own \`> **Base version:**\` header is ` +
+        'the fork point — edit that instead.\n',
+    )
+    return
+  }
+
   // Checkout mode: the branch is built in the primary checkout, so none of the
   // worktree machinery below applies — no slot, no trust entry and no bootstrap.
   // Handled first precisely so none of that runs by accident.
@@ -933,13 +963,24 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   const upGit = gitReader(dir)
   const upStatus = upGit(['status', '--porcelain'])
   const upDirtyPaths = dirtyPaths(upGit)
-  // An authoring run does not ask whether the spec is on the fork point — it is
-  // known to be nowhere, and that is the healthy state of the lane, not the
-  // "would fork without the spec it is for" refusal. `onFork: undefined` is the
-  // gate's cannot-tell branch, which allows (negative-checks rule 4). The
-  // untracked read is skipped the same way: there is no folder to ask about.
-  const upOnFork = authoring ? { onFork: undefined, foundOn: null } : specOnForkPoint(dir, upGit, spec)
-  const upSpecUntracked = authoring ? false : specIsUntracked(dir, upGit, spec)
+  // A spec with no document on disk does not ask whether the spec is on the
+  // fork point — it is known to be nowhere, and that is the healthy state of
+  // the authoring lane, not the "would fork without the spec it is for"
+  // refusal. `onFork: undefined` is the gate's cannot-tell branch, which allows
+  // (negative-checks rule 4). The untracked read is skipped the same way: there
+  // is no folder to ask about.
+  //
+  // NOT `authoring`, which is only the run that OPENED the lane. The test-first
+  // skills re-run `up` without `--docs` for the setup commands before the spec
+  // is written, and that run resolves — off the registry record the lane left —
+  // so `authoring` is false while `spec.path` is still null. Asking git about a
+  // null path threw, which is a crash rather than a refusal: the condition is
+  // whether there is a document, and it always was.
+  const noDocument = authoring || !spec.path
+  const upOnFork = noDocument
+    ? { onFork: undefined, foundOn: null }
+    : specOnForkPoint(dir, upGit, spec)
+  const upSpecUntracked = noDocument ? false : specIsUntracked(dir, upGit, spec)
 
   // Trust the shared worktree root so edits into the freshly-provisioned worktree
   // don't prompt. One absolute entry (the root) covers every spec; self-heals on
@@ -1031,9 +1072,15 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   // Positive, so an operator reading the plan knows the missing spec folder is
   // the lane working rather than something the engine failed to find.
   if (authoring) {
-    out.push('  authoring: no spec document yet — /spec writes it in the worktree')
+    out.push('  authoring: no spec document yet — the skill writes it in the worktree')
     out.push(`  recorded:  added to ${config.registry} until the spec is written`)
   }
+  // Only where one was NAMED. The fork point is otherwise base HEAD, which is
+  // the unremarkable case, and a line asserting it on every provision would
+  // make the one run that forked from a tag look like every other.
+  if (authoring && flags.from !== undefined) {
+    out.push(`  fork:      ${flags.from}  (the branch forks from here, not from base)`)
+  }
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
@@ -1050,21 +1097,20 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  // Seed files first (setup may depend on them), then the setup commands —
-  // both run in the worktree, under one heading.
-  const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
+  // 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 || []),
+  ]
   if (worktreeSteps.length) {
     out.push('')
     out.push('  then, in the worktree, run:')
     for (const cmd of worktreeSteps) out.push(`    ${cmd}`)
   }
-  if (plan.envContents) {
-    out.push('')
-    out.push(`  write ${config.docker.envFile} in the worktree:`)
-    for (const line of plan.envContents.replace(/\n$/, '').split('\n')) {
-      out.push(`    ${line}`)
-    }
-  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -1084,6 +1130,38 @@ function speclessMap(dir, config) {
 }
 
 // A read-only git reader over `cwd`: returns trimmed stdout, or null on failure.
+/**
+ * Is `ref` a fork point git will accept? Returns a refusal string, or null.
+ *
+ * THIS IS AN ACCUSATION, so it fires only on a positive signal
+ * (`.claude/rules/negative-checks.md` rule 1). `rev-parse --verify` returning
+ * nothing means one of two very different things — the ref does not exist, or
+ * git could not answer at all — and only the first is evidence. So the control
+ * question is asked first: if git cannot even name its own directory, the ref
+ * is passed straight through and `git worktree add` refuses it far more loudly
+ * than a planner guessing from an absence ever could (rule 4).
+ *
+ * WHAT WOULD FOOL THIS: a ref that exists but is not a commit — an annotated
+ * tag object is peeled by `^{commit}`, so that case is covered, but a blob or
+ * tree ref would be rejected here and rejected by `git worktree add` too. Being
+ * wrong that way costs a refusal on something that could never have worked.
+ */
+function badForkRef(cwd, ref) {
+  const git = gitReader(cwd)
+  if (!ref) {
+    return 'spec-env up: --from needs a ref — the tag or commit to fork from.\n'
+  }
+  // The control question. No repo, no git, an unreadable directory — all land
+  // here, and none of them is evidence about the ref.
+  if (git(['rev-parse', '--git-dir']) === null) return null
+  if (git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) !== null) return null
+  return (
+    `spec-env up: --from ${ref} — git does not know that ref here, so the ` +
+    'worktree would fork from somewhere else without saying so.\n' +
+    '  check the tag exists (git tag --list), or fetch it first.\n'
+  )
+}
+
 function gitReader(cwd) {
   return (argv) => {
     try {
@@ -5016,6 +5094,7 @@ 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] === '--from') flags.from = args[++i]
     else if (args[i] === '--session') flags.session = args[++i]
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])

package/src/env/provision.js

@@ -4,8 +4,8 @@
  * 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`,
- * `docker compose up`) and the rendered `.env` contents — but performs no side
+ * 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
  * registry and passes the slot; this stays deterministic and unit-testable with
  * no live git/docker.
@@ -73,6 +73,50 @@ function seedCommandFor(file, mode) {
 }
 
 
+// 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(', ')
@@ -294,8 +338,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,
- *                     setupCommands, docs, attached }
+ *                     envContents, commands, seedCommands, envCommands,
+ *                     setupCommands, dockerCommands, docs, attached }
+ *
+ * The worktree steps run in that order: seeds, env file, setup, compose.
  */
 function planUp(spec, alloc, config, ctx, opts = {}) {
   const { slot, attached } = alloc
@@ -367,12 +413,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
       : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
-  if (wantsDocker) {
-    commands.push(
-      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
-        ` --project-name ${spec.projectName} up -d`,
-    )
-  }
+  // 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
@@ -398,11 +456,13 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
     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,
     // 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
@@ -481,6 +541,7 @@ module.exports = {
   planCheckoutUp,
   planSpecCommit,
   seedCommandFor,
+  envFileCommandFor,
   worktreeCd,
   resolveStack,
   composeFileArg,

package/src/env/teardown.js

@@ -94,6 +94,10 @@ function planDown(spec, config, flags, ctx) {
   }
 
   // --- docker compose down (drop volumes unless kept) ---
+  // Run from the primary checkout with no `--env-file`, unlike `up`, and on
+  // purpose: compose finds the stack's containers, networks and volumes by the
+  // project label `--project-name` gives it, so it needs nothing from the env
+  // file — which may already be gone with a half-removed worktree.
   if (wantsDocker) {
     const base =
       `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +