shapeup-sdlc 3.1.0 → 3.1.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Shape Up SDLC harness for Claude Code: shaping, intake, orient, scope-mapping, building (T0-verified, sandboxed, scope-contracted), evaluation and QA skills orchestrated by a tech-lead.",
   "author": {
     "name": "Liberty Nguyen",

package/AGENTS.md

@@ -65,7 +65,9 @@ Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient
 
 - Orders/results live in `.shapeup/<slug>/orders|results/`; the envelope schemas ship inside the tech-lead skill.
 - The plugin's run entry points need a one-time permission grant — `npx shapeup-sdlc init` writes it into `.claude/settings.json` (`permissions.allow`); without it a headless run stalls at step one. That grant is necessary, not sufficient: it covers the run's own deterministic entry points, not the generic file edits every worker skill makes constantly, or any command a worker reaches for beyond the grant's own exact shape. A truly unattended run also needs a Claude Code permission mode that covers those (`acceptEdits` at minimum) — the plugin cannot grant that on your behalf.
-- Two storage tiers (ADR-0001): COMMITTED `shapeup/<slug>/` (shaping, spec, scopes, wiring-map, project-profile, requirements, hill, `REPORT.md` frozen at L4) vs GITIGNORED `.shapeup/` (board, orders/results, T0/eval/QA artifacts, ledgers, metrics, gate answers).
+- Two storage tiers (ADR-0001): COMMITTED `shapeup/<slug>/` (shaping, spec, scopes, wiring-map, project-profile, requirements, hill, `REPORT.md` frozen at L4) vs GITIGNORED `.shapeup/` (board, orders/results, T0/eval/QA artifacts, ledgers, metrics, gate answers, and the run scripts staged for launch).
+- **The run launches from a copy inside your project, and it has to.** The Workflow tool loads a script only from a directory the session may already read; the plugin installs outside your project, so naming the shipped path is refused before the run begins and no permission rule repairs it — the grant authorises the tool, not what it may read. Opening a run therefore re-copies the run scripts to `.shapeup/workflows/` and reports the path the launch names. A run in flight keeps the copy it started with: an upgrade reaches the next run, not the current round.
+- **A write the substrate does not cover is denied for as long as the dispatch is in flight, and no longer.** A dispatch is live from the moment its order is compiled until a result for *that* dispatch lands, and liveness is read off the run's order set — not off the pointer that names the run, which outlives it. So a finished run fences nothing, a re-dispatch is fenced again, and the committed tier is never a worker's to write: those files belong to the orchestrator, whose window is a phase boundary rather than the middle of somebody else's order.
 - Every run has a `run_id` — the receipt mints it, and orders, T0 artifacts, trial rows, agent-call journal rows and hook decisions all carry it. It is the only key that separates two runs of the same feature: everything else (`order_id`, round/attempt) repeats. It is **not** a time boundary — a relaunch resumes the same run and reuses the key, so one `run_id` legitimately spans every launch after a paused gate or a kill, with hours of wall clock between them, and `orders/<id>.json` is rewritten by each. Anything measuring elapsed time reads the append-only records, never the span of a key. SHIP S.7 exports the run's records as fact tables under `.shapeup/exports/<run_id>/` before the run trace is superseded; a WorkResult carries no `run_id` and reaches it through `order_id`.
 - Every run projects a **run graph** — `.shapeup/<slug>/graph.jsonl`, append-only, written only by
   `reduce graph`. Two families kept separate: work lineage (Run, Order, Result, Verdict, Trial,

package/README.md

@@ -219,8 +219,9 @@ the layer that carries it, and the three layers here fail differently:
 - `PreToolUse` (`Skill|Agent`) — **`harness verify envelope` denies any worker dispatch whose order
   file is missing or fails the WorkOrder schema.** A malformed envelope never reaches a worker.
 - `PreToolUse` (`Edit|Write|MultiEdit`) — **`hooks/sandbox-guard.mjs` blocks a write that no LIVE
-  order's substrate permits.** It reads every compiled-but-not-yet-ingested order rather than a
-  pointer to one, so scopes building concurrently are each held to their own contract; `frozen`
+  order's substrate permits.** It reads every order that is compiled and not yet answered — a result
+  at least as new as the order itself — rather than a pointer to one, so scopes building
+  concurrently are each held to their own contract and a finished run fences nothing; `frozen`
   outranks everything, across all of them.
 - `PreToolUse` (`Bash|Read|Write|Edit|MultiEdit`) — **`hooks/safety-spine.mjs` denies destructive
   commands** (`rm -rf` on unrecoverable targets, force-push/push-to-main, `git reset --hard`,

package/SECURITY.md

@@ -69,7 +69,7 @@ sitting, and reading them is the recommended review.
 | [`safety-spine.mjs`](hooks/safety-spine.mjs) | PreToolUse (`Bash\|Read\|Write\|Edit\|MultiEdit`) | The proposed command/path; `.shapeup/safety-overrides.json` | Yes — provably destructive ops only: `rm -rf` on unrecoverable targets, `git push --force` / push to main, `git reset --hard`, `git clean -fdx`, `DROP TABLE`/`TRUNCATE`, reads of `.env`/keys/cloud credentials, and any write to its own overrides file | Never blocks an unmatched command; `--force-with-lease` stays allowed |
 | [`gate-intake.mjs`](hooks/gate-intake.mjs) | PreToolUse (`Skill`) | The `tech-lead` dispatch's own arguments | Yes — an orchestrator dispatch carrying no resolvable intake (no pitch, spec, resume or requirement text) | Fails open on `--order` and on any ambiguous arg shape |
 | [`harness verify envelope`](kernel/verify/envelope.mjs) | PreToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the JSON schemas | Yes — a worker dispatch whose order file is missing or schema-invalid | Never gates a dispatch that carries no `--order` (standalone skill use stays free) |
-| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the `substrate` block of every LIVE order (compiled, not yet ingested) | Yes — any write no live order permits: outside every `allowed`/`shared`, inside any `frozen`, or a `Write` to an `append_only` path | No-op unless an order is live; the active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
+| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the `substrate` block of every LIVE order — compiled, with no result at least as new as the order's own `compiled_at` | Yes — any write no live order permits: outside every `allowed`/`shared`, inside any `frozen`, or a `Write` to an `append_only` path | No-op unless an order is live, which a finished run no longer is: the pointer names the run, never a dispatch. The active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
 | [`dispatch-receipt.mjs`](hooks/dispatch-receipt.mjs) | PostToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the tool result's own report of which skill ran | **No — it has no deny path at all.** It records that the shipped skill ran, so `harness reduce ingest` can refuse a result no dispatch produced | Never writes an attestation for a result that does not name a resolved skill; never fails the call it observes (every write is inside `try`/`catch`) |
 | [`gate-zerowork.mjs`](hooks/gate-zerowork.mjs) | Stop | Run receipts on disk; the session transcript; the decision ledger | **Yes — the one blocking hook.** Returns `decision:"block"` when the session dispatched the orchestrator and produced no run receipt | Defers the moment any receipt exists; `stop_hook_active` caps it at one block per stop chain |
 
@@ -83,6 +83,11 @@ sitting, and reading them is the recommended review.
   any kind.
 - **The safety-spine actively blocks secret reads** (`.env`, `*.pem`, `*.key`, ssh/cloud
   credentials) rather than merely not making them.
+- **The script the run executes is a copy, and the copy is the shipped file.** Opening a run
+  copies the plugin's own workflow scripts into the gitignored `.shapeup/workflows/`, because the
+  Workflow tool loads a script only from a directory the session may already read and the plugin
+  installs outside your project. They are copied byte for byte — never generated, templated or
+  rewritten — so what you review in the plugin is what runs, and nothing else is added to your tree.
 - The installer (`scripts/install-harness.sh`) writes only into the target project
   (`.claude/`, `shapeup/`, `.gitignore`) and tells you what it
   is going to do first; the `curl | bash` form requires an explicit `--yes` for exactly that

package/commands/build.md

@@ -21,7 +21,7 @@ it belongs to the orchestrator:
 
 ```
 Workflow({
-  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
+  scriptPath: ".shapeup/workflows/shapeup-run.js",
   args: <the RunArgs object>
 })
 ```

package/commands/ship.md

@@ -20,7 +20,7 @@ launch and does not drive it turn by turn:
 
 ```
 Workflow({
-  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
+  scriptPath: ".shapeup/workflows/shapeup-run.js",
   args: <the RunArgs object>
 })
 ```

package/hooks/gate-zerowork.mjs

@@ -56,7 +56,7 @@
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
-import { localDir, globLocal } from "../kernel/lib/paths.mjs";
+import { localDir, globLocal, globWorkflowsStage } from "../kernel/lib/paths.mjs";
 import { runHook, readStdin, settle, decisionsPath } from "./lib/decision.mjs";
 
 const MAX_TRANSCRIPT_BYTES = 20 * 1024 * 1024;
@@ -255,7 +255,7 @@ export function buildReason({ narration, census, enforcement }) {
     "it needs, unless --no-native-workflow was given, in which case approve the launch once):",
     "",
     "  Workflow({",
-    "    scriptPath: \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js\",",
+    `    scriptPath: "${globWorkflowsStage("shapeup-run.js")}",  // staged by \`init run\`, above`,
     "    args: <the RunArgs object>",
     "  })",
     "",

package/hooks/sandbox-guard.mjs

@@ -13,14 +13,34 @@
 // and the contract the hook enforces the same object, for every operation, with no per-operation
 // code here.
 //
-// IT READS EVERY LIVE ORDER, NOT A POINTER TO ONE. `.shapeup/active-order` still names the run and
-// seeds the search — `harness compile` publishes it as it writes each order, which is what fences
-// the lanes that never reach the workflow (`--tiny`, the prose round loop, a standalone `/build`).
-// But a single pointer cannot survive concurrency: with scopes building side by side the last
-// compile wins the pointer, and a write from scope A is then judged against scope B's contract —
-// a false block or a false permit depending on which way the race fell. So the candidate set is
-// every order under `orders/` with no matching file under `results/` (compiled, not yet ingested),
-// and a write is permitted when SOME live contract covers it.
+// IT READS EVERY LIVE ORDER, NOT A POINTER TO ONE. `.shapeup/active-order` names the run and
+// nothing more — `harness compile` publishes it as it writes each order, which is what fences the
+// lanes that never reach the workflow (`--tiny`, the prose round loop, a standalone `/build`).
+// A single pointer cannot survive concurrency: with scopes building side by side the last compile
+// wins the pointer, and a write from scope A would be judged against scope B's contract — a false
+// block or a false permit depending on which way the race fell. So the candidate set is every
+// order under `orders/` that is not yet ANSWERED, and a write is permitted when SOME live contract
+// covers it.
+//
+// THE POINTER IS NOT A LIVENESS SIGNAL, and it used to be one: the order it names was counted live
+// unconditionally, "so the single-order lane behaves as it did before concurrency existed". The arm
+// bought nothing — an order that is genuinely in flight has no result yet and is already live by
+// the rule below — and it cost the checkout permanently. The pointer has one writer and no eraser,
+// so the LAST dispatch of a FINISHED run stayed live for good and fenced everything to that one
+// substrate: after a ship, an ordinary edit anywhere in the repo was denied, and the next feature
+// could not write even its own run trace, because the carve-out below is keyed to the slug the
+// stale pointer names. The documented fail-open state ("no pointer — not inside a dispatch") became
+// unreachable after the first run, and the only way out was to delete a file nothing documents.
+// The arm is gone; `reduce ship` and ``harness init run --force`` retire the pointer as well, so a
+// leftover one is untidy rather than load-bearing.
+//
+// ANSWERED IS A COMPARISON, NOT A PRESENCE TEST, and the difference is a hole the removal above
+// would otherwise open. Order filenames for the run-level operations carry no round (`hammer.json`,
+// `wire.json`, `analyze.json`), so re-dispatching one inside the same run rewrites the order beside
+// the PREVIOUS dispatch's result — and a presence test reads that as finished and runs the new
+// dispatch unfenced. An order counts as answered only when its result file is at least as new as
+// the order's own `compiled_at`, the stamp the compiler writes INTO the order, which a copy or a
+// touch cannot perturb. An order carrying no stamp falls back to presence, which is all it ever had.
 //
 // That is the same question as "the writer's own contract" because scope substrates are disjoint by
 // construction — `harness verify spec`'s DISJOINT rule fails a spec where two scopes claim the same
@@ -50,10 +70,10 @@
 // Contract: PreToolUse stdin JSON { tool_name, tool_input:{file_path | edits[].file_path}, cwd }.
 // Deny via { hookSpecificOutput: { hookEventName, permissionDecision:"deny", permissionDecisionReason } }.
 
-import { readFileSync, existsSync, appendFileSync, mkdirSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, appendFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { resolve, join, relative, dirname, sep } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
-import { LOCAL, activeOrder, ordersDir, resultsDir, metricsShard } from "../kernel/lib/paths.mjs";
+import { LOCAL, SHARED, activeOrder, ordersDir, resultsDir, metricsShard } from "../kernel/lib/paths.mjs";
 import { runHook, readStdin, settle } from "./lib/decision.mjs";
 
 // --- tiny glob matcher: supports *, **, ? — enough for substrate globs, zero dependencies ---
@@ -89,28 +109,48 @@ function readJSON(p) {
 }
 
 /**
- * Every order for this run that has been compiled and not yet ingested.
+ * Has this order been answered — i.e. has a result for THIS dispatch landed?
  *
- * "Not yet ingested" is read off the filesystem — an order with a same-named file under `results/`
- * has finished — because that is the only signal that survives a killed session. The pointer's own
- * order is always included, even when its result has landed, so the single-order lane behaves
- * exactly as it did before concurrency existed.
+ * Filesystem-only, because that is the one signal that survives a killed session. See the banner's
+ * "ANSWERED IS A COMPARISON" note for why a same-named result file is not on its own an answer.
+ *
+ * @param {string} resultPath - Where this order's result would be.
+ * @param {object} order - The parsed order, for its `compiled_at` stamp.
+ * @returns {boolean} True when the result belongs to this dispatch rather than an earlier one.
+ */
+function answered(resultPath, order) {
+  let mtimeMs;
+  try { mtimeMs = statSync(resultPath).mtimeMs; } catch { return false; }
+  const compiledAt = Date.parse(order?.compiled_at ?? "");
+  if (Number.isNaN(compiledAt)) return true;    // no stamp to compare against — presence is the answer
+  // WHOLE SECONDS, because that is all some filesystems keep of an mtime — HFS+ among them, which
+  // this plugin's own development volume uses. The stamp carries milliseconds; compared raw against
+  // a truncated mtime, a result written in the same second as its compile reads as OLDER than the
+  // order and the order stays live. Flooring the stamp costs a one-second window the other way — a
+  // re-dispatch inside the same second as the previous result reads as answered — which no real
+  // dispatch is fast enough to hit.
+  return mtimeMs >= Math.floor(compiledAt / 1000) * 1000;
+}
+
+/**
+ * Every order for this run that has been compiled and not yet answered.
  *
  * @param {string} cwd - Project root.
- * @param {string} slug - The active run's slug.
- * @param {string} pointerOrder - Absolute path of the order the pointer names.
+ * @param {string} slug - The run named by the pointer.
  * @returns {object[]} Parsed orders; unreadable files are skipped, never treated as permissive.
  */
-function liveOrders(cwd, slug, pointerOrder) {
+function liveOrders(cwd, slug) {
   const dir = ordersDir(cwd, slug);
-  const done = new Set(existsSync(resultsDir(cwd, slug)) ? readdirSync(resultsDir(cwd, slug)) : []);
-  const paths = new Set(existsSync(pointerOrder) ? [pointerOrder] : []);
-  if (existsSync(dir)) {
-    for (const f of readdirSync(dir)) {
-      if (f.endsWith(".json") && !done.has(f)) paths.add(join(dir, f));
-    }
+  if (!existsSync(dir)) return [];
+  const rDir = resultsDir(cwd, slug);
+  const live = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    const order = readJSON(join(dir, f));
+    if (!order) continue;
+    if (!answered(join(rDir, f), order)) live.push(order);
   }
-  return [...paths].map(readJSON).filter(Boolean);
+  return live;
 }
 
 function extractPaths(toolInput) {
@@ -159,9 +199,10 @@ async function main() {
   // writer's own contract" are the same question — and only the first can be asked without a
   // shared mutable pointer.
   //
-  // Live = compiled and not yet ingested. An order whose result is on disk has finished; leaving it
-  // in the candidate set would keep a finished scope's substrate open for the rest of the run.
-  const orders = liveOrders(cwd, active.slug, resolve(cwd, active.order_path));
+  // Live = compiled and not yet answered. An order whose result is on disk has finished; leaving it
+  // in the candidate set would keep a finished scope's substrate open for the rest of the run — and
+  // leaving the POINTER's own order in unconditionally kept a finished RUN's substrate open forever.
+  const orders = liveOrders(cwd, active.slug);
   if (orders.length === 0) defer(`no live order for ${active.slug}`, "no-order");
 
   const withSubstrate = orders.filter((o) => o.substrate);
@@ -219,6 +260,18 @@ async function main() {
     defer(`${targetPaths.length} path(s) inside a live order's substrate (${contracts.length} live) — permitted`, "in-substrate");
   }
 
+  // THE REMEDY DIFFERS BY TIER, and naming the wrong one costs a session real time. A product-code
+  // path outside every substrate is a scope-cut question, and widening the order is the honest fix.
+  // A path under the COMMITTED tier is not: no build scope may own the run's own governance and
+  // spec artifacts, so widening a substrate to reach one is the wrong move in a plausible-looking
+  // direction. Those files belong to the orchestrator, whose write window is a phase boundary —
+  // no dispatch in flight — and never the middle of somebody else's dispatch.
+  const committed = violations.filter((v) => v.split(/[\\/]/)[0] === SHARED);
+  const hint = committed.length === violations.length
+    ? `${SHARED}/ is committed tier: these belong to the orchestrator, not to a worker substrate. `
+      + "Write them at a phase boundary, with no dispatch in flight — do not widen an order to reach one."
+    : "If this write legitimately crosses scopes, the order's substrate needs to be expanded (e.g. via ba --remap).";
+
   logPathology(metricsPath, {
     schema_version: 1,
     at: new Date().toISOString(),
@@ -240,7 +293,7 @@ async function main() {
         permissionDecisionReason:
           `Sandbox guard (PA3) — no live order's substrate covers these writes:\n` +
           `${blockReasons.join("\n")}\n` +
-          `If this write legitimately crosses scopes, the order's substrate needs to be expanded (e.g. via ba --remap).`,
+          hint,
       },
     },
   };

package/kernel/compile.mjs

@@ -771,17 +771,17 @@ export async function cli(rawArgv) {
   // through.
   //
   // `hooks/sandbox-guard.mjs` enforces the order's own `substrate` block — allowed/shared,
-  // append_only, frozen — and it finds the order through `.shapeup/active-order`. Until this
-  // write existed the pointer had exactly one author, the workflow script, so the guard fenced
-  // the workflow lane and DEFERRED everywhere else: `--tiny`, the prose round loop, and a
-  // standalone `/build` all compiled an order carrying a write contract that nothing enforced.
-  // A substrate that is only enforced on the lane that also happens to be the most supervised
-  // one is the wrong way round.
+  // append_only, frozen — and it finds the RUN through `.shapeup/active-order`. Until this write
+  // existed the pointer had exactly one author, the workflow script, so the guard fenced the
+  // workflow lane and DEFERRED everywhere else: `--tiny`, the prose round loop, and a standalone
+  // `/build` all compiled an order carrying a write contract that nothing enforced. A substrate
+  // that is only enforced on the lane that also happens to be the most supervised one is the wrong
+  // way round. This is now the pointer's ONLY author.
   //
-  // Compiling an order is the moment the write contract comes into existence, so it is the
-  // correct moment to publish it. The workflow script still sets the pointer explicitly before
-  // dispatch (it interleaves phases and must be exact about which order is live); this write
-  // makes the SAME mechanism cover callers that never reach that code.
+  // Compiling an order is the moment the write contract comes into existence, so it is the correct
+  // moment to publish it. What the pointer supplies is the run's slug; which of that run's orders
+  // are LIVE is derived from the order set (compiled, not yet answered), never from this file — so
+  // republishing it on every compile costs nothing and a stale one fences nothing.
   //
   // Best-effort, on stderr, and never fatal: a compiled order that cannot publish its pointer is
   // still a valid order, and stdout belongs to the order path the caller consumes. The guard

package/kernel/init/run.mjs

@@ -68,7 +68,7 @@
 // that takes a phase, not an init-run flag that takes a slug: the one instruction available at the
 // one moment it mattered named a mechanism that does not parse.
 
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, copyFileSync, rmSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { decideLane, treeSize } from "./fit.mjs";
@@ -76,7 +76,10 @@ import { runArgs } from "../lib/argv.mjs";
 import { uncoerce } from "../lib/contract.mjs";
 import { deriveSnapshot } from "../reduce/snapshot.mjs";
 import { mintRunId } from "../lib/paths.mjs";
-import { localRoot, activeScope, globLocal, globShared, ordersDir, resultsDir } from "../lib/paths.mjs";
+import {
+  localRoot, activeScope, activeOrder, globLocal, globShared, ordersDir, resultsDir,
+  workflowsStage, globWorkflowsStage,
+} from "../lib/paths.mjs";
 import { resolveWorkers } from "../verify/skills.mjs";
 
 export const RECEIPT_VERSION = 1;
@@ -257,6 +260,58 @@ export function resolveAbandonedOrders(cwd, slug) {
   return resolved;
 }
 
+/**
+ * Copy the plugin's run scripts into the project so the launch can actually read them.
+ *
+ * WHY A COPY, AND WHY HERE. `Workflow({scriptPath})` loads a script only from somewhere the session
+ * is already allowed to read — the working directory, or a directory the operator added. The plugin
+ * is installed OUTSIDE the project (a version-stamped cache directory on a marketplace install), so
+ * naming the shipped path fails the launch outright, and no permission rule fixes it: the grant that
+ * authorises the Workflow tool says nothing about where it may read from. The failure is invisible
+ * in development, where the plugin root and the working directory are the same tree, and total for
+ * everybody else. A project-local copy is inside the working directory by construction, so it loads
+ * in every permission mode without widening what the session may read.
+ *
+ * Opening a run is the right moment: it is the one step every lane passes through before a launch,
+ * and it already knows which copy of the plugin answered.
+ *
+ * `refresh` is what keeps an upgrade from arriving mid-round. Opening a run (or forcing over one)
+ * overwrites the staged copies, so a plugin upgrade reaches the NEXT run. A call that finds a run
+ * already open only fills in what is missing: that run should finish on the orchestrator it started
+ * with, and swapping the script under a resumed round is a different build than the one the gates
+ * were answered for — but a relaunch with no script at all is a dead end, so a copy that is gone
+ * (a cleaned run workspace, a run opened by a version that never staged) is written back.
+ *
+ * Best-effort by design: a project that cannot be written to still opens its run and can still be
+ * launched from the install path by an operator who adds that directory. Reporting beats refusing.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} pluginRoot - The plugin copy that answered this call.
+ * @param {object} [opts] - Options.
+ * @param {boolean} [opts.refresh] - Overwrite an existing copy (true) or only fill gaps (false).
+ * @returns {{ok: boolean, dir: string, staged: string[], reason?: string}} Outcome, for the caller to report.
+ */
+export function stageWorkflows(cwd, pluginRoot, { refresh = true } = {}) {
+  const src = join(pluginRoot, "skills", "tech-lead", "workflows");
+  const dir = workflowsStage(cwd);
+  let names;
+  try {
+    names = readdirSync(src).filter((f) => f.endsWith(".js")).sort();
+  } catch (e) {
+    return { ok: false, dir, staged: [], reason: `no workflow scripts at ${src}: ${e.message}` };
+  }
+  try {
+    mkdirSync(dir, { recursive: true });
+    for (const f of names) {
+      const dst = join(dir, f);
+      if (refresh || !existsSync(dst)) copyFileSync(join(src, f), dst);
+    }
+  } catch (e) {
+    return { ok: false, dir, staged: [], reason: `could not stage into ${dir}: ${e.message}` };
+  }
+  return { ok: true, dir, staged: names };
+}
+
 // ---- CLI -------------------------------------------------------------------
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
@@ -398,6 +453,19 @@ export function cli(rawArgv) {
 
   const runRoot = localRoot(cwd, slug);
   const receiptPath = join(runRoot, "receipt.json");
+
+  // STAGE THE RUN SCRIPTS BEFORE THE ALREADY-OPEN REFUSAL, not after: a session resuming a paused
+  // run reaches that refusal and nothing else, and it still needs a `scriptPath` it can name. What
+  // it does NOT get is a swapped orchestrator — see stageWorkflows() for why `refresh` is false
+  // exactly when a run is already open and is not being forced over.
+  // `Boolean(...)`, not the bare flag: an absent `--force` is `undefined`, and `false || undefined`
+  // is `undefined`, which a destructured default reads as "not passed" and turns back into `true`.
+  const staged = stageWorkflows(cwd, plugin.root, { refresh: !existsSync(receiptPath) || Boolean(args.force) });
+  if (!staged.ok) {
+    console.error(`⚠ init-run: could not stage the run scripts — ${staged.reason}`);
+    console.error(`  Launch from the install path instead, and add ${plugin.root} to the session's`);
+    console.error("  readable directories (/add-dir) if the Workflow tool refuses to load it.");
+  }
   // A RUN IS ALREADY OPEN. This is the resume path, and it used to be a dead end.
   //
   // The refusal is right: silently re-initialising would discard the round history the circuit
@@ -437,6 +505,10 @@ export function cli(rawArgv) {
       "To re-derive this at any time:",
       "  node <plugin>/kernel/harness.mjs reduce snapshot --cwd <dir>",
       "To abandon the open run and start over, deliberately: --force",
+      "",
+      staged.ok
+        ? `Relaunch the same run with: Workflow({scriptPath: "${globWorkflowsStage("shapeup-run.js")}", args: <the same RunArgs>})`
+        : "The run scripts are NOT staged in this project — see the warning above before relaunching.",
     ].join("\n"));
   }
 
@@ -453,6 +525,10 @@ export function cli(rawArgv) {
         `⚠ init-run --force: resolved ${abandoned.length} dispatched-but-unanswered order(s) as abandoned — ${abandoned.join(", ")}`,
       );
     }
+    // And the pointer the abandoned run left behind. It names a run that is being forced over, so
+    // the next compile republishes it within the second; retiring it here means a `--force` that
+    // resolves nothing still leaves no stale claim about which run is open.
+    rmSync(activeOrder(cwd), { force: true });
   }
 
   const startedAt = new Date().toISOString();
@@ -483,6 +559,8 @@ export function cli(rawArgv) {
     intake_sha256: receipt.intake_sha256,
     intake_chars: receipt.intake_chars,
     config,
+    // What the launch names. Project-local by necessity, not by preference — see stageWorkflows().
+    workflow_script: staged.ok ? globWorkflowsStage("shapeup-run.js") : null,
     next: "GATE L0 — pin the run config, emit the gate block, then ORIENT.",
   }, null, 2));
 }

package/kernel/lib/paths.mjs

@@ -258,8 +258,34 @@ export const workingDir = (cwd, slug) => join(localRoot(cwd, slug), "working");
  * rows, above all, which without it are written unjoinable to any run.
  */
 export const activeScope = (cwd) => join(localDir(cwd), "active-scope");
-/** The pointer the sandbox guard reads to answer "which order is executing?". */
+/**
+ * The pointer that tells the sandbox guard WHICH RUN it is fencing.
+ *
+ * It names a run, not a live dispatch. `harness compile` republishes it as it writes each order —
+ * the one place every lane passes through — and the guard uses the `slug` in it to find the run's
+ * order set; liveness is then derived from that set, never from this file. That separation is
+ * deliberate: this pointer has one writer and no natural eraser, so a run that ends leaves it
+ * behind, and anything that treated it as "a dispatch is in flight" kept a finished run's last
+ * substrate armed over an idle checkout. `reduce ship` and ``harness init run --force`` retire it
+ * so it does not outlive its run, and the guard is correct either way.
+ */
 export const activeOrder = (cwd) => join(localDir(cwd), "active-order");
+
+/**
+ * Where the run scripts are staged for launch, inside the project.
+ *
+ * The orchestrator's Workflow scripts ship with the plugin, which lives OUTSIDE the project — and
+ * the Workflow tool will only load a script it is already allowed to read, meaning the working
+ * directory or a directory the operator added. An install path therefore fails the launch outright,
+ * with no permission rule that can fix it: the grant that authorises the tool does not widen where
+ * it may read from. So ``harness init run`` copies the shipped scripts here, and the launch names
+ * this project-local path. LOCAL, because a staged copy is a build artifact of the run, not a
+ * source file anybody should review or commit.
+ */
+export const workflowsStage = (cwd) => join(localDir(cwd), "workflows");
+
+/** The staged run script as the LAUNCH names it — project-relative, `/`-joined on every platform. */
+export const globWorkflowsStage = (...parts) => [LOCAL, "workflows", ...parts].join("/");
 /** Hook receipts — one row per evaluation, so `allow` carries evidence. */
 export const decisions = (cwd) => join(localDir(cwd), "decisions.jsonl");
 /** Human-authored safety escape hatch. LOCAL so no PR can widen another machine's envelope. */

package/kernel/reduce/ship.mjs

@@ -26,12 +26,13 @@
 //
 // Exit: 0 written (path on stdout), 2 usage error.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
 import {
   report as reportPath, tasksDir, verdictsDir, trials, evaluationDir, qaDir,
   roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared, resultsDir,
+  activeOrder,
 } from "../lib/paths.mjs";
 import { readTrials } from "../verify/t0.mjs";
 import { ratchetReport } from "../probe/stats.mjs";
@@ -349,6 +350,15 @@ export async function cli(rawArgv) {
   } else {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, markdown, "utf8");
+
+    // THE RUN IS OVER, SO RETIRE ITS POINTER. `harness compile` publishes `.shapeup/active-order`
+    // as it writes each order and nothing ever erased it, so the pointer outlived every run that
+    // produced one. That is harmless to the guard now — liveness comes from the order set, and a
+    // shipped run has no unanswered orders — but a pointer naming a finished run is a fact on disk
+    // that is no longer true, and the next reader to trust it inherits the same class of bug.
+    // Only on the writing path: `--stdout` is a preview of the report, not the end of the run.
+    rmSync(activeOrder(cwd), { force: true });
+
     console.log(relShared(args.slug, "REPORT.md"));
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Shape Up for coding agents \u2014 with gates the agent can't talk its way past. Harness for Claude Code.",
   "bin": {
     "shapeup-sdlc": "bin/init.mjs"

package/skills/tech-lead/SKILL.md

@@ -68,11 +68,11 @@ check the lane:
   `.shapeup/<slug>/run-args.json` before launching**, fresh on every launch and relaunch: the flags
   reach the workflow as a value in memory, so it is the run's only evidence of what it was launched
   with, and a run that cannot state its own configuration cannot have a claim about it checked.
-  Then launch the run script with the **`Workflow` tool**:
+  Then launch with the **`Workflow` tool** — naming `init run`'s staged copy, never the install path:
 
 ```
 Workflow({
-  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
+  scriptPath: ".shapeup/workflows/shapeup-run.js",
   args: <the RunArgs object>
 })
 ```
@@ -91,6 +91,12 @@ launch prompts for approval once per session and the unattended lane is unavaila
 comes back "requires approval" in a headless session, stop and say so — do not hand-build the
 feature instead.
 
+**Why a project-local `scriptPath`.** The tool loads a script only from a directory the session may
+already read, and the plugin installs outside your project, so the shipped path is refused before the
+run begins — no permission rule repairs it. `init run` re-copies the scripts to `.shapeup/workflows/`
+on every open, never on a relaunch, so a run finishes on the orchestrator it started with. If staging
+failed, launch from the install path and have the operator `/add-dir` the plugin directory.
+
 ## Step 3 — the pause protocol: branch on `RunReturn.status`
 
 | `status` | What the workflow is telling you | What you do |