mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/story-close/merge-subject.js

@@ -1,198 +0,0 @@
-/**
- * merge-subject.js — assemble the conventional-commit subject used by
- * `runFinalizeMerge` and `runResumeMerge` and auto-truncate it on a
- * word boundary when it would exceed commitlint's `header-max-length`.
- *
- * Story #2466 (Epic #2453) auto-generated a 102-char merge subject that
- * commitlint rejected; `story-close.js`'s merge step silently rolled
- * back to staged-only on each retry. This helper prevents the rejection
- * by shaping the subject pre-commit:
- *
- *   - The Conventional-Commits prefix (`<type>(<scope>): ` if scope is
- *     provided, otherwise `<type>: `) is preserved verbatim.
- *   - The ` (resolves #N)` suffix is preserved verbatim.
- *   - The title segment is truncated on a word boundary (whitespace),
- *     never mid-word, until the assembled subject's byte length fits
- *     within the cap.
- *   - On truncation, an operator-facing `Logger.warn` fires once and a
- *     `truncated-from: <original>` body trailer is returned so the
- *     caller can append it to the commit body.
- *
- * The cap is loaded from commitlint config via `@commitlint/load`,
- * cached per-cwd, and falls back to 100 (the
- * `@commitlint/config-conventional` default) when load fails.
- *
- * Pure (the shape function) + cached async loader. No I/O at shape time.
- */
-
-import path from 'node:path';
-import { Logger as DefaultLogger } from '../../Logger.js';
-import { resolvesToken } from '../resolves-token.js';
-
-const COMMITLINT_DEFAULT_HEADER_MAX_LENGTH = 100;
-const headerCapCache = new Map();
-
-/**
- * Load commitlint's `header-max-length` rule value for the given cwd.
- * Caches the resolved cap per absolute cwd so repeated close-path calls
- * inside a single process do not re-read commitlint config.
- *
- * Returns the default (100) when commitlint is not installed, the
- * config is missing, or the rule is absent / disabled.
- *
- * @param {string} cwd
- * @param {{ logger?: { warn?: Function } }} [opts]
- * @returns {Promise<number>}
- */
-export async function loadHeaderMaxLength(cwd, opts = {}) {
-  const logger = opts.logger ?? DefaultLogger;
-  const key = path.resolve(cwd);
-  if (headerCapCache.has(key)) return headerCapCache.get(key);
-  let cap = COMMITLINT_DEFAULT_HEADER_MAX_LENGTH;
-  try {
-    const mod = await import('@commitlint/load');
-    const load = mod.default ?? mod.load ?? mod;
-    const loaded = await load({}, { cwd: key });
-    const rule = loaded?.rules?.['header-max-length'];
-    if (Array.isArray(rule) && rule.length >= 3) {
-      const [level, _applicable, value] = rule;
-      if (level > 0 && Number.isFinite(value) && value > 0) {
-        cap = value;
-      }
-    }
-  } catch (err) {
-    logger?.warn?.(
-      `[merge-subject] commitlint header-max-length load failed; ` +
-        `using default ${COMMITLINT_DEFAULT_HEADER_MAX_LENGTH}: ${err?.message ?? err}`,
-    );
-  }
-  headerCapCache.set(key, cap);
-  return cap;
-}
-
-/**
- * Test-only: clear the per-cwd cap cache.
- */
-export function _resetHeaderMaxLengthCache() {
-  headerCapCache.clear();
-}
-
-function buildPrefix(type, scope) {
-  return scope ? `${type}(${scope}): ` : `${type}: `;
-}
-
-// Caps the `truncated-from: <subject>` trailer at `cap` bytes so it
-// satisfies commitlint's `footer-max-line-length` rule. Without this
-// cap, an original subject near the header cap (100) produces a
-// ~116-char trailer line.
-function buildTruncatedFromTrailer(originalSubject, cap) {
-  const prefix = 'truncated-from: ';
-  const budget = Math.max(0, cap - Buffer.byteLength(prefix, 'utf8'));
-  if (Buffer.byteLength(originalSubject, 'utf8') <= budget) {
-    return `${prefix}${originalSubject}`;
-  }
-  const ellipsisBytes = Buffer.byteLength('…', 'utf8');
-  let value = originalSubject;
-  while (Buffer.byteLength(value, 'utf8') + ellipsisBytes > budget) {
-    value = value.slice(0, -1);
-  }
-  return `${prefix}${value}…`;
-}
-
-function truncateTitleOnWordBoundary(title, budget) {
-  if (budget <= 0) return '';
-  if (Buffer.byteLength(title, 'utf8') <= budget) return title;
-  // Greedy: drop trailing tokens until the title fits the byte budget.
-  let truncated = title;
-  while (Buffer.byteLength(truncated, 'utf8') > budget) {
-    const lastWs = truncated.search(/\s+\S*$/u);
-    if (lastWs <= 0) {
-      // No earlier whitespace — fall back to byte-safe slice.
-      truncated = truncated.slice(0, Math.max(0, truncated.length - 1));
-      continue;
-    }
-    truncated = truncated.slice(0, lastWs);
-  }
-  return truncated.replace(/\s+$/u, '');
-}
-
-/**
- * Shape a Conventional-Commits subject so it fits within `headerMaxLength`.
- *
- * Returns `{ subject, original, truncated, bodyTrailer }`:
- *   - `subject`     — the (possibly truncated) one-line subject.
- *   - `original`    — the un-truncated subject (always populated).
- *   - `truncated`   — boolean, true iff truncation fired.
- *   - `bodyTrailer` — `truncated-from: <original>` when truncated, else null.
- *
- * Side effects: on truncation, emits a single `Logger.warn` line naming
- * the original and truncated subjects.
- *
- * @param {{
- *   type: string,
- *   scope?: string|null,
- *   title: string,
- *   storyId: number|string,
- *   headerMaxLength?: number,
- *   logger?: { warn?: Function },
- * }} args
- * @returns {{ subject: string, original: string, truncated: boolean, bodyTrailer: string|null }}
- */
-export function shapeMergeSubject({
-  type,
-  scope = null,
-  title,
-  storyId,
-  headerMaxLength = COMMITLINT_DEFAULT_HEADER_MAX_LENGTH,
-  logger = DefaultLogger,
-}) {
-  const lcTitle = title.charAt(0).toLowerCase() + title.slice(1);
-  const prefix = buildPrefix(type, scope);
-  const suffix = resolvesToken(storyId);
-  const originalSubject = `${prefix}${lcTitle}${suffix}`;
-  if (Buffer.byteLength(originalSubject, 'utf8') <= headerMaxLength) {
-    return {
-      subject: originalSubject,
-      original: originalSubject,
-      truncated: false,
-      bodyTrailer: null,
-    };
-  }
-  const fixedBytes =
-    Buffer.byteLength(prefix, 'utf8') + Buffer.byteLength(suffix, 'utf8');
-  const titleBudget = headerMaxLength - fixedBytes;
-  const truncatedTitle = truncateTitleOnWordBoundary(lcTitle, titleBudget);
-  const subject = `${prefix}${truncatedTitle}${suffix}`;
-  logger?.warn?.(
-    `[merge-subject] subject exceeded commitlint cap (${headerMaxLength}); ` +
-      `truncated on word boundary. original="${originalSubject}" ` +
-      `truncated="${subject}"`,
-  );
-  return {
-    subject,
-    original: originalSubject,
-    truncated: true,
-    bodyTrailer: buildTruncatedFromTrailer(originalSubject, headerMaxLength),
-  };
-}
-
-/**
- * Convenience: shape a subject and assemble the final commit message
- * (subject plus optional trailer block). Returns a single string suitable
- * for passing as the `-m` argument to `git commit` / `git merge`.
- *
- * @param {Parameters<typeof shapeMergeSubject>[0]} args
- * @returns {{ message: string, subject: string, original: string, truncated: boolean }}
- */
-export function buildMergeMessageWithCap(args) {
-  const shaped = shapeMergeSubject(args);
-  const message = shaped.bodyTrailer
-    ? `${shaped.subject}\n\n${shaped.bodyTrailer}`
-    : shaped.subject;
-  return {
-    message,
-    subject: shaped.subject,
-    original: shaped.original,
-    truncated: shaped.truncated,
-  };
-}

package/.agents/scripts/lib/orchestration/story-close/phases/branch-restore.js

@@ -1,105 +0,0 @@
-/**
- * phases/branch-restore.js — capture + restore the main-repo's starting
- * branch around the merge-lock-protected close (Story #2138 / #2141; moved
- * into the phases pipeline by Story #2460, Epic #2453).
- *
- * The orchestrator captures the starting branch BEFORE entering the
- * merge lock and runs `restoreStartingBranch` in a `finally` block, so
- * any throw inside `runStoryCloseLocked` leaves the operator on the
- * branch they came in on rather than stranded mid-rebase / mid-merge.
- *
- * Public surface:
- *   - captureStartingBranch(cwd, deps?)    ← exported (story-close.js re-export)
- *   - restoreStartingBranch(opts, deps?)   ← exported (story-close.js re-export)
- */
-
-import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
-import { Logger } from '../../../Logger.js';
-
-/**
- * Capture the main-repo's current branch name before `runStoryCloseLocked`
- * runs. Returns `{ ok: true, branch }` on success, `{ ok: false, reason }`
- * when HEAD is detached or `git rev-parse` fails.
- *
- * @param {string} cwd
- * @param {{ gitSpawn?: typeof defaultGitSpawn }} [deps]
- * @returns {{ ok: true, branch: string } | { ok: false, reason: string }}
- */
-export function captureStartingBranch(cwd, deps = {}) {
-  const gitSpawn = deps.gitSpawn ?? defaultGitSpawn;
-  const res = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
-  if (res.status !== 0) {
-    return {
-      ok: false,
-      reason: `rev-parse-failed: ${res.stderr || 'unknown'}`,
-    };
-  }
-  const branch = (res.stdout || '').trim();
-  if (!branch || branch === 'HEAD') {
-    return { ok: false, reason: 'detached-head' };
-  }
-  return { ok: true, branch };
-}
-
-/**
- * Restore the main-repo to `startingBranch` via `git switch`. Refuses the
- * switch when the destination tree is dirty (`git status --porcelain` is
- * non-empty). Never invokes `git reset --hard` or `git checkout --force`.
- *
- * Returns a structured envelope so callers (and tests) can assert which
- * branch they end up on and why.
- *
- * @param {object} opts
- * @param {string} opts.cwd
- * @param {{ ok: boolean, branch?: string, reason?: string }} opts.captured
- * @param {{ gitSpawn?: typeof defaultGitSpawn, logger?: object }} [deps]
- * @returns {{ restored: boolean, branch?: string, reason?: string, skipped?: boolean }}
- */
-export function restoreStartingBranch({ cwd, captured }, deps = {}) {
-  const gitSpawn = deps.gitSpawn ?? defaultGitSpawn;
-  const log = deps.logger ?? Logger;
-  if (!captured || captured.ok !== true) {
-    return {
-      restored: false,
-      skipped: true,
-      reason: captured?.reason
-        ? `no-starting-branch: ${captured.reason}`
-        : 'no-starting-branch',
-    };
-  }
-  const { branch } = captured;
-  const currentRes = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
-  if (currentRes.status === 0 && currentRes.stdout.trim() === branch) {
-    return { restored: true, branch, reason: 'already-on-branch' };
-  }
-  const statusRes = gitSpawn(cwd, 'status', '--porcelain');
-  if (statusRes.status !== 0) {
-    log.warn?.(
-      `[story-close] branch-restore: \`git status --porcelain\` failed in ${cwd}: ${statusRes.stderr || 'unknown'}`,
-    );
-    return {
-      restored: false,
-      branch,
-      reason: `status-failed: ${statusRes.stderr || 'unknown'}`,
-    };
-  }
-  if (statusRes.stdout.length > 0) {
-    log.error?.(
-      `[story-close] branch-restore: refusing to switch to \`${branch}\` — working tree is dirty in ${cwd}. ` +
-        `Resolve the local changes manually, then \`git switch ${branch}\`.`,
-    );
-    return { restored: false, branch, reason: 'dirty-tree' };
-  }
-  const switchRes = gitSpawn(cwd, 'switch', branch);
-  if (switchRes.status !== 0) {
-    log.warn?.(
-      `[story-close] branch-restore: \`git switch ${branch}\` failed: ${switchRes.stderr || 'unknown'}`,
-    );
-    return {
-      restored: false,
-      branch,
-      reason: `switch-failed: ${switchRes.stderr || 'unknown'}`,
-    };
-  }
-  return { restored: true, branch };
-}

package/.agents/scripts/lib/orchestration/story-close/phases/close.js

@@ -1,222 +0,0 @@
-/**
- * phases/close.js — merge + post-merge pipeline phase (Story #2460,
- * Epic #2453 — CLI thinning pilot).
- *
- * Runs once the pre-merge gates have passed (or been skipped on a
- * resume path). Owns:
- *   - the resume-aware merge runner dispatch (`runResumeMerge` vs
- *     `runFinalizeMerge`, skipped entirely on a `resumeFromPostMerge` path),
- *   - the post-merge close pipeline (ticket transitions, cascade, health,
- *     dashboard regen) via `runPostMergeClose`,
- *   - the success-path close-result envelope serialisation.
- *
- * Public surface:
- *   - runMergePhase(ctx)
- *   - runPostMergePhase(ctx)
- *   - runClosePhase(ctx)         ← composite (merge → post-merge)
- *
- * The split between `runMergePhase` and `runPostMergePhase` keeps each
- * function at one level of abstraction (and well under the < 200 LOC /
- * CC < 12 phase-file budget).
- */
-
-import { Logger } from '../../../Logger.js';
-import { PROJECT_ROOT } from '../../../project-root.js';
-import { STATE_LABELS } from '../../ticketing.js';
-import { runFinalizeMerge, runResumeMerge } from '../merge-runner.js';
-import { runPostMergeClose } from '../post-merge-close.js';
-
-/**
- * Story #2961 — final assertion that the Story ticket reached
- * `agent::done` after the post-merge cascade. The cascade is the single
- * writer of the `closing → done` label flip; without this readback,
- * `runStoryClose` returns `success: true` even when the flip silently
- * failed (the failure mode that Epic #2880 wave 0's friction note
- * F-W0-2 surfaced via the runner's GitHub probe — see Story #2894).
- *
- * Outcomes:
- *   - `{ ok: true }` — ticket has `agent::done` (or is closed).
- *   - `{ ok: false, actualLabels }` — cascade returned but the label
- *     never reached `agent::done`. The caller must downgrade
- *     `success: true` → `success: false`.
- *   - `{ ok: 'skipped', warning }` — `provider.getTicket` threw. The
- *     verification could not run, but the close itself succeeded, so
- *     the caller returns the success envelope with a `warnings[]` entry.
- */
-export async function verifyFinalStoryLabel({ provider, storyId }) {
-  if (!provider || typeof provider.getTicket !== 'function') {
-    return {
-      ok: 'skipped',
-      warning: `label-verification-skipped: provider.getTicket unavailable`,
-    };
-  }
-  let ticket;
-  try {
-    ticket = await provider.getTicket(storyId, { fresh: true });
-  } catch (err) {
-    return {
-      ok: 'skipped',
-      warning: `label-verification-skipped: ${err?.message ?? err}`,
-    };
-  }
-  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
-  if (labels.includes(STATE_LABELS.DONE) || ticket?.state === 'closed') {
-    return { ok: true };
-  }
-  return { ok: false, actualLabels: labels };
-}
-
-/**
- * Run the merge step. Skipped entirely on the already-merged resume path
- * — the merge already landed on `origin/epic/<id>` during the prior close
- * attempt; the only remaining work is the post-merge pipeline.
- */
-export async function runMergePhase(ctx) {
-  const {
-    resumeFromConflict,
-    resumeFromPostMerge,
-    cwd,
-    epicBranch,
-    storyBranch,
-    story,
-    storyId,
-    epicId,
-    config,
-    bus,
-    progress,
-    progressLog,
-  } = ctx;
-
-  if (resumeFromPostMerge) {
-    progress(
-      'MERGE',
-      `Skipping rebase + merge — story tip already reachable from ${epicBranch}`,
-    );
-    return;
-  }
-
-  const mergeArgs = {
-    cwd,
-    epicBranch,
-    storyBranch,
-    storyTitle: story.title,
-    storyId,
-    epicId,
-    config,
-    bus,
-    log: progressLog,
-  };
-  await (resumeFromConflict ? runResumeMerge : runFinalizeMerge)(mergeArgs);
-}
-
-/**
- * Run the post-merge close pipeline — ticket transitions, cascade, health
- * regen, dashboard regen. Returns the final close-result envelope.
- */
-export async function runPostMergePhase(ctx) {
-  const {
-    config,
-    storyId,
-    epicId,
-    story,
-    storyBranch,
-    epicBranch,
-    cwd,
-    provider,
-    notifyFn,
-    tasks,
-    skipDashboard,
-    progress,
-    phaseTimer,
-    clearPhaseTimerState,
-    bus,
-  } = ctx;
-
-  return runPostMergeClose({
-    config,
-    storyId,
-    epicId,
-    story,
-    storyBranch,
-    epicBranch,
-    cwd,
-    projectRoot: PROJECT_ROOT,
-    provider,
-    notify: notifyFn,
-    tasks,
-    skipDashboard,
-    progress,
-    logger: Logger,
-    phaseTimer,
-    clearPhaseTimerState,
-    bus,
-  });
-}
-
-/**
- * Pure envelope builder. Given the post-merge `result` and the
- * `verifyFinalStoryLabel` verdict, returns the close-result envelope
- * `runClosePhase` will surface back to `runStoryClose`. Exported so the
- * contract test can drive the failure / skipped / success branches
- * without spinning up the merge + cascade pipeline.
- */
-export function buildCloseEnvelope({ result, verdict, storyId }) {
-  if (verdict.ok === false) {
-    const failedResult = {
-      ...result,
-      status: 'failed',
-      phase: 'closing',
-      reason: 'label-transition-failed',
-      actualLabels: verdict.actualLabels,
-    };
-    Logger.warn?.(
-      `[story-close] ❌ Story #${storyId} cascade returned but label is not ` +
-        `${STATE_LABELS.DONE} (actual: ${JSON.stringify(verdict.actualLabels)}). ` +
-        `Returning failure envelope.`,
-    );
-    return { success: false, result: failedResult };
-  }
-  if (verdict.ok === 'skipped') {
-    return {
-      success: true,
-      result: { ...result, warnings: [verdict.warning] },
-    };
-  }
-  return { success: true, result };
-}
-
-/**
- * Composite phase: merge → post-merge close → final-label readback →
- * envelope serialise. The caller (`runStoryCloseLocked` in
- * story-close.js) marks the `close` phase on its phase timer before
- * calling in.
- */
-export async function runClosePhase(ctx) {
-  await runMergePhase(ctx);
-  const result = await runPostMergePhase(ctx);
-
-  // Story #2961 — final readback before declaring success. The
-  // post-merge cascade is the single writer for the `closing → done`
-  // label flip; if it silently failed, surface a failure envelope here
-  // rather than relying on the runner's downstream GitHub probe.
-  const verdict = await verifyFinalStoryLabel({
-    provider: ctx.provider,
-    storyId: ctx.storyId,
-  });
-  const envelope = buildCloseEnvelope({
-    result,
-    verdict,
-    storyId: ctx.storyId,
-  });
-
-  Logger.info(
-    `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(envelope.result, null, 2)}\n--- END RESULT ---\n`,
-  );
-  if (envelope.success) {
-    ctx.progress(
-      'DONE',
-      `✅ Story #${ctx.storyId} merged into ${ctx.epicBranch}. ${envelope.result.ticketsClosed.length} ticket(s) closed.`,
-    );
-  }
-  return envelope;
-}