@skitterbyte/skitterspec 22.4.0 → 23.0.0

package/MIGRATION.md

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

package/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

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

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

package/assets/rules/spec-planning.md

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

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

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

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

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

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

package/assets/skills/spec-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-hotfix/SKILL.md

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

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

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