shapeup-sdlc 1.7.0 → 3.0.0

package/skills/tech-lead/scripts/lib/paths.mjs

@@ -1,280 +0,0 @@
-// paths — the single source of truth for where the harness writes.
-//
-// WHY THIS FILE EXISTS (measured by grepping the shipped tree, not theorized).
-//
-// The two storage roots were hard-coded across the tree in TWO syntaxes that no single search
-// finds:
-//
-//     "docs/shapeup-sdlc/<slug>/scopes/..."            spelled string literals
-//     join(cwd, "docs", "shapeup-sdlc", slug, ...)      segment-built sites
-//
-// A find/replace over the first set leaves the second silently pointing at the old root. That is
-// the failure mode this project keeps rediscovering: a change that appears complete, produces no
-// error, and is wrong — `lib/is-main.mjs` (a guard duplicated 18 times, inert under a symlink) and
-// `lib/argv.mjs` (`rNaN-a1.json` written with exit 0) are the same defect at different layers. The
-// remedy each time is to give the duplicated thing one home and add a test that no one may bypass
-// it — asserted by the structural suite.
-//
-// It also removes a live ambiguity. `gate-answers.mjs` resolved three candidate paths and
-// `sandbox-guard.mjs` built a fourth independently; the same filename meant "my personal lane" at
-// one path and "team policy" at another, auto-discovered with no flag (ADR-0001 §Context).
-//
-// TIER DISCIPLINE, restated here because this is where it becomes mechanical:
-//   SHARED (committed) — prose a teammate reads: shaping, spec, contracts, requirements, report.
-//   LOCAL (gitignored) — run state, envelopes, verification artifacts, machine policy.
-// See ADR-0001 (consumer file organization).
-//
-// Zero dependencies. Pure — every function takes `cwd` and returns a path; nothing here touches
-// the filesystem, so importing this module can never have a side effect.
-
-import { join } from "node:path";
-
-// ---------------------------------------------------------------------------
-// The two roots. Renaming a root is these two lines plus migration 0006.
-// ---------------------------------------------------------------------------
-
-// Both roots are POSIX strings, deliberately. They are used two ways — fed to `join()` (which
-// normalises separators on Windows) and interpolated into SUBSTRATE GLOBS, which are matched
-// against repo-relative POSIX paths by `sandbox-guard`. A backslash reaching a glob would silently
-// stop matching, so the canonical form is the one the globs need.
-
-/**
- * Committed tier — the authored deliverable a teammate gets on `git pull`.
- *
- * Was `docs/shapeup-sdlc`. Moved out of `docs/` because many projects publish that directory
- * through a static-site generator, which either publishes the spec tree by accident or fails the
- * site build on it (ADR-0001).
- */
-export const SHARED = "shapeup";
-
-/** Gitignored tier — run state for the machine that invoked the harness. Was `.shapeup-sdlc`. */
-export const LOCAL = ".shapeup";
-
-/**
- * The pre-ADR-0001 roots. Migration `0006` moves a project from these to the pair above;
- * `bin/init.mjs` writes ignore rules covering both so a half-migrated checkout cannot commit a
- * run trace. Nothing else should read these.
- */
-export const LEGACY = { shared: "docs/shapeup-sdlc", local: ".shapeup-sdlc" };
-
-// ---------------------------------------------------------------------------
-// Roots
-// ---------------------------------------------------------------------------
-
-/**
- * The committed tier root.
- * @param {string} cwd - Project root.
- * @returns {string} `<cwd>/shapeup`.
- */
-export const sharedDir = (cwd) => join(cwd, SHARED);
-
-/**
- * The gitignored tier root.
- * @param {string} cwd - Project root.
- * @returns {string} `<cwd>/.shapeup`.
- */
-export const localDir = (cwd) => join(cwd, LOCAL);
-
-/**
- * A feature's committed root.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {string} `<cwd>/shapeup/<slug>`.
- */
-export const sharedRoot = (cwd, slug) => join(cwd, SHARED, slug);
-
-/**
- * A feature's run-trace root.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {string} `<cwd>/.shapeup/<slug>`.
- */
-export const localRoot = (cwd, slug) => join(cwd, LOCAL, slug);
-
-// ---------------------------------------------------------------------------
-// SHARED — the deliverable
-// ---------------------------------------------------------------------------
-
-/** The committed spec tree — the evaluator's grading truth. */
-export const specDir = (cwd, slug) => join(sharedRoot(cwd, slug), "spec");
-/** Use-case directory inside the spec tree. */
-export const usecasesDir = (cwd, slug) => join(specDir(cwd, slug), "usecases");
-/** Shaping artifacts — pitch, framing, breadboard, baseline, glossary. */
-export const shapingDir = (cwd, slug) => join(sharedRoot(cwd, slug), "shaping");
-// The three contracts are markdown on disk and JSON on the wire (ADR-0001) — see
-// `lib/contract-md.mjs`. `readContract()` accepts either extension, so a project mid-migration
-// keeps working; these builders name the form the harness WRITES.
-
-/** Scope contracts, one markdown file per vertical slice. */
-export const scopesDir = (cwd, slug) => join(sharedRoot(cwd, slug), "scopes");
-/** One scope contract by id. */
-export const scopeContract = (cwd, slug, id) => join(scopesDir(cwd, slug), `${id}.md`);
-/** The wiring map — engine → seam → entry-point call site → affordance. */
-export const wiringMap = (cwd, slug) => join(sharedRoot(cwd, slug), "wiring-map.md");
-/** Archetype + entry_point; gates the reachability arm of trace-lint. */
-export const projectProfile = (cwd, slug) => join(sharedRoot(cwd, slug), "project-profile.md");
-/** The REQ clause registry that covers-closure checks against. */
-export const requirements = (cwd, slug) => join(sharedRoot(cwd, slug), "requirements.md");
-/** Hill shards — mechanical phase per scope. */
-export const hillDir = (cwd, slug) => join(sharedRoot(cwd, slug), "hill");
-/** The frozen ship report, written once at GATE L4. */
-export const report = (cwd, slug) => join(sharedRoot(cwd, slug), "REPORT.md");
-/** Team-shared coaching rules, read back by the three coachable workers. */
-export const knowledgeBaseDir = (cwd) => join(sharedDir(cwd), "knowledge-base");
-/** One worker's coaching file. */
-export const knowledgeBase = (cwd, skill) => join(knowledgeBaseDir(cwd), `${skill}.md`);
-// `.harness-version` and `.harness-migrations` were resolved here, committed by necessity as
-// ADR-0001's third exception. Their sole writer was the upgrade path's data-migration runner, which
-// has been removed; no code in the plugin has written either file since. The helpers went with
-// them rather than remaining as resolvable paths to files nothing produces — a path helper is a
-// claim that the file is part of the layout, and this one would have been false.
-
-// ---------------------------------------------------------------------------
-// LOCAL — run state
-// ---------------------------------------------------------------------------
-
-/** The run receipt — the mechanical fact that a run started (GATE L0.1). */
-export const receipt = (cwd, slug) => join(localRoot(cwd, slug), "receipt.json");
-/** The intake, verbatim, next to its digest in the receipt. */
-export const intake = (cwd, slug) => join(localRoot(cwd, slug), "intake.md");
-/** The run ledger — rounds, decisions, status frontmatter. */
-export const harnessRun = (cwd, slug) => join(localRoot(cwd, slug), "harness-run.md");
-/** File-derived mid-run digest, frozen before compaction. */
-export const runSnapshot = (cwd, slug) => join(localRoot(cwd, slug), "run-snapshot.json");
-/** The task board directory. */
-export const tasksDir = (cwd, slug) => join(localRoot(cwd, slug), "tasks");
-/** The board index. */
-export const boardIndex = (cwd, slug) => join(tasksDir(cwd, slug), "_index.md");
-/** Compiled WorkOrders. */
-export const ordersDir = (cwd, slug) => join(localRoot(cwd, slug), "orders");
-/** Returned WorkResults. */
-export const resultsDir = (cwd, slug) => join(localRoot(cwd, slug), "results");
-/** T0 verification artifacts. */
-export const t0Dir = (cwd, slug) => join(localRoot(cwd, slug), "t0");
-/** Immutable per-attempt verdict artifacts the evaluator must cite. */
-export const verdictsDir = (cwd, slug) => join(t0Dir(cwd, slug), "verdicts");
-/** The append-only trial ledger the ratchet reduces over. */
-export const trials = (cwd, slug) => join(t0Dir(cwd, slug), "trials.jsonl");
-/** Finished-scope fixture registry for the seesaw regression check. */
-export const seesawRegistry = (cwd, slug) => join(localRoot(cwd, slug), "seesaw", "registry.json");
-/** Evaluator output — report, evidence, verdict ledger. */
-export const evaluationDir = (cwd, slug) => join(localRoot(cwd, slug), "evaluation");
-/** QA hunt output. */
-export const qaDir = (cwd, slug) => join(localRoot(cwd, slug), "qa");
-/** Scout recon — code-surface map, spikes, discovered seed. */
-export const orientDir = (cwd, slug) => join(localRoot(cwd, slug), "orient");
-/** Time-boxed spike workspace. */
-export const spikesDir = (cwd, slug) => join(localRoot(cwd, slug), "spikes");
-/** Covers-closure + reachability run trace. */
-export const traceDir = (cwd, slug) => join(localRoot(cwd, slug), "trace");
-/** The discovered-task ledger every discovery flow appends to. */
-export const discoveryLedger = (cwd, slug) => join(localRoot(cwd, slug), "discovery", "ledger.md");
-/**
- * Adjudicated decisions, read back by `compile-order` as binding precedent.
- *
- * LOCAL since ADR-0001. It was committed, and it is appended to DURING a build round — so a run
- * left the working tree dirty in the deliverable tier while it was still building. Its
- * conclusions reach the team in `REPORT.md` at GATE L4 instead, frozen once.
- */
-export const roundLedger = (cwd, slug) => join(localRoot(cwd, slug), "round-ledger.md");
-
-/**
- * Spec WORKING NOTES — analysis that informed the contract but is not the contract.
- *
- * `synthesis.md`, `assess-report.md`, `feedback.md`, `api-feasibility.md`, `integration.md`. The
- * committed `spec/` keeps only what the evaluator grades against and a reviewer needs (ADR-0001
- * "contract vs working artifact").
- */
-export const workingDir = (cwd, slug) => join(localRoot(cwd, slug), "working");
-
-// --- checkout-wide ---------------------------------------------------------
-
-/** The pointer the sandbox guard reads to answer "which scope is checked out?". */
-export const activeScope = (cwd) => join(localDir(cwd), "active-scope");
-/** The pointer the sandbox guard reads to answer "which order is executing?". */
-export const activeOrder = (cwd) => join(localDir(cwd), "active-order");
-/** 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. */
-export const safetyOverrides = (cwd) => join(localDir(cwd), "safety-overrides.json");
-/**
- * Telemetry shards.
- *
- * LOCAL since ADR-0001. Committed, they put `process.env.HOSTNAME` — a person's laptop name —
- * into the repository, and append-only JSONL in git only grows. The cost, stated plainly: with
- * these local, `stats.mjs` becomes a personal tool and "is the KB flywheel working across the
- * team?" is no longer answerable from the repo.
- */
-export const metricsDir = (cwd) => join(localDir(cwd), "metrics");
-/** This machine's telemetry shard. */
-export const metricsShard = (cwd, id = process.env.HOSTNAME || "local") =>
-  join(metricsDir(cwd), `${id}.jsonl`);
-/** Archived pitches. */
-export const pitchArchiveDir = (cwd) => join(localDir(cwd), "pitch-archive");
-
-/**
- * Gate answer sets, in resolution order (first hit wins).
- *
- * ONE TIER ONLY, since ADR-0001. There used to be a third candidate — a COMMITTED
- * `gate-answers.json`, auto-discovered with no flag — so a file with `preset: ci` pre-approved
- * GATE L4 ship sign-off for everyone who pulled the repo, and the same filename meant "my
- * personal lane" at one path and "team policy" at another. Consent is now per-machine by
- * construction: no committed file can cross a gate on another person's behalf.
- *
- * @param {string} cwd - Project root.
- * @param {(string|null)} [slug] - Feature slug; adds the per-run candidate when given.
- * @returns {string[]} Candidate paths, most specific first.
- */
-export const gateAnswerCandidates = (cwd, slug = null) => [
-  ...(slug ? [join(localRoot(cwd, slug), "gate-answers.json")] : []),
-  join(localDir(cwd), "gate-answers.json"),
-];
-
-// ---------------------------------------------------------------------------
-// Relative forms — for messages, receipts and anything a human reads
-// ---------------------------------------------------------------------------
-
-/**
- * A run-trace path relative to the project root, for display.
- * @param {string} slug - Feature slug.
- * @param {...string} parts - Path segments under the feature's local root.
- * @returns {string} e.g. `.shapeup/checkout/t0/verdicts`.
- */
-export const relLocal = (slug, ...parts) => join(LOCAL, slug, ...parts);
-
-/**
- * A deliverable path relative to the project root, for display.
- * @param {string} slug - Feature slug.
- * @param {...string} parts - Path segments under the feature's shared root.
- * @returns {string} e.g. `shapeup/checkout/spec`.
- */
-export const relShared = (slug, ...parts) => join(SHARED, slug, ...parts);
-
-// ---------------------------------------------------------------------------
-// Glob forms — substrate whitelists, matched against repo-relative POSIX paths
-// ---------------------------------------------------------------------------
-
-/**
- * A run-trace glob. Always POSIX-separated: `sandbox-guard` matches these against
- * `path.relative()` output normalised to forward slashes, so a `join()` here would stop matching
- * on Windows without any error to notice.
- * @param {string} slug - Feature slug.
- * @param {...string} parts - Glob segments under the feature's local root.
- * @returns {string} e.g. `.shapeup-sdlc/checkout/tasks/**`.
- */
-export const globLocal = (slug, ...parts) => [LOCAL, slug, ...parts].join("/");
-
-/**
- * A deliverable glob, POSIX-separated for the same reason as {@link globLocal}.
- * @param {string} slug - Feature slug.
- * @param {...string} parts - Glob segments under the feature's shared root.
- * @returns {string} e.g. `shapeup/checkout/scopes/*.md`.
- */
-export const globShared = (slug, ...parts) => [SHARED, slug, ...parts].join("/");
-
-/**
- * The coaching file a coachable worker reads, as a repo-relative path for the WorkOrder payload.
- * @param {string} skill - Worker name (task-executor | ba-pitch-analyzer | qa-edge-hunter).
- * @returns {string} e.g. `shapeup/knowledge-base/task-executor.md`.
- */
-export const relKnowledgeBase = (skill) => [SHARED, "knowledge-base", `${skill}.md`].join("/");

package/skills/tech-lead/scripts/run-workflow.mjs

@@ -1,381 +0,0 @@
-#!/usr/bin/env node
-// run-workflow — a Bash-invoked control plane for Workflow-format orchestrator scripts.
-//
-// WHY THIS FILE EXISTS. The `Workflow` tool — the only lane for scoped specs — is denied in a
-// headless session with "Review dynamic workflow before running". Left to it, `shapeup-run.js`
-// executes zero times and the agent improvises the feature by hand instead; a session can reach
-// GATE L4 with a valid receipt while the lane never started. Bash HAS a path-scoped grantable
-// prefix, and `npx shapeup-sdlc init` already
-// writes exactly that rule (`Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/<owner>/scripts/:*)` —
-// bin/init.mjs mergePipelinePermissions), so this file runs the SAME Workflow-format script through
-// a surface the install already grants.
-//
-// ⟐ ONE CORRECTION, from probing the permission layer rather than concluding from denials. It is
-// NOT true that no permission string can grant the tool: a bare `"Workflow"` entry in
-// `permissions.allow` grants it, and with that entry removed the same call is denied. So the tool
-// was never ungrantable — the installer simply never wrote the entry, because it writes Bash
-// prefixes only. The defect is real, and it is an INSTALLER defect: the plugin never granted the
-// permission its own lane needs.
-//
-// TWO THINGS SURVIVE THE CORRECTION, and they are the reason this file still exists rather than a
-// one-line change to `init`:
-//   1. THE GRANT CANNOT BE SCOPED. `Workflow(<path>)` and `Workflow(<script>)` are both denied —
-//      only the bare token works, which grants EVERY dynamic workflow script in the project,
-//      including one a model writes at runtime. A harness whose thesis is "gates the agent cannot
-//      talk its way past" should not ask for blanket dynamic-code execution. The Bash prefix is
-//      path-scoped to this directory.
-//   2. It costs no new grant at all: existing installs already allow it.
-// The one-line `"Workflow"` grant remains a legitimate alternative for anyone who prefers the
-// native runtime's resume/isolation, and the upgrade notes document it as such. It is a choice
-// with a real trade-off, which is why it is documented rather than silently taken.
-//
-// IT LIVES IN `scripts/` FOR A LOAD-BEARING REASON, not a filing one. The grant `init` already
-// writes is a PREFIX rule over this exact directory, so shipping the launcher here means every
-// install that ever ran `npx shapeup-sdlc init` can already start the lane — zero new permission
-// strings, zero migration for existing users. Putting it anywhere else would require a new grant
-// and reproduce the same denial one directory over. The structural suite asserts that the
-// documented call site is covered by a prefix `bin/init.mjs` actually writes.
-//
-// PROVENANCE: prototyped and proven before it shipped — a headless `acceptEdits` session runs the
-// lane through a granted Bash prefix with zero denials, this loader executes the unmodified
-// `shapeup-run.js`, and a real worker dispatches under `acceptEdits`.
-//
-// WHAT IT PROVIDES to the script — the Workflow runtime surface shapeup-run.js actually uses:
-//   args, agent(prompt, {label, phase, schema, model, effort}), parallel(thunks),
-//   pipeline(items, ...stages), phase(title), log(msg), budget, workflow() [stub — throws].
-// Scripts keep the Workflow tool's contract: `export const meta = {...}` + a bare top-level body
-// with top-level `await` and `return`. The loader rewrites the one export and wraps the body in an
-// AsyncFunction; nothing about the script format changes, which is the point — shapeup-run.js runs
-// through this file byte-identical to how it ships.
-//
-// HOW agent() DISPATCHES. Each call spawns a fresh headless CLI session:
-//   claude -p <prompt> --model <m> --output-format json --permission-mode acceptEdits
-// (detached process group, SIGTERM-then-SIGKILL escalation on timeout, so a hook grandchild can
-// never hold a dead worker's pipe open — without that, a time-capped session can outlive its cap
-// many times over). Workers are
-// stateless, craft-only, pipeline-blind (the envelope port) — fresh processes fit that contract
-// exactly; nothing here shares context between dispatches. `schema` is enforced by instruction +
-// parse + shallow validation + one retry; a worker that still fails returns null, which is the
-// Workflow tool's own documented behavior for a dead subagent and the case every shapeup-run.js
-// call site already survives (mechEnvelope).
-//
-// DIVERGENCES from the Workflow tool, stated rather than silent. None is reached by
-// `shapeup-run.js`, which is why this lane can carry it today; each is a real gap for any other
-// script, and a reader deciding whether to write one should read this list as a limit, not a note:
-//   - budget counts USD (summed from each worker envelope's total_cost_usd), not output tokens.
-//     Interface is identical: {total, spent(), remaining()}; total comes from --budget-usd.
-//   - Date.now()/Math.random() are NOT banned inside scripts. The tool bans them for replay-safe
-//     resume; this file journals every dispatch (journal.jsonl) but does not implement
-//     resume-from-journal. shapeup-run.js resumes from DISK state by design, not from the
-//     journal — which is why the lane's kill/resume story (`kill-resume-probe: PASS`, four
-//     assertions on a live SIGKILL) does not depend on this and survives the surface swap.
-//   - workflow() (child workflows) throws. shapeup-run.js inlines its round loop and never calls it.
-//   - isolation: 'worktree' throws. shapeup-run.js is sequential today (design doc D3).
-//   - schema validation is shallow (type + required keys + declared property types, one level).
-//
-// A RUN OUTLIVES A FOREGROUND TOOL CALL. A real pipeline runs for tens of minutes; every
-// foreground Bash call has a ceiling well below that. Launch it as a BACKGROUND Bash call and read
-// `<run-dir>/result.json`, which this file writes on completion with the same `{ok, result}` shape
-// stdout carries. Headless callers must also set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0`, or the
-// wait is cut at 600 s and a truncated run is reported as a clean one.
-//
-// STDOUT DISCIPLINE: stdout carries exactly one JSON line — {ok, result} — because whatever
-// launched this process (a mech courier, an outer session, a test) reads stdout as data. All
-// narration goes to stderr.
-//
-// exit 0: script completed; stdout = {"ok":true,"result":...}
-// exit 1: script threw or the launch failed after parsing; stdout = {"ok":false,"error":...}
-// exit 2: argv rejected before anything ran (lib/argv.mjs) — nothing spawned, nothing written.
-
-import { spawn } from "node:child_process";
-import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from "node:fs";
-import { resolve, basename } from "node:path";
-import process from "node:process";
-import { runArgs } from "./lib/argv.mjs";
-import { isMain } from "./lib/is-main.mjs";
-
-/**
- * The typed argv boundary.
- *
- * FAILING CLOSED IS THE POINT HERE, not hygiene. The cost of a silent launch failure is not that the lane
- * refused to start — it is that the refusal was quiet enough for an agent to route around, so a
- * run that never happened reported like one that did. A launcher that accepts `--max-concurrency`
- * with no value and proceeds on `NaN` is the same shape of defect: this rejects at exit 2 with a
- * machine-readable reason before a single worker is spawned or a run directory created.
- */
-export const ARGV_SPEC = {
-  usage: 'run-workflow.mjs <workflow-script.js> [--args <json> | --args-file <path>] ' +
-         "[--run-dir <dir>] [--worker-permission-mode <mode>] [--worker-cwd <dir>] " +
-         "[--max-concurrency <n>] [--agent-timeout-s <n>] [--budget-usd <n>]",
-  _: { arity: 1, name: "workflow-script.js" },
-  args: { type: "json" },
-  "args-file": { type: "path" },
-  "run-dir": { type: "path" },
-  "worker-permission-mode": { type: "enum", values: ["acceptEdits", "default", "plan", "bypassPermissions"] },
-  "worker-cwd": { type: "path" },
-  "max-concurrency": { type: "int", min: 1, max: 32 },
-  "agent-timeout-s": { type: "int", min: 1 },
-  "budget-usd": { type: "num", min: 0 },
-};
-
-/**
- * Resolve parsed argv into the loader's configuration.
- * @param {object} a - The object `runArgs(ARGV_SPEC)` returns.
- * @returns {object} Fully defaulted, absolute-path configuration.
- */
-export function configure(a) {
-  const script = resolve(a._[0]);
-  return {
-    script,
-    args: a.argsFile ? JSON.parse(readFileSync(a.argsFile, "utf8")) : (a.args ?? {}),
-    runDir: a.runDir
-      ? resolve(a.runDir)
-      : resolve(`.run-workflow-${basename(script).replace(/\.[^.]+$/, "")}-${process.pid}`),
-    workerPermissionMode: a.workerPermissionMode || "acceptEdits",
-    workerCwd: a.workerCwd ? resolve(a.workerCwd) : process.cwd(),
-    maxConcurrency: a.maxConcurrency ?? 4,
-    agentTimeoutS: a.agentTimeoutS ?? 900,
-    budgetUsd: a.budgetUsd ?? null,
-  };
-}
-
-// ---------------------------------------------------------------------------------------------
-// Loader — the Workflow tool's script format, executed as-is. One rewrite (`export const meta`
-// -> `const meta`), then the whole body becomes an AsyncFunction so top-level `await` and
-// top-level `return` mean exactly what the tool defines them to mean.
-// ---------------------------------------------------------------------------------------------
-function loadWorkflow(path) {
-  let src = readFileSync(path, "utf8");
-  src = src.replace(/^export\s+const\s+meta\s*=/m, "const meta =");
-  if (/^export\s/m.test(src)) {
-    throw new Error(`${basename(path)}: unsupported export — Workflow scripts export only \`const meta\``);
-  }
-  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
-  return new AsyncFunction(
-    "args", "agent", "parallel", "pipeline", "phase", "log", "budget", "workflow",
-    `"use strict";\n${src}`
-  );
-}
-
-// ---------------------------------------------------------------------------------------------
-// Concurrency — a plain semaphore; excess agent() calls queue, mirroring the tool's cap.
-// ---------------------------------------------------------------------------------------------
-function makeSemaphore(max) {
-  let active = 0; const queue = [];
-  const release = () => { active--; const next = queue.shift(); if (next) { active++; next(); } };
-  const acquire = () => new Promise((res) => {
-    if (active < max) { active++; res(); } else queue.push(res);
-  });
-  return { acquire, release };
-}
-
-// ---------------------------------------------------------------------------------------------
-// Worker spawn — one headless CLI session per dispatch. Process-group kill on timeout
-// (hook grandchildren keep pipes open, so
-// signaling one pid is not a cap).
-// ---------------------------------------------------------------------------------------------
-const KILL_GRACE_MS = 10_000;
-
-function runClaude({ prompt, model, permissionMode, cwd, timeoutMs }) {
-  return new Promise((resolvePromise) => {
-    const child = spawn("claude", [
-      "-p", prompt,
-      "--model", model,
-      "--output-format", "json",
-      "--permission-mode", permissionMode,
-    ], { cwd, env: process.env, detached: true });
-
-    let stdout = "", stderr = "", settled = false, killed = false;
-    const settle = (r) => { if (!settled) { settled = true; clearTimeout(timer); clearTimeout(hardTimer); resolvePromise(r); } };
-
-    let hardTimer = null;
-    const timer = setTimeout(() => {
-      killed = true;
-      try { process.kill(-child.pid, "SIGTERM"); } catch { /* already gone */ }
-      hardTimer = setTimeout(() => { try { process.kill(-child.pid, "SIGKILL"); } catch { /* already gone */ } }, KILL_GRACE_MS);
-    }, timeoutMs);
-
-    child.stdout.on("data", (d) => { stdout += d; });
-    child.stderr.on("data", (d) => { stderr += d; });
-    child.on("error", (e) => settle({ ok: false, error: `cannot spawn claude: ${e.message}`, killed, stdout, stderr }));
-    child.on("close", (code) => {
-      let envelope = null;
-      try { envelope = JSON.parse(stdout.trim()); } catch { /* non-JSON stdout stays raw */ }
-      settle({ ok: code === 0 && envelope !== null && envelope.is_error !== true, code, killed, envelope, stdout, stderr });
-    });
-  });
-}
-
-// ---------------------------------------------------------------------------------------------
-// Structured output — instruction + extraction + shallow validation + one retry.
-// Extraction is parseMechJson's balanced-scan (shapeup-run.js:176) — proven against couriers
-// that wrap clean JSON in commentary; the same failure mode applies to whole workers.
-// ---------------------------------------------------------------------------------------------
-function extractJson(text) {
-  if (typeof text !== "string") return null;
-  const s = text.trim();
-  try { return JSON.parse(s); } catch { /* fall through to extraction */ }
-  const start = s.search(/[{[]/);
-  if (start < 0) return null;
-  const open = s[start], close = open === "{" ? "}" : "]";
-  let depth = 0, inStr = false, esc = false;
-  for (let i = start; i < s.length; i++) {
-    const c = s[i];
-    if (inStr) {
-      if (esc) esc = false;
-      else if (c === "\\") esc = true;
-      else if (c === '"') inStr = false;
-      continue;
-    }
-    if (c === '"') { inStr = true; continue; }
-    if (c === open) depth++;
-    else if (c === close && --depth === 0) {
-      try { return JSON.parse(s.slice(start, i + 1)); } catch { return null; }
-    }
-  }
-  return null;
-}
-
-function shallowValidate(schema, value) {
-  const problems = [];
-  if (!schema || typeof schema !== "object") return problems;
-  if (schema.type === "object") {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-      return [`expected object, got ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`];
-    }
-    for (const k of schema.required || []) if (!(k in value)) problems.push(`missing required key "${k}"`);
-    for (const [k, sub] of Object.entries(schema.properties || {})) {
-      if (!(k in value) || !sub.type) continue;
-      const v = value[k];
-      const t = sub.type === "integer" ? (Number.isInteger(v) ? "integer" : typeof v)
-        : Array.isArray(v) ? "array" : typeof v;
-      if (t !== sub.type && !(sub.type === "number" && typeof v === "number")) {
-        problems.push(`key "${k}": expected ${sub.type}, got ${t}`);
-      }
-    }
-  } else if (schema.type === "array" && !Array.isArray(value)) {
-    problems.push(`expected array, got ${typeof value}`);
-  }
-  return problems;
-}
-
-const schemaInstruction = (schema) =>
-  "\n\n---\nSTRUCTURED OUTPUT REQUIRED. Your final reply must be ONLY a single JSON value that " +
-  "validates against this JSON Schema — no prose, no markdown fences, nothing before or after " +
-  `it:\n${JSON.stringify(schema)}`;
-
-// ---------------------------------------------------------------------------------------------
-// main
-// ---------------------------------------------------------------------------------------------
-async function main() {
-  const cli = configure(runArgs(ARGV_SPEC));
-  mkdirSync(cli.runDir, { recursive: true });
-  const journalPath = resolve(cli.runDir, "journal.jsonl");
-  const journal = (entry) => appendFileSync(journalPath, JSON.stringify(entry) + "\n");
-  const note = (m) => process.stderr.write(`[run-workflow] ${m}\n`);
-
-  const sem = makeSemaphore(cli.maxConcurrency);
-  let seq = 0, costAccum = 0, currentPhase = null;
-
-  const budget = {
-    total: cli.budgetUsd,
-    spent: () => costAccum,
-    remaining: () => (cli.budgetUsd == null ? Infinity : Math.max(0, cli.budgetUsd - costAccum)),
-  };
-
-  async function agent(prompt, opts = {}) {
-    const id = ++seq;
-    const label = opts.label || `agent-${id}`;
-    const model = opts.model || "sonnet";
-    const phaseName = opts.phase || currentPhase;
-    if (budget.total != null && budget.remaining() <= 0) {
-      throw new Error(`budget exhausted ($${costAccum.toFixed(3)} of $${budget.total}) before agent "${label}"`);
-    }
-    if (opts.isolation) throw new Error(`agent "${label}": isolation: 'worktree' is not implemented on this lane`);
-    await sem.acquire();
-    const startedAt = new Date().toISOString();
-    const t0 = process.hrtime.bigint();
-    try {
-      let fullPrompt = opts.schema ? prompt + schemaInstruction(opts.schema) : prompt;
-      let result = null, attempts = 0, sessions = [];
-      while (attempts < 2) {
-        attempts++;
-        note(`agent#${id} "${label}" attempt ${attempts} (model=${model}, mode=${cli.workerPermissionMode})`);
-        const r = await runClaude({
-          prompt: fullPrompt, model, permissionMode: cli.workerPermissionMode,
-          cwd: cli.workerCwd, timeoutMs: cli.agentTimeoutS * 1000,
-        });
-        const env = r.envelope || {};
-        sessions.push({ session_id: env.session_id ?? null, cost_usd: env.total_cost_usd ?? null, is_error: env.is_error ?? null, killed: r.killed });
-        if (typeof env.total_cost_usd === "number") costAccum += env.total_cost_usd;
-        if (!r.ok) { result = null; if (r.killed) break; continue; }
-        if (!opts.schema) { result = env.result ?? null; break; }
-        const parsed = extractJson(env.result);
-        const problems = parsed === null ? ["reply contained no parseable JSON"] : shallowValidate(opts.schema, parsed);
-        if (problems.length === 0) { result = parsed; break; }
-        note(`agent#${id} "${label}" schema problems: ${problems.join("; ")}`);
-        fullPrompt = prompt + schemaInstruction(opts.schema) +
-          `\n\nA previous attempt failed validation: ${problems.join("; ")}. Correct this.`;
-        result = null;
-      }
-      const wallMs = Number(process.hrtime.bigint() - t0) / 1e6;
-      journal({ seq: id, label, phase: phaseName, model, permission_mode: cli.workerPermissionMode,
-        started_at: startedAt, wall_ms: Math.round(wallMs), attempts, sessions, ok: result !== null, result });
-      return result;
-    } finally {
-      sem.release();
-    }
-  }
-
-  // Thunk errors resolve to null and the call never rejects — the Workflow tool's contract,
-  // which shapeup-run.js's call sites (mechEnvelope, dispatch guards) are written against.
-  const parallel = (thunks) => Promise.all(
-    thunks.map((t) => Promise.resolve().then(t).catch((e) => { note(`parallel thunk failed: ${e.message}`); return null; }))
-  );
-
-  // No barrier between stages; a stage that throws drops the item to null and skips the rest.
-  const pipeline = (items, ...stages) => Promise.all(
-    items.map(async (item, i) => {
-      let acc = item;
-      for (const stage of stages) {
-        try { acc = await stage(acc, item, i); }
-        catch (e) { note(`pipeline item ${i} failed: ${e.message}`); return null; }
-      }
-      return acc;
-    })
-  );
-
-  const phase = (title) => { currentPhase = title; note(`── phase: ${title}`); };
-  const log = (m) => note(String(m));
-  const workflow = () => { throw new Error("workflow() child workflows are not implemented on this lane"); };
-
-  const fn = loadWorkflow(cli.script);
-  note(`running ${basename(cli.script)} (run-dir ${cli.runDir})`);
-  const result = await fn(cli.args, agent, parallel, pipeline, phase, log, budget, workflow);
-
-  const summary = { ok: true, script: basename(cli.script), agents_dispatched: seq,
-    cost_usd: Number(costAccum.toFixed(6)), result };
-  writeFileSync(resolve(cli.runDir, "result.json"), JSON.stringify(summary, null, 2) + "\n");
-  process.stdout.write(JSON.stringify({ ok: true, result }) + "\n");
-  return cli.runDir;
-}
-
-if (isMain(import.meta.url)) {
-  main().catch((e) => {
-    // The failure is written where a background caller will look for it, not only to a stdout
-    // nobody is reading: a launch that dies silently is the exact shape this file exists to end.
-    process.stdout.write(JSON.stringify({ ok: false, error: e.message }) + "\n");
-    process.stderr.write(`[run-workflow] FATAL ${e.stack}\n`);
-    try {
-      const dir = process.argv.includes("--run-dir")
-        ? resolve(process.argv[process.argv.indexOf("--run-dir") + 1])
-        : null;
-      if (dir) {
-        mkdirSync(dir, { recursive: true });
-        writeFileSync(resolve(dir, "result.json"),
-          JSON.stringify({ ok: false, error: e.message }, null, 2) + "\n");
-      }
-    } catch { /* the stdout line above is still the record */ }
-    process.exit(1);
-  });
-}