mandrel 1.94.0 → 2.0.0

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

@@ -1,464 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * wave-tick.js — thin CLI shim around `lib/wave-runner/tick.js`.
- *
- * Reads the `epic-run-state` checkpoint plus fresh Story labels and
- * prints one `WaveTickResult` envelope. The slash-command operator
- * (`/deliver`) consumes the envelope to decide whether to dispatch
- * the next wave, observe in-flight stories, or finalize the Epic.
- *
- * Usage:
- *   node .agents/scripts/wave-tick.js --epic <epicId> [--check-idle <minutes>]
- *
- * The tick is stateless — "loop until terminal" is the caller's job
- * (today: the markdown's wave loop).
- *
- * Output: one JSON object on stdout. Schema in `lib/wave-runner/tick.js`.
- */
-
-import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { epicLedgerPath } from './lib/config/temp-paths.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
-import { createProvider } from './lib/provider-factory.js';
-import { tick } from './lib/wave-runner/tick.js';
-
-const HELP = `Usage: node .agents/scripts/wave-tick.js --epic <epicId> [--check-idle <minutes>]
-
-Stateless wave-loop planner. Reads the epic-run-state checkpoint on
-Epic #<id>, evaluates the live story-label state, and prints one
-WaveTickResult envelope describing the next dispatchable action.
-
-When --check-idle <minutes> is supplied, the planner skips the normal
-WaveTickResult emit and instead scans the per-Epic lifecycle ledger
-(temp/epic-<id>/lifecycle.ndjson) for in-flight Stories whose most
-recent lifecycle event is older than the threshold. Emits a single
-JSON envelope on stdout and exits non-zero when at least one stalled
-Story is detected. The envelope shape mirrors the wave-stall
-structured-comment payload so the slash-command host can post it
-verbatim.
-`;
-
-export async function runWaveTickCli({
-  epicId,
-  cwd,
-  injectedProvider,
-  injectedConfig,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError('runWaveTickCli: --epic must be a positive integer');
-  }
-
-  const config = injectedConfig ?? resolveConfig({ cwd });
-  const provider = injectedProvider ?? createProvider(config);
-
-  const result = await tick({
-    epic: epicId,
-    collaborators: { provider },
-    ctx: { config },
-  });
-
-  return result;
-}
-
-/**
- * Scan the per-Epic lifecycle ledger and compute, per in-flight Story,
- * the timestamp of its most recent lifecycle event. A Story is
- * "in-flight" when the ledger carries a `story.dispatch.start` record
- * without a matching `story.dispatch.end`. Any other `story.*` event
- * (notably `story.heartbeat` from Story #3057) refreshes the Story's
- * last-event timestamp.
- *
- * Pure helper — exported for unit tests.
- *
- * @param {string} ledgerPath Absolute path to `lifecycle.ndjson`.
- * @returns {Map<number, string>} `storyId → ISO-8601 timestamp`. Empty
- *   when the ledger is missing, unreadable, or carries no in-flight
- *   Stories.
- */
-export function readLedgerLastEvents(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('story.')) continue;
-    const storyId = record.payload?.storyId;
-    if (!Number.isInteger(storyId) || storyId <= 0) continue;
-    if (event === 'story.dispatch.start') started.add(storyId);
-    else if (event === 'story.dispatch.end') ended.add(storyId);
-    const ts = typeof record.ts === 'string' ? record.ts : null;
-    if (ts) {
-      const prior = lastTs.get(storyId);
-      if (!prior || prior < ts) lastTs.set(storyId, 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;
-}
-
-/**
- * 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
- * `git log -1 --format=%cI`, or `null` when the branch does not exist, has no
- * commits, or git is unavailable.
- *
- * This is the secondary liveness signal the idle watchdog consults before
- * flagging a Story as stalled: a healthy long-running Story routinely exceeds
- * the heartbeat threshold during `implementing → closing` (heartbeats fire
- * only at phase transitions), but its branch keeps gaining commits. A recent
- * commit is hard, deterministic evidence of forward progress that does not
- * depend on a heartbeat landing in the ledger. Pure-ish (shells out to git)
- * and injectable so unit tests never spawn a subprocess.
- *
- * @param {number} storyId
- * @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', branch, '--'], {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    if (!out) return null;
-    const ms = Date.parse(out);
-    return Number.isFinite(ms) ? ms : null;
-  } catch {
-    // Branch absent / git unavailable — no deterministic signal.
-    return null;
-  }
-}
-
-/**
- * Build the wave-stall envelope. Pure helper — exported for unit tests.
- *
- * A Story whose latest ledger event is older than the threshold is *not*
- * flagged as stalled when its `story-<id>` branch carries a commit newer
- * than the threshold (Story #3900). Branch commits are deterministic
- * forward-progress evidence that survives the heartbeat-cadence gap during
- * `implementing → closing`, so consulting them eliminates the false-positive
- * re-dispatch hazard (two agents on one branch) the watchdog otherwise
- * manufactures for every healthy long-running Story.
- *
- * @param {object} args
- * @param {number} args.epicId
- * @param {number} args.thresholdMinutes
- * @param {Map<number, string>} args.lastEvents `storyId → ISO-8601 ts`
- *   from {@link readLedgerLastEvents}.
- * @param {Date} args.now Reference clock for the staleness comparison.
- * @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[],
- *   stalledSlices: Array<{sliceId: string, lastEventAt: string, idleMinutes: number}>,
- *   inFlightSlices: string[]
- * }}
- */
-export function buildWaveStallEnvelope({
-  epicId,
-  thresholdMinutes,
-  lastEvents,
-  now,
-  branchActivity = branchLastCommitMs,
-  sliceEvents = new Map(),
-  epicBranchActivity = (eid) =>
-    branchLastCommitMs(0, { branch: `epic-${eid}` }),
-}) {
-  const checkedAt = now.toISOString();
-  const thresholdMs = thresholdMinutes * 60 * 1000;
-  const stalled = [];
-  const inFlight = [];
-  for (const [storyId, ts] of lastEvents) {
-    inFlight.push(storyId);
-    const eventMs = Date.parse(ts);
-    if (!Number.isFinite(eventMs)) continue;
-    const idleMs = now.getTime() - eventMs;
-    if (idleMs < thresholdMs) continue;
-
-    // Ledger says idle — consult the branch as a deterministic liveness
-    // signal before declaring a stall. A recent commit means the Story is
-    // making progress despite the heartbeat-cadence gap.
-    const commitMs = branchActivity(storyId);
-    if (
-      typeof commitMs === 'number' &&
-      Number.isFinite(commitMs) &&
-      now.getTime() - commitMs < thresholdMs
-    ) {
-      continue;
-    }
-
-    stalled.push({
-      storyId,
-      lastEventAt: ts,
-      idleMinutes: Math.floor(idleMs / 60000),
-    });
-  }
-  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,
-    thresholdMinutes,
-    checkedAt,
-    stalled,
-    inFlight,
-    stalledSlices,
-    inFlightSlices,
-  };
-}
-
-/**
- * Run the `--check-idle` path. Exported so unit tests can drive the
- * branch without spawning the CLI subprocess.
- *
- * @param {object} args
- * @param {number} args.epicId
- * @param {number} args.thresholdMinutes
- * @param {string} [args.ledgerPath] Override for tests; defaults to the
- *   canonical `temp/epic-<id>/lifecycle.ndjson`.
- * @param {Date} [args.now] Override for tests; defaults to wall clock.
- * @param {object} [args.config] Optional resolved config for tempRoot.
- * @param {(storyId: number) => (number|null)} [args.branchActivity]
- *   Branch-liveness resolver; defaults to {@link branchLastCommitMs}.
- *   Injected for tests so the watchdog never spawns git.
- * @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,
-  thresholdMinutes,
-  ledgerPath,
-  now = new Date(),
-  config,
-  branchActivity = branchLastCommitMs,
-  epicBranchActivity,
-}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError('runCheckIdle: epicId must be a positive integer');
-  }
-  if (!Number.isInteger(thresholdMinutes) || thresholdMinutes <= 0) {
-    throw new TypeError(
-      'runCheckIdle: thresholdMinutes must be a positive integer',
-    );
-  }
-  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 + envelope.stalledSlices.length,
-  };
-}
-
-async function main(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      epic: { type: 'string' },
-      'check-idle': { type: 'string' },
-      help: { type: 'boolean', short: 'h' },
-    },
-    strict: false,
-    allowPositionals: true,
-  });
-
-  if (values.help) {
-    process.stdout.write(`${HELP}\n`);
-    return;
-  }
-
-  const epicId = Number.parseInt(
-    String(values.epic ?? '').replace(/^#/, ''),
-    10,
-  );
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    Logger.error('wave-tick: --epic <id> is required (positive integer)');
-    process.exitCode = 2;
-    return;
-  }
-
-  if (values['check-idle'] !== undefined) {
-    const thresholdMinutes = Number.parseInt(String(values['check-idle']), 10);
-    if (!Number.isInteger(thresholdMinutes) || thresholdMinutes <= 0) {
-      Logger.error(
-        'wave-tick: --check-idle <minutes> must be a positive integer',
-      );
-      process.exitCode = 2;
-      return;
-    }
-    const { envelope, stalledCount } = runCheckIdle({
-      epicId,
-      thresholdMinutes,
-    });
-    process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
-    process.exitCode = stalledCount > 0 ? 1 : 0;
-    return;
-  }
-
-  const result = await runWaveTickCli({ epicId });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-runAsCli(import.meta.url, () => main(process.argv.slice(2)), {
-  source: 'wave-tick',
-});

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

@@ -1,172 +0,0 @@
----
-name: epic-plan-consolidate
-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 `plan-persist.js`
-  validates and persists it. Reconciles the draft against the Tech Spec
-  "Delivery Slicing" ceiling via scope-preserving operations only.
-allowed_tools:
-  - Read
-  - Write
-  - Bash
----
-
-# epic-plan-consolidate
-
-## Policy Capsule
-
-- Run only after `epic-plan-decompose-author` has written `temp/epic-<Epic_ID>/tickets.json`; fail loudly if the draft array is missing. Read the sectioned Epic body (which carries the folded Tech Spec sections) from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
-- Emit exactly two artifacts inside `temp/epic-<Epic_ID>/`: the **consolidated** `tickets.json` (overwriting the draft array in place) and a human-readable `consolidation-report.md` (the rationale + before/after diff the operator reviews at the HITL gate). Both MUST exist before returning.
-- **Scope conservation is the load-bearing invariant.** You are a *critic*, not a second author: you MUST NOT add scope, invent tickets, or drop acceptance criteria. Every acceptance item and every `verify` entry present in the draft MUST survive into the consolidated array (possibly re-homed onto a merged Story). **This is your contract, not a machine guarantee:** there is **no runtime acceptance-union diff** on your output. The only deterministic runtime backstop the validator applies after you run is the standard ticket-structure validation — it does not re-derive the pre-consolidation acceptance/verify union, so a critic that silently dropped an acceptance item would **not** be caught downstream. (The repo's unit test exercises a *pure model* of the merge over an over-fragmented fixture to document the intended invariant; it does not inspect this Skill's actual output.) Conserve scope yourself, deliberately, on every merge.
-- Your operations are constrained to exactly two shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
-- Consume the Tech Spec **"Delivery Slicing"** section as a **ceiling, not a target**, when one is present: the Architect's proposed N shippable Stories is an *upper bound*, not a floor. Cluster the draft's Stories toward that grouping, and go **below** N when slices form dependent single-consumer chains — a slice whose "Independent? No" row carries no justification (parallelism, risk isolation, or delivery-envelope pressure) folds into its consumer. You **never** split above N. When the section is **absent**, degrade gracefully — apply only the cohesion rules below and leave the rest of the draft shape intact.
-- Apply the same cohesion heuristic the author skill leads with: **one Story = one coherent change with one reason to exist**, and the **single-consumer merge rule** (a Story whose only consumer is one sibling Story is merged into that sibling). Lead every merge decision with the change's reason, not its file count.
-- **Missing reason-to-exist check (cohesion gate).** Every draft Story body MUST carry a non-empty `reason_to_exist` meta field (the parseable form of "one Story = one coherent change with one reason to exist", encoded in the `<!-- meta: {"reason_to_exist": "..."} -->` comment and surfaced as `body.reason_to_exist` by `lib/story-body/story-body.js`). Flag any Story whose body carries **no** non-empty reason to exist: a Story that cannot state its single reason in one sentence is a cohesion smell — it is probably two Stories, or two Stories that should be merged into one. Name each flagged Story in the consolidation report so the operator sees the cohesion gap at the HITL diff gate.
-- After every merge, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
-- The consolidation report MUST name each operation applied (merged slugs → surviving slug, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call. When the consolidated count drops **below** the Delivery-Slicing count (a below-ceiling coarsening), the report MUST surface that fact explicitly — e.g. `Below ceiling: N (Delivery Slicing) → M (consolidated)` — and attach a one-line rationale to each below-ceiling merge (which dependent single-consumer slice folded into which consumer, and why it was unjustified), so the operator sees the coarsening at the Phase 8.3 advisory diff.
-
-## Role
-
-Senior Project Manager + Orchestrator, acting as a **holistic critic** with
-fresh context — deliberately *separate* from `epic-plan-decompose-author` (the
-generator) so the pass is a fresh-context review, not a same-pass self-critique.
-The `/plan` workflow delivers that fresh context by **dispatching this skill
-inside a genuine sub-agent** (`Agent` tool, `subagent_type: general-purpose`) at
-Phase 8.3, rather than activating it inline in the authoring turn — the
-sub-agent does not inherit the conversation that authored the draft, so the
-critic cannot grade its own homework.
-
-> **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
-> why this critic runs with fresh context, why scope conservation is your
-> contract rather than a runtime guarantee, and how the below-ceiling
-> coarsening case is reported.
-
-## When to use
-
-`/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**
-`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.
-
-## Inputs
-
-The `/plan` workflow dispatches this skill inside a fresh-context sub-agent,
-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 `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"**
-  section (authored by `epic-plan-spec-author`) is the
-  grouping **ceiling** when present (you may merge below it, never split above
-  it); degrade gracefully when it is absent.
-
-## Outputs
-
-- `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 `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
-  operator at the HITL diff gate before the persist call.
-
-Both files MUST exist before the Skill returns.
-
-## Procedure
-
-### Step 1 — Load the draft and the ceiling
-
-Read `temp/epic-<Epic_ID>/tickets.json` (the draft array) and
-`temp/epic-<Epic_ID>/decomposer-context.json` (for the `epicBody`, which
-carries the Tech Spec sections). Locate
-the **"Delivery Slicing"** section. Pin two facts before mutating
-anything:
-
-1. The **grouping ceiling** — the N shippable Stories the Architect proposed in
-   Delivery Slicing, or `null` when the section is absent (graceful-degrade
-   mode: cohesion rules only). Treat N as an upper bound you may go below, not a
-   floor you must hit. Note which slices are marked "Independent? No" and
-   whether each carries a justification (parallelism, risk isolation, or
-   delivery-envelope pressure) — an unjustified dependent slice is a
-   fold-into-consumer candidate.
-2. The **draft Story count** — so you can spot over-fragmented capability
-   clusters.
-
-### Step 2 — Plan the consolidation
-
-Across the draft Story array, decide which Stories merge:
-
-- **Over-fragmented capability** → when several draft Stories map to one
-  Delivery-Slicing slice (or one coherent reason to exist), merge them into a
-  single Story: union their `changes` / `acceptance` / `verify` / `references`,
-  write one coherent `goal`, and keep the union of labels.
-- **Single-consumer Story** → merge into the one sibling that consumes it. This
-  is the primary lever for going **below** the Delivery-Slicing ceiling: an
-  "Independent? No" slice whose only consumer is one sibling folds into that
-  sibling unless its row justifies staying separate (parallelism, risk
-  isolation, or delivery-envelope pressure). Coarsening below N here is
-  expected, not an over-reach — record it as a below-ceiling merge (see Step 4).
-- **Missing reason to exist** → flag any Story whose body carries no non-empty
-  `reason_to_exist` meta field. A Story that cannot name its single coherent
-  reason is a cohesion smell; record it in the report so the operator can
-  re-scope it (merge, split, or have the author supply the reason) at the HITL
-  gate.
-
-Never split a draft Story to *reach* N — N is a ceiling, and adding scope is
-out of contract. Record each decision with its one-line reason for the report.
-
-### Step 3 — Rewire dependencies and conserve scope
-
-After applying the operations:
-
-- **Rewire `depends_on`**: drop self-edges, re-point any edge that named a
-  deleted slug at its surviving successor, and dedupe. No `depends_on` may
-  reference a slug absent from the consolidated array.
-- **Conserve scope**: assert the union of all `acceptance` items and all
-  `verify` entries across the consolidated array equals the union across the
-  draft. Nothing is dropped; nothing new is invented. If you cannot preserve an
-  item, you have over-reached — back the operation out.
-
-### Step 4 — Write both artifacts
-
-Write the consolidated array to `temp/epic-<Epic_ID>/tickets.json` (2-space
-indent, machine-consumed) and the rationale + before/after diff to
-`temp/epic-<Epic_ID>/consolidation-report.md`. When the consolidated count
-landed **below** the Delivery-Slicing ceiling, the report MUST call that out
-explicitly — a `Below ceiling: N (Delivery Slicing) → M (consolidated)` line
-plus a one-line rationale per below-ceiling merge (which dependent
-single-consumer slice folded into which consumer, and why it was unjustified) —
-so the operator sees the coarsening at the Phase 8.3 advisory diff.
-
-### Step 5 — Hand back to `/plan`
-
-Return control. The workflow shows the operator the consolidation report at the
-HITL diff gate; on approval it runs
-`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`.
-
-## Constraints
-
-- Do **not** call the GitHub API from this Skill. It reads two temp artifacts
-  and writes two temp artifacts; persistence belongs to the script.
-- Do **not** write outside `temp/epic-<Epic_ID>/`.
-- Do **not** add scope or invent tickets. The two permitted operations (merge
-  Stories, rewire `depends_on`) are exhaustive — anything else is out of
-  contract.
-- If `temp/epic-<Epic_ID>/tickets.json` is missing, fail loudly and instruct
-  the caller to run the `epic-plan-decompose-author` Skill first.
-- The validator
-  ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
-  is the authoritative post-consolidation gate. Re-consolidate when it
-  rejects rather than patching tickets by hand.

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

@@ -1,51 +0,0 @@
-# epic-plan-consolidate — examples & extended rationale
-
-Read this file on demand. The SKILL.md carries the operating contract (Policy
-Capsule, Inputs / Outputs, Procedure, Constraints); this file carries the
-extended rationale behind the consolidation pass — why it is a separate,
-fresh-context critic and how the scope-conservation invariant is enforced by
-you rather than by the runtime.
-
-## Why a separate fresh-context critic
-
-This Skill acts as a **holistic critic** with fresh context (a Senior Project
-Manager + Orchestrator lens). It is deliberately *separate* from
-`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
-weak mode this is built to escape. The generator maps Epic capabilities to
-Stories ~1:1; this critic steps back and looks at the *whole* decomposition
-against the Tech Spec's intentional grouping before any GitHub write.
-
-## Scope conservation is your contract, not a machine guarantee
-
-Scope conservation is the load-bearing invariant: you MUST NOT add scope,
-invent tickets, or drop acceptance criteria. Every acceptance item and every
-`verify` entry present in the draft MUST survive into the consolidated array
-(possibly re-homed onto a merged Story).
-
-**This is your contract, not a machine guarantee.** There is **no runtime
-acceptance-union diff** on your output. The only deterministic runtime backstop
-the validator applies after you run is the standard ticket-structure
-validation — it does not re-derive the pre-consolidation acceptance/verify
-union, so a critic that silently dropped an acceptance item would **not** be
-caught downstream. (The repo's unit test exercises a *pure model* of the merge
-over an over-fragmented fixture to document the intended invariant; it does not
-inspect this Skill's actual output.) Conserve scope yourself, deliberately, on
-every merge — and if you cannot preserve an item, you have over-reached, so back
-the operation out.
-
-## Ceiling, not target — the below-ceiling coarsening case
-
-Consume the Tech Spec **"Delivery Slicing"** section as a **ceiling, not a
-target** when present: the Architect's proposed N shippable Stories is an
-*upper bound*, not a floor. Cluster the draft's Stories toward that grouping,
-and go **below** N when slices form dependent single-consumer chains — a slice
-whose "Independent? No" row carries no justification (parallelism, risk
-isolation, or delivery-envelope pressure) folds into its consumer. You **never**
-split above N.
-
-When the consolidated count drops **below** the Delivery-Slicing count, the
-consolidation report MUST surface that fact explicitly — e.g.
-`Below ceiling: N (Delivery Slicing) → M (consolidated)` — and attach a one-line
-rationale to each below-ceiling merge (which dependent single-consumer slice
-folded into which consumer, and why it was unjustified), so the operator sees
-the coarsening at the Phase 8.3 advisory diff.