@skitterbyte/skitterspec-jira 1.0.0 → 2.0.0

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

@@ -1,10 +1,10 @@
 ---
 name: spec-status
-description: Show a spec's one-way sync status against Jira — a read-only drift report naming what would push, and whether the tracker's status has drifted from the spec's. Changes nothing. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-status", "is this spec in sync with Jira", "what would push", or "show spec sync status".
+description: Show a spec's one-way sync status against Jira — a read-only report naming what would push, and whether someone edited the issue's description since the last push. Changes nothing. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-status", "is this spec in sync with Jira", "what would push", or "show spec sync status".
 disable-model-invocation: true
 ---
 
-# /spec-status — one-way sync drift report
+# /spec-status — one-way sync report
 
 > Stay silent while this runs — speak only to ask something you cannot answer
 > yourself, or to report a failure at the moment it happens. Read
@@ -15,13 +15,17 @@ Read-only. Reports two things and writes nothing:
 
 1. **Pending push** — has the spec changed since the last push (is there an issue
    description/state or any phase subtask to create or update)?
-2. **State drift** — does Jira's issue status differ from the spec's status?
-   (The repo wins on the next push; this is just a heads-up, e.g. a card moved
-   on the board.)
+2. **Description edited** — did someone edit the issue's description on Jira
+   since the last push? The next push replaces it, so this is worth reading
+   first.
+
+**Status is not compared, deliberately.** Skitterspec tells Jira about its
+own transitions and never reads a status back: a card someone moved by hand is
+theirs to have moved, and push resends State only when the spec itself moves.
 
 The repo is the source of truth; Jira is a generated mirror, so there is no
-per-field "conflict" — only "what would the next push send" and "did the mirror
-drift".
+per-field "conflict" — only "what would the next push send" and "did someone
+write over the mirror's text".
 
 **Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
 tell the user how to enable Jira sync and stop.
@@ -30,18 +34,16 @@ tell the user how to enable Jira sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Fetch the Jira issue (optional, for drift)
+## 2. Fetch the Jira issue (optional, for the description check)
 
 If the spec has a `jira_identifier`, discover the Jira MCP read tool
 (`getJiraIssue`) and write the issue JSON to a temp file. If Jira isn't
-connected, skip the drift lines (still report pending-push).
+connected, skip the description check (still report pending-push).
 
-**Write the whole issue, including its `description`.** The engine reports two
-independent kinds of drift off that one file: the status someone moved, and the
-**description someone edited**. Write only the status fields and the second
-check has nothing to look at — and it says nothing rather than guessing, so the
-loss is silent. Keep `url` too: it is what the description line points the
-reader at.
+**Write the whole issue, including its `description`.** That is the field the
+check reads; without it the check has nothing to look at — and it says nothing
+rather than guessing, so the loss is silent. Keep `url` too: it is what the
+description line points the reader at.
 
 **The description itself never enters the conversation.** The engine hashes it
 and compares hashes; what it prints is *that* the text changed, plus where to
@@ -58,8 +60,9 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
 ```
 
 - Reports `push: pending — N to create, M to update` or `up to date`.
-- With `--remote`, adds a `drift:` line comparing Jira's issue status to the
-  spec's status.
+- With `--remote`, adds a `drift:` line when the issue's description was
+  edited on Jira since the last push, and nothing otherwise. It never
+  reports the issue's state.
 - With `--workspace-states`, fails loudly if a configured status name isn't in
   the project (no workflow transition could ever reach it, so the push would
   refuse at apply time).
@@ -88,18 +91,17 @@ the shape; this section carries only what is specific here.
 **Verdicts**
 
 - `✅` — in sync; nothing would push.
-- `⚠️` — drift: N objects would push, Jira's status was moved by hand, or the
-  issue's **description** was edited on Jira since the last push. None is an
-  error — the repo wins on the next push — but all are the reason someone ran
-  this. **Say which**, since the three call for different things: a pending push
-  is routine, a moved status is usually someone else's automation, and an edited
-  description means a person wrote something that the next push replaces.
+- `⚠️` — N objects would push, or the issue's **description** was edited on
+  Jira since the last push. Neither is an error, but both are the reason
+  someone ran this. **Say which**, since they call for different things: a
+  pending push is routine, and an edited description means a person wrote
+  something that the next push replaces.
 - `⏸` — no config, or the spec is not linked. Nothing to compare.
 
 **Fields:** `Tracker` · `Follow-ups` · `Next`
 
-`Tracker` is the drift in one line — what would push, and whether the tracker's
-status diverged. `Next` is `/spec-push` when a push is pending, and nothing to
+`Tracker` is the answer in one line — what would push, and whether the
+description was edited. `Next` is `/spec-push` when a push is pending, and nothing to
 do when it is not.
 
 A **`phases: <mode>`** line names the phase mode that resolved for this spec's

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

@@ -44,7 +44,7 @@ In a project that installs the Jira superset the binary is
 | "link this spec to PROJ-1 by hand" | `stamp <spec> --issue PROJ-1` |
 | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
 | "what ticket am I on?", writing a commit | `ref` |
-| "what shipped in this release?" | `released` |
+| "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
 | "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and credentials in one |
 | "set my Jira credentials", "am I authenticated?" | `credentials <status\|set\|unset>` |
 | push one spec, or "what would push?" | **defer** — see below |
@@ -66,7 +66,7 @@ Two front doors to one write path is worse than none:
 
 - **Push one spec** → `/spec-push`. It owns the transport choice, the
   status-name gate, the plan, the apply, the stamping and the snapshot.
-- **Per-spec drift** ("is this spec in sync?", "what would push?") →
+- **Per-spec status** ("is this spec in sync?", "what would push?") →
   `/spec-status`.
 
 Say which skill you're handing to and stop; don't reimplement either.
@@ -170,8 +170,10 @@ and never write `Refs: none`.
 
 `released` reports the tickets in a commit range — by default since the most
 recent tag, and it always prints the range it chose so a wrong default is
-visible. It is **read-only**: it does not move anything in Jira. A release can
-be cut and never deployed, so transitioning tickets stays a deliberate act.
+visible. It is **read-only**: it does not move anything in Jira. Each ticket
+row names the `spec` and `url` behind it (`null` when no spec linked the ref),
+so `--json` is what a project's CI pipes into its own tooling to record a
+release or a deploy. Recording those is the project's job, not skitterspec's.
 
 Relay the **unreferenced count** even when it is zero. A chore commit
 legitimately carries no ticket and a *missed* trailer looks identical, so

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

@@ -91,7 +91,9 @@ and continue — the branch has no commits base doesn't already have.
 `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
+need them. Run only the lines under that heading; a
+`skipped (nothing in the land matched):` block lists conditional entries this
+land did not need, and is information, never commands. 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**.
@@ -129,8 +131,8 @@ the shape; this section carries only what is specific here.
 
 **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
+`Notes` carries the after-land commands §4 ran, and where, and any it
+skipped because the land matched no `when` — 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

package/bin/skitterspec-jira.js

@@ -20,6 +20,13 @@ if (!existsSync(join(__dirname, '..', 'src'))) {
 }
 
 const { run, HELP } = require('../src/cli.js')
+
+// The provider's isolation defaults, registered beneath the project's own
+// env.config.json so `spec-env stage` claims this provider's snapshot sidecar
+// without a hand edit (see common src/env/config.js, setProviderEnvDefaults).
+require('../src/env/config.js').setProviderEnvDefaults(
+  require('../src/vendor/jira/config.js').ENV_CONFIG_DEFAULTS,
+)
 const {
   PROVIDER_COMMANDS,
   providerHelpSection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-jira",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -88,6 +88,8 @@ const {
   collectReview,
   reviewTierStack,
   reviewTierLine,
+  isTailnetAddress,
+  tailnetLabel,
   renderReviewPage,
   renderReviewBlock,
   reviewOutPath,
@@ -165,7 +167,13 @@ const { planHotfixLand, planHotfixFinish } = require('./env/hotfix.js')
 const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
 const { planDev } = require('./env/dev.js')
 const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
-const { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
+const {
+  renderRoutes,
+  portsHeld,
+  portsAnswering,
+  portsInUseOn,
+  waitListening,
+} = require('./env/proxy.js')
 const {
   mintToken,
   servableSpecs,
@@ -185,7 +193,7 @@ const pkg = require('../package.json')
 // supersets the hand-off names both where both ship the command, and the one
 // that does where only one does.
 const PROVIDER_COMMANDS = {
-  'spec-sync': '@skitterbyte/skitterspec-linear or @skitterbyte/skitterspec-jira',
+  'spec-sync': '@skitterbyte/skitterspec-linear, @skitterbyte/skitterspec-jira, @skitterbyte/skitterspec-github or @skitterbyte/skitterspec-azure-boards',
   'spec-sanitise': '@skitterbyte/skitterspec-linear',
 }
 
@@ -1914,6 +1922,7 @@ function specEnvIntegrate(dir, config, specArg) {
       aheadOfBase: cahead !== null && Number(cahead) > 0,
       checkoutPath: dir,
       onBranch: cgit(['rev-parse', '--abbrev-ref', 'HEAD']) === spec.branch,
+      changedFiles: landRange(cgit, base, spec.branch),
     })
     if (cplan.blocked) {
       process.stdout.write(`spec-env integrate: blocked — ${cplan.reason}.\n`)
@@ -2011,6 +2020,7 @@ function specEnvIntegrate(dir, config, specArg) {
     base,
     aheadOfBase,
     mainRepoPath: dir,
+    changedFiles: landRange(gitReader(dir), base, spec.branch),
   })
 
   if (plan.blocked) {
@@ -2037,13 +2047,47 @@ function specEnvIntegrate(dir, config, specArg) {
   process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
 }
 
+// The files a land brings into the base branch: `base...branch`, merge-base to
+// the branch tip. Read before the rebase runs, so it is the branch's own
+// changes — `base..branch` would also list what the base gained meanwhile and
+// over-match. A diff git would not answer is null: unknown, never empty.
+function landRange(git, base, branch) {
+  const out = git(['diff', '--name-only', `${base}...${branch}`])
+  if (out === null) return null
+  return out.split('\n').map((l) => l.trim()).filter(Boolean)
+}
+
 // 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.
+// without the key sees exactly the output it always has, and one of plain
+// strings sees exactly what it saw before entries could be conditional.
 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}`)
+  if (!afterLand || !afterLand.entries || afterLand.entries.length === 0) return ''
+  const entries = afterLand.entries
+  const ran = entries.filter((e) => e.decision !== 'skipped')
+  const skipped = entries.filter((e) => e.decision === 'skipped')
+  const width = Math.max(...entries.map((e) => e.run.length))
+  const out = ['']
+  if (ran.length) {
+    out.push(`  then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`)
+    for (const e of ran) {
+      // The reason is a shell COMMENT, not prose after a dash: these lines are
+      // run as printed, and `cmd — path changed` would hand the command two
+      // stray arguments.
+      if (e.decision === 'matched') out.push(`    ${e.run.padEnd(width)}   # ${e.matched} changed`)
+      else if (e.decision === 'unknown') out.push(`    ${e.run.padEnd(width)}   # range unknown`)
+      else out.push(`    ${e.run}`)
+    }
+  } else {
+    out.push(`  after-land, in the primary checkout (${afterLand.cwd}): nothing to run.`)
+  }
+  if (ran.some((e) => e.decision === 'unknown')) {
+    out.push("  the land's changed files are unknown here, so the conditional entries run.")
+  }
+  if (skipped.length) {
+    out.push('  skipped (nothing in the land matched):')
+    for (const e of skipped) out.push(`    ${e.run.padEnd(width)}   # when ${e.when.join(', ')}`)
+  }
   return out.join('\n') + '\n'
 }
 
@@ -2105,6 +2149,12 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
       .map((l) => l.slice(2).trim()),
   )
   const commits = fixCommits.filter((sha) => !already.has(sha))
+  // What main gains from the whole fix, for afterLand's `when` — taken from
+  // every fix commit rather than the remaining ones, so a carry resumed after a
+  // partial run still sees what the earlier picks changed. A commit git would
+  // not describe makes the range unknown (null), which runs the conditional
+  // entries rather than skipping them.
+  const files = carryFiles(wtGit, fixCommits)
 
   // Which checkout, if any, has the base branch checked out.
   const list = git(['worktree', 'list', '--porcelain']) || ''
@@ -2117,14 +2167,24 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
   let carry
   if (where) {
     const st = gitReader(where)(['status', '--porcelain'])
-    carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits }
+    carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits, files }
   } else {
     const tmpPath = path.join(path.dirname(spec.worktreePath), `${spec.slug}-carry-${base}`)
-    carry = { strategy: 'worktree', path: dir, tmpPath, commits }
+    carry = { strategy: 'worktree', path: dir, tmpPath, commits, files }
   }
   return { fixCommits, carry }
 }
 
+function carryFiles(git, commits) {
+  const files = new Set()
+  for (const sha of commits) {
+    const out = git(['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
+    if (out === null) return null
+    for (const line of out.split('\n')) if (line.trim()) files.add(line.trim())
+  }
+  return [...files]
+}
+
 // `hotfix finish`: tear a landed hotfix down once its deploy is out. The guards
 // live in `planHotfixFinish`; this gathers the facts, refuses from inside the
 // worktree it is about to remove, and runs the two git commands itself.
@@ -4200,6 +4260,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
       // use, and the engine cannot know — that guess failed three separate ways
       // in one day. Now every tier is listed, labelled, and either a URL or the
       // one command that turns it on.
+      // The runners-up print as `also:` lines inside the network tier's own
+      // rendering — `reviewTierLine` carries them, which is what puts them
+      // under `network:` rather than dangling after the stack (they used to
+      // print below `remote:`, against the comment that placed them).
       reviewTierStack({
         served,
         fileUrl: reviewFileUrl(out),
@@ -4208,11 +4272,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
       })
         .map((t) => reviewTierLine(t) + '\n')
         .join('') +
-      // The runners-up sit UNDER the network tier, because that is what they are
-      // alternatives to — and virtual adapters are gone from them entirely.
-      (served && !served.loopback && (served.alternates || []).length
-        ? served.alternates.map((u) => `    also:  ${u}\n`).join('')
-        : '') +
       // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
       // `network` are two doors into one room — the page POSTs to
       // `location.pathname`, so both reach this server and this pending store.
@@ -4514,8 +4573,14 @@ function lanAddresses(nets = require('node:os').networkInterfaces()) {
  * where the opposite hides the only address that works.
  */
 function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
-  return rankLanAddresses(nets)
+  const ranked = rankLanAddresses(nets)
+  // A tailnet address IS reachable from a phone off the LAN, but macOS puts it
+  // on `utunN`, which the virtual filter drops. It is appended after every
+  // other offerable address so the wifi one stays the best guess at home.
+  const tailnet = ranked.filter((e) => VIRTUAL_IFACE.test(e.iface) && isTailnetAddress(e.address))
+  return ranked
     .filter((e) => !VIRTUAL_IFACE.test(e.iface))
+    .concat(tailnet)
     .map((e) => e.address)
 }
 
@@ -4988,7 +5053,7 @@ async function specEnvConnect(dir, config, specArg) {
   // Stop any proxy we already run (a previous connect), freeing the canonical
   // ports, then refuse if the primary checkout still holds one of them.
   await stopProcess(proxyProc, { rootDir: dir })
-  const busy = await portsInUse(routes.map((r) => r.frontPort), config.proxy.host)
+  const busy = await portsHeld(routes.map((r) => r.frontPort), config.proxy.host)
   if (busy.length) {
     process.stdout.write(
       `spec-connect: canonical port(s) ${busy.join(', ')} are in use (your main dev server?).\n` +
@@ -5199,7 +5264,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
   const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
   let serverUp = null
   if (canonicalPorts.length) {
-    const up = await portsInUse(canonicalPorts, config.proxy.host)
+    const up = await portsAnswering(canonicalPorts, config.proxy.host)
     serverUp = up.length === canonicalPorts.length
   }
 
@@ -5892,6 +5957,7 @@ module.exports = {
   unknownCommand,
   rankLanAddresses,
   offerableLanAddresses,
+  tailnetLabel,
   reviewTierStack,
   serveProcFor,
   serverScriptOk,

package/src/env/config.js

@@ -22,11 +22,16 @@
  *     seedFiles:{ mode, files } | [ ".env", ... ],  // gitignored files copied/
  *               // symlinked from the main checkout into a fresh worktree before
  *               // 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
+ *     setup:    [ "cmd" | { run, when }, ... ],  // bootstrap commands run in
+ *               // the worktree right after `git worktree add` (e.g. install
+ *               // deps); `when` is ignored there — normalised to strings, with
+ *               // the triggered entries also kept as `setupTriggers`
+ *     afterLand:[ "cmd" | { run, when } | { setup: true }, ... ],  // commands
+ *               // run in the PRIMARY checkout after a land (integrate's ff,
+ *               // hotfix land's main cherry-pick), e.g. a data migration;
+ *               // `when` globs gate an entry on the land's changed files, and
+ *               // `{ setup: true }` expands to `setupTriggers`; literal, no
+ *               // token expansion; normalised to `{ run, when }`; 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)
@@ -169,11 +174,16 @@ 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([]),
+  // The `setup` entries that declared `when` globs, as `{ run, when }`. Derived
+  // at load, never configured directly: `afterLand`'s `{ setup: true }` expands
+  // to these, so a setup step can re-run after a land that changes its inputs.
+  setupTriggers: 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.
+  // branch where a spec's tokens mean nothing. Normalised to `{ run, when }`,
+  // `when` null for an always-run entry. 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.
@@ -352,6 +362,7 @@ function defaults() {
     docker: { ...DEFAULT_CONFIG.docker },
     seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
     setup: [],
+    setupTriggers: [],
     afterLand: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
@@ -524,11 +535,49 @@ function normalizeSeedFiles(parsed) {
  * stray entry can't crash provisioning.
  */
 function normalizeSetup(parsed) {
+  return normalizeCommands(parsed).map((e) => e.run)
+}
+
+/**
+ * Normalise a list of command entries into `{ run, when }`. A string is an
+ * always-run entry (`when: null`); `{ run, when }` keeps its trigger globs, with
+ * a string `when` coerced to a one-item list. An object whose `run` is blank, or
+ * whose `when` holds no usable glob, is dropped rather than demoted to
+ * always-run — a malformed trigger must not quietly widen into "every time".
+ */
+function normalizeCommands(parsed) {
   const out = []
   for (const raw of parsed) {
-    if (typeof raw !== 'string') continue
-    const cmd = raw.trim()
-    if (cmd) out.push(cmd)
+    if (typeof raw === 'string') {
+      const run = raw.trim()
+      if (run) out.push({ run, when: null })
+      continue
+    }
+    if (!isObject(raw) || typeof raw.run !== 'string') continue
+    const run = raw.run.trim()
+    if (!run) continue
+    if (raw.when === undefined) {
+      out.push({ run, when: null })
+      continue
+    }
+    const globs = typeof raw.when === 'string' ? [raw.when] : Array.isArray(raw.when) ? raw.when : []
+    const when = normalizeFileList(globs)
+    if (when.length) out.push({ run, when })
+  }
+  return out
+}
+
+// `afterLand` entries: `normalizeCommands`, plus `{ setup: true }` expanded in
+// place to the triggered setup entries. With none declared it expands to
+// nothing — the shorthand names a set, and an empty set is a valid one.
+function normalizeAfterLand(parsed, setupTriggers) {
+  const out = []
+  for (const raw of parsed) {
+    if (isObject(raw) && raw.setup === true) {
+      for (const t of setupTriggers) out.push({ run: t.run, when: [...t.when] })
+      continue
+    }
+    out.push(...normalizeCommands([raw]))
   }
   return out
 }
@@ -560,12 +609,15 @@ function mergeConfig(base, parsed) {
   }
 
   if (Array.isArray(parsed.setup)) {
-    base.setup = normalizeSetup(parsed.setup)
+    const entries = normalizeCommands(parsed.setup)
+    base.setup = entries.map((e) => e.run)
+    base.setupTriggers = entries.filter((e) => e.when)
   }
 
-  // Same rule as `setup`: a stray entry is dropped, never thrown on.
+  // Same rule as `setup`: a stray entry is dropped, never thrown on. Read after
+  // `setup`, which `{ setup: true }` expands from.
   if (Array.isArray(parsed.afterLand)) {
-    base.afterLand = normalizeSetup(parsed.afterLand)
+    base.afterLand = normalizeAfterLand(parsed.afterLand, base.setupTriggers)
   }
 
   if (Array.isArray(parsed.dev)) {
@@ -707,6 +759,48 @@ function mergeConfig(base, parsed) {
  * It is advisory in the strongest sense: nothing here acts on it, and a config
  * full of strays loads exactly as it always did.
  */
+// The isolation keys a ticketing provider needs a project to declare — set
+// once per process by a provider superset's bin, beneath whatever the
+// project's own env.config.json says. They used to reach only the
+// `env.config.json.example` composed at build time, which left every project
+// that adopted a provider over an EXISTING isolation config (or skipped the
+// example) with a `spec.companionPaths` that never claims the provider's
+// snapshot sidecar — `spec-env stage` then classifies the spec's own
+// `<baseDir>/<identifier>.base.json` as foreign and `/commit` leaves it
+// behind. The base distribution registers nothing and behaves as before.
+let providerEnvDefaults = null
+function setProviderEnvDefaults(overrides) {
+  providerEnvDefaults = overrides || null
+}
+
+// Fill ONLY the keys the project's file does not mention: a key the file sets —
+// including explicitly to '' or [] — is the project's decision and stands
+// ("the two keys are one fix" in scripts/build-dist.test.js is the contract:
+// blanking identifierField must keep disabling the companion expansion).
+function applyProviderEnvDefaults(config, parsed) {
+  if (!providerEnvDefaults) return config
+  const d = providerEnvDefaults
+  const pBranch = parsed && typeof parsed.branch === 'object' && parsed.branch !== null ? parsed.branch : null
+  if (
+    d.branch &&
+    typeof d.branch.identifierField === 'string' &&
+    !(pBranch && 'identifierField' in pBranch) &&
+    !config.branch.identifierField
+  ) {
+    config.branch.identifierField = d.branch.identifierField
+  }
+  const pSpec = parsed && typeof parsed.spec === 'object' && parsed.spec !== null ? parsed.spec : null
+  if (
+    d.spec &&
+    Array.isArray(d.spec.companionPaths) &&
+    !(pSpec && 'companionPaths' in pSpec) &&
+    !config.spec.companionPaths.length
+  ) {
+    config.spec.companionPaths = [...d.spec.companionPaths]
+  }
+  return config
+}
+
 function loadEnvConfig(dir = process.cwd()) {
   const base = defaults()
   const file = join(dir, CONFIG_FILE)
@@ -715,7 +809,9 @@ function loadEnvConfig(dir = process.cwd()) {
   try {
     raw = readFileSync(file, 'utf-8')
   } catch (error) {
-    if (error.code === 'ENOENT') return { config: base, present: false, unknown: [], badReviewers: [] }
+    if (error.code === 'ENOENT') {
+      return { config: applyProviderEnvDefaults(base, null), present: false, unknown: [], badReviewers: [] }
+    }
     throw error
   }
 
@@ -727,7 +823,7 @@ function loadEnvConfig(dir = process.cwd()) {
   }
 
   return {
-    config: mergeConfig(base, parsed),
+    config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
     present: true,
     unknown: collectUnknownKeys(parsed),
     badReviewers: collectBadReviewers(parsed),
@@ -736,6 +832,7 @@ function loadEnvConfig(dir = process.cwd()) {
 
 module.exports = {
   loadEnvConfig,
+  setProviderEnvDefaults,
   resolveServePort,
   derivedServePort,
   servePortRoot,

package/src/env/glob.js

@@ -0,0 +1,34 @@
+'use strict'
+
+/**
+ * Restricted glob matching for repo-relative paths, shared by the live-overlay
+ * migration check and the conditional `afterLand` entries. Zero-dependency.
+ */
+
+// Translate a restricted glob into an anchored RegExp: `**` matches across path
+// separators (with an optional trailing `/`), `*` matches within a segment, `?`
+// a single non-separator char. Enough for repo-path globs, no dependency.
+function globToRegExp(glob) {
+  let re = ''
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i]
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*'
+        i++
+        if (glob[i + 1] === '/') i++ // consume the `/` in `**/`
+      } else {
+        re += '[^/]*'
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+    } else if ('.+^${}()|[]\\/'.includes(ch)) {
+      re += '\\' + ch
+    } else {
+      re += ch
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+module.exports = { globToRegExp }