@skitterbyte/skitterspec 22.3.2 → 22.5.0

package/README.md

@@ -164,7 +164,8 @@ live:    off — /spec-live to put it live
 `local` and `network` are two doors into one room — the same server, the same
 waiting verdict — so the wait covers both. `remote` is a published page, which
 is a separate store: a verdict there needs `/spec-reviewed`, and it is off until
-you type `/spec-remote-review`. The `live:` line is the other way to judge a
+you type `/spec-remote-review`, which permits **that spec** to publish, publishes
+the waiting page and re-shows the links. The `live:` line is the other way to judge a
 change: whether it is also **running**, and the page has a button to put it
 there.
 
@@ -182,7 +183,7 @@ All optional, in `specs/.core/env.config.json`:
 |-----|---------|------|
 | `review.serve` | `"always"` | whether a render stands the local server up. `"never"` gives you a `file://` page, whose buttons copy a command instead of sending |
 | `review.allowNetwork` | `true` | whether that server binds every interface, so the page opens on your phone |
-| `review.allowRemote` | `false` | whether publishing is permitted at all. `/spec-remote-review` toggles it; it permits publishing, it does not publish |
+| `review.allowRemote` | `false` | whether publishing is permitted for every spec — the project default. `/spec-remote-review` permits one spec at a time in a gitignored sidecar and never edits this key (`review allow remote --project` does) |
 | `review.required` | `true` | whether a finished phase owes a verdict |
 | `review.commitWith` | `"/commit"` | the skill a committing verdict hands off to |
 | `review.reader` | `"detect"` | where you are reading — `local`, `remote`, or detect it |

package/assets/commands/spec-remote-review.md

@@ -1,22 +1,37 @@
 ---
-description: Permit or forbid publishing a review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
+description: Permit or forbid publishing this spec's review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
 argument-hint: "[on | off]"
 allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
 disable-model-invocation: true
 ---
 !`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
 
-Relay the engine output above verbatim. Add nothing and run nothing else.
+Relay the engine output above verbatim. Add nothing to it.
+
+**Then one thing, and only when the engine asked for it.** Where the output
+carries a `review:` and a `publish:` line, typing this command **is** the ask
+to publish that page: the banner named this command beside a review the reader
+could not reach, so the link is what they are waiting for. Publish it exactly
+as `/spec-diff` §6 describes (run the `publish:` command, publish the copy it
+names with a store, write the URL file), then re-emit the review banner with
+all three tiers, `remote` now carrying the URL. A wait already running keeps
+running; do not restart it or the server. If the harness refuses the publish,
+say so in one line and keep the banner as it was, because local and network
+still work.
+
+With no `publish:` line, run nothing else. Nothing has a page to publish, or
+the tier was turned off.
 
 **Bare toggles.** That is the common case: you are looking at a render whose
 `remote:` line says which way it currently is, and what you want is the other
 one. `on` and `off` are there for when you are not looking at it.
 
-**It permits publishing; it publishes nothing.** A published page is one
-skitterspec cannot delete, so publishing stays an explicit ask
-(`/spec-diff` §6) — and a verdict pressed on one needs `/spec-reviewed`, because
-nothing pushes from an artifact's store into a conversation.
+**It is per spec.** The engine resolves the spec from the worktree you are
+standing in and records the permission in the gitignored review store, so
+the base branch is untouched and no other spec may publish because of it.
+`skitterspec spec-env review allow remote --project` is the committed,
+every-spec form, for a team that wants it.
 
-**It writes a committed file.** `specs/.core/env.config.json` in the primary
-checkout, whichever tree you ran this from — so it changes for everyone who
-pulls and leaves that tree dirty. The engine says so; do not soften it.
+**A published page is one skitterspec cannot delete**, and a verdict pressed
+on one needs `/spec-reviewed`, because nothing pushes from an artifact's store
+into a conversation.

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",
@@ -132,6 +144,23 @@ through to a documented conservative default; see the field notes below.
   // redundant). Example: ["pnpm install --frozen-lockfile"].
   "setup": [],
 
+  // Commands to run in the PRIMARY checkout after a land — the counterpart of
+  // `setup`, for whatever landed code needs before the base branch is usable
+  // locally (e.g. ["pnpm db:data-migration"] for imperative data migrations
+  // your deploy runs and nothing runs on your dev DB). An array, run in order;
+  // [] (or absent) = none, and every plan prints exactly what it always did.
+  //   `spec-env integrate` prints them after the fast-forward (worktree and
+  //   checkout mode), and also after "already landed" — a land on another
+  //   machine leaves them pending here. `spec-env hotfix land` prints them
+  //   after the cherry-pick onto the base branch, and not at all when
+  //   `hotfix.cherryPickMain` is false, since the base gained nothing.
+  // The engine only plans: /spec-complete, /spec-to-main and /no-spec run
+  // them (a /spec documents-only land does not). They stop at the first
+  // failure, report it as a caveat, and never undo the land or block
+  // teardown. Literal strings — tokens are NOT expanded, because they run on
+  // the base branch where a spec's {slug} or {portOffset} mean nothing.
+  "afterLand": [],
+
   // Host dev servers `spec-env dev up <spec>` starts on the spec's port block
   // (for apps that run via `pnpm dev` on the host, not inside the Docker stack).
   // An array so UI + API (or more) are supervised independently; [] = none.
@@ -329,10 +358,14 @@ through to a documented conservative default; see the field notes below.
   //                    page opens on your phone, or loopback only. THIS IS WHAT
   //                    CHOOSES THE BIND; `reader` no longer does. Default: true,
   //                    which matches what the engine already did.
-  //   `allowRemote`  — whether PUBLISHING is permitted at all. It permits it; it
-  //                    publishes nothing. Default: FALSE, because a published
-  //                    page is one skitterspec cannot delete, so it must never
-  //                    happen unasked.
+  //   `allowRemote`  — whether PUBLISHING is permitted for EVERY spec. It
+  //                    permits it; it publishes nothing. Default: FALSE,
+  //                    because a published page is one skitterspec cannot
+  //                    delete, so it must never happen unasked. This is the
+  //                    PROJECT DEFAULT: `/spec-remote-review` permits one spec
+  //                    at a time, in a gitignored sidecar beside its page, and
+  //                    never edits this file — `review allow remote --project`
+  //                    is what does.
   //
   // `local` and `network` are two doors into ONE ROOM — the page POSTs to
   // `location.pathname`, so both reach the same server and the same waiting

package/assets/rules/spec-planning.md

@@ -29,8 +29,12 @@ finding one. They are marked `disable-model-invocation`, meaning
 **only you can run them** — a skill that wants one will tell you to type it
 rather than invoking it.
 
-**`/spec-remote-review`** is the newest and the smallest: it toggles
-`review.allowRemote`, and takes `on`/`off` when you would rather say which.
+**`/spec-remote-review`** is the newest and the smallest: it toggles whether
+**this spec** may publish, and takes `on`/`off` when you would rather say which.
+The permission is per worktree, kept in the gitignored review store, so the base
+branch is never dirtied and no other spec gains it; `review.allowRemote` in the
+committed config is the project default beneath it. Turned on beside a page
+that already exists, it is the ask to publish that page and re-show the stack.
 It exists because a render's `remote:` line has to name something a person can
 act on, and `skitterspec spec-env review allow remote` is not what anyone
 reconstructs from a page they are reading on a phone. Making the line

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

@@ -156,6 +156,14 @@ three, in that order — never the bare `page:` path.
   **forgets the specless record**, which is what stops a torn-down name going on
   answering to every verb with a path that is no longer there.
 
+  **Between the two, run the after-land commands.** Where the `integrate` plan
+  ends with a `then, in the primary checkout (<path>), run:` section — the
+  project's `afterLand` — run those commands there, in order, once the
+  fast-forward has succeeded, and on an already-landed no-op too. A lockfile
+  refresh is exactly the land that needs them.
+  **Stop at the first non-zero exit**: the run becomes `⚠️`, naming the command that failed and the ones that
+  did not run, and it **never undoes the land and never stops the `down`**.
+
   **If the rebase conflicts, stop.** `git rebase --abort`, leave the commit on
   the branch, tear nothing down, and report `❌` with the conflict — there is a
   standing worktree, which is what separates `❌` from `⏸`.
@@ -181,7 +189,9 @@ the shape; this section carries only what is specific here.
 **Verdicts**
 
 - `✅` — the work is done, the tests are green, and the verdict was acted on.
-- `⚠️` — done and green, with something worth knowing.
+- `⚠️` — done and green, with something worth knowing — an after-land command
+  that failed, for one. `Notes` carries what the after-land commands ran, or
+  where they stopped; nothing about them when none are configured.
 - `❌` — the tests are red, or the land failed part-way. Quote the failure and
   say what is standing.
 - `⏸` — refused before acting: no name given, the name is already a spec, the

package/assets/skills/spec/SKILL.md

@@ -363,6 +363,12 @@ It plans a rebase onto the base branch in the worktree, then a
 refuses on a dirty tree, which is correct here: the commit ran first, so anything
 still uncommitted at this point is not this spec's and the land must not proceed.
 
+**Do not run its after-land section.** Where the plan ends with
+`then, in the primary checkout (<path>), run:`, those are the project's
+`afterLand` commands — a data migration, an install — and they exist for code
+that landed. This land is documents only, so it changes nothing they would
+catch up on; `/spec-complete`, `/spec-to-main` and `/no-spec` run them.
+
 **If the rebase conflicts, stop and say so.** It is unlikely on a
 documents-only branch and not impossible — two specs authored at once can both
 touch `specs/.core/`. Run `git rebase --abort`, leave the commit sitting on the

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

@@ -113,16 +113,21 @@ the shape; this section carries only what is specific here.
 
 - `✅` — every phase done, tests green, landed, torn down.
 - `⚠️` — finished, with something worth knowing: teardown declined, a tracker
-  refresh that failed, a hotfix tag still waiting to be pushed.
+  refresh that failed, a hotfix tag still waiting to be pushed, an after-land
+  command that failed.
 - `❌` — it acted and stopped part-way — a conflicted rebase, a failed
   cherry-pick, a red base after landing. Say what state the repo is in and quote
   the failure; there is a mess to clear and the reader needs to know where.
 - `⏸` — phases are unfinished, tests are red, or the tree is dirty. Nothing
   moved.
 
-**Fields:** `Tracker` · `Spec` · `Tests` · `Landed` · `Worktree` ·
+**Fields:** `Tracker` · `Spec` · `Tests` · `Notes` · `Landed` · `Worktree` ·
 `Follow-ups` · `Next`
 
+`Notes` carries the after-land commands step 6 ran, and where — or, on a
+failure, the command that failed and the ones that did not run. A project with
+no `afterLand` says nothing about it.
+
 **Report this spec and no other.** A completion is the moment it is most
 tempting to survey what is left — what else is in flight, what is in the
 backlog, which worktrees are still standing — and it is the moment it helps
@@ -167,8 +172,12 @@ Use the hotfix landing instead of the integrate steps below:
    cherry-pick --abort` there, relay the conflict, and **stop** — don't offer
    teardown.
    On a **no-op** ("nothing to land"), say so and continue.
-3. **Re-test on `main`** after the cherry-pick — it must be **green**.
-4. **Report** the deploy tag(s) and the `main` cherry-pick. It **never pushes** —
+3. **Run the after-land commands** when the plan ends with a
+   `then, in the primary checkout (<path>), run:` section — exactly as step 3
+   of 6-feature/bug below says. `hotfix land` prints it only when it
+   cherry-picks onto `main`, so a prod-only land or a no-op has none.
+4. **Re-test on `main`** after the cherry-pick — it must be **green**.
+5. **Report** the deploy tag(s) and the `main` cherry-pick. It **never pushes** —
    remind the user to `git push origin <deploy-tag>` to deploy. Then teardown
    (step 7) applies: a tagged hotfix branch tears down with **no `--force`**.
 
@@ -207,9 +216,20 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
    `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
    to the user; do not tear anything down.
    On a **no-op** ("already landed"), just say so and continue.
-3. **Re-test on base.** Run the project's test command from the primary checkout;
+3. **Run the after-land commands.** Where the plan ends with a
+   `then, in the primary checkout (<path>), run:` section — the project's
+   `afterLand`, such as a data migration — run those commands in that
+   directory, in order, after the fast-forward succeeds. **Also on the no-op**:
+   the engine prints them there deliberately, because a land made on another
+   machine leaves them pending here. **Stop at the first non-zero exit** — a
+   later command may depend on it — and carry on with the rest of the skill:
+   a failure makes the run `⚠️`, naming the command that failed and the ones
+   that did not run, and it
+   **never undoes the land and never blocks teardown** (step 7). The land is correct; catching up is the operator's.
+   No section, nothing to run, and nothing to say about it.
+4. **Re-test on base.** Run the project's test command from the primary checkout;
    it must be **green** before you call the landing done.
-4. **Report** the landing (base branch, fast-forward result). It **never pushes** —
+5. **Report** the landing (base branch, fast-forward result). It **never pushes** —
    mention the user can `git push` the base branch themselves.
 
 ## 7. Tear down the environment (opt-in, only if configured)
@@ -221,7 +241,9 @@ teardown is folded in here).
 
 **The precondition is that the work actually landed.** Only tear down when step 6
 completed: it landed (or reported "already landed") **and** the base suite came
-back green. A rebase conflict, a work-loss abort or a red suite means step 6 told
+back green. A failed after-land command is **not** a reason to stop here — the
+land stands, and the command is the operator's to re-run from the primary
+checkout, which teardown does not touch. A rebase conflict, a work-loss abort or a red suite means step 6 told
 you to stop — tear nothing down, because the worktree is where the user picks the
 problem up. That precondition is what makes a confirmation redundant: by the time
 you get here the branch is an ancestor of base and the engine's guards have

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

@@ -363,7 +363,7 @@ still has a decision in front of them and has not made it.
 |--------|----|------|
 | `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
 | `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
-| `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
+| `allow-remote` | `skitterspec spec-env review allow remote <spec> --set on` | publish (§6), re-render, wait again |
 
 **THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
 live is about the diff on screen; handing the whole instance back to `main` is a
@@ -420,18 +420,22 @@ text, and do not infer an offer that is not there — the boundary that keeps
 another spec's workbench out of this lives in that field rather than in prose
 here.
 
-**`allow` writes a committed file, and that is worth a sentence.** It edits
-`specs/.core/env.config.json` in the **primary checkout**, so it changes
-behaviour for everyone who pulls and leaves that tree dirty — unlike the live
-actions, which move a branch and write a gitignored receipt. The engine prints
-the absolute path and whose tree it dirtied; relay that rather than letting a
-shared setting change land silently. And it is **enable-only**: there is no
+**`allow network` writes a committed file, and that is worth a sentence.** It
+edits `specs/.core/env.config.json` in the **primary checkout**, so it changes
+behaviour for everyone who pulls and leaves that tree dirty — one server binds
+for every spec, so the bind cannot be narrower. The engine prints the absolute
+path; relay that rather than letting a shared setting change land silently.
+**`allow remote` is per spec** and writes only a gitignored sidecar beside the
+page, so the base branch stays clean and no other spec may publish. And it is **enable-only**: there is no
 action that turns a tier off, because turning `network` off from a page reached
 over the network kills the page doing the turning.
 
-**`allow remote` permits publishing. It does not publish.** Publishing stays an
-explicit ask in every case (§6), because the page it leaves behind is one this
-tooling cannot remove.
+**`allow remote` permits publishing. It does not publish by itself.**
+Publishing stays an explicit ask (§6), because the page it leaves behind is one
+this tooling cannot remove. A reader who presses `Allow remote` on the page, or
+types `/spec-remote-review` beside a waiting review, **has** asked: the engine
+names the page on its `review:`/`publish:` lines, and that page is published
+and the stack re-shown. Nothing it does not name is published.
 
 ## 3. Gate it on nothing
 

package/assets/skills/spec-to-main/SKILL.md

@@ -87,6 +87,16 @@ nothing else.
 On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
 and continue — the branch has no commits base doesn't already have.
 
+**Then run the after-land commands.** Where the plan ends with a
+`then, in the primary checkout (<path>), run:` section — the project's
+`afterLand`, such as a data migration — run those commands in that directory,
+in order, after the fast-forward and **before** the re-test below, which may
+need them. Run them on the no-op too: the engine prints them there because a
+land made elsewhere leaves them pending here.
+**Stop at the first non-zero exit**, and carry on with §5: a failure makes the run `⚠️`, naming the command
+that failed and the ones that did not run, and it **never undoes the land**.
+No section, nothing to run, and nothing to say about it.
+
 ## 5. Re-test on base, then report
 
 - Run the project's test command **from the primary checkout** — base must be
@@ -111,12 +121,17 @@ the shape; this section carries only what is specific here.
 **Verdicts**
 
 - `✅` — the branch is on the base and the base is green.
-- `⚠️` — landed, with something worth knowing.
+- `⚠️` — landed, with something worth knowing — an after-land command that
+  failed, for one.
 - `❌` — the rebase conflicted, or the base went red after the fast-forward.
   Quote it; the repo is mid-something and that is what the reader needs.
 - `⏸` — a dirty worktree, red tests, or no spec to land. Nothing moved.
 
-**Fields:** `Branch` · `Tests` · `Landed` · `Follow-ups` · `Next`
+**Fields:** `Branch` · `Tests` · `Notes` · `Landed` · `Follow-ups` · `Next`
+
+`Notes` carries the after-land commands §4 ran, and where — or the one that
+failed and the ones that did not run. Nothing about it when none are
+configured.
 
 **No `Spec` field, deliberately.** This skill changes no status and moves no
 folder, and a `Spec` line here would read as though it had. The spec stays

package/package.json

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

@@ -94,6 +94,9 @@ const {
   reviewUrlPath,
   reviewPublishPath,
   readReviewUrl,
+  readRemoteAllow,
+  writeRemoteAllow,
+  withSpecRemote,
   publishedPageNotice,
   reviewServerNotice,
   renderReviewFragment,
@@ -1097,21 +1100,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')
 }
 
@@ -1733,7 +1735,8 @@ function specEnvIntegrate(dir, config, specArg) {
     }
     if (cplan.noop) {
       process.stdout.write(
-        `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n`,
+        `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n` +
+          afterLandSection(cplan.afterLand),
       )
       return
     }
@@ -1741,7 +1744,7 @@ function specEnvIntegrate(dir, config, specArg) {
                   `  base:      ${base}`, `  branch:    ${cplan.branch}`, '',
                   '  run these (abort the rebase on conflict):']
     for (const cmd of cplan.commands) cout.push(`    ${cmd}`)
-    process.stdout.write(cout.join('\n') + '\n')
+    process.stdout.write(cout.join('\n') + '\n' + afterLandSection(cplan.afterLand))
     return
   }
 
@@ -1830,7 +1833,8 @@ function specEnvIntegrate(dir, config, specArg) {
   }
   if (plan.noop) {
     process.stdout.write(
-      `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n`,
+      `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n` +
+        afterLandSection(plan.afterLand),
     )
     return
   }
@@ -1844,7 +1848,17 @@ function specEnvIntegrate(dir, config, specArg) {
   out.push('')
   out.push('  run these (abort the rebase on conflict):')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  process.stdout.write(out.join('\n') + '\n')
+  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
+}
+
+// The `afterLand` commands, as a section printed after a land plan — or after
+// integrate's already-landed line. Empty string when none apply, so a project
+// without the key sees exactly the output it always has.
+function afterLandSection(afterLand) {
+  if (!afterLand || !afterLand.commands || afterLand.commands.length === 0) return ''
+  const out = ['', `  then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`]
+  for (const cmd of afterLand.commands) out.push(`    ${cmd}`)
+  return out.join('\n') + '\n'
 }
 
 // Land a hotfix: tag the branch with the patch-bumped base tag (the prod deploy
@@ -1932,7 +1946,7 @@ function specEnvHotfix(dir, config, positional, flags) {
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
   out.push('')
   out.push(`  then push the deploy tag yourself:  git push origin ${plan.prodTag}`)
-  process.stdout.write(out.join('\n') + '\n')
+  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
 }
 
 // What the primary checkout has GAINED right now, by content. `dir` is already
@@ -2527,24 +2541,32 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
 }
 
 /**
- * `review allow <network|remote> [--off]` — permit or withdraw a review tier.
+ * `review allow <network|remote> [<spec>] [--off | --set <on|off|>] [--project]`
+ * — permit or withdraw a review tier.
  *
- * THE FIRST THING IN THIS ENGINE TO WRITE `env.config.json`, and that is why it
- * is narrow: it reads, sets one key under `review`, and writes back with the
- * indent the file already uses. It never reorders, never adds a key nobody
- * asked for, and never touches another section.
+ * TWO SCOPES, because the two tiers are different kinds of decision.
+ *
+ * `network` is a BIND, and one server binds for every spec at once — so it is a
+ * project setting and lives in the committed `env.config.json`.
  *
- * WHAT WOULD FOOL THIS: a config written with comments. `loadEnvConfig` parses
- * it with `JSON.parse`, so such a file already fails to load and there is no
- * comment-preserving case to protect — but a file indented with anything other
- * than two spaces IS reformatted, which is cosmetic and worth knowing before it
- * shows up in someone's diff.
+ * `remote` PERMITS PUBLISHING, which sends one spec's diff to a third party. It
+ * was project-wide too, and that was bug-remote-review-toggle: typed from a
+ * worktree with a review waiting, it dirtied the base branch's committed config
+ * and permitted every other spec in the repo to publish as well. So it is now
+ * PER SPEC — a sidecar in the gitignored review store, layered over the
+ * committed key by `withSpecRemote`. `--project` keeps the committed write for
+ * a team that wants it everywhere.
+ *
+ * THE COMMITTED WRITE IS NARROW: it reads, sets one key under `review`, and
+ * writes back with two-space indent. It never reorders, never adds a key nobody
+ * asked for, and never touches another section.
  *
- * IT EDITS A COMMITTED FILE. Turning network reviews on for yourself turns them
- * on for everyone who pulls, so the output says so rather than leaving it to be
- * discovered by a colleague's render.
+ * WHAT WOULD FOOL THIS: a config indented with anything other than two spaces
+ * IS reformatted by the committed write — cosmetic, but worth knowing before it
+ * shows up in someone's diff. A config with comments already fails to load, so
+ * there is no comment-preserving case to protect.
  */
-function specEnvReviewAllow(dir, config, tier, flags) {
+function specEnvReviewAllow(dir, config, tier, specArg, flags) {
   const TIERS = { network: 'allowNetwork', remote: 'allowRemote' }
   const key = TIERS[String(tier || '').trim()]
   if (!key) {
@@ -2557,39 +2579,63 @@ function specEnvReviewAllow(dir, config, tier, flags) {
     process.exitCode = 1
     return
   }
-  // THREE WAYS TO SAY WHAT THE TIER SHOULD BE, and only the third is new.
-  // Bare `allow <tier>` turns it ON and `--off` turns it off, exactly as they
-  // always have — every existing caller and test reads those.
-  //
-  // `--set` exists because a SLASH COMMAND can only make one static
-  // substitution: `/spec-remote-review on` has to reach the engine as the word
-  // the person typed, not as a flag the command file worked out. An EMPTY value
-  // is the bare form of that command, and it toggles — which is the common case,
-  // because a reader flipping a tier is looking at the line that says which way
-  // it currently is.
+
+  // WHICH SPEC, for the per-spec scope — resolved before anything is read, so a
+  // refusal changes nothing. An unknown name throws rather than falling back:
+  // permitting the wrong spec to publish looks exactly like permitting the
+  // right one.
+  const perSpec = key === 'allowRemote' && !flags.project
+  let spec = null
+  let out = null
+  if (perSpec) {
+    try {
+      spec = resolveSpecWithWorktree(dir, config, specArg)
+    } catch (err) {
+      process.stdout.write(
+        `spec-env review allow: ${err.message}\n` +
+          '  remote is permitted per spec — name it, or run this from its worktree.\n' +
+          '  --project permits every spec instead (writes the committed env.config.json).\n' +
+          '  Nothing changed.\n',
+      )
+      process.exitCode = 1
+      return
+    }
+    out = reviewOutPath(dir, spec.folder, null)
+  }
+
+  // What the tier is now, through the same precedence the render uses — so a
+  // toggle means "the other thing the render showed".
+  const file = path.resolve(dir, 'specs/.core/env.config.json')
+  const committed = () => {
+    try {
+      const now = JSON.parse(fs.readFileSync(file, 'utf8'))
+      return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
+    } catch {
+      return config.review[key]
+    }
+  }
+  const current = () => {
+    if (perSpec) {
+      const own = readRemoteAllow(out)
+      if (own !== null) return own
+    }
+    return Boolean(committed())
+  }
+
+  // THREE WAYS TO SAY WHAT THE TIER SHOULD BE. Bare `allow <tier>` turns it ON
+  // and `--off` turns it off, exactly as they always have. `--set` exists
+  // because a SLASH COMMAND can only make one static substitution: the word the
+  // person typed reaches the engine as a word. An EMPTY value toggles.
   let on = !flags.off
   if (flags.set !== undefined) {
     const said = String(flags.set).trim().toLowerCase()
     if (said === '') {
-      // Toggle. Read through the same precedence the report below uses, so
-      // "turn it to the other thing" means the other thing the render showed.
-      const current = Boolean(
-        (() => {
-          try {
-            const now = JSON.parse(fs.readFileSync(path.resolve(dir, 'specs/.core/env.config.json'), 'utf8'))
-            return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
-          } catch {
-            return config.review[key]
-          }
-        })(),
-      )
-      on = !current
+      on = !current()
     } else if (said === 'on' || said === 'off') {
       on = said === 'on'
     } else {
-      // Refused by name, like an unknown tier. A misspelt state coerced to a
-      // default is the one outcome worth more than a round trip — and the
-      // wrong default here opens a port or permits a publish.
+      // Refused by name, like an unknown tier. The wrong default here opens a
+      // port or permits a publish.
       process.stdout.write(
         `spec-env review allow: ${JSON.stringify(String(flags.set))} is not a state — ` +
           'one of on, off, or nothing at all to toggle. Nothing changed.\n',
@@ -2598,58 +2644,77 @@ function specEnvReviewAllow(dir, config, tier, flags) {
       return
     }
   }
-  const file = path.resolve(dir, 'specs/.core/env.config.json')
-  let parsed
-  try {
-    parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
-  } catch (err) {
-    // Cannot tell what is in there, so write nothing. Overwriting a config we
-    // could not read is unrecoverable, and the alternative costs one message.
-    //
-    // NARROWER THAN IT LOOKS: `loadEnvConfig` already refuses the whole
-    // `spec-env` command on an unparseable config, naming the file and the
-    // parse position — so this branch is reachable only if the file changes
-    // between that load and this write. It is kept for that race rather than
-    // deleted as dead, and the upstream refusal is what the test asserts.
-    process.stdout.write(
-      `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
-        'nothing changed.\n',
-    )
-    process.exitCode = 1
-    return
+
+  const before = current()
+  let wrote
+  if (perSpec) {
+    wrote = writeRemoteAllow(out, on)
+  } else {
+    let parsed
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch (err) {
+      // Cannot tell what is in there, so write nothing. Reachable only if the
+      // file changes between `loadEnvConfig` and here — that load already
+      // refuses an unparseable config.
+      process.stdout.write(
+        `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
+          'nothing changed.\n',
+      )
+      process.exitCode = 1
+      return
+    }
+    parsed.review = { ...(parsed.review || {}), [key]: on }
+    fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
+    wrote = file
   }
-  const before = Boolean(
-    parsed.review && parsed.review[key] !== undefined ? parsed.review[key] : config.review[key],
-  )
-  parsed.review = { ...(parsed.review || {}), [key]: on }
-  fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
 
   const lines = [
-    `spec-env review allow: ${tier} reviews are now ${on ? 'ON' : 'OFF'}` +
+    `spec-env review allow: ${tier} reviews${spec ? ` for ${spec.folder}` : ''} are now ${on ? 'ON' : 'OFF'}` +
       (before === on ? ' (unchanged)' : ''),
-    // THE ABSOLUTE PATH, not one relative to `dir`. `dir` is re-anchored to the
-    // primary checkout, so run from inside a worktree this writes a file in a
-    // DIFFERENT TREE — and a relative path reads as the tree you are standing
-    // in. Found by running it from a worktree and reverting the surprise.
-    `  wrote: ${file}`,
-    '  that is the primary checkout, whichever tree you ran this from, and the file is',
-    '  COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
+    // THE ABSOLUTE PATH. `dir` is re-anchored to the primary checkout, so run
+    // from a worktree this writes in a different tree — and a relative path
+    // reads as the tree you are standing in.
+    `  wrote: ${wrote}`,
   ]
+  if (perSpec) {
+    lines.push('  this spec only, in the gitignored review store — the committed config is untouched.')
+  } else {
+    lines.push(
+      '  that is the primary checkout, whichever tree you ran this from, and the file is',
+      '  COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
+    )
+  }
   if (key === 'allowNetwork') {
     lines.push(
       on
         ? '  the next render binds every interface, so the page opens on your phone.'
         : '  the next render binds 127.0.0.1 only, reachable from this machine.',
     )
+  } else if (!on) {
+    lines.push(
+      '  publishing is no longer permitted; any page already published stays up.\n' +
+        '  turn it back on with: /spec-remote-review',
+    )
   } else {
     lines.push(
-      on
-        ? '  this PERMITS publishing; it publishes nothing. A published page cannot be\n' +
-          '  deleted by skitterspec, and a verdict there needs /spec-reviewed.\n' +
-          '  turn it back off with: /spec-remote-review'
-        : '  publishing is no longer permitted; any page already published stays up.\n' +
-          '  turn it back on with: /spec-remote-review',
+      '  a published page cannot be deleted by skitterspec,\n' +
+        '  and a verdict there needs /spec-reviewed.\n' +
+        '  turn it back off with: /spec-remote-review',
     )
+    // THE REVIEW IT WAS TYPED FOR. The banner names this command beside a page
+    // the reader cannot reach, so turning remote on is the ask to publish THAT
+    // page — and saying nothing about it left the reader with no link at all.
+    // A page on disk is the positive signal; with none there is nothing to
+    // publish, and nothing is named.
+    if (spec && fs.existsSync(out)) {
+      lines.push(
+        `  review:   ${spec.folder} has a page — publish it and re-show the stack`,
+        `  publish:  skitterspec spec-env review ${spec.folder} --publish-copy`,
+      )
+    } else {
+      lines.push('  this PERMITS publishing; it publishes nothing.')
+    }
   }
   process.stdout.write(lines.join('\n') + '\n')
 }
@@ -2762,6 +2827,9 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
   // CHECKOUT, keyed by the spec's folder name; not one byte of it comes from
   // the worktree. `--out` moves the page and its sidecars together.
   const out = reviewOutPath(dir, spec.folder, flags.out)
+  // This spec's own remote permission over the project default — a
+  // per-worktree decision, never the committed config (bug-remote-review-toggle).
+  config = withSpecRemote(config, out)
 
   // The other half of a confirmation: a pass the operator says is not theirs.
   // Left in the store it is reported on every render until they stop reading the
@@ -5065,6 +5133,7 @@ async function specEnv(rest) {
     else if (args[i] === '--stop') flags.stop = true
     else if (args[i] === '--rotate-token') flags.rotateToken = true
     else if (args[i] === '--off') flags.off = true
+    else if (args[i] === '--project') flags.project = true
     else if (args[i] === '--status') flags.status = true
     else if (args[i] === '--port') flags.port = args[++i]
     else if (args[i] === '--host') flags.host = args[++i]
@@ -5230,7 +5299,7 @@ async function specEnv(rest) {
         break
       }
       if (positional[0] === 'allow') {
-        specEnvReviewAllow(dir, config, positional[1], flags)
+        specEnvReviewAllow(dir, config, positional[1], positional[2], flags)
         break
       }
       if (positional[0] === 'skip') {
@@ -5250,7 +5319,8 @@ async function specEnv(rest) {
         `Usage: skitterspec spec-env <${SPEC_ENV_VERBS.join('|')}> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--run-reviewers] [--notes <json>] [--verdict <word>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n` +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
         '  review serve --rotate-token    mint a new URL token; every handed-out link dies\n' +
-        '  review allow <network|remote> [--off]  permit a review tier (writes env.config.json)\n' +
+        '  review allow <network|remote> [<spec>] [--off] [--project]  permit a review tier\n' +
+        '                                   (network: env.config.json; remote: this spec only)\n' +
           '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
           '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
           '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +

package/src/env/config.js

@@ -24,6 +24,9 @@
  *               // setup runs (mode: "symlink" default | "copy"); empty = none
  *     setup:    [ "cmd", ... ],  // bootstrap commands run in the worktree right
  *               // after `git worktree add` (e.g. install deps); empty = none
+ *     afterLand:[ "cmd", ... ],  // commands run in the PRIMARY checkout after a
+ *               // land (integrate's ff, hotfix land's main cherry-pick), e.g. a
+ *               // data migration; literal, no token expansion; empty = none
  *     dev:      [ { name, command, portVar, health?, frontPort? } ],  // host dev
  *               // servers started on the spec's port block (empty = none)
  *     proxy:    { enabled, host },  // bundled front-door proxy (spec-env connect)
@@ -166,6 +169,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // `git worktree add` (before Docker/dev), on every provision. Array of shell
   // strings (e.g. "pnpm install"); {slug}/{branch}/… expand. Default: none.
   setup: Object.freeze([]),
+  // Commands run in the primary checkout after a land, printed by `spec-env
+  // integrate` (including its already-landed no-op) and by `hotfix land` when
+  // it cherry-picks onto the base branch. The skill runs them; the engine only
+  // plans. Literal strings — no {slug}/{port} tokens, since they run on the base
+  // branch where a spec's tokens mean nothing. Default: none.
+  afterLand: Object.freeze([]),
   // Host dev servers started on the spec's port block by `spec-env dev up`.
   // Each: { name, command, portVar, health?, frontPort? }. Default: none.
   dev: Object.freeze([]),
@@ -332,6 +341,7 @@ function defaults() {
     docker: { ...DEFAULT_CONFIG.docker },
     seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
     setup: [],
+    afterLand: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
     registry: DEFAULT_CONFIG.registry,
@@ -542,6 +552,11 @@ function mergeConfig(base, parsed) {
     base.setup = normalizeSetup(parsed.setup)
   }
 
+  // Same rule as `setup`: a stray entry is dropped, never thrown on.
+  if (Array.isArray(parsed.afterLand)) {
+    base.afterLand = normalizeSetup(parsed.afterLand)
+  }
+
   if (Array.isArray(parsed.dev)) {
     base.dev = normalizeDev(parsed.dev)
   }

package/src/env/hotfix.js

@@ -21,6 +21,7 @@
  */
 
 const path = require('node:path')
+const { afterLandFor } = require('./integrate.js')
 
 /**
  * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
@@ -50,7 +51,7 @@ function tagSlug(tag) {
  * @param {object} config normalised env config (reads `config.hotfix`).
  * @param {object} ctx   { worktreeState:{dirty}, aheadOfBase, fixRange, mainRepoPath,
  *                          base, extraTargets: string[], existingTags: string[] }
- * @returns {object} { blocked, noop, reason, commands, prodTag, targets, branch, base }
+ * @returns {object} { blocked, noop, reason, commands, afterLand, prodTag, targets, branch, base }
  */
 function planHotfixLand(spec, config, ctx) {
   const c = ctx || {}
@@ -62,6 +63,7 @@ function planHotfixLand(spec, config, ctx) {
     noop: false,
     reason: null,
     commands: [],
+    afterLand: afterLandFor(null),
     prodTag: null,
     targets: [],
     branch,
@@ -122,12 +124,16 @@ function planHotfixLand(spec, config, ctx) {
   }
 
   // 3. Cherry-pick the fix onto the base branch (main) for the next release.
+  //    Only then does the primary checkout gain anything, so only then do the
+  //    after-land commands apply — a prod-only land leaves main untouched.
+  let afterLand = result.afterLand
   if (hotfixCfg.cherryPickMain !== false) {
     commands.push(`git -C ${c.mainRepoPath} cherry-pick ${fixRange}`)
     targets.push({ kind: 'main', base: c.base })
+    afterLand = afterLandFor(config, c.mainRepoPath)
   }
 
-  return { ...result, commands, prodTag, targets, fixRange }
+  return { ...result, commands, afterLand, prodTag, targets, fixRange }
 }
 
 module.exports = { bumpPatch, tagSlug, planHotfixLand }

package/src/env/integrate.js

@@ -15,28 +15,32 @@
  * hands back — so the planner never needs to reason about conflicts.
  *
  * @param {object} spec  resolved spec: { branch, worktreePath, folder, ... }
- * @param {object} config normalised env config (unused today; kept for symmetry).
+ * @param {object} config normalised env config (reads `afterLand`).
  * In CHECKOUT mode there is no worktree: the branch is already checked out in the
  * primary checkout, so landing is a rebase in place, a switch to base, and the
  * fast-forward. `planIntegrateCheckout` below covers that; the shape of what it
  * returns is identical so callers need no second code path.
  *
  * @param {object} ctx   { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath }
- * @returns {object} { blocked, noop, reason, commands, base, branch }
+ * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
  */
 function planIntegrate(spec, config, ctx) {
   const { worktreeState = {}, base, aheadOfBase, mainRepoPath } = ctx || {}
   const branch = spec.branch
-  const result = { blocked: false, noop: false, reason: null, commands: [], base, branch }
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
 
   // The completion edits must be committed first — never rebase a dirty tree.
   if (worktreeState.dirty) {
     return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the completion first' }
   }
 
-  // Nothing on the branch that isn't already on base → already landed.
+  // Nothing on the branch that isn't already on base → already landed. The
+  // after-land commands still apply: the land may have happened on another
+  // machine or in an earlier session, leaving them pending in THIS checkout.
   if (!aheadOfBase) {
-    return { ...result, noop: true }
+    return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath) }
   }
 
   return {
@@ -45,6 +49,7 @@ function planIntegrate(spec, config, ctx) {
       `git -C ${spec.worktreePath} rebase ${base}`,
       `git -C ${mainRepoPath} merge --ff-only ${branch}`,
     ],
+    afterLand: afterLandFor(config, mainRepoPath),
   }
 }
 
@@ -65,7 +70,9 @@ function planIntegrate(spec, config, ctx) {
 function planIntegrateCheckout(spec, config, ctx) {
   const { dirty, base, aheadOfBase, checkoutPath, onBranch } = ctx || {}
   const branch = spec.branch
-  const result = { blocked: false, noop: false, reason: null, commands: [], base, branch }
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
 
   // "Already landed" is answered FIRST, before any refusal. A landed spec needs
   // no action wherever the checkout happens to be standing — and after a
@@ -73,7 +80,7 @@ function planIntegrateCheckout(spec, config, ctx) {
   // would refuse the very spec this just finished landing. /spec-complete calls
   // integrate again on exactly that state.
   if (!aheadOfBase) {
-    return { ...result, noop: true }
+    return { ...result, noop: true, afterLand: afterLandFor(config, checkoutPath) }
   }
   if (dirty) {
     return {
@@ -100,7 +107,20 @@ function planIntegrateCheckout(spec, config, ctx) {
       `git -C ${checkoutPath} switch ${base}`,
       `git -C ${checkoutPath} merge --ff-only ${branch}`,
     ],
+    afterLand: afterLandFor(config, checkoutPath),
   }
 }
 
-module.exports = { planIntegrate, planIntegrateCheckout }
+// The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
+// primary checkout, standing on base) once the land commands have succeeded.
+// A blocked plan carries the empty form — nothing landed, so nothing follows.
+function afterLandFor(config, cwd) {
+  const commands = (config && Array.isArray(config.afterLand)) ? [...config.afterLand] : []
+  return { cwd: commands.length ? cwd : null, commands }
+}
+
+function noAfterLand() {
+  return { cwd: null, commands: [] }
+}
+
+module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor }

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/review.js

@@ -668,7 +668,13 @@ function surfacesFor({ live, tiers, buttons = null }) {
       // the primary checkout — changing behaviour for everyone who pulls and
       // leaving that tree dirty. A setting change of that reach must not land
       // because someone tapped a button labelled only `Allow remote`.
-      note: t.note || 'writes env.config.json — committed, and shared',
+      // `remote` is per spec now (bug-remote-review-toggle): a gitignored
+      // sidecar, so the base branch is untouched and no other spec may publish.
+      note:
+        t.note ||
+        (t.tier === 'remote'
+          ? 'this spec only — nothing committed'
+          : 'writes env.config.json — committed, and shared'),
       // The same thing from a terminal, for the reader who is nowhere near the
       // page. Only `remote` has a command of its own: `network` is ON by
       // default, so turning it off is a rare deliberate act and a slash command
@@ -2391,6 +2397,46 @@ function readReviewUrl(outPath) {
   }
 }
 
+/**
+ * Whether ONE SPEC may publish, beside its page in the gitignored store.
+ *
+ * WHY PER SPEC. `review.allowRemote` in the committed config permits every
+ * spec in the repo at once, and writing it from a worktree dirtied the base
+ * branch (bug-remote-review-toggle). Publishing sends a diff to a third party,
+ * so what may generate an artifact is decided per worktree; the committed key
+ * stays as the project default beneath it.
+ */
+function reviewRemotePath(outPath) {
+  return outPath.replace(/\.html$/, '') + '.remote.json'
+}
+
+// true / false when the sidecar says so, null for every cannot-tell — absent,
+// unreadable, a non-boolean — so the committed default stands
+// (`.claude/rules/negative-checks.md` rule 4: a typo must not permit a publish).
+function readRemoteAllow(outPath) {
+  try {
+    const v = JSON.parse(fs.readFileSync(reviewRemotePath(outPath), 'utf8')).allowRemote
+    return typeof v === 'boolean' ? v : null
+  } catch {
+    return null
+  }
+}
+
+function writeRemoteAllow(outPath, on, at = new Date().toISOString()) {
+  const file = reviewRemotePath(outPath)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify({ allowRemote: on, at }, null, 2) + '\n')
+  return file
+}
+
+// The config one spec's render reads: the project's, with this spec's own
+// remote permission over it. A new object — the caller's config is shared.
+function withSpecRemote(config, outPath) {
+  const own = readRemoteAllow(outPath)
+  if (own === null) return config
+  return { ...config, review: { ...config.review, allowRemote: own } }
+}
+
 // Default output path for a spec's page, under the gitignored `.spec-env/`.
 function reviewOutPath(dir, specFolder, out) {
   if (out) return path.resolve(dir, out)
@@ -2512,6 +2558,10 @@ module.exports = {
   reviewUrlPath,
   reviewPublishPath,
   readReviewUrl,
+  reviewRemotePath,
+  readRemoteAllow,
+  writeRemoteAllow,
+  withSpecRemote,
   publishedPageNotice,
   reviewServerNotice,
   fragmentTemplate,

package/src/env/serve.js

@@ -46,6 +46,7 @@ const {
   renderReviewPage,
   renderReviewBlock,
   reviewOutPath,
+  withSpecRemote,
   validateNotesBlob,
   readPending,
   passState: readPassState,
@@ -595,7 +596,9 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
     receipt: null,
     worktreeExists: Boolean(spec.worktreePath && fs.existsSync(spec.worktreePath)),
   })
-  const tiers = pageTiers(config)
+  // This spec's own remote permission, read per request so a toggle shows on
+  // the next refresh without restarting the server.
+  const tiers = pageTiers(withSpecRemote(config, out))
 
   let data = collectReview({
     spec,

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)}` +