mandrel 1.92.0 → 1.94.0

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

@@ -124,6 +124,66 @@ export function readLedgerLastEvents(ledgerPath) {
   return out;
 }
 
+/**
+ * Single-delivery analogue of {@link readLedgerLastEvents} (Epic #4476, M5).
+ * A single-delivery run has no Story fan-out; the whole Epic is one long
+ * guarded session walking the Delivery Slicing table, and its liveness signal
+ * is `slice.heartbeat` (emitted off the token stream by the PostToolUse hook).
+ * This scans the ledger for `slice.*` events, treats a slice carrying a
+ * `slice.start` without a matching `slice.end` as in-flight, and returns each
+ * in-flight slice's most recent event timestamp — the same
+ * started-without-ended shape the Story reader uses, keyed by the string
+ * `sliceId`. Any `slice.*` event (notably `slice.heartbeat`) refreshes the
+ * timestamp.
+ *
+ * Pure helper — exported for unit tests.
+ *
+ * @param {string} ledgerPath Absolute path to `lifecycle.ndjson`.
+ * @returns {Map<string, string>} `sliceId → ISO-8601 timestamp`. Empty when
+ *   the ledger is missing, unreadable, or carries no in-flight slices.
+ */
+export function readLedgerSliceEvents(ledgerPath) {
+  if (!ledgerPath || !existsSync(ledgerPath)) return new Map();
+  let raw;
+  try {
+    raw = readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return new Map();
+  }
+  if (!raw) return new Map();
+  const started = new Set();
+  const ended = new Set();
+  const lastTs = new Map();
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!record || record.kind !== 'emitted') continue;
+    const event = typeof record.event === 'string' ? record.event : '';
+    if (!event.startsWith('slice.')) continue;
+    const sliceId = record.payload?.sliceId;
+    if (typeof sliceId !== 'string' || sliceId.length === 0) continue;
+    if (event === 'slice.start') started.add(sliceId);
+    else if (event === 'slice.end') ended.add(sliceId);
+    const ts = typeof record.ts === 'string' ? record.ts : null;
+    if (ts) {
+      const prior = lastTs.get(sliceId);
+      if (!prior || prior < ts) lastTs.set(sliceId, ts);
+    }
+  }
+  const out = new Map();
+  for (const id of started) {
+    if (ended.has(id)) continue;
+    const ts = lastTs.get(id);
+    if (ts) out.set(id, ts);
+  }
+  return out;
+}
+
 /**
  * Deterministic branch-activity resolver (Story #3900). Returns the epoch-ms
  * timestamp of the most recent commit on `story-<storyId>` via
@@ -139,18 +199,25 @@ export function readLedgerLastEvents(ledgerPath) {
  * and injectable so unit tests never spawn a subprocess.
  *
  * @param {number} storyId
- * @param {{ cwd?: string, exec?: typeof execFileSync }} [deps]
+ * @param {{ cwd?: string, exec?: typeof execFileSync, branch?: string }} [deps]
+ *   `branch` overrides the default `story-<storyId>` ref — the single-delivery
+ *   watchdog passes `epic-<id>` (Epic #4476, M5) to consult the one
+ *   integration branch instead of a per-Story branch.
  * @returns {number|null} epoch-ms of the last commit, or null.
  */
 export function branchLastCommitMs(storyId, deps = {}) {
   const exec = deps.exec ?? execFileSync;
   const cwd = deps.cwd ?? process.cwd();
+  const branch =
+    typeof deps.branch === 'string' && deps.branch
+      ? deps.branch
+      : `story-${storyId}`;
   try {
-    const out = exec(
-      'git',
-      ['log', '-1', '--format=%cI', `story-${storyId}`, '--'],
-      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
-    ).trim();
+    const out = exec('git', ['log', '-1', '--format=%cI', branch, '--'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
     if (!out) return null;
     const ms = Date.parse(out);
     return Number.isFinite(ms) ? ms : null;
@@ -180,13 +247,26 @@ export function branchLastCommitMs(storyId, deps = {}) {
  * @param {(storyId: number) => (number|null)} [args.branchActivity]
  *   Resolver for the last commit epoch-ms on `story-<id>`. Defaults to
  *   {@link branchLastCommitMs}. Injected for tests.
+ * @param {Map<string, string>} [args.sliceEvents] `sliceId → ISO-8601 ts`
+ *   from {@link readLedgerSliceEvents} (Epic #4476, M5). Single-delivery has
+ *   no Story fan-out; its liveness signal is `slice.heartbeat`. When
+ *   non-empty, in-flight slices are surfaced under the additive
+ *   `inFlightSlices` / `stalledSlices` fields — the story fields are
+ *   untouched, so a fan-out run's envelope is byte-for-byte unchanged.
+ * @param {(epicId: number) => (number|null)} [args.epicBranchActivity]
+ *   Resolver for the last commit epoch-ms on the single-delivery integration
+ *   branch `epic-<id>` — the deterministic forward-progress signal for the
+ *   one long session, mirroring the per-Story branch check. Injected for
+ *   tests.
  * @returns {{
  *   kind: 'wave-stall',
  *   epicId: number,
  *   thresholdMinutes: number,
  *   checkedAt: string,
  *   stalled: Array<{storyId: number, lastEventAt: string, idleMinutes: number}>,
- *   inFlight: number[]
+ *   inFlight: number[],
+ *   stalledSlices: Array<{sliceId: string, lastEventAt: string, idleMinutes: number}>,
+ *   inFlightSlices: string[]
  * }}
  */
 export function buildWaveStallEnvelope({
@@ -195,6 +275,9 @@ export function buildWaveStallEnvelope({
   lastEvents,
   now,
   branchActivity = branchLastCommitMs,
+  sliceEvents = new Map(),
+  epicBranchActivity = (eid) =>
+    branchLastCommitMs(0, { branch: `epic-${eid}` }),
 }) {
   const checkedAt = now.toISOString();
   const thresholdMs = thresholdMinutes * 60 * 1000;
@@ -227,6 +310,37 @@ export function buildWaveStallEnvelope({
   }
   inFlight.sort((a, b) => a - b);
   stalled.sort((a, b) => a.storyId - b.storyId);
+
+  // Single-delivery slice liveness (additive). A slice that has gone silent
+  // past the threshold is a stall UNLESS the `epic-<id>` branch carries a
+  // recent commit — the same forward-progress carve-out the Story path uses.
+  const stalledSlices = [];
+  const inFlightSlices = [];
+  for (const [sliceId, ts] of sliceEvents) {
+    inFlightSlices.push(sliceId);
+    const eventMs = Date.parse(ts);
+    if (!Number.isFinite(eventMs)) continue;
+    const idleMs = now.getTime() - eventMs;
+    if (idleMs < thresholdMs) continue;
+
+    const commitMs = epicBranchActivity(epicId);
+    if (
+      typeof commitMs === 'number' &&
+      Number.isFinite(commitMs) &&
+      now.getTime() - commitMs < thresholdMs
+    ) {
+      continue;
+    }
+
+    stalledSlices.push({
+      sliceId,
+      lastEventAt: ts,
+      idleMinutes: Math.floor(idleMs / 60000),
+    });
+  }
+  inFlightSlices.sort();
+  stalledSlices.sort((a, b) => a.sliceId.localeCompare(b.sliceId));
+
   return {
     kind: 'wave-stall',
     epicId,
@@ -234,6 +348,8 @@ export function buildWaveStallEnvelope({
     checkedAt,
     stalled,
     inFlight,
+    stalledSlices,
+    inFlightSlices,
   };
 }
 
@@ -251,7 +367,13 @@ export function buildWaveStallEnvelope({
  * @param {(storyId: number) => (number|null)} [args.branchActivity]
  *   Branch-liveness resolver; defaults to {@link branchLastCommitMs}.
  *   Injected for tests so the watchdog never spawns git.
- * @returns {{envelope: object, stalledCount: number}}
+ * @param {(epicId: number) => (number|null)} [args.epicBranchActivity]
+ *   Single-delivery integration-branch (`epic-<id>`) liveness resolver;
+ *   injected for tests. Defaults to {@link branchLastCommitMs} with the
+ *   `epic-<id>` ref.
+ * @returns {{envelope: object, stalledCount: number}} `stalledCount` counts
+ *   both stalled Stories (fan-out) and stalled slices (single delivery), so a
+ *   dead single-delivery session still exits the CLI non-zero.
  */
 export function runCheckIdle({
   epicId,
@@ -260,6 +382,7 @@ export function runCheckIdle({
   now = new Date(),
   config,
   branchActivity = branchLastCommitMs,
+  epicBranchActivity,
 }) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError('runCheckIdle: epicId must be a positive integer');
@@ -271,14 +394,20 @@ export function runCheckIdle({
   }
   const resolvedPath = ledgerPath ?? epicLedgerPath(epicId, config);
   const lastEvents = readLedgerLastEvents(resolvedPath);
+  const sliceEvents = readLedgerSliceEvents(resolvedPath);
   const envelope = buildWaveStallEnvelope({
     epicId,
     thresholdMinutes,
     lastEvents,
     now,
     branchActivity,
+    sliceEvents,
+    ...(epicBranchActivity ? { epicBranchActivity } : {}),
   });
-  return { envelope, stalledCount: envelope.stalled.length };
+  return {
+    envelope,
+    stalledCount: envelope.stalled.length + envelope.stalledSlices.length,
+  };
 }
 
 async function main(argv) {

package/.agents/skills/core/api-and-interface-design/SKILL.md

@@ -19,7 +19,7 @@ description:
 - Define the contract before implementing — interfaces are the spec; implementation follows.
 - Validate at system **boundaries** (API routes, form handlers, env-var loaders, third-party responses) using a strict schema. After validation, internal code trusts the types; do not re-validate between internal functions.
 - Treat third-party API responses as untrusted data — validate shape and content before using them in any decision, render, or logic path.
-- Prefer **addition over modification**: extend interfaces with optional fields rather than changing existing types or removing fields; reach for the deprecation playbook (see `deprecation-and-migration`) when removal is unavoidable.
+- Prefer **addition over modification**: extend interfaces with optional fields rather than changing existing types or removing fields. When removal is unavoidable, use an expand–contract migration — ship the replacement, migrate consumers, then remove the old surface in a later release.
 - Follow REST resource conventions (`GET/POST/PATCH/DELETE /resource`, sub-resources at `/resource/:id/child`) and paginate every list endpoint with `page` + `pageSize` query params and a `pagination` envelope.
 - Security input-validation and test-tier MUSTs come from `.agents/rules/security-baseline.md` and `.agents/rules/testing-standards.md` respectively — apply both, and never put DB/wire-shape assertions outside the contract tier.
 
@@ -55,8 +55,10 @@ ordering — becomes a de facto contract once users depend on it. Implications:
   potential commitment.
 - **Don't leak implementation details.** If users can observe it, they will
   depend on it.
-- **Plan for deprecation at design time.** See `deprecation-and-migration`
-  for how to safely remove things users depend on.
+- **Plan for deprecation at design time.** Remove things users depend on via
+  expand–contract: add the replacement, migrate consumers behind a deprecation
+  window, then delete the old surface — never break a published contract in one
+  step.
 - **Tests are not enough.** Even with perfect contract tests, "safe" changes
   can break real users who depend on undocumented behavior.
 

package/.agents/skills/core/code-review-and-quality/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: code-review-and-quality
 description:
-  Conducts multi-axis code review. Use before merging any change. Use when
-  reviewing code written by yourself, another agent, or a human. Use when you
-  need to assess code quality across multiple dimensions before it enters the
-  main branch.
+  Conducts multi-axis code review and runs the disciplined post-green refactor
+  pass. Use before merging any change, when reviewing code written by yourself,
+  another agent, or a human, or when the opt-in `delivery.refactorStage`
+  checkpoint asks for a behaviour-preserving CRAP/duplication pass after the
+  suite is green.
 ---
 
 # Code Review and Quality
@@ -18,9 +19,11 @@ description:
 - Reject "clever" code in favour of the boring, obvious solution. Abstractions MUST earn their complexity (no generalizing before the third use case).
 - Flag dead code artifacts (`_unused` vars, backwards-compat shims, `// removed` comments) and require their removal before merge.
 - Defer to `.agents/rules/security-baseline.md` and the `security-and-hardening` skill for security review; explicit checks include input validation, no hardcoded secrets, parameterized queries, encoded output, authn+authz, and treating external data as untrusted.
-- Defer to `performance-optimization` for perf review; explicit checks include no N+1 queries, no unbounded fetches, no blocking sync work, no obviously oversized bundles.
+- Review performance on the hot path only, and measure before optimizing; explicit checks include no N+1 queries, no unbounded fetches, no blocking sync work, no obviously oversized bundles.
 - Disallow scope creep in a PR: drive-by cleanups, adjacent refactors, and "while I'm here" edits should be split into a separate change.
 - Bug-fix reviews cover **both** the fix and the regression test; a fix without a failing-then-passing test is not approvable.
+- **Refactoring is post-green and behaviour-preserving.** Run the refactor pass only when the suite is already green and gates pass; inputs, outputs, side effects, error semantics, and ordering MUST be identical before and after, and existing tests MUST keep passing **without modification** (if a test had to change, behaviour changed — revert).
+- **Lower CRAP by lowering complexity, and remove duplication at the root.** Target the highest-CRAP well-covered functions and the largest verbatim duplications by measurement (`check-baselines.js`), not by smell; extract one well-named helper rather than leaving near-copies. CRAP must not rise and maintainability must not fall on any touched file, and no gate, floor, or threshold may be retuned to make the pass "succeed".
 
 ## Overview
 
@@ -105,8 +108,8 @@ introduce vulnerabilities?
 
 ### 5. Performance
 
-For detailed profiling and optimization, see `performance-optimization`. Does
-the change introduce performance problems?
+Measure before optimizing, and only on the hot path. Does the change introduce
+performance problems?
 
 - Any N+1 query patterns?
 - Any unbounded loops or unconstrained data fetching?
@@ -409,6 +412,50 @@ Every dependency is a liability.
   optional
 - Accepting "I'll fix it later" — it never happens
 
+## Post-Green Refactor Pass
+
+Review's sibling discipline is the **behaviour-preserving refactor** that drives
+CRAP (Change Risk Anti-Patterns) and duplication down _after_ the code is green
+— the pass wired in as the opt-in `delivery.refactorStage` checkpoint. It
+optimises for the measured CRAP and duplication axes the baselines ratchet, not
+for subjective readability, and it never runs from red.
+
+**When to run:** a baseline report flags a high-CRAP function that is already
+well-covered (so the lever is complexity, not coverage); the same logic is
+duplicated across two or more files and the copies are drifting; or the
+`delivery.refactorStage` checkpoint fires after gates pass and before a Story
+closes. **When NOT to:** before tests are green (write/fix tests first), or when
+a function's CRAP is high because it is _uncovered_ — that is a missing-test
+problem, so drive it with the TDD cycle in
+[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md).
+
+```text
+Confirm green + baseline  →  pick highest-CRAP / largest dup
+        ▲                                  │
+        │                                  ▼
+  re-run gates, confirm   ◄──  refactor   ◄──  comprehend the target
+  CRAP↓ / maint↑, tests pass   (one change)    (call sites + tests)
+```
+
+1. **Baseline.** Confirm green and capture current CRAP and maintainability
+   (`node .agents/scripts/check-baselines.js`) — your do-no-harm reference.
+2. **Target by measurement.** Pick the highest-CRAP well-covered function, or
+   the largest verbatim duplication. Work worst-first.
+3. **Comprehend before you touch (Chesterton's Fence).** Read the call sites and
+   the tests that pin the behaviour first; an "unnecessary" abstraction may
+   exist for testability or extensibility.
+4. **Refactor one step.** Extract a focused function, flatten nesting into guard
+   clauses, replace a nested ternary / boolean-flag param, or extract a single
+   shared helper for the duplication (dedup the _behaviour_, not just the text —
+   look-alike blocks that encode different responsibilities stay separate).
+5. **Verify.** Re-run the affected tests (unmodified) and the baselines. CRAP
+   must not rise, maintainability must not fall, tests must pass. If a test
+   needed editing, revert — behaviour changed.
+
+Keep each refactor an isolated, reviewable commit separate from feature or fix
+work, refactor only the targeted functions/duplications (no drive-by rewrites),
+and leave no dead code behind (unused imports, orphaned helpers).
+
 ## Verification
 
 After review is complete:
@@ -419,3 +466,12 @@ After review is complete:
 - [ ] Tests pass
 - [ ] Build succeeds
 - [ ] The verification story is documented (what changed, how it was verified)
+
+After a post-green refactor pass:
+
+- [ ] The suite was green before and after, with **no test modifications**
+- [ ] CRAP did not rise and maintainability did not fall on any touched file
+      (baselines re-run and compared)
+- [ ] No gate, floor, or coverage threshold was loosened
+- [ ] Duplication was removed at the root (one helper), not just locally patched
+- [ ] Each refactor is an isolated commit, separate from feature or fix work

package/.agents/skills/core/debugging-and-error-recovery/SKILL.md

@@ -15,7 +15,7 @@ description:
 - Follow the triage checklist in order — **Reproduce → Localize → Diagnose → Fix → Verify → Guard** — and never skip steps.
 - A bug you cannot reproduce reliably is a bug you cannot fix with confidence. Invest in reproduction before patching.
 - Fix the **root cause**, not the symptom. Suppressing an error, swallowing an exception, or stubbing an assertion is not a fix.
-- Every bug fix ships with a **failing-then-passing regression test** (the Prove-It Pattern from `test-driven-development`). A fix without a guard test is incomplete.
+- Every bug fix ships with a **failing-then-passing regression test** (the Prove-It Pattern in `.agents/rules/testing-standards.md`). A fix without a guard test is incomplete.
 - Apply the **Anti-Thrashing** rule: if you have applied the same kind of fix more than once and the failure mode hasn't changed, the diagnosis is wrong — re-plan.
 - For non-reproducible bugs, classify them (timing / environment / state / random), add targeted instrumentation, and document conditions instead of chasing in the dark.
 - Bisect history with `git bisect` (or equivalent) when "something used to work" and you cannot localize from the diff.

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Run a holistic, pre-persist consolidation pass over the draft Story
   ticket array an Epic's decompose phase produced. Use during Phase 8 of
   `/plan`, after `epic-plan-decompose-author` writes
-  `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
+  `temp/epic-<Epic_ID>/tickets.json` and before `plan-persist.js`
   validates and persists it. Reconciles the draft against the Tech Spec
   "Delivery Slicing" ceiling via scope-preserving operations only.
 allowed_tools:
@@ -48,7 +48,7 @@ critic cannot grade its own homework.
 `/plan` Phase 8, as the **8.3 — Holistic Consolidation** sub-step:
 immediately after `epic-plan-decompose-author` writes
 `temp/epic-<Epic_ID>/tickets.json` and **before**
-`epic-plan-decompose.js --tickets …` validates and persists. The pass operates
+`plan-persist.js --tickets …` validates and persists. The pass operates
 on the temp artifact so the holistic adjustment happens before the GitHub
 write; the deterministic validator runs *after* it, so the critic can never
 emit a plan the validator would reject.
@@ -61,7 +61,7 @@ passing the Epic ID as the Skill argument. The Skill itself reads:
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** Story array the
   `epic-plan-decompose-author` Skill wrote. This is the consolidation input.
 - `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope
-  emitted by `epic-plan-decompose.js --emit-context`. Read `epicBody`
+  emitted by `plan-context.js --epic <Epic_ID>`. Read `epicBody`
   from it — the sectioned Epic body carrying the folded Tech Spec
   sections (there is no separate `techSpec` key — Story #4324). The
   **"Delivery Slicing"**
@@ -74,7 +74,7 @@ passing the Epic ID as the Skill argument. The Skill itself reads:
 - `temp/epic-<Epic_ID>/tickets.json` — the **consolidated** array, overwriting
   the draft. Same schema as the author skill emits (flat Story array; Stories
   carry top-level `acceptance[]` / `verify[]`; `body` is a serialized string).
-  The downstream `epic-plan-decompose.js --tickets …` validator is the final
+  The downstream `plan-persist.js --tickets …` validator is the final
   gate — author for its rules, not for "looks right."
 - `temp/epic-<Epic_ID>/consolidation-report.md` — a human-readable
   rationale + before/after diff. This is the artifact the workflow shows the
@@ -152,7 +152,7 @@ so the operator sees the coarsening at the Phase 8.3 advisory diff.
 
 Return control. The workflow shows the operator the consolidation report at the
 HITL diff gate; on approval it runs
-`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+`node .agents/scripts/plan-persist.js --epic <Epic_ID> --tickets
 temp/epic-<Epic_ID>/tickets.json`, which validates the consolidated array,
 persists the hierarchy, and flips the Epic to `agent::ready`.
 

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -2,9 +2,9 @@
 name: epic-plan-decompose-author
 description: >-
   Author the Story ticket JSON for an Epic from the decomposer
-  authoring context emitted by `epic-plan-decompose.js --emit-context`. Use
+  authoring context emitted by `plan-context.js --epic <Epic_ID>`. Use
   during Phase 8 of `/plan` when the host LLM needs to write the ticket
-  array before `epic-plan-decompose.js` validates and persists it.
+  array before `plan-persist.js` validates and persists it.
 allowed_tools:
   - Read
   - Write
@@ -15,11 +15,11 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Run only after `epic-plan-decompose.js --emit-context` has written `temp/epic-<Epic_ID>/decomposer-context.json`; fail loudly if the file is missing.
+- Run only after `plan-context.js --epic <Epic_ID>` has written `temp/epic-<Epic_ID>/decomposer-context.json`; fail loudly if the file is missing.
 - Emit exactly one artifact: `temp/epic-<Epic_ID>/tickets.json` (a JSON array). Do not write anywhere else, and never call the GitHub API from this Skill — persistence belongs to the script.
 - Output is JSON only — no prose, no Markdown fence. The downstream validator (`lib/orchestration/ticket-validator.js`) is the authoritative gate.
 - **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the validator rejecting the draft, or a Phase 8.3/8.4/8.5 critic flagging specific Stories — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/tickets.json`, fixing only the rejected or flagged Stories, rather than re-authoring the whole array from scratch. `helpers/plan-epic.md` bounds each critic's feedback to **one refinement pass** — apply the edit and re-run the downstream step once; do not loop.
-- Treat **`maxTickets`** from the context envelope as a **reviewability budget**, not a hard authoring cap (Story #2798). Merge narrow, single-module Stories into their capability first; if the plan genuinely needs more, emit the full plan and add a compact `over_budget_rationale` note inside the first Story's `## Goal` section explaining why the plan exceeds the budget. Operator persistence then requires the explicit `--allow-over-budget` override on `epic-plan-decompose.js`; without it the persist step rejects the over-budget array. Never truncate the JSON array to fit.
+- Treat **`maxTickets`** from the context envelope as a **reviewability budget**, not a hard authoring cap (Story #2798). Merge narrow, single-module Stories into their capability first; if the plan genuinely needs more, emit the full plan and add a compact `over_budget_rationale` note inside the first Story's `## Goal` section explaining why the plan exceeds the budget. Operator persistence then requires the explicit `--allow-over-budget` override on `plan-persist.js`; without it the persist step rejects the over-budget array. Never truncate the JSON array to fit.
 - Honour the 2-tier hierarchy: every ticket is a **Story** attached directly to the Epic. Stories carry the implementation scope inline; no Feature and no lower ticket tier exists. Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
 - **Decompose at deliverable granularity, not module/task level.** A Story is a capability slice a frontier model delivers and self-verifies in one pass — a shippable slice a reviewer would accept as a single PR — not a single module or file. See the STORY SIZING section for the full guidance and the single-consumer merge rule.
 - Every ticket carries `type::story` and `persona::*` labels. Every Story ticket object MUST carry top-level `acceptance: string[]` and `verify: string[]` arrays (read by `hasInlineAcceptanceAndVerify` in the validator) and `body` MUST be a **string** produced by `serialize()` from `lib/story-body/story-body.js` — an object body causes `createOp` in `epic-spec-reconciler-ops.js` to throw `StoryBodyParseError` (Story #3302), and is also silently discarded by `composeStoryBody` in the GitHub provider, producing an empty issue body.
@@ -41,7 +41,7 @@ orchestrator can execute autonomously.
 ## When to use
 
 `/plan` Phase 8, immediately after
-`epic-plan-decompose.js --emit-context` writes
+`plan-context.js --epic <Epic_ID>` writes
 `temp/epic-<Epic_ID>/decomposer-context.json`. The Skill replaces the
 inline "Author the Ticket Array" step in the legacy workflow body —
 the caller dispatches this Skill via the `Skill` tool, supplies the Epic
@@ -54,7 +54,7 @@ The dispatcher passes the Epic ID as the Skill argument. The Skill itself
 reads:
 
 - `temp/epic-<Epic_ID>/decomposer-context.json` — produced by
-  `node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --emit-context`.
+  `node .agents/scripts/plan-context.js --epic <Epic_ID>`.
   Fields:
   - `epic.id`, `epic.title`
   - `epicBody` — the sectioned Epic body. It carries everything the
@@ -93,7 +93,7 @@ reads:
   objects conforming to the schema in this Skill's body.
 
 The file MUST exist before the Skill returns. The caller will then run
-`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+`node .agents/scripts/plan-persist.js --epic <Epic_ID> --tickets
 temp/epic-<Epic_ID>/tickets.json`, which validates the array, persists
 the hierarchy as GitHub issues, and transitions the Epic to
 `agent::ready`. The script's validator is the final gate — author for
@@ -140,7 +140,7 @@ machine-consumed.
 ### Step 4 — Hand back to `/plan`
 
 Return control. The caller invokes
-`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+`node .agents/scripts/plan-persist.js --epic <Epic_ID> --tickets
 temp/epic-<Epic_ID>/tickets.json`, which validates, persists, and flips
 the Epic to `agent::ready`.
 

package/.agents/skills/core/epic-plan-premortem/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Run a fresh-context, code-reading pre-mortem critic over the draft Story
   ticket array an Epic's decompose phase produced. Use during Phase 8 of
   `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write
-  `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
+  `temp/epic-<Epic_ID>/tickets.json` and before `plan-persist.js`
   validates and persists it. Reads the sectioned Epic body AND the cited
   code surfaces, then emits predicted-rework findings before any GitHub write.
 allowed_tools:
@@ -49,7 +49,7 @@ independent of the draft it grades.
 after `epic-plan-decompose-author` writes (and, when present,
 `epic-plan-consolidate` consolidates) `temp/epic-<Epic_ID>/tickets.json`, after
 the reachability completeness critic (8.4), and **before**
-`epic-plan-decompose.js --tickets …` validates and persists. The pass operates
+`plan-persist.js --tickets …` validates and persists. The pass operates
 on the temp artifact and emits a report so the operator sees predicted rework in
 the Phase 8 HITL diff before the GitHub write; the author re-runs on the
 findings and the deterministic validator runs *after*, so nothing this critic
@@ -63,7 +63,7 @@ passing the Epic ID as the Skill argument. The Skill itself reads:
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** (or consolidated) Story
   array. This is the pre-mortem subject.
 - `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope emitted
-  by `epic-plan-decompose.js --emit-context`. Read `epicBody` from it —
+  by `plan-context.js --epic <Epic_ID>`. Read `epicBody` from it —
   the sectioned Epic body carrying the folded Tech Spec sections
   (there is no separate `techSpec` key — Story #4324).
 - **The repository working tree** — the actual files each Story's `changes[]` /
@@ -126,7 +126,7 @@ line. Paste identifiers and short rationale only — never full source bodies.
 Return control. The workflow shows the operator the pre-mortem report at the
 Phase 8 HITL diff; on operator approval it re-runs
 `epic-plan-decompose-author` on the findings **before** the persist call
-(`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+(`node .agents/scripts/plan-persist.js --epic <Epic_ID> --tickets
 temp/epic-<Epic_ID>/tickets.json`). This Skill itself persists nothing.
 
 ## Constraints