mandrel 1.57.0

package/.agents/scripts/epic-plan-decompose.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * epic-plan-decompose.js — Story #2466 thin CLI shell.
+ *
+ * Phase 8 (decompose) entry point for the split planning flow. The
+ * deterministic decomposer engine and reconciler-based persist flow
+ * have been split into phase modules under
+ * `lib/orchestration/epic-plan-decompose/phases/`:
+ *
+ *   1. planning-artifacts — `ensurePlanningArtifacts`,
+ *                            `resolveConflictPolicy`.
+ *   2. dag                — `resolveDependencies`,
+ *                            `orderTicketsForCreation`.
+ *   3. context            — `buildDecomposerSystemPrompt`,
+ *                            `buildDecompositionContext`.
+ *   4. creation           — sub-issue link reconciliation, Epic label
+ *                            transitions, and the advisory ticket-cap
+ *                            warning (`reconcileSubIssueLinks`,
+ *                            `setEpicLabel`, `warnTicketCapNearLimit`).
+ *   5. persist            — `runDecomposePhase` (reconciler-based flow).
+ *   6. cli                — argument parsing + `main()` pipeline.
+ *
+ * Modes:
+ *   --emit-context     Prints the decomposer authoring context (PRD body,
+ *                      Tech Spec body, risk heuristics, system prompt,
+ *                      ticket cap) as JSON. The authoring middle is the
+ *                      `epic-plan-decompose-author` Skill
+ *                      (`.agents/skills/core/epic-plan-decompose-author/SKILL.md`).
+ *
+ *   (default)          Given an author-provided tickets JSON file,
+ *                      persists the Feature/Story/Task hierarchy via the
+ *                      structural reconciler, flips the Epic to
+ *                      `agent::ready`, and updates the `epic-plan-state`
+ *                      structured comment.
+ *
+ * --force re-decomposes (closes existing child Features/Stories/Tasks).
+ *
+ * Exit codes:
+ *   0 — phase complete, Epic is now `agent::ready`.
+ *   1 — fatal error (see stderr).
+ *
+ * Public CLI surface and named exports are byte-identical to the pre-
+ * refactor implementation.
+ */
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { main } from './lib/orchestration/epic-plan-decompose/phases/cli.js';
+import {
+  buildDecomposerSystemPrompt,
+  buildDecompositionContext,
+} from './lib/orchestration/epic-plan-decompose/phases/context.js';
+import {
+  orderTicketsForCreation,
+  resolveDependencies,
+} from './lib/orchestration/epic-plan-decompose/phases/dag.js';
+import { runDecomposePhase } from './lib/orchestration/epic-plan-decompose/phases/persist.js';
+import { ensurePlanningArtifacts } from './lib/orchestration/epic-plan-decompose/phases/planning-artifacts.js';
+
+// Named exports preserved for the existing test surface. The pre-refactor
+// module published these and the consumers (`tests/ticket-decomposer.test.js`,
+// `tests/scripts/epic-plan-decompose.body-preservation.test.js`,
+// `tests/scripts/epic-plan-decompose.sub-issue-safety-net.test.js`,
+// `tests/scripts/epic-plan.spec-flow.test.js`) still depend on them.
+export {
+  buildDecomposerSystemPrompt,
+  buildDecompositionContext,
+  ensurePlanningArtifacts,
+  orderTicketsForCreation,
+  resolveDependencies,
+  runDecomposePhase,
+};
+
+runAsCli(import.meta.url, main, { source: 'epic-plan-decompose' });

package/.agents/scripts/epic-plan-healthcheck.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+
+/* node:coverage ignore file */
+
+/**
+ * epic-plan-healthcheck.js — Post-Plan Readiness Check
+ *
+ * Runs at the end of /epic-plan (Phase 10) to validate the backlog and
+ * optionally prime the execution environment before handing off to
+ * /epic-deliver.
+ *
+ * Modes (additive — the fast checks below always run):
+ *   (default)         — config validation + git remote check only.
+ *                       Targets <2s.
+ *   --paranoid        — adds ticket-hierarchy revalidation.
+ *   --prime-install   — adds the pnpm content-addressable-store priming
+ *                       path (up to 300s).
+ *
+ * Output: a single line of structured JSON on stdout —
+ *   { ok, degraded, reason, checks: [{name, ok, durationMs, detail}] }
+ *
+ * The script always exits 0; callers decide whether to act on `ok: false`.
+ * The plan is already committed to GitHub, so failing the script does not
+ * un-create tickets.
+ *
+ * Usage:
+ *   node epic-plan-healthcheck.js --epic <EPIC_ID> \
+ *     [--paranoid] [--prime-install] [--dry-run]
+ *
+ * @see .agents/workflows/epic-plan.md Phase 10
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { parseTicketId } from './lib/cli-args.js';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  PROJECT_ROOT,
+  resolveConfig,
+  validateOrchestrationConfig,
+} from './lib/config-resolver.js';
+import { gitSpawn } from './lib/git-utils.js';
+import { Logger } from './lib/Logger.js';
+import { TYPE_LABELS } from './lib/label-constants.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const progress = Logger.createProgress('plan-healthcheck', { stderr: true });
+
+// ---------------------------------------------------------------------------
+// CLI parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the healthcheck-specific CLI surface. Kept local to the script so the
+ * shared `parseSprintArgs` helper does not have to learn about every script's
+ * private flags.
+ *
+ * @param {string[]} [argv]
+ * @returns {{ epicId: number|null, paranoid: boolean,
+ *   primeInstall: boolean, dryRun: boolean }}
+ */
+function parseHealthcheckArgs(argv = process.argv) {
+  const { values, positionals } = parseArgs({
+    args: argv.slice(2),
+    options: {
+      epic: { type: 'string', short: 'e' },
+      paranoid: { type: 'boolean', default: false },
+      'prime-install': { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  return {
+    epicId: parseTicketId(values.epic) ?? parseTicketId(positionals[0]),
+    paranoid: !!values.paranoid,
+    primeInstall: !!values['prime-install'],
+    dryRun: !!values['dry-run'],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Individual checks
+//
+// Each check returns { ok: boolean, detail: string }. The orchestrator wraps
+// it with `name` and `durationMs` for the structured output.
+// ---------------------------------------------------------------------------
+
+/** Validate the resolved `.agentrc.json` config. */
+function checkConfig(config) {
+  try {
+    validateOrchestrationConfig(config);
+    return { ok: true, detail: 'Config is valid.' };
+  } catch (err) {
+    return { ok: false, detail: `Config validation failed: ${err.message}` };
+  }
+}
+
+/** Verify `origin` is reachable and `baseBranch` exists on it. */
+function checkGitRemote(baseBranch, cwd) {
+  const remote = gitSpawn(
+    cwd,
+    'ls-remote',
+    '--exit-code',
+    'origin',
+    baseBranch,
+  );
+  if (remote.status === 0) {
+    return {
+      ok: true,
+      detail: `Remote reachable, base branch '${baseBranch}' exists.`,
+    };
+  }
+  if (
+    remote.stderr.includes('Could not resolve host') ||
+    remote.stderr.includes('unable to access')
+  ) {
+    return {
+      ok: false,
+      detail: `Git remote 'origin' is not reachable: ${remote.stderr.slice(0, 200)}`,
+    };
+  }
+  return {
+    ok: false,
+    detail: `Base branch '${baseBranch}' not found on origin.`,
+  };
+}
+
+/**
+ * Detect whether a Story body carries an inline `## Acceptance` section with
+ * at least one checklist item. Epic #3078 — under 3-tier hierarchy, Stories
+ * carry acceptance inline, so the hierarchy check uses this signal as the
+ * mark of a complete, executable Story.
+ *
+ * @param {string} body
+ * @returns {boolean}
+ */
+function hasInlineAcceptance(body) {
+  if (typeof body !== 'string' || body.length === 0) return false;
+  const match = body.match(/^##\s+Acceptance\s*$/im);
+  if (!match) return false;
+  const tail = body.slice(match.index + match[0].length);
+  // Capture until the next top-level `## ` heading (or EOF).
+  const sectionEnd = tail.search(/^##\s+\S/m);
+  const section = sectionEnd === -1 ? tail : tail.slice(0, sectionEnd);
+  // A non-empty acceptance section needs at least one bullet (with or
+  // without a checkbox marker).
+  return /^\s*-\s+(?:\[[ xX]\]\s+)?\S/m.test(section);
+}
+
+/**
+ * Validate Epic ticket hierarchy. 3-tier is the only supported hierarchy
+ * after Task #3154 deleted `planning.hierarchy`: every Story must carry an
+ * inline `## Acceptance` checklist; there is no Task layer to graph.
+ *
+ * @param {object} provider
+ * @param {number|null} epicId
+ */
+async function checkTickets(provider, epicId) {
+  if (!epicId) {
+    return {
+      ok: false,
+      detail: '--paranoid requires --epic <ID> to fetch the ticket hierarchy.',
+    };
+  }
+
+  let tickets;
+  try {
+    tickets = await provider.getSubTickets(epicId);
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `Could not fetch Epic #${epicId} tickets: ${err.message}`,
+    };
+  }
+
+  if (tickets.length === 0) {
+    return { ok: false, detail: `Epic #${epicId} has no child tickets.` };
+  }
+
+  const features = tickets.filter((t) =>
+    t.labels.includes(TYPE_LABELS.FEATURE),
+  );
+  const stories = tickets.filter((t) => t.labels.includes(TYPE_LABELS.STORY));
+
+  const errors = [];
+  if (features.length === 0) errors.push('no type::feature tickets');
+  if (stories.length === 0) errors.push('no type::story tickets');
+
+  const missingAcceptance = stories.filter(
+    (s) => !hasInlineAcceptance(s.body ?? ''),
+  );
+  if (missingAcceptance.length > 0) {
+    const ids = missingAcceptance.map((s) => `#${s.id}`).join(', ');
+    errors.push(
+      `${missingAcceptance.length} story/stories missing inline acceptance: ${ids}`,
+    );
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, detail: errors.join('; ') };
+  }
+
+  const missingComplexity = stories.filter(
+    (s) => !s.labels.some((l) => l.startsWith('complexity::')),
+  );
+  const advisory =
+    missingComplexity.length > 0
+      ? ` (advisory: ${missingComplexity.length} story/stories missing complexity label)`
+      : '';
+
+  return {
+    ok: true,
+    detail: `${features.length} features, ${stories.length} stories (3-tier, inline acceptance) — hierarchy valid${advisory}.`,
+  };
+}
+
+/** Prime the pnpm content-addressable store via `pnpm install --frozen-lockfile`. */
+function primePnpmStore(cwd, dryRun) {
+  const lockFile = path.join(cwd, 'pnpm-lock.yaml');
+  if (!fs.existsSync(lockFile)) {
+    return {
+      ok: false,
+      detail: 'No pnpm-lock.yaml found — cannot prime store.',
+    };
+  }
+  if (dryRun) {
+    return { ok: true, detail: 'pnpm store prime skipped (dry-run).' };
+  }
+
+  progress('PRIME', 'Priming pnpm content-addressable store...');
+  const start = Date.now();
+  const result = spawnSync('pnpm', ['install', '--frozen-lockfile'], {
+    cwd,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+    timeout: 300_000,
+  });
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+
+  if (result.status === 0) {
+    return { ok: true, detail: `pnpm store primed in ${elapsed}s.` };
+  }
+  const reason =
+    result.signal === 'SIGTERM'
+      ? `timeout after ${elapsed}s`
+      : `exit ${result.status}`;
+  return {
+    ok: false,
+    detail: `pnpm store prime failed (${reason}). First worktree install will be slower. stderr: ${(result.stderr ?? '').slice(0, 300)}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+async function timed(name, fn) {
+  const start = Date.now();
+  const { ok, detail } = await fn();
+  return { name, ok, durationMs: Date.now() - start, detail };
+}
+
+/**
+ * Run the post-plan health check.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.epicId]              Epic ID (required for --paranoid).
+ * @param {boolean} [opts.paranoid]           Add ticket-hierarchy revalidation.
+ * @param {boolean} [opts.primeInstall]       Add pnpm-store priming.
+ * @param {boolean} [opts.dryRun]             Skip real install side effects.
+ * @param {object}  [opts.injectedProvider]   Test-only injection point.
+ * @param {object}  [opts.injectedConfig]     Test-only injection point.
+ * @returns {Promise<{ok: boolean, degraded: boolean, reason: string|null,
+ *   checks: Array<{name: string, ok: boolean, durationMs: number, detail: string}>}>}
+ */
+// exported for tests — Story-level reuse runner reserved for future test coverage
+export async function runPlanHealthcheck(opts = {}) {
+  const ARG_KEYS = ['epicId', 'paranoid', 'primeInstall', 'dryRun'];
+  const hasExplicitArgs = ARG_KEYS.some((k) => Object.hasOwn(opts, k));
+  const parsed = hasExplicitArgs
+    ? {
+        epicId: opts.epicId ?? null,
+        paranoid: !!opts.paranoid,
+        primeInstall: !!opts.primeInstall,
+        dryRun: !!opts.dryRun,
+      }
+    : parseHealthcheckArgs();
+
+  const { epicId, paranoid, primeInstall, dryRun } = parsed;
+  const cwd = PROJECT_ROOT;
+
+  const config = opts.injectedConfig || resolveConfig();
+  const baseBranch = config.project?.baseBranch ?? 'main';
+
+  progress(
+    'HEALTH',
+    `Running post-plan health check${epicId ? ` for Epic #${epicId}` : ''} (mode=${paranoid ? 'paranoid' : 'fast'}${primeInstall ? '+prime-install' : ''})...`,
+  );
+
+  const checks = [];
+
+  // Fast lane: config + git remote always run.
+  progress('CHECK', 'Validating resolved config...');
+  checks.push(await timed('config', async () => checkConfig(config)));
+
+  progress('CHECK', 'Checking git remote...');
+  checks.push(
+    await timed('git-remote', async () => checkGitRemote(baseBranch, cwd)),
+  );
+
+  // Paranoid lane: ticket-hierarchy revalidation (3-tier only).
+  if (paranoid) {
+    const provider = opts.injectedProvider || createProvider(config);
+    progress('CHECK', 'Validating ticket hierarchy...');
+    checks.push(
+      await timed('ticket-hierarchy', () => checkTickets(provider, epicId)),
+    );
+  }
+
+  // Optional pnpm-store priming.
+  if (primeInstall) {
+    progress('CHECK', 'Priming pnpm store...');
+    checks.push(
+      await timed('prime-install', async () => primePnpmStore(cwd, dryRun)),
+    );
+  }
+
+  const failed = checks.filter((c) => !c.ok);
+  const ok = failed.length === 0;
+  const result = {
+    ok,
+    degraded: !ok,
+    reason: ok ? null : failed.map((c) => `${c.name}: ${c.detail}`).join('; '),
+    checks,
+  };
+
+  if (ok) {
+    progress('HEALTH', `All ${checks.length} check(s) passed.`);
+  } else {
+    progress(
+      'HEALTH',
+      `${failed.length} of ${checks.length} check(s) failed: ${failed.map((c) => c.name).join(', ')}.`,
+    );
+  }
+
+  // The structured result is the only thing on stdout.
+  Logger.info(JSON.stringify(result));
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main guard
+// ---------------------------------------------------------------------------
+
+runAsCli(import.meta.url, runPlanHealthcheck, {
+  source: 'epic-plan-healthcheck',
+});

package/.agents/scripts/epic-plan-spec-validate.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * epic-plan-spec-validate.js — Phase 7.5 Tech Spec post-authoring gate CLI.
+ *
+ * `/epic-plan` Phase 7 authors the Tech Spec; Phase 8.3 (Holistic
+ * Consolidation) reconciles the draft ticket array against the Tech Spec's
+ * `## Delivery Slicing` section, which the decompose-author skill uses as the
+ * capability-boundary anchor. When that section is absent the consolidation
+ * pass runs against a void and produces groupings that reflect technical
+ * shape rather than capability boundaries.
+ *
+ * This CLI is the hard gate between Phase 7 and Phase 8: it reads the authored
+ * `techspec.md`, runs {@link ./lib/orchestration/spec-section-validator.js#validateSpecSections},
+ * and exits non-zero when the required section is missing so decomposition
+ * cannot proceed against an un-anchored spec. It is the Phase 8-side
+ * counterpart to the Phase 6 Epic Clarity Gate (`epic-plan-clarity.js`) —
+ * same detect-then-prompt pattern, one phase later.
+ *
+ * Usage:
+ *   epic-plan-spec-validate.js --techspec <path> [--json]
+ *
+ * Exit codes:
+ *   0 — every required section present.
+ *   1 — at least one required section missing, or a fatal error (bad path,
+ *       unreadable file). The failure message names the missing section(s)
+ *       and tells the operator how to recover.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+import { validateSpecSections } from './lib/orchestration/spec-section-validator.js';
+
+/**
+ * Build the operator-facing failure message for a missing-section result.
+ * Names each missing section and tells the operator whether to re-author the
+ * spec or add the section by hand before continuing to Phase 8.
+ *
+ * @param {{ techspecPath: string, missing: string[] }} args
+ * @returns {string}
+ */
+export function formatMissingSectionMessage({ techspecPath, missing }) {
+  const list = missing.map((name) => `## ${name}`).join(', ');
+  return [
+    `[epic-plan-spec-validate] Tech Spec is missing required section(s): ${list}`,
+    `  Spec file: ${techspecPath}`,
+    '',
+    `  Phase 8 (decomposition) reconciles the draft ticket array against the`,
+    `  Tech Spec's "## Delivery Slicing" section — without it, the Phase 8.3`,
+    `  consolidation pass has no capability-boundary anchor and groups by`,
+    `  technical shape instead.`,
+    '',
+    '  To continue, do ONE of the following before re-running Phase 8:',
+    `    1. Re-author the Tech Spec (re-run the Phase 7 spec-author step) so it`,
+    `       emits a "## Delivery Slicing" section, OR`,
+    `    2. Add a "## Delivery Slicing" section to the Tech Spec by hand,`,
+    `       describing the capability boundaries the work should be sliced along.`,
+  ].join('\n');
+}
+
+/**
+ * Validate an authored Tech Spec file for the required post-authoring
+ * sections. Pure-ish wrapper around `validateSpecSections` that owns the file
+ * read so the CLI `main` stays a thin arg-parse shell.
+ *
+ * @param {{ techspecPath: string }} args
+ * @returns {Promise<{ ok: boolean, missing: string[], present: string[] }>}
+ */
+export async function validateSpecFile({ techspecPath }) {
+  const body = await readFile(techspecPath, 'utf8');
+  return validateSpecSections({ body });
+}
+
+/* node:coverage ignore next */
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      techspec: { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+  });
+
+  if (!values.techspec) {
+    throw new Error(
+      'Usage: epic-plan-spec-validate.js --techspec <path> [--json]',
+    );
+  }
+
+  const techspecPath = values.techspec;
+  const result = await validateSpecFile({ techspecPath });
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify({ techspecPath, ...result })}\n`);
+  }
+
+  if (!result.ok) {
+    throw new Error(
+      formatMissingSectionMessage({ techspecPath, missing: result.missing }),
+    );
+  }
+
+  Logger.info(
+    `[epic-plan-spec-validate] Tech Spec section gate passed: ${result.present
+      .map((name) => `## ${name}`)
+      .join(', ')} present.`,
+  );
+}
+
+runAsCli(import.meta.url, main, { source: 'epic-plan-spec-validate' });