mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -2,7 +2,6 @@ import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
   DEFAULT_TASK_SIZING,
   DELIVERABLE_GRANULARITY_GUIDANCE,
-  SOFT_STORIES_PER_FEATURE,
 } from '../orchestration/ticket-validator-sizing.js';
 
 /**
@@ -13,22 +12,23 @@ import {
  * resolved value; importing it here means a fallback path (no caller-supplied
  * value) still tracks the framework default in `lib/config/limits.js`.
  *
- * 3-tier is the only published hierarchy after Task #3154 deleted the
- * `planning.hierarchy` flag: the prompt omits the Task layer entirely and
- * asks the planner to inline acceptance/verify on the Story body.
+ * 2-tier is the only published hierarchy after Story #4041 removed the
+ * Feature tier: the prompt emits Stories only (direct Epic children) and
+ * asks the planner to carry acceptance/verify as top-level ticket arrays.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
 } = {}) {
-  return render3TierPrompt({ maxTickets });
+  return render2TierPrompt({ maxTickets });
 }
 
 /**
- * 3-tier prompt (Epic #3078). Decomposes to Feature → Story only — no Task
- * layer. Acceptance criteria and verification commands live inline on the
- * Story body so the executing agent has everything it needs in one ticket.
+ * 2-tier prompt (Story #4041). Decomposes to Stories only — no Feature and
+ * no Task layer. Acceptance criteria and verification commands live inline
+ * on the Story body so the executing agent has everything it needs in one
+ * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render3TierPrompt({ maxTickets }) {
+function render2TierPrompt({ maxTickets }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
   const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
@@ -40,16 +40,16 @@ function render3TierPrompt({ maxTickets }) {
   const { definition: granularityDefinition, singleConsumerRule } =
     DELIVERABLE_GRANULARITY_GUIDANCE;
   return `You are an expert Senior Project Manager and Orchestrator.
-Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a highly-granular 2-level ticket hierarchy for an AI Agent to execute.
+Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
 
 ### HIERARCHY RULES:
-1. **Features**: Large functional milestones (e.g., "Authentication Provider Integration").
-2. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
-   - MUST be nested under a Feature.
-   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. There is NO Task layer in this hierarchy — acceptance criteria and verification commands live inline on the Story body (see STORY BODY SCHEMA below).
+1. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
+   - Every Story attaches directly to the Epic — there is NO Feature tier and NO Task layer in this hierarchy.
+   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
+   - Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
 
 ### LABEL CONVENTIONS:
-- Every ticket must have a \`type::[feature|story]\` label. The \`type::task\` label is FORBIDDEN under this hierarchy.
+- Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
 - Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
 
 ### OUTPUT FORMAT:
@@ -58,43 +58,52 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 ### JSON SCHEMA:
 [
   {
-    "slug": "unique_string_id",
-    "type": "feature" | "story",
+    "slug": "hyphen-case-id",
+    "type": "story",
     "title": "Short descriptive title",
-    "body": <string for features; see STORY BODY SCHEMA below for stories>,
-    "labels": ["type::...", "persona::..."],
-    "parent_slug": "slug_of_parent_ticket" (leave empty for features to nest under epic),
-    "depends_on": ["slug_of_blocking_dependency"] (optional array of slugs that block execution)
+    "body": <string — see STORY BODY SCHEMA below>,
+    "acceptance": ["<testable, observable criterion>", ...],
+    "verify": ["<exact command or test path> (<tier>)", ...],
+    "labels": ["type::story", "persona::..."],
+    "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
   }
 ]
 
-### FEATURE BODY:
-For Features, \`body\` is a brief string under 2 sentences. Features are navigational — the work happens at the Story level — so dense bodies waste output budget.
+**Slug format**: \`^[a-z0-9][a-z0-9-]*\$\` — hyphen-case only. Underscores are rejected by the validator.
 
-#### FEATURE GROUPING — CAPABILITY/STAKEHOLDER, NOT EXECUTION SHAPE:
+### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
+\`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
-- **Do not group Stories by technical execution shape (cron jobs, middleware, scripts). Group by the capability or stakeholder they serve.** Two Stories that happen to share a delivery mechanism — both are cron sweeps, both are Express middleware, both are CLI scripts — do NOT belong in the same Feature just because of that shared shape. The Feature axis is the user-facing capability or the stakeholder served, never the implementation vehicle.
-- **Operational/compliance work gets its own Feature.** Retention purges, audit-log sweeps, scheduled cleanups, observability emitters, and other operational/compliance chores serve operators and compliance, not end users. Place them in a dedicated \`compliance-and-observability\` or \`data-retention\` Feature — do NOT fold them into a user-facing Feature (e.g. notification flows) merely because they share a cron/scheduled execution shape with user-facing Stories.
-- **Smell test:** if the only thing two Stories have in common is *how* they run (a scheduled job, a request interceptor, a build step) rather than *whom* they serve or *what* capability they deliver, they are mis-grouped. Re-home the operational/compliance Story into its own capability Feature.
+The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object (not nested inside \`body\`). The validator reads \`story.acceptance\` and \`story.verify\` directly — nesting them inside the body makes them invisible to the validator and the decompose is rejected.
 
-### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-For stories, \`body\` is a STRUCTURED OBJECT, not a string. Stories are consumed by non-interactive sub-agents that must self-verify from the Story body alone — there is no Task layer below — so the Story itself must carry everything an agent needs to execute and self-verify.
-
-  "body": {
-    "goal":                  "<one sentence — tie this story to the parent Feature slug, naming the slug>",
-    "changes":               ["<file path>: <verb> <object>", ...],
-    "acceptance":            ["<testable, observable criterion>", ...],
-    "verify":                ["<exact command or test path> (<tier>)", ...],
-    "estimated_test_files":  <integer — number of test files this Story is expected to create or modify; omit when not estimable>
-  }
+The serialized \`body\` string renders these markdown sections (in order):
+
+    ## Goal
+    <one sentence — why this Story exists within the Epic>
+
+    ## Changes
+    - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
+    - ...
+
+    ## Acceptance
+    - [ ] <testable, observable criterion>
+    - ...
+
+    ## Verify
+    - <exact command or test path> (<tier>)
+    - ...
+
+    ## References
+    - {"path": "<read-only dependency path>", "assumption": "exists"}
+    - ...
 
 #### STORY BODY RULES:
 
-- **goal**: One sentence stating WHY this story exists. MUST name the parent Feature slug.
-- **changes**: Each bullet MUST be \`<path-or-glob>: <concrete verb> <object>\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Vague verbs ("clean up", "refactor", "improve", "polish", "tighten") are FORBIDDEN unless paired with a named target — "refactor src/x.ts: extract handleSubmit" is fine, "refactor the form" is not.
-- **acceptance**: Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
-- **verify**: Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
-- **estimated_test_files** (optional): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
+- **goal** (in body string): One sentence stating WHY this story exists within the Epic.
+- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
+- **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
+- **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
+- **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
 
@@ -104,10 +113,8 @@ The primary question is **cohesion, not count**: *is this one coherent change wi
 
 - **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one.
 - ${singleConsumerRule}
-- **Split independent, parallelizable work** into sibling Stories under the same Feature — but only when the pieces genuinely have separate reasons to exist.
+- **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
 - **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.
-- **Every Feature MUST decompose into at least TWO Stories.** A Feature with a single Story is the work of a Story, not a Feature — collapse it (drop the Feature wrapper and attach its lone Story to a sibling Feature, or merge the Feature into another). The validator HARD-rejects a Feature with fewer than two Stories.
-- **Features typically decompose into ≤${SOFT_STORIES_PER_FEATURE} Stories; otherwise split into a sibling Feature.** A Feature stretching past ${SOFT_STORIES_PER_FEATURE} Stories is a sign the Feature scope is two features.
 
 **Numeric backstop (validator-enforced).** These thresholds are sourced from the single \`DEFAULT_TASK_SIZING\` constant in \`ticket-validator-sizing.js\` — there is no second copy to drift:
 
@@ -117,7 +124,7 @@ The primary question is **cohesion, not count**: *is this one coherent change wi
 
 #### \`wide\` DECLARATION (optional — for legitimately broad changes):
 
-A Story whose footprint is legitimately broad declares \`body.wide\` carrying a one-line human-readable reason:
+A Story whose footprint is legitimately broad declares \`wide\` carrying a one-line human-readable reason. Encode it in the \`<!-- meta: {"wide": {"reason": "..."}} -->\` comment that \`serialize()\` appends to the body string — it is NOT a top-level ticket field:
 
 \`\`\`json
 "wide": { "reason": "hard contract cutover: migrate every <X> call site in one PR" }
@@ -139,11 +146,11 @@ Declaring \`wide\` with a non-empty reason **lifts the \`hardFiles\` rejection**
 - Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in PRD §2"]\`. Silence on style sourcing is a smell.
 
 ### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
-The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
+The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file. (These Gherkin \`.feature\` files are BDD artifacts, unrelated to any ticket tier.)
 
 When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
 
-- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against, for parent Feature <slug>").
+- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
 - **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
 - **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
 - **acceptance**: MUST assert (a) every new \`.feature\` file exists, and (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
@@ -153,16 +160,16 @@ When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you
 When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
-When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story \`body.acceptance\` by appending an item of the form:
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
 "Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
 This prevents the executing agent from redoing work the upstream Story already merged.
 
-CRITICAL: Dependencies should follow execution blockers. For hierarchical grouping, strictly use 'parent_slug' (Story parent MUST be a Feature). Features should have no 'parent_slug' (they attach to Epic).
-IMPORTANT DEPENDENCY RULE: Cross-Feature Story dependencies are allowed via \`depends_on\` at the Story level (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
+CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
+IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
 
 ### REVIEWABILITY BUDGET (Story #2798):
 \`maxTickets = ${maxTickets}\` is a **reviewability budget**, not a hard authoring cap. It marks the count of tickets a human operator can comfortably review in one planning pass; emitting more than this overflows the operator's review window. Default behaviour:
 - **Stay at or under the budget when possible.** Merge narrow, single-module stories into larger, cohesive capability stories before splitting; small Stories should merge back into siblings rather than spawn their own container.
-- **Do NOT truncate or over-compress to fit.** If the plan genuinely needs more tickets than the budget, emit the full plan anyway and add a compact \`over_budget_rationale\` string at the top of the FIRST Feature's \`body\` explaining (a) why the plan exceeds the budget and (b) what was already merged to keep the count down. The operator will then either accept the plan by re-running the decompose with the explicit \`--allow-over-budget\` override flag, or push back and ask for a re-scope.
+- **Do NOT truncate or over-compress to fit.** If the plan genuinely needs more tickets than the budget, emit the full plan anyway and add a compact \`over_budget_rationale\` note inside the FIRST Story's \`## Goal\` section explaining (a) why the plan exceeds the budget and (b) what was already merged to keep the count down. The operator will then either accept the plan by re-running the decompose with the explicit \`--allow-over-budget\` override flag, or push back and ask for a re-scope.
 - **Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
 }

package/.agents/scripts/lib/transpile.js

@@ -0,0 +1,93 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { Logger } from './Logger.js';
+
+const require = createRequire(import.meta.url);
+
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+
+let _ts = null;
+let _tsLoadFailed = false;
+
+function loadTypeScript() {
+  if (_ts) return _ts;
+  if (_tsLoadFailed) return null;
+  try {
+    _ts = require('typescript');
+    return _ts;
+  } catch {
+    _tsLoadFailed = true;
+    return null;
+  }
+}
+
+/**
+ * Resolve the `typescript` package version, used to stamp baselines so
+ * consumers can detect transpiler drift. Returns `'0.0.0'` when the
+ * dependency is unresolvable — callers treat that sentinel as "unknown
+ * environment" and may refuse to persist a baseline that includes TS rows.
+ *
+ * @returns {string}
+ */
+export function resolveTsTranspilerVersion() {
+  const ts = loadTypeScript();
+  if (ts && typeof ts.version === 'string') return ts.version;
+  return '0.0.0';
+}
+
+function isTypeScriptPath(filePath) {
+  return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
+}
+
+/**
+ * Pre-transpile TypeScript or TSX sources to JavaScript that the
+ * Esprima-based escomplex kernel can parse. Returns the input unchanged
+ * for `.js` / `.mjs` / `.cjs` paths.
+ *
+ * Type annotations introduce no control flow, so the transpiled output
+ * scores identically to the original TS for cyclomatic complexity,
+ * Halstead volume, and the maintainability index. `.tsx` uses the
+ * `react-jsx` emit so JSX expressions become function calls escomplex
+ * can read; `.preserve` would leave JSX in the output and Esprima would
+ * choke on it.
+ *
+ * On transpile failure the helper returns `null` — callers treat that
+ * as "skip this file" rather than crashing the scan.
+ *
+ * @param {string} filePath
+ * @param {string} source
+ * @returns {string|null}
+ */
+export function transpileIfNeeded(filePath, source) {
+  if (!isTypeScriptPath(filePath)) return source;
+  const ts = loadTypeScript();
+  if (!ts) {
+    Logger.warn(
+      `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
+        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
+    );
+    return null;
+  }
+  try {
+    const result = ts.transpileModule(source, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        isolatedModules: true,
+        noEmitHelpers: true,
+        importHelpers: false,
+        removeComments: false,
+        jsx: ts.JsxEmit.ReactJSX,
+        sourceMap: false,
+      },
+      fileName: path.basename(filePath),
+      reportDiagnostics: false,
+    });
+    return result.outputText;
+  } catch (err) {
+    Logger.warn(
+      `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/wave-runner/tick.js

@@ -36,22 +36,11 @@ import { WaveRunnerError } from './wave-runner-error.js';
  *   currentWave:    number
  *   totalWaves:     number
  *
- * When `spec` is omitted, the planner falls back to the checkpoint's
- * `state.plan` (the GH-derived dependency-DAG grouping originally seeded
- * by /epic-plan) — behaviour is byte-identical to the pre-spec path.
- * When `spec` is supplied, wave grouping is driven by `spec.stories[].wave`
- * (the declarative SSOT from `.agents/epics/<epic-id>.yaml`) and slugs are
- * resolved to GH issue numbers via the sibling `<epic-id>.state.json`
- * mapping; the checkpoint is still consulted for `currentWave`,
- * `totalWaves`, and `waves[]` history but its `plan[]` is overridden.
+ * Wave grouping comes from the checkpoint's `state.plan` (the GH-derived
+ * dependency-DAG grouping originally seeded by /plan).
  *
  * @typedef {object} WaveTickArgs
  * @property {number | { id: number }} epic
- * @property {object} [spec] Parsed epic-spec (see lib/spec/loader.js). When
- *   provided, wave grouping comes from `spec.stories[].wave`.
- * @property {object} [state] Parsed epic-state (see lib/spec/loader.js).
- *   When `spec` is provided, this must be supplied so slugs can resolve to
- *   issue numbers via `state.mapping[slug].issueNumber`.
  * @property {{
  *   provider?: object,
  *   epicRunStateStore?: { read: () => Promise<object|null> },
@@ -74,8 +63,6 @@ export async function tick(args = {}) {
   } = args.collaborators ?? {};
   const ctx = args.ctx ?? {};
   const provider = collabProvider ?? ctx.provider;
-  const spec = args.spec ?? null;
-  const specState = args.state ?? null;
   if (!provider) {
     throw new WaveRunnerError('invalid-input', 'provider is required');
   }
@@ -104,7 +91,8 @@ export async function tick(args = {}) {
   }
 
   const currentWave = positiveIntOrZero(state.currentWave);
-  const { plan, totalWaves } = resolvePlan(state, spec, specState);
+  const plan = Array.isArray(state.plan) ? state.plan : [];
+  const totalWaves = positiveIntOrZero(state.totalWaves);
   const history = Array.isArray(state.waves) ? state.waves : [];
 
   if (totalWaves === 0 || currentWave >= totalWaves) {
@@ -460,143 +448,6 @@ function storyIdOf(s) {
   return s.id ?? s.storyId ?? s.number;
 }
 
-/**
- * Walk `spec.features[].stories[]` and bucket entries by their `wave`
- * value, mapping slugs → GH issue numbers via the sibling state file.
- * Returns `Story[][]` indexed by wave number; missing waves between 0 and
- * the highest declared wave are emitted as empty arrays so wave N is
- * always reachable as `plan[N]`.
- *
- * Each emitted entry is shaped to match the checkpoint plan's
- * `{ id, title }` contract that the rest of `tick()` already consumes:
- *
- *   - `id` is the GH issue number resolved from `state.mapping[slug].issueNumber`
- *     so the same provider.getTicket(id) path used by the spec-less plan
- *     keeps working unchanged.
- *   - `title` is carried through from `story.title` so the wave-start
- *     signal can include the Story's human-readable name without an
- *     extra provider round-trip.
- *   - `slug` is preserved on the entry so observability + future
- *     re-resolution paths can re-key against the spec.
- *
- * When a Story slug has no resolved `issueNumber` in `state.mapping`
- * (a fresh spec entry the reconciler has not materialised yet), the entry
- * is skipped — un-materialised Stories cannot be dispatched anyway, and
- * including them with a `null` id would surface as a `story-fetch`
- * failure inside `tick()`. The reconciler will close the loop on the
- * next apply; until then, an empty wave is a faithful reflection of
- * GitHub state.
- *
- * Pure function — does not read disk, does not call GH. Callers are
- * expected to compose it with `loadSpec` + `loadState` from
- * `lib/spec/loader.js`.
- *
- * @param {object} spec Parsed epic-spec (see lib/spec/loader.js).
- * @param {{mapping?: Record<string, {issueNumber?: number}>}|null} [state]
- *   Parsed epic-state. May be omitted; if missing, no entries can be
- *   resolved and `groupByWave` returns `[]`.
- * @returns {Array<Array<{id: number, title?: string, slug: string}>>}
- */
-export function groupByWave(spec, state = null) {
-  const mapping =
-    state && typeof state.mapping === 'object' && state.mapping !== null
-      ? state.mapping
-      : {};
-  const entries = extractValidStoryEntries(spec, mapping);
-  if (entries.length === 0) return [];
-  const byWave = new Map();
-  let maxWave = -1;
-  for (const { wave, entry } of entries) {
-    if (!byWave.has(wave)) byWave.set(wave, []);
-    byWave.get(wave).push(entry);
-    if (wave > maxWave) maxWave = wave;
-  }
-  if (maxWave < 0) return [];
-  const out = [];
-  for (let i = 0; i <= maxWave; i += 1) {
-    out.push(byWave.get(i) ?? []);
-  }
-  return out;
-}
-
-/**
- * Walk every feature/story pair in `spec` and emit only the entries that
- * survive the spec-validity cascade: the story must be a non-null object,
- * declare a non-negative integer `wave`, declare a string `slug`, and
- * resolve to a numeric `issueNumber` in `mapping`. Each surviving entry
- * is returned as `{ wave, entry }` where `entry` carries the same shape
- * (`{ id, title, slug }`) that `groupByWave` previously pushed into its
- * per-wave bucket.
- *
- * Extracted from `groupByWave` so the bucketing transform stays
- * straight-line; this predicate owns the entire defensive guard cascade
- * and is the right place to add new validation rules going forward.
- *
- * @param {object|null|undefined} spec Parsed epic-spec.
- * @param {Record<string, {issueNumber?: number}>} mapping
- *   Slug → issue-number lookup from the sibling state file.
- * @returns {Array<{wave: number, entry: {id: number, title?: string, slug: string}}>}
- */
-export function extractValidStoryEntries(spec, mapping) {
-  const out = [];
-  const features = Array.isArray(spec?.features) ? spec.features : [];
-  for (const feature of features) {
-    const stories = Array.isArray(feature?.stories) ? feature.stories : [];
-    for (const story of stories) {
-      const resolved = resolveStoryEntry(story, mapping);
-      if (resolved) out.push(resolved);
-    }
-  }
-  return out;
-}
-
-/**
- * Validate a single `story` against the spec-validity cascade and return
- * `{ wave, entry }` when every guard passes, or `null` when any guard
- * trips. Splitting the per-story cascade out keeps both
- * `extractValidStoryEntries` (which owns iteration) and `resolveStoryEntry`
- * (which owns validation) below CRAP 5 even when none of the branches are
- * exercised at runtime — the predicate's cyclomatic footprint is small
- * enough that uncovered branches do not blow the baseline budget.
- *
- * @param {*} story Candidate story from `spec.features[].stories[]`.
- * @param {Record<string, {issueNumber?: number}>} mapping Slug → issue lookup.
- * @returns {{wave: number, entry: {id: number, title?: string, slug: string}} | null}
- */
-function resolveStoryEntry(story, mapping) {
-  if (!story || typeof story !== 'object') return null;
-  if (!Number.isInteger(story.wave) || story.wave < 0) return null;
-  if (typeof story.slug !== 'string' || !story.slug) return null;
-  const mapped = mapping[story.slug];
-  if (!mapped || typeof mapped.issueNumber !== 'number') return null;
-  return {
-    wave: story.wave,
-    entry: { id: mapped.issueNumber, title: story.title, slug: story.slug },
-  };
-}
-
-/**
- * Resolve which plan + totalWaves drive this tick. When `spec` is
- * supplied, the spec-derived grouping wins (and totalWaves comes from
- * the spec since the checkpoint may lag); otherwise the checkpoint's
- * plan is used unchanged. Extracted so `tick()`'s cyclomatic complexity
- * stays inside its baseline budget — the route choice is now a single
- * call, not three ternaries inline.
- *
- * @param {object} state Checkpoint state (already validated as object).
- * @param {object|null} spec Parsed epic-spec or `null` when omitted.
- * @param {object|null} specState Parsed epic-state for slug mapping.
- * @returns {{plan: Array<Array<object>>, totalWaves: number}}
- */
-function resolvePlan(state, spec, specState) {
-  if (spec) {
-    const specPlan = groupByWave(spec, specState);
-    return { plan: specPlan, totalWaves: specPlan.length };
-  }
-  const plan = Array.isArray(state.plan) ? state.plan : [];
-  return { plan, totalWaves: positiveIntOrZero(state.totalWaves) };
-}
-
 /**
  * A Story is "done" when it carries `agent::done` OR its GitHub issue is
  * `state === 'closed'`. The closed-state arm (Story #3907) is what aligns the

package/.agents/scripts/lib/workers/crap-worker.js

@@ -29,7 +29,7 @@
 import fs from 'node:fs';
 import { parentPort } from 'node:worker_threads';
 import { calculateCrapForSource } from '../crap-engine.js';
-import { transpileIfNeeded } from '../maintainability-utils.js';
+import { transpileIfNeeded } from '../transpile.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit

package/.agents/scripts/lib/workers/maintainability-report-worker.js

@@ -39,7 +39,7 @@ import {
   calculateReport,
   calculateReportForFile,
 } from '../maintainability-engine.js';
-import { transpileIfNeeded } from '../maintainability-utils.js';
+import { transpileIfNeeded } from '../transpile.js';
 
 /**
  * Score a pre-sourced content string (Story #3696). Mirrors

package/.agents/scripts/lib/worktree/lifecycle/creation.js

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import {
   applyNodeModulesStrategy,
   installDependencies,
+  probeReusedInstall,
 } from '../node-modules-strategy.js';
 import {
   findByPath,
@@ -41,6 +42,23 @@ export async function ensure(ctx, storyId, branch) {
     if (typeof ctx.onPhase === 'function') ctx.onPhase(name);
   };
 
+  // Reuse must not blindly skip the install: when the prior run's install
+  // failed (or was interrupted), `skipped/worktree-reused` defeats the
+  // retry exactly when it matters — `deriveInstallAction('skipped')` skips.
+  // Probe for a completed install; on a failed probe, retry the install
+  // here and surface its real outcome.
+  const reuseInstallStatus = () => {
+    const strategy = ctx.config?.nodeModulesStrategy ?? 'per-worktree';
+    const probe = probeReusedInstall(strategy, wtPath);
+    if (probe.status !== 'failed') return probe;
+    ctx.logger.warn(
+      `worktree.reuse install probe failed (${probe.reason}) — retrying install in ${wtPath}`,
+    );
+    // `ctx.installDependencies` is a test-injection seam; production ctx
+    // bags leave it unset and get the real installer.
+    return (ctx.installDependencies ?? installDependencies)(ctx, wtPath);
+  };
+
   if (existing) {
     if (existing.branch && existing.branch !== br) {
       throw new Error(
@@ -53,7 +71,7 @@ export async function ensure(ctx, storyId, branch) {
     return {
       path: wtPath,
       created: false,
-      installStatus: { status: 'skipped', reason: 'worktree-reused' },
+      installStatus: reuseInstallStatus(),
     };
   }
 
@@ -87,7 +105,7 @@ export async function ensure(ctx, storyId, branch) {
         return {
           path: wtPath,
           created: false,
-          installStatus: { status: 'skipped', reason: 'worktree-reused' },
+          installStatus: reuseInstallStatus(),
         };
       }
     }