mandrel 1.93.0 → 1.94.0

package/.agents/scripts/sync-claude-agents.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * Projects .agents/agents/ (and .agents/local/agents/ when present) into a flat
+ * `.claude/agents/` tree so Claude Code exposes each role definition as a
+ * role-scoped sub-agent (`subagent_type: <name>`). Exact sibling of
+ * `sync-claude-commands.js` — same header, same local-shadow policy, same
+ * orphan-reap, same prune-exempt handling for the consumer-authored
+ * `.agents/local/agents/` source. Two source directories are enumerated in
+ * order:
+ *
+ *   1. PAYLOAD_SRC  — `.agents/agents/`  (the installed Mandrel payload)
+ *   2. LOCAL_SRC    — `.agents/local/agents/`  (consumer-authored, prune-exempt)
+ *
+ * The payload directory wins on basename collision: if both sources supply
+ * `foo.md`, the payload copy is projected and the local copy is ignored with a
+ * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
+ * agent defs are also protected from the orphan-reap — they survive
+ * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
+ *
+ * Only top-level `.md` files project (`.claude/agents/<name>.md`). Unlike the
+ * commands sync there is no `loops/` namespace and no plugin tree to reap — the
+ * agent surface is flat.
+ *
+ * A `.claude/agents/<name>.md` runs on its **own** system prompt — it does NOT
+ * inherit the `CLAUDE.md` @-import closure — so a spawn routed to a role agent
+ * stops re-paying the always-loaded context (issue #4478). The role defs
+ * @-import `security-baseline.md` so the inviolable security MUSTs stay
+ * single-sourced.
+ *
+ * Usage:  node .agents/scripts/sync-claude-agents.js
+ */
+
+// cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applyHeader } from './lib/command-header.js';
+import { Logger } from './lib/Logger.js';
+
+// Resolve the project root from the invocation cwd — the consumer project where
+// `.agents/` is materialized and where Claude Code loads `.claude/agents/`.
+// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
+// runs from `node_modules/mandrel/.agents/scripts/`, so that climb lands on the
+// package dir and the defs would be written *inside node_modules* rather than
+// the consumer. Every real invocation runs with cwd at the project root
+// (`npm run sync:agents`, the prepare hook). Tests drive fixture trees via the
+// SYNC_CLAUDE_AGENTS_SRC/DEST overrides below.
+const PROJECT_ROOT = process.cwd();
+
+// Env-var overrides exist so the sync logic can be exercised against a fixture
+// agents tree in isolation. When unset, behaviour is unchanged — the script
+// defaults to the real agents / .claude/agents directories. SYNC_CLAUDE_AGENTS_SRC
+// overrides the PAYLOAD source only; LOCAL_SRC is always derived from the project
+// root so fixture tests can isolate the payload source.
+const PAYLOAD_SRC =
+  process.env.SYNC_CLAUDE_AGENTS_SRC ??
+  path.join(PROJECT_ROOT, '.agents', 'agents');
+const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'agents');
+
+const DEST_DIR =
+  process.env.SYNC_CLAUDE_AGENTS_DEST ??
+  path.join(PROJECT_ROOT, '.claude', 'agents');
+
+export const HEADER =
+  '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+export const LOCAL_HEADER =
+  '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+/**
+ * Return true when the given directory path exists and is accessible.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+fs.mkdirSync(DEST_DIR, { recursive: true });
+
+// Top-level .md files project flat. Subdirectories are skipped.
+const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
+
+// Enumerate sources: payload first, then local (if it exists). Payload wins on
+// basename collision — a consumer must not silently shadow a core role def.
+const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
+
+/** @type {Array<{dir: string, name: string}>} */
+const entries = SRC_DIRS.flatMap((dir) =>
+  fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(isTopLevelAgent)
+    .map((e) => ({ dir, name: e.name })),
+);
+
+// Collision policy: payload wins, warn on a shadowed local file.
+const byName = new Map();
+for (const e of entries) {
+  if (byName.has(e.name)) {
+    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+    continue;
+  }
+  byName.set(e.name, e);
+}
+
+// sourceSet drives the orphan-reap: any existing agent def not in this set is
+// removed.
+const sourceSet = new Set(byName.keys());
+
+/**
+ * List the `.md` agent defs currently on disk in the destination.
+ *
+ * @returns {string[]}
+ */
+function listExistingAgents() {
+  try {
+    return fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+for (const name of listExistingAgents()) {
+  if (!sourceSet.has(name)) {
+    fs.unlinkSync(path.join(DEST_DIR, name));
+    Logger.info(`  removed  ${name} (no longer in .agents/agents)`);
+  }
+}
+
+// Copy each role def, injecting the auto-generated header after any leading
+// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
+// agent's name/description). Use a distinct header comment for local-origin files.
+let synced = 0;
+const resolvedEntries = Array.from(byName.values());
+await Promise.all(
+  resolvedEntries.map(async ({ dir, name }) => {
+    const isLocal = dir === LOCAL_SRC;
+    const header = isLocal ? LOCAL_HEADER : HEADER;
+    const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
+    const dest = path.join(DEST_DIR, name);
+    const target = applyHeader(content, header);
+
+    // Skip write if content is already identical (avoid noisy git diffs).
+    try {
+      const existingContent = await fs.promises.readFile(dest, 'utf8');
+      if (existingContent === target) return;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    await fs.promises.writeFile(dest, target, 'utf8');
+    synced++;
+    Logger.info(`  synced   ${name}`);
+  }),
+);
+
+Logger.info(
+  `\n✔ ${synced} file(s) synced, ${sourceSet.size} total agents in .claude/agents/`,
+);

package/.agents/scripts/update-ticket-state.js

@@ -13,6 +13,10 @@
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
+import {
+  enqueueLabel,
+  outboxPathFor,
+} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   cascadeCompletion,
   STATE_LABELS,
@@ -33,6 +37,8 @@ if (
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
+      buffer: { type: 'boolean' },
+      epic: { type: 'string' },
     },
     strict: false,
   });
@@ -69,6 +75,31 @@ if (
       return;
     }
 
+    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
+    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
+    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
+    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
+    // immediately and are never buffered. Requires --epic to locate the outbox.
+    if (
+      values.buffer &&
+      state !== STATE_LABELS.BLOCKED &&
+      state !== STATE_LABELS.DONE
+    ) {
+      const epicId = Number.parseInt(values.epic ?? '', 10);
+      if (!Number.isInteger(epicId) || epicId <= 0) {
+        throw new Error('--buffer requires --epic <id>');
+      }
+      enqueueLabel({
+        outboxPath: outboxPathFor(epicId, config),
+        ticketId,
+        state,
+      });
+      Logger.info(
+        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
+      );
+      return;
+    }
+
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );

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`.