mandrel 1.91.0 → 1.92.0

package/.agents/scripts/lib/loop-units/validate-loop-unit.js

@@ -1,197 +0,0 @@
-/**
- * lib/loop-units/validate-loop-unit.js — loop-unit frontmatter validator.
- *
- * Parses a loop-unit markdown file's YAML frontmatter and AJV-validates
- * it against `.agents/schemas/loop-unit.schema.json` (Ajv2020). Mirrors
- * the validation pattern established by `lib/spec/loader.js` (Ajv2020 +
- * ajv-formats + js-yaml, cached compiled validator, normalised
- * `{ path, message }` issues).
- *
- * A "loop unit" is a markdown file under `.agents/workflows/loops/` whose
- * leading `---`-fenced YAML frontmatter block defines a recurring unit of
- * work (cadence, goal, conditional verify, round cap, exhaustion policy).
- *
- * Public surface:
- *   • `parseFrontmatter(source)` → extracts and YAML-parses the leading
- *     `---`-fenced block. Returns the parsed object (or `{}` for an empty
- *     block). Throws `LoopUnitParseError` when the block is absent or the
- *     YAML does not parse.
- *   • `validateLoopUnit(filePath, opts?)` → reads the file, parses its
- *     frontmatter, validates against the schema, and returns
- *     `{ valid, issues, data }`. `issues` is an array of
- *     `{ path, message }` (empty when valid). Never throws on a *validation*
- *     failure — it reports it via `valid: false` — but does throw
- *     `LoopUnitParseError` for an unreadable file or unparseable
- *     frontmatter so callers can distinguish "structurally broken file"
- *     from "schema-invalid unit".
- *
- * The module makes no GitHub calls and no process mutations; it is pure
- * file I/O + schema validation. The `opts` bag accepts `{ schemaPath, fs }`
- * so tests can point at a sandbox schema without monkey-patching globals.
- */
-
-import {
-  existsSync as defaultExistsSync,
-  readFileSync as defaultReadFileSync,
-} from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-import yaml from 'js-yaml';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-// scripts/lib/loop-units/ → scripts/lib/ → scripts/ → .agents/
-const PROJECT_AGENTS_DIR = path.resolve(__dirname, '..', '..', '..');
-export const DEFAULT_SCHEMA_PATH = path.join(
-  PROJECT_AGENTS_DIR,
-  'schemas',
-  'loop-unit.schema.json',
-);
-
-const defaultFsAdapter = Object.freeze({
-  existsSync: defaultExistsSync,
-  readFileSync: defaultReadFileSync,
-});
-
-let cachedValidator = null;
-let cachedValidatorKey = null;
-
-/**
- * Compile (and cache) the Ajv2020 validator for the loop-unit schema.
- * Cached by absolute schema path so tests can swap to a sandbox schema.
- *
- * @param {string} schemaPath
- * @param {{ readFileSync: typeof defaultReadFileSync }} fs
- * @returns {(data: unknown) => boolean}
- */
-function getValidator(schemaPath, fs) {
-  if (cachedValidator && cachedValidatorKey === schemaPath) {
-    return cachedValidator;
-  }
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
-  cachedValidator = ajv.compile(schema);
-  cachedValidatorKey = schemaPath;
-  return cachedValidator;
-}
-
-/**
- * Raised when a loop-unit file cannot be read, has no YAML frontmatter
- * block, or the frontmatter does not parse as YAML.
- */
-export class LoopUnitParseError extends Error {
-  /**
-   * @param {string} filePath
-   * @param {string} reason
-   */
-  constructor(filePath, reason) {
-    super(`Loop unit ${filePath} could not be parsed: ${reason}`);
-    this.name = 'LoopUnitParseError';
-    this.filePath = filePath;
-    this.reason = reason;
-  }
-}
-
-// Leading `---`-fenced YAML block. Tolerates CRLF and a leading BOM. The
-// closing fence is a `---` (or `...`) on its own line.
-const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\s*(?:\r?\n|$)/;
-
-/**
- * Extract and YAML-parse the leading `---`-fenced frontmatter block from a
- * markdown source string.
- *
- * @param {string} source        raw file contents
- * @param {string} [filePath]    used only for error messages
- * @returns {object}             the parsed frontmatter object (`{}` if empty)
- * @throws {LoopUnitParseError}  when no fence is present or the YAML fails
- */
-export function parseFrontmatter(source, filePath = '<string>') {
-  const match = FRONTMATTER_RE.exec(source);
-  if (!match) {
-    throw new LoopUnitParseError(
-      filePath,
-      'no YAML frontmatter block (expected a leading "---" fence)',
-    );
-  }
-  let parsed;
-  try {
-    parsed = yaml.load(match[1], { filename: filePath });
-  } catch (err) {
-    throw new LoopUnitParseError(
-      filePath,
-      `frontmatter is not valid YAML: ${err.message}`,
-    );
-  }
-  if (parsed == null) return {};
-  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new LoopUnitParseError(
-      filePath,
-      'frontmatter must be a YAML mapping',
-    );
-  }
-  return parsed;
-}
-
-/**
- * Convert Ajv's error array into a `{ path, message }` shape. For
- * `required` errors Ajv leaves the missing property in
- * `params.missingProperty` rather than the instance path, so we append it
- * so the caller sees `/loop/verify` instead of `/loop` and the message
- * names the missing field.
- *
- * @param {Array<{instancePath:string,message:string,keyword:string,params?:Record<string,unknown>}>} ajvErrors
- * @returns {Array<{path:string,message:string}>}
- */
-function normaliseAjvErrors(ajvErrors) {
-  return (ajvErrors ?? []).map((err) => {
-    let p = err.instancePath || '/';
-    let message = err.message ?? 'validation failed';
-    if (
-      err.keyword === 'required' &&
-      typeof err.params?.missingProperty === 'string'
-    ) {
-      const sep = p === '/' ? '' : '/';
-      p = `${p}${sep}${err.params.missingProperty}`;
-      message = `must have required property '${err.params.missingProperty}'`;
-    }
-    return { path: p, message };
-  });
-}
-
-/**
- * Read, parse, and schema-validate a loop-unit markdown file.
- *
- * @param {string} filePath
- * @param {{ schemaPath?: string, fs?: typeof defaultFsAdapter }} [opts]
- * @returns {{ valid: boolean, issues: Array<{path:string,message:string}>, data: object }}
- * @throws {LoopUnitParseError} when the file is unreadable or its
- *   frontmatter is missing/unparseable.
- */
-export function validateLoopUnit(filePath, opts = {}) {
-  const fs = opts.fs ?? defaultFsAdapter;
-  const schemaPath = opts.schemaPath ?? DEFAULT_SCHEMA_PATH;
-
-  if (!fs.existsSync(filePath)) {
-    throw new LoopUnitParseError(filePath, 'file does not exist');
-  }
-
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    throw new LoopUnitParseError(filePath, `unreadable: ${err.message}`);
-  }
-
-  const data = parseFrontmatter(raw, filePath);
-  const validate = getValidator(schemaPath, fs);
-  const ok = validate(data);
-
-  return {
-    valid: ok,
-    issues: ok ? [] : normaliseAjvErrors(validate.errors),
-    data,
-  };
-}

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/cli.js

@@ -1,167 +0,0 @@
-/**
- * cli.js — Phase 6 (CLI entry orchestration) of the epic-plan-decompose
- * pipeline (Story #2466).
- *
- * Owns CLI flag parsing, the `--emit-context` JSON envelope path, and
- * the tickets-file load → `runDecomposePhase` persist path. The
- * partial-failure diagnostics emitter lives in the sibling
- * `diagnostics.js` module.
- *
- * @module lib/orchestration/epic-plan-decompose/phases/cli
- */
-
-import { readFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-
-import { drainPendingCleanupAtBoot } from '../../../../epic-plan-spec.js';
-import {
-  PROJECT_ROOT,
-  resolveConfig,
-  validateOrchestrationConfig,
-} from '../../../config-resolver.js';
-import {
-  Logger,
-  routeAllOutputToStderr,
-  STDERR_LOGGER,
-} from '../../../Logger.js';
-import { createProvider } from '../../../provider-factory.js';
-import { buildDecompositionContext } from './context.js';
-import { reportPartialFailure } from './diagnostics.js';
-import { runDecomposePhase } from './persist.js';
-
-const CLI_OPTIONS = {
-  epic: { type: 'string' },
-  tickets: { type: 'string' },
-  force: { type: 'boolean', default: false },
-  resume: { type: 'boolean', default: false },
-  'allow-over-budget': { type: 'boolean', default: false },
-  'allow-large-fan-out': { type: 'boolean', default: false },
-  'emit-context': { type: 'boolean', default: false },
-  pretty: { type: 'boolean', default: false },
-  'full-context': { type: 'boolean', default: false },
-};
-
-const USAGE =
-  'Usage: epic-plan-decompose.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --tickets <file>) [--force | --resume] [--allow-over-budget] [--allow-large-fan-out]';
-
-function parseEpicId(rawEpic) {
-  if (!rawEpic) throw new Error(USAGE);
-  const epicId = Number.parseInt(rawEpic, 10);
-  if (Number.isNaN(epicId)) {
-    throw new Error(`Invalid epic ID: "${rawEpic}" — must be a number.`);
-  }
-  return epicId;
-}
-
-function loadResolvedConfig() {
-  let config;
-  try {
-    config = resolveConfig();
-    // Epic #2880 / F14B: pass the canonical resolved config directly.
-    // The legacy `config.orchestration` pointer is gone; the validator
-    // reads `config.github` and `config.delivery.worktreeIsolation`.
-    validateOrchestrationConfig(config);
-  } catch (err) {
-    throw new Error(
-      `Orchestration config schema validation failed:\n${err.message}`,
-    );
-  }
-  return config;
-}
-
-async function driveDrainPendingCleanup({ config, provider, emitContext }) {
-  try {
-    await drainPendingCleanupAtBoot({
-      repoRoot: PROJECT_ROOT,
-      // Epic #2880 / F14B: drainPendingCleanupAtBoot now reads opts.config
-      // (canonical) and resolves the worktree root from
-      // config.delivery.worktreeIsolation.root.
-      config,
-      provider,
-      logger: emitContext ? STDERR_LOGGER : undefined,
-    });
-  } catch (err) {
-    Logger.warn(`[epic-plan-decompose] worktree sweep skipped: ${err.message}`);
-  }
-}
-
-async function runEmitContextPath({ epicId, provider, config, values }) {
-  const ctx = await buildDecompositionContext(epicId, provider, config, {
-    fullContext: values['full-context'],
-  });
-  // Surface the resolved reviewability budget on stderr so the operator
-  // sees the same value the decomposer prompt embeds. `maxTickets` is a
-  // framework constant (LIMITS_DEFAULTS.maxTickets), no longer an
-  // operator-configurable key. Story #2798 — language is "reviewability
-  // budget", not "prompt cap".
-  Logger.error(
-    `[epic-plan-decompose] Resolved maxTickets reviewability budget = ${ctx.maxTickets} (framework constant).`,
-  );
-  const json = values.pretty
-    ? JSON.stringify(ctx, null, 2)
-    : JSON.stringify(ctx);
-  process.stdout.write(`${json}\n`);
-}
-
-async function loadTicketsFile(ticketsPath) {
-  if (!ticketsPath) {
-    throw new Error(
-      'Missing --tickets <file>. (Use --emit-context first to gather authoring context.)',
-    );
-  }
-  const raw = await readFile(ticketsPath, 'utf8');
-  try {
-    return JSON.parse(raw);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
-    );
-  }
-}
-
-async function runPersistPath({ epicId, provider, config, values }) {
-  const tickets = await loadTicketsFile(values.tickets);
-  let result;
-  try {
-    result = await runDecomposePhase(epicId, provider, { tickets }, config, {
-      force: values.force,
-      resume: values.resume,
-      allowOverBudget: values['allow-over-budget'],
-      allowLargeFanOut: values['allow-large-fan-out'],
-    });
-  } catch (err) {
-    await reportPartialFailure({ epicId, provider, err });
-    throw err;
-  }
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-/* node:coverage ignore next */
-export async function main() {
-  const { values } = parseArgs({ options: CLI_OPTIONS });
-  const epicId = parseEpicId(values.epic);
-  if (values.force && values.resume) {
-    throw new Error('--force and --resume are mutually exclusive.');
-  }
-
-  const config = loadResolvedConfig();
-  // Epic #2880 / F14B: createProvider takes the canonical resolved config
-  // (it reads config.github). The legacy config.orchestration pointer is
-  // gone; passing it yields undefined and crashes the provider factory's
-  // hard guard.
-  const provider = createProvider(config);
-  const emitContext = values['emit-context'];
-
-  // Story #2278 — in --emit-context mode stdout is reserved for the JSON
-  // envelope. Flip every Logger sink that could land on stdout to stderr
-  // before any orchestration code runs.
-  if (emitContext) routeAllOutputToStderr();
-
-  await driveDrainPendingCleanup({ config, provider, emitContext });
-
-  if (emitContext) {
-    await runEmitContextPath({ epicId, provider, config, values });
-    return;
-  }
-  await runPersistPath({ epicId, provider, config, values });
-}

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/cli-args.js

@@ -1,69 +0,0 @@
-/**
- * cli-args.js — argv parsing + validation for the `epic-plan-spec` CLI.
- *
- * Extracted from `epic-plan-spec.js` (refs #3685) so the top-level entry
- * stays a thin wire-up that scores at or above the maintainability floor;
- * the option schema and the epic-id guards live here.
- *
- * Story #4324: the separate-ticket persist flags `--techspec` /
- * `--acceptance-spec` are retired with the context-ticket classes. The
- * authored content now lands as sections of the Epic body; pass it via
- * `--tech-spec <file>` and `--acceptance-table <file>`. The old flags fail
- * with a usage error naming the removal.
- */
-
-import { parseArgs } from 'node:util';
-
-/** Retired flags → the replacement guidance surfaced in the usage error. */
-const RETIRED_FLAGS = Object.freeze({
-  '--techspec':
-    '--techspec was retired by the context-ticket fold (Story #4324): the Tech Spec is no longer a separate context::tech-spec ticket. Pass --tech-spec <file> — the content lands as a managed section of the Epic body.',
-  '--acceptance-spec':
-    '--acceptance-spec was retired by the context-ticket fold (Story #4324): the Acceptance Spec is no longer a separate context::acceptance-spec ticket. Pass --acceptance-table <file> — the AC-ID table lands as the ## Acceptance Table section of the Epic body.',
-});
-
-/**
- * Parse and validate the `epic-plan-spec` CLI arguments.
- *
- * @param {string[]} [argv] Defaults to `process.argv.slice(2)`.
- * @returns {{ values: Record<string, unknown>, epicId: number }}
- * @throws {Error} when `--epic` is missing or not a number, or when a
- *   retired separate-ticket persist flag is supplied.
- */
-export function parseEpicPlanSpecArgs(argv = process.argv.slice(2)) {
-  for (const arg of argv) {
-    const flag = arg.split('=')[0];
-    if (RETIRED_FLAGS[flag]) {
-      throw new Error(`[epic-plan-spec] ${RETIRED_FLAGS[flag]}`);
-    }
-  }
-
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      epic: { type: 'string' },
-      'tech-spec': { type: 'string' },
-      'acceptance-table': { type: 'string' },
-      'risk-verdict': { type: 'string' },
-      force: { type: 'boolean', default: false },
-      'force-review': { type: 'boolean', default: false },
-      steal: { type: 'boolean', default: false },
-      'emit-context': { type: 'boolean', default: false },
-      pretty: { type: 'boolean', default: false },
-      'full-context': { type: 'boolean', default: false },
-    },
-  });
-
-  if (!values.epic) {
-    throw new Error(
-      'Usage: epic-plan-spec.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --tech-spec <file> --risk-verdict <file> [--acceptance-table <file>]) [--force]',
-    );
-  }
-
-  const epicId = Number.parseInt(values.epic, 10);
-  if (Number.isNaN(epicId)) {
-    throw new Error(`Invalid epic ID: "${values.epic}" — must be a number.`);
-  }
-
-  return { values, epicId };
-}

package/.agents/scripts/lib/orchestration/plan-runner/plan-router.js

@@ -1,86 +0,0 @@
-/**
- * plan-router — given an Epic's current labels, decide which plan-phase CLI
- * should run next.
- *
- * Used by the local `/plan` wrapper (chains spec → decompose).
- *
- * The router is intentionally stateless. Callers feed the current label set
- * (a string array, usually from `provider.getEpic(id).labels`) and receive a
- * `{ phase, script, command }` descriptor; no I/O is performed.
- */
-
-import { AGENT_LABELS } from '../../label-constants.js';
-
-export const PLAN_PHASE_NAMES = Object.freeze({
-  SPEC: 'spec',
-  DECOMPOSE: 'decompose',
-});
-
-/**
- * Canonical descriptor for each planning phase. `script` is the repo-relative
- * path used by the local wrapper; `command` is the slash-command invocation
- * operators fire.
- *
- * Spec and Decompose are served by the unified `/plan` wrapper with a
- * `--phase` flag — the phase workflows themselves live at
- * `.agents/workflows/helpers/epic-plan-{spec,decompose}.md` and are not
- * directly invokable slash commands.
- *
- * Exported as `PLAN_PHASE_DESCRIPTORS` to make the CLI-routing role explicit
- * (it describes which wrapper script/slash-command serves each planning phase).
- */
-export const PLAN_PHASE_DESCRIPTORS = Object.freeze({
-  [PLAN_PHASE_NAMES.SPEC]: {
-    phase: PLAN_PHASE_NAMES.SPEC,
-    script: '.agents/scripts/epic-plan-spec.js',
-    command: '/plan --phase spec',
-    parkingLabel: AGENT_LABELS.REVIEW_SPEC,
-  },
-  [PLAN_PHASE_NAMES.DECOMPOSE]: {
-    phase: PLAN_PHASE_NAMES.DECOMPOSE,
-    script: '.agents/scripts/epic-plan-decompose.js',
-    command: '/plan --phase decompose',
-    parkingLabel: AGENT_LABELS.READY,
-  },
-});
-
-/**
- * Given the Epic's current labels, pick the next plan phase to run in the
- * local `/plan` wrapper.
- *
- * Precedence:
- *   1. If the Epic already carries `agent::ready`, there is nothing left to
- *      do — return `null` (the wrapper surfaces a no-op message).
- *   2. If the Epic carries `agent::review-spec`, decomposition is the next
- *      step (the operator has finished review).
- *   3. Otherwise (fresh Epic), start with the spec phase.
- *
- * @param {string[]} labels Current labels on the Epic.
- * @returns {object|null} Phase descriptor or null when no more work remains.
- */
-export function nextPhaseForEpic(labels = []) {
-  const set = new Set(labels);
-  if (set.has(AGENT_LABELS.READY)) return null;
-  if (set.has(AGENT_LABELS.REVIEW_SPEC)) {
-    return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.DECOMPOSE];
-  }
-  return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.SPEC];
-}
-
-/**
- * For a given current phase, return the next phase the local wrapper should
- * advance to. Used to chain spec → decompose after operator confirmation.
- *
- * @param {string} currentPhase One of `PLAN_PHASE_NAMES`.
- * @returns {object|null}
- */
-export function advancePhase(currentPhase) {
-  switch (currentPhase) {
-    case PLAN_PHASE_NAMES.SPEC:
-      return PLAN_PHASE_DESCRIPTORS[PLAN_PHASE_NAMES.DECOMPOSE];
-    case PLAN_PHASE_NAMES.DECOMPOSE:
-      return null;
-    default:
-      return null;
-  }
-}