mandrel 1.91.0 → 1.92.0

package/.agents/scripts/git-rebase-and-resolve.js

@@ -1,234 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file -- rebase CLI; conflict-resolution heuristics over real git state, testing would assert only the mock structure */
-
-/**
- * git-rebase-and-resolve.js — Rebase pipeline for `/git-merge-pr` Step 2.5.
- *
- * `/git-merge-pr` previously embedded the rebase retry loop as prose in
- * markdown: "rebase onto base → if conflicts, follow the template → stage and
- * continue → force-push". That works right up until the LLM forgets one of
- * the steps (the force-push with `--force-with-lease`, the abort on
- * cascading conflicts, the continue after each resolved batch).
- *
- * This script runs the rebase, reports the outcome in structured form, and
- * — when a conflict stops the rebase — leaves the working tree in the
- * conflicted state so the caller can apply manual resolutions and invoke
- * `--continue` (delegating back to git's native flow rather than trying to
- * automate conflict merging, which is a problem for judgment not scripting).
- *
- * Usage:
- *   node .agents/scripts/git-rebase-and-resolve.js --onto <base> [--head <branch>] [--continue] [--abort] [--json]
- *
- * Modes:
- *   (default)     — `git fetch origin`, checkout head, `git rebase <onto>`.
- *   --continue    — `git rebase --continue` after resolutions are staged.
- *   --abort       — `git rebase --abort` to bail cleanly.
- *
- * Output (always JSON when --json, otherwise human-readable):
- *   {
- *     outcome: 'clean' | 'conflict' | 'aborted' | 'continued',
- *     head, onto,
- *     conflictedFiles: [...],
- *     stderr: "...",
- *   }
- *
- * Exit codes:
- *   0 — clean rebase or continue that completed.
- *   1 — conflict state (caller must resolve then invoke --continue).
- *   2 — usage / git error.
- */
-
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { gitSpawn } from './lib/git-utils.js';
-import { Logger } from './lib/Logger.js';
-import { PROJECT_ROOT } from './lib/project-root.js';
-
-function currentBranch(cwd) {
-  const res = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
-  return res.status === 0 ? res.stdout.trim() : null;
-}
-
-function listConflictedFiles(cwd) {
-  const res = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
-  if (res.status !== 0) return [];
-  return res.stdout
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(Boolean);
-}
-
-/**
- * Perform a rebase and classify the outcome. Pure seam: callers inject a
- * `git` runner for tests.
- *
- * @param {{
- *   onto: string,
- *   head?: string,
- *   cwd?: string,
- *   git?: { spawn: (cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string } },
- * }} opts
- */
-export function runRebase({
-  onto,
-  head,
-  cwd = PROJECT_ROOT,
-  git = { spawn: gitSpawn },
-}) {
-  if (!onto) throw new Error('[rebase] --onto is required.');
-
-  const fetch = git.spawn(cwd, 'fetch', 'origin');
-  if (fetch.status !== 0) {
-    return {
-      outcome: 'error',
-      head: head ?? null,
-      onto,
-      conflictedFiles: [],
-      stderr: fetch.stderr ?? '',
-    };
-  }
-
-  if (head) {
-    const checkout = git.spawn(cwd, 'checkout', head);
-    if (checkout.status !== 0) {
-      return {
-        outcome: 'error',
-        head,
-        onto,
-        conflictedFiles: [],
-        stderr: checkout.stderr ?? '',
-      };
-    }
-    git.spawn(cwd, 'pull', 'origin', head);
-  }
-
-  const rebase = git.spawn(cwd, 'rebase', onto);
-  if (rebase.status === 0) {
-    return {
-      outcome: 'clean',
-      head: head ?? currentBranch(cwd),
-      onto,
-      conflictedFiles: [],
-      stderr: '',
-    };
-  }
-
-  // Non-zero exit: likely conflict. Enumerate the unmerged files so the caller
-  // can route to the conflict-template procedure.
-  const conflicted = listConflictedFiles(cwd);
-  return {
-    outcome: conflicted.length > 0 ? 'conflict' : 'error',
-    head: head ?? currentBranch(cwd),
-    onto,
-    conflictedFiles: conflicted,
-    stderr: rebase.stderr ?? '',
-  };
-}
-
-export function continueRebase({
-  cwd = PROJECT_ROOT,
-  git = { spawn: gitSpawn },
-}) {
-  const res = git.spawn(cwd, 'rebase', '--continue');
-  if (res.status === 0) {
-    return { outcome: 'continued', conflictedFiles: [], stderr: '' };
-  }
-  return {
-    outcome: 'conflict',
-    conflictedFiles: listConflictedFiles(cwd),
-    stderr: res.stderr ?? '',
-  };
-}
-
-export function abortRebase({ cwd = PROJECT_ROOT, git = { spawn: gitSpawn } }) {
-  const res = git.spawn(cwd, 'rebase', '--abort');
-  return {
-    outcome: res.status === 0 ? 'aborted' : 'error',
-    stderr: res.stderr ?? '',
-  };
-}
-
-/**
- * Pure: parse argv into the normalized rebase-action option bag.
- *
- * @param {string[]} argv
- * @returns {{ onto?: string, head?: string, continueFlag: boolean, abortFlag: boolean, json: boolean }}
- */
-export function parseRebaseArgs(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      onto: { type: 'string' },
-      head: { type: 'string' },
-      continue: { type: 'boolean', default: false },
-      abort: { type: 'boolean', default: false },
-      json: { type: 'boolean', default: false },
-    },
-    strict: false,
-  });
-  return {
-    onto: values.onto,
-    head: values.head,
-    continueFlag: values.continue === true,
-    abortFlag: values.abort === true,
-    json: values.json === true,
-  };
-}
-
-/** Pure: did the rebase end in a clean / non-failure outcome? */
-export function isCleanRebaseOutcome(outcome) {
-  return (
-    outcome === 'clean' || outcome === 'continued' || outcome === 'aborted'
-  );
-}
-
-/** Pure: render the human-facing output lines for a rebase result. */
-export function renderRebaseHumanLines(result) {
-  const lines = [`[rebase] outcome: ${result.outcome}`];
-  if (result.conflictedFiles?.length > 0) {
-    lines.push(`[rebase] conflicted files (${result.conflictedFiles.length}):`);
-    for (const f of result.conflictedFiles) lines.push(`  - ${f}`);
-  }
-  return lines;
-}
-
-/**
- * Pure: dispatch the parsed args to the matching rebase action. Throws when
- * the implicit-rebase path was selected without `--onto`. Exported for tests.
- */
-export function selectRebaseAction(args) {
-  if (args.abortFlag) return { kind: 'abort' };
-  if (args.continueFlag) return { kind: 'continue' };
-  if (!args.onto) {
-    return {
-      kind: 'usage-error',
-      message:
-        'Usage: node git-rebase-and-resolve.js --onto <base> [--head <branch>] [--json]',
-    };
-  }
-  return { kind: 'rebase', onto: args.onto, head: args.head };
-}
-
-function runSelectedAction(action, cwd) {
-  if (action.kind === 'abort') return abortRebase({ cwd });
-  if (action.kind === 'continue') return continueRebase({ cwd });
-  return runRebase({ onto: action.onto, head: action.head, cwd });
-}
-
-function emitRebaseHuman(result) {
-  for (const line of renderRebaseHumanLines(result)) Logger.info(line);
-  if (result.stderr?.trim()) Logger.error(result.stderr.trim());
-}
-
-/* node:coverage ignore next */
-async function main() {
-  const args = parseRebaseArgs(process.argv.slice(2));
-  const action = selectRebaseAction(args);
-  if (action.kind === 'usage-error') throw new Error(action.message);
-  const result = runSelectedAction(action, PROJECT_ROOT);
-  if (args.json) process.stdout.write(`${JSON.stringify(result)}\n`);
-  else emitRebaseHuman(result);
-  if (!isCleanRebaseOutcome(result.outcome)) process.exit(1);
-}
-
-runAsCli(import.meta.url, main, { source: 'git-rebase-and-resolve' });

package/.agents/scripts/hierarchy-gate.js

@@ -1,192 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * .agents/scripts/hierarchy-gate.js — Hierarchy Completeness Gate
- *
- * Walks the Epic's full sub-issue graph (Stories) and verifies
- * every descendant is closed. Where the wave gate asks "did the sprint
- * complete what it committed to?" (manifest view), this gate asks "is
- * anything still open under this Epic?" (live GitHub graph view).
- *
- * The two gates catch different problems and are intentionally distinct:
- *   - The wave gate misses descendants that exist on GitHub but were never
- *     in the manifest — mid-sprint additions, recuts that bypassed the
- *     dispatcher, or legacy `context::*` artifacts on historical Epics.
- *   - The hierarchy gate misses parked follow-ons that live as separate
- *     top-level Stories outside the Epic's sub-issue graph.
- *
- * Per ticket type the rule is:
- *   - Stories   — must be closed.
- *   - Auxiliary (legacy `context::*` artifacts) — ignored. Story #4324
- *     folded planning content into the Epic body; historical Epics keep
- *     their old context tickets, which are reference-only here.
- *
- * **2-tier hierarchy (Story #4041).** Mandrel ships only Epic / Story
- * tickets. `getSubTickets(<storyId>)` returns `[]`; the walk
- * terminates at the Story. Acceptance criteria live inline on the
- * Story body.
- *
- * Usage:
- *   node .agents/scripts/hierarchy-gate.js --epic <EPIC_ID>
- *
- * Exit codes:
- *   0 — every descendant ticket is closed.
- *   1 — one or more descendants are still open.
- *   2 — configuration or provider error.
- */
-
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
-import { TYPE_LABELS } from './lib/label-constants.js';
-import { createProvider } from './lib/provider-factory.js';
-import { concurrentMap } from './lib/util/concurrent-map.js';
-
-/**
- * Bounded fan-out for per-level `getSubTickets` calls. Matches the
- * wave-record-io.js precedent (Story #3024).
- */
-const SUB_TICKET_FETCH_CONCURRENCY = 4;
-
-function classify(ticket) {
-  const labels = ticket.labels ?? [];
-  if (labels.includes(TYPE_LABELS.STORY)) return 'story';
-  // Legacy planning artifacts (pre-#4324 `context::*` tickets on
-  // historical Epics) are ignored — they are reference artifacts, not
-  // deliverables. New Epics carry planning content on the body itself.
-  if (labels.some((l) => typeof l === 'string' && l.startsWith('context::'))) {
-    return 'auxiliary';
-  }
-  return 'other';
-}
-
-function ticketIsComplete(ticket) {
-  if (ticket.state !== 'closed') {
-    return { ok: false, reason: 'open' };
-  }
-  return { ok: true };
-}
-
-/**
- * BFS the sub-issue graph from the Epic. Returns one entry per descendant
- * ticket with full metadata — the caller checks completeness and formats
- * the failure list.
- */
-async function collectDescendants(provider, epicId) {
-  const visited = new Set([epicId]);
-  const out = [];
-  // Level-order BFS: each round fetches the whole frontier's children with a
-  // bounded-parallel map instead of one awaited round-trip per node. Stories
-  // are leaves (no sub-issues by contract), so they are never expanded
-  // — that skip alone removes the largest class of wasted GraphQL calls.
-  let frontier = [epicId];
-  while (frontier.length > 0) {
-    const levels = await concurrentMap(
-      frontier,
-      async (parentId) => {
-        try {
-          return await provider.getSubTickets(parentId);
-        } catch (err) {
-          throw new Error(`getSubTickets(#${parentId}) failed: ${err.message}`);
-        }
-      },
-      { concurrency: SUB_TICKET_FETCH_CONCURRENCY },
-    );
-    const next = [];
-    for (const children of levels) {
-      for (const child of children) {
-        if (visited.has(child.id)) continue;
-        visited.add(child.id);
-        out.push(child);
-        const labels = child.labels ?? [];
-        if (!labels.includes(TYPE_LABELS.STORY)) next.push(child.id);
-      }
-    }
-    frontier = next;
-  }
-  return out;
-}
-
-export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
-  if (!epicId || Number.isNaN(epicId) || epicId <= 0) {
-    throw new Error('Usage: node hierarchy-gate.js --epic <EPIC_ID>');
-  }
-
-  const config = resolveConfig();
-  const provider = injectedProvider || createProvider(config);
-
-  let descendants;
-  try {
-    descendants = await collectDescendants(provider, epicId);
-  } catch (err) {
-    Logger.error(`[hierarchy-gate] ${err.message}`);
-    process.exit(2);
-  }
-
-  const failures = { story: [], other: [] };
-  let auxiliaryDeferred = 0;
-  for (const ticket of descendants) {
-    const kind = classify(ticket);
-    if (kind === 'auxiliary') {
-      auxiliaryDeferred += 1;
-      continue;
-    }
-    const verdict = ticketIsComplete(ticket);
-    if (!verdict.ok) {
-      failures[kind].push({
-        id: ticket.id,
-        title: ticket.title,
-        reason: verdict.reason,
-      });
-    }
-  }
-
-  const totalOpen = failures.story.length + failures.other.length;
-
-  if (totalOpen > 0) {
-    Logger.error(
-      `[hierarchy-gate] ❌ Hierarchy-completeness gate FAILED for Epic #${epicId}: ${totalOpen} descendant(s) incomplete.`,
-    );
-    const sections = [
-      ['story', 'Stories'],
-      ['other', 'Untyped descendants'],
-    ];
-    for (const [key, label] of sections) {
-      if (failures[key].length === 0) continue;
-      Logger.error(`\n  ${label}:`);
-      for (const item of failures[key]) {
-        Logger.error(`    - #${item.id} (${item.reason}) — ${item.title}`);
-      }
-    }
-    Logger.error('\nClose the open descendants and re-run `/deliver`.');
-    process.exit(1);
-  }
-
-  const auxNote =
-    auxiliaryDeferred > 0
-      ? ` (${auxiliaryDeferred} legacy auxiliary ticket${auxiliaryDeferred === 1 ? '' : 's'} ignored)`
-      : '';
-  Logger.info(
-    `[hierarchy-gate] ✅ All ${descendants.length - auxiliaryDeferred} planned descendant(s) under Epic #${epicId} are closed${auxNote}.`,
-  );
-  return {
-    success: true,
-    total: descendants.length,
-    checked: descendants.length - auxiliaryDeferred,
-    auxiliaryDeferred,
-  };
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      epic: { type: 'string' },
-    },
-    strict: false,
-  });
-  const epicId = Number.parseInt(values.epic ?? '', 10);
-  await runHierarchyGate({ epicId });
-}
-
-runAsCli(import.meta.url, main, { source: 'hierarchy-gate' });

package/.agents/scripts/hydrate-context.js

@@ -1,179 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * hydrate-context.js — CLI wrapper for context hydration.
- *
- * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
- *
- * Delegates to `hydrateContext` from `lib/orchestration/context-hydration-engine.js`
- * and emits the `{ prompt }` JSON envelope on stdout. Pass `--emit prompt`
- * to write the raw hydrated prompt (no JSON wrapper) instead — this is the
- * sole supported hydration entry point.
- *
- * Usage:
- *   node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
- *   node .agents/scripts/hydrate-context.js --ticket <id> --emit prompt
- *
- * If `--epic` is omitted, the epic id is parsed from the ticket body
- * (`Epic: #N`). Persona / skills are derived from the ticket's labels.
- */
-
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { getEpicBranch, getStoryBranch } from './lib/git-utils.js';
-import { envelopeToPrompt } from './lib/orchestration/context-envelope.js';
-import {
-  hydrateContext,
-  parseHierarchy,
-} from './lib/orchestration/context-hydration-engine.js';
-import { createProvider } from './lib/provider-factory.js';
-
-const HELP = `Usage: node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
-
-Flags:
-  --ticket   GitHub issue number to hydrate (required).
-  --epic     Epic id (optional; parsed from the ticket body when omitted).
-  --help     Show this message.
-
-Output: a single JSON object {"prompt": "..."} on stdout by default.
-  --emit envelope  Write {"envelope": {...}} instead (debug / inspection).
-  --emit prompt    Write the raw hydrated prompt (no JSON wrapper) to stdout.
-`;
-
-/**
- * Build the normalized task object the hydration engine expects from a
- * full ticket fetched via the provider. Persona and skills come from the
- * `persona::*` and `skill::*` labels.
- */
-export function ticketToTask(ticket) {
-  const labels = ticket.labels ?? [];
-  const persona = labels
-    .find((l) => l.startsWith('persona::'))
-    ?.replace('persona::', '');
-  const skills = labels
-    .filter((l) => l.startsWith('skill::'))
-    .map((l) => l.replace('skill::', ''));
-
-  return {
-    id: ticket.id ?? ticket.number,
-    title: ticket.title,
-    body: ticket.body ?? '',
-    labels,
-    persona,
-    skills,
-  };
-}
-
-/**
- * Core: build the hydrated prompt and return the MCP-compatible envelope.
- * Exported so tests can pin parity against direct SDK invocation without a
- * subprocess.
- */
-export async function runHydrateContext({ ticketId, epicId, provider }) {
-  const ticket = await provider.getTicket(ticketId);
-  const hierarchy = parseHierarchy(ticket.body ?? '');
-
-  const resolvedEpicId = epicId ?? hierarchy.epic ?? null;
-
-  const storyId =
-    hierarchy.story ??
-    hierarchy.parent ??
-    ticket.id ??
-    ticket.number ??
-    ticketId;
-
-  if (!resolvedEpicId) {
-    throw new Error(
-      `[hydrate-context] Could not resolve epic id for ticket #${ticketId}; ` +
-        `pass --epic explicitly or ensure the body contains "Epic: #N".`,
-    );
-  }
-
-  const epicBranch = getEpicBranch(resolvedEpicId);
-  const taskBranch = getStoryBranch(resolvedEpicId, storyId);
-
-  const task = ticketToTask({ ...ticket, id: ticketId });
-  const envelope = await hydrateContext(
-    task,
-    provider,
-    epicBranch,
-    taskBranch,
-    resolvedEpicId,
-  );
-  const prompt = envelopeToPrompt(envelope);
-  return { prompt, envelope };
-}
-
-export function parseArgv(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      ticket: { type: 'string' },
-      epic: { type: 'string' },
-      emit: { type: 'string' },
-      help: { type: 'boolean' },
-    },
-    strict: false,
-  });
-  return values;
-}
-
-/**
- * Pure: classify parsed CLI values into a runnable intent. Pulling this
- * decision out of `main` keeps the side-effecting wrapper at CC ≤ 2 and
- * lets the unit tests exercise every branch directly.
- *
- * Shapes:
- *   - { kind: 'help' }
- *   - { kind: 'usage-error', message }
- *   - { kind: 'run', ticketId, epicId | undefined, emit?: 'envelope' | 'prompt' }
- */
-export function classifyCliInvocation(values) {
-  if (values?.help) return { kind: 'help' };
-  const ticketId = Number.parseInt(values?.ticket ?? '', 10);
-  if (!Number.isFinite(ticketId) || ticketId <= 0) {
-    return {
-      kind: 'usage-error',
-      message: `[hydrate-context] --ticket <id> is required.\n${HELP}`,
-    };
-  }
-  const epicId = values?.epic ? Number.parseInt(values.epic, 10) : undefined;
-  const intent = { kind: 'run', ticketId, epicId };
-  if (values?.emit === 'envelope' || values?.emit === 'prompt') {
-    intent.emit = values.emit;
-  }
-  return intent;
-}
-
-export async function main(argv = process.argv.slice(2)) {
-  const intent = classifyCliInvocation(parseArgv(argv));
-  if (intent.kind === 'help') {
-    process.stdout.write(HELP);
-    return;
-  }
-  if (intent.kind === 'usage-error') {
-    process.stderr.write(intent.message);
-    process.exit(2);
-  }
-
-  const config = resolveConfig();
-  const provider = createProvider(config);
-  const result = await runHydrateContext({
-    ticketId: intent.ticketId,
-    epicId: intent.epicId,
-    provider,
-  });
-  if (intent.emit === 'prompt') {
-    process.stdout.write(result.prompt);
-    return;
-  }
-  const stdoutPayload =
-    intent.emit === 'envelope'
-      ? { envelope: result.envelope }
-      : { prompt: result.prompt };
-  process.stdout.write(`${JSON.stringify(stdoutPayload)}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'hydrate-context' });