mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/planning-context-budget.js

@@ -1,213 +0,0 @@
-/**
- * planning-context-budget.js
- *
- * Bounded planning-context budget for the `--emit-context` planning scripts
- * (Epic #817 Story 9). Provides a summary representation of large markdown
- * payloads (project docs, Epic body, Tech Spec body) so the host LLM is not
- * handed multi-100KB envelopes when the underlying material exceeds the
- * configured `maxBytes` budget.
- *
- * Two pure helpers:
- *   - `summarizeDoc(filePath, content, maxBytes)` extracts headings + bounded
- *     excerpts for one document.
- *   - `applyBudget(items, limits, opts)` decides full vs summary for a
- *     collection of `{ path, content }` items based on `summaryMode` and the
- *     total payload size.
- *
- * Both functions are deterministic and have no I/O.
- */
-
-const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
-
-/**
- * Default per-excerpt cap so a single section heading does not consume the
- * entire per-doc byte budget. The bounded sum across excerpts is enforced
- * separately by {@link summarizeDoc}.
- */
-const DEFAULT_PER_EXCERPT_BYTES = 800;
-
-/**
- * Default planning-context limits when callers do not pass through
- * `getLimits(config).planningContext`. Mirrors `LIMITS_DEFAULTS` in
- * `lib/config/limits.js` so this module is usable in standalone tests.
- */
-export const PLANNING_CONTEXT_DEFAULTS = Object.freeze({
-  maxBytes: 50000,
-  summaryMode: 'auto',
-});
-
-function byteLen(s) {
-  if (s == null) return 0;
-  return Buffer.byteLength(String(s), 'utf-8');
-}
-
-function extractHeadings(content) {
-  if (!content) return [];
-  const lines = String(content).split(/\r?\n/);
-  const out = [];
-  for (const line of lines) {
-    const m = HEADING_RE.exec(line);
-    if (m) out.push({ level: m[1].length, text: m[2] });
-  }
-  return out;
-}
-
-/**
- * Split a markdown body into preamble + per-heading sections so excerpts can
- * be emitted with the heading they belong to. Lines preceding the first
- * `## ` / `### ` heading become the `preamble` section (heading: null).
- */
-function splitSections(content) {
-  if (!content) return [];
-  const lines = String(content).split(/\r?\n/);
-  const sections = [{ heading: null, body: [] }];
-  for (const line of lines) {
-    const m = HEADING_RE.exec(line);
-    if (m) {
-      sections.push({ heading: m[2], body: [] });
-    } else {
-      sections[sections.length - 1].body.push(line);
-    }
-  }
-  return sections;
-}
-
-/**
- * Trim a multi-line section to the first non-empty paragraph, capped at
- * `maxBytes` of utf-8. Preserves whitespace inside the kept paragraph but
- * collapses leading/trailing blank lines so excerpts stay compact.
- */
-function firstParagraph(lines, maxBytes) {
-  const text = lines.join('\n').replace(/^\s+|\s+$/g, '');
-  if (!text) return '';
-  // Take up to the first blank-line break (paragraph boundary).
-  const para = text.split(/\n\s*\n/)[0] ?? '';
-  const trimmed = para.trim();
-  if (byteLen(trimmed) <= maxBytes) return trimmed;
-  // Hard truncate at maxBytes utf-8 with an ellipsis marker so callers can
-  // tell the excerpt is bounded rather than corrupt.
-  const buf = Buffer.from(trimmed, 'utf-8').subarray(0, maxBytes);
-  // Avoid splitting a multi-byte codepoint at the boundary.
-  let safe = buf.toString('utf-8');
-  if (safe.length > 1 && safe.charCodeAt(safe.length - 1) === 0xfffd) {
-    safe = safe.slice(0, -1);
-  }
-  return `${safe.replace(/\s+$/, '')}…`;
-}
-
-/**
- * Summarise a single markdown doc. Emits headings + per-section excerpts
- * (preamble first), each bounded so a runaway section never blows the budget.
- *
- * @param {string} filePath repo-relative path used as the `path` field
- * @param {string} content full markdown body
- * @param {number} [maxBytes=50000] total per-doc byte budget for excerpts
- * @returns {{ path: string, headings: string[], excerpts: Array<{heading: string|null, snippet: string}>, byteSize: number }}
- */
-export function summarizeDoc(filePath, content, maxBytes = 50000) {
-  const safeContent = typeof content === 'string' ? content : '';
-  const byteSize = byteLen(safeContent);
-  const headingObjs = extractHeadings(safeContent);
-  const headings = headingObjs.map((h) => h.text);
-
-  const sections = splitSections(safeContent);
-  const perExcerptCap = Math.min(
-    DEFAULT_PER_EXCERPT_BYTES,
-    Math.max(120, Math.floor(maxBytes / Math.max(1, sections.length))),
-  );
-
-  const excerpts = [];
-  let used = 0;
-  for (const sec of sections) {
-    if (used >= maxBytes) break;
-    const remaining = Math.max(0, maxBytes - used);
-    const cap = Math.min(perExcerptCap, remaining);
-    const snippet = firstParagraph(sec.body, cap);
-    if (!snippet) continue;
-    excerpts.push({ heading: sec.heading, snippet });
-    used += byteLen(snippet);
-  }
-
-  return {
-    path: filePath,
-    headings,
-    excerpts,
-    byteSize,
-  };
-}
-
-function normalizeItems(items) {
-  if (!Array.isArray(items)) return [];
-  return items
-    .filter((it) => it && typeof it === 'object')
-    .map((it) => ({
-      path: it.path ?? it.name ?? '',
-      content: typeof it.content === 'string' ? it.content : '',
-    }));
-}
-
-function totalBytes(items) {
-  let n = 0;
-  for (const it of items) n += byteLen(it.content);
-  return n;
-}
-
-function buildFullItems(items) {
-  return items.map((it) => ({
-    path: it.path,
-    content: it.content,
-    byteSize: byteLen(it.content),
-  }));
-}
-
-function buildSummaryItems(items, maxBytes) {
-  // Distribute the byte budget across docs proportional to their size, with
-  // a per-doc floor so even tiny docs get a heading + tiny excerpt.
-  const total = totalBytes(items) || 1;
-  const floor = Math.max(512, Math.floor(maxBytes / Math.max(1, items.length)));
-  return items.map((it) => {
-    const share = Math.max(
-      floor,
-      Math.floor((byteLen(it.content) / total) * maxBytes),
-    );
-    return summarizeDoc(it.path, it.content, share);
-  });
-}
-
-/**
- * Apply the planning-context budget to a collection of doc-shaped items.
- *
- * @param {Array<{path?: string, name?: string, content: string}>} items
- * @param {{ maxBytes?: number, summaryMode?: 'auto'|'always'|'never' }} [limits]
- * @param {{ fullContext?: boolean }} [opts] — `fullContext: true` forces full
- *   mode regardless of `summaryMode` (mirrors the `--full-context` CLI flag).
- * @returns {{ mode: 'full'|'summary', items: Array<object>, totalBytes: number }}
- */
-export function applyBudget(items, limits = {}, opts = {}) {
-  const merged = { ...PLANNING_CONTEXT_DEFAULTS, ...(limits || {}) };
-  const { maxBytes, summaryMode } = merged;
-  const { fullContext = false } = opts;
-
-  const norm = normalizeItems(items);
-  const total = totalBytes(norm);
-
-  if (fullContext || summaryMode === 'never') {
-    return { mode: 'full', items: buildFullItems(norm), totalBytes: total };
-  }
-  if (summaryMode === 'always') {
-    return {
-      mode: 'summary',
-      items: buildSummaryItems(norm, maxBytes),
-      totalBytes: total,
-    };
-  }
-  // auto — summarise iff payload exceeds the budget.
-  if (total > maxBytes) {
-    return {
-      mode: 'summary',
-      items: buildSummaryItems(norm, maxBytes),
-      totalBytes: total,
-    };
-  }
-  return { mode: 'full', items: buildFullItems(norm), totalBytes: total };
-}

package/.agents/scripts/lib/orchestration/planning-risk.js

@@ -1,194 +0,0 @@
-/**
- * planning-risk.js — derive the Epic planning-risk envelope from a
- * planner-authored risk verdict.
- *
- * Pure ESM, no I/O. The planner (the `epic-plan-spec-author` Skill) judges
- * the Epic it just specced and supplies a verdict of shape
- * `{ axes: [{ axis, level, rationale }], summary }`, validated against
- * `.agents/schemas/risk-verdict.schema.json` before it reaches this module.
- * This module owns the deterministic control-flow outputs — overall level,
- * review requirement, acceptance disposition, and gate decision — so the
- * model supplies the *judgment input* while the harness owns the *gate
- * decision* (Epic #3865 hard cutover from the retired keyword-regex
- * classifier; see `docs/roadmap.md` Part 1).
- */
-
-/** @typedef {'low' | 'medium' | 'high'} RiskLevel */
-/** @typedef {'required' | 'recommended' | 'not-applicable'} AcceptanceDisposition */
-/** @typedef {'review-required' | 'auto-proceed'} GateDecision */
-
-/**
- * @typedef {Object} PlanningRiskAxis
- * @property {string} axis
- * @property {RiskLevel} level
- * @property {string} rationale
- */
-
-/**
- * @typedef {Object} RiskVerdict
- * @property {PlanningRiskAxis[]} axes
- * @property {string} summary
- */
-
-/**
- * @typedef {Object} PlanningRiskEnvelope
- * @property {PlanningRiskAxis[]} axes
- * @property {RiskLevel} overallLevel
- * @property {boolean} requiresReview
- * @property {AcceptanceDisposition} acceptanceDisposition
- * @property {GateDecision} gateDecision
- * @property {string} [acceptanceWaivedReason] Present only when the
- *   acceptance disposition was forced to `not-applicable` by a non-axis
- *   signal (currently: no BDD runner detected). An operator-visible
- *   rationale so the override is never silent (Story #4145).
- */
-
-/**
- * @typedef {Object} BddRunnerProbe
- * @property {string|null} runner
- * @property {boolean} fallback `true` when no supported BDD runner was
- *   detected in the project (`verifyBddRunnerPendingTag`).
- * @property {string} [reason]
- */
-
-const LEVEL_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
-
-/**
- * Axes whose presence forces a `required` acceptance disposition. Mirrored
- * by the `axis` enum in `.agents/schemas/risk-verdict.schema.json` — keep
- * the two lists in sync.
- */
-export const REQUIRED_AXES = new Set([
-  'visible-behavior',
-  'public-api',
-  'security',
-  'data-migration',
-  'billing',
-  'destructive-mutation',
-  'critical-workflow',
-]);
-
-/**
- * Axes that, when they are the only signals present, waive the acceptance
- * spec (`not-applicable`). Mirrored by the `axis` enum in
- * `.agents/schemas/risk-verdict.schema.json` — keep the two lists in sync.
- */
-export const NOT_APPLICABLE_AXES = new Set([
-  'docs-only',
-  'test-harness',
-  'internal-refactor',
-]);
-
-/**
- * @param {PlanningRiskAxis[]} axes
- * @returns {RiskLevel}
- */
-function resolveOverallLevel(axes) {
-  if (axes.length === 0) return 'low';
-  return axes.reduce(
-    (highest, entry) =>
-      LEVEL_RANK[entry.level] > LEVEL_RANK[highest] ? entry.level : highest,
-    'low',
-  );
-}
-
-/**
- * @param {PlanningRiskAxis[]} axes
- * @param {RiskLevel} overallLevel
- * @returns {AcceptanceDisposition}
- */
-function resolveAcceptanceDisposition(axes, overallLevel) {
-  const requiredAxes = axes.filter((entry) => REQUIRED_AXES.has(entry.axis));
-  if (requiredAxes.length > 0) {
-    return 'required';
-  }
-  if (
-    overallLevel === 'medium' ||
-    axes.some((entry) => entry.level === 'medium')
-  ) {
-    return 'recommended';
-  }
-  if (
-    axes.length > 0 &&
-    axes.every((entry) => NOT_APPLICABLE_AXES.has(entry.axis))
-  ) {
-    return 'not-applicable';
-  }
-  if (overallLevel === 'low') return 'not-applicable';
-  return 'recommended';
-}
-
-/**
- * @param {RiskLevel} overallLevel
- * @param {PlanningRiskAxis[]} axes
- * @returns {boolean}
- */
-function resolveRequiresReview(overallLevel, axes) {
-  if (overallLevel === 'high') return true;
-  if (overallLevel === 'medium') {
-    return axes.some(
-      (entry) =>
-        entry.level === 'medium' &&
-        (REQUIRED_AXES.has(entry.axis) || entry.axis === 'visible-behavior'),
-    );
-  }
-  return false;
-}
-
-/**
- * Derive the stable planningRisk envelope from a schema-validated planner
- * verdict. Pure derivation — schema validation happens at the read boundary
- * (`plan-persist.js` via `loadRiskVerdict`), never here, so a malformed verdict fails closed
- * before this function runs.
- *
- * **No-BDD-runner waiver (Story #4145).** The acceptance disposition the risk
- * axes derive presumes a BDD runner exists to satisfy an authored AC table.
- * When `opts.bddRunner.fallback === true` (no supported runner detected — e.g.
- * a `node:test` repo with no `tests/features/**`), an authored AC table can
- * never be reconciled by `@epic-<id>-ac-*` feature tags, so `/deliver`
- * finalize would abort. In that case the disposition is **forced** to
- * `not-applicable` regardless of the risk axes, and `acceptanceWaivedReason`
- * records the override so it is operator-visible, not silent. The
- * `requiresReview` / `gateDecision` outputs are unaffected — a high-risk
- * Epic still routes to review; only the acceptance-spec requirement is
- * waived. Repos that ship a BDD runner (`fallback !== true`) are unaffected.
- *
- * @param {RiskVerdict} [verdict]
- * @param {{ bddRunner?: BddRunnerProbe|null }} [opts]
- * @returns {PlanningRiskEnvelope}
- */
-export function deriveRiskEnvelope(verdict = {}, { bddRunner = null } = {}) {
-  const axes = (Array.isArray(verdict.axes) ? verdict.axes : []).map(
-    ({ axis, level, rationale }) => ({ axis, level, rationale }),
-  );
-
-  const overallLevel = resolveOverallLevel(axes);
-  const axisDisposition = resolveAcceptanceDisposition(axes, overallLevel);
-  const requiresReview = resolveRequiresReview(overallLevel, axes);
-  const gateDecision = requiresReview ? 'review-required' : 'auto-proceed';
-
-  const noBddRunner = bddRunner?.fallback === true;
-  // Force the waiver only when the axes would otherwise have required (or
-  // recommended) an AC table; if the disposition is already not-applicable
-  // there is nothing to override and no waiver rationale to surface.
-  const forceWaiver = noBddRunner && axisDisposition !== 'not-applicable';
-  const acceptanceDisposition = forceWaiver
-    ? 'not-applicable'
-    : axisDisposition;
-
-  /** @type {PlanningRiskEnvelope} */
-  const envelope = {
-    axes,
-    overallLevel,
-    requiresReview,
-    acceptanceDisposition,
-    gateDecision,
-  };
-  if (forceWaiver) {
-    envelope.acceptanceWaivedReason =
-      `no BDD runner detected (${bddRunner?.reason ?? 'no-bdd-runner-detected'}) — ` +
-      `an authored acceptance-spec AC table cannot be reconciled by feature tags, ` +
-      `so the acceptance disposition is waived to not-applicable (was ${axisDisposition}).`;
-  }
-  return envelope;
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/branch-cleanup.js

@@ -1,56 +0,0 @@
-/**
- * phases/branch-cleanup.js — post-merge Story branch deletion phase.
- *
- * Delegates the "delete this branch from local + remote, treat not-found
- * as success" idempotency contract to `lib/git-branch-cleanup.js` so the
- * deletion rules live in one place. A local delete failure is logged
- * loudly (operators usually need to investigate a stale worktree),
- * while a remote not-found is treated as a no-op.
- */
-
-import { deleteBranchBoth } from '../../../git-branch-cleanup.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function branchCleanupPhase(ctx, state = {}) {
-  const {
-    storyBranch,
-    repoRoot,
-    progress,
-    logger,
-    branchCleanup = deleteBranchBoth,
-  } = ctx;
-  const log = reapPhaseLogger(progress);
-  log('CLEANUP', `Deleting story branch: ${storyBranch}`);
-
-  const result = branchCleanup(storyBranch, {
-    cwd: repoRoot,
-    noVerify: true,
-  });
-
-  if (!result.local.deleted) {
-    const stderr = (result.local.stderr || '').trim();
-    const reapStatus = state.worktreeReap?.status;
-    logger.error(
-      `  Local branch ${storyBranch} delete failed: ${stderr || 'unknown'}. ` +
-        `Check for stale worktrees (git worktree list).` +
-        (reapStatus ? ` worktreeReap=${reapStatus}.` : ''),
-    );
-  }
-  if (result.remote.deleted) {
-    if (result.remote.reason === 'not-found') {
-      log('CLEANUP', `Remote branch ${storyBranch} not found — skipped`);
-    } else {
-      log('CLEANUP', `✅ Remote branch ${storyBranch} deleted`);
-    }
-  }
-
-  return {
-    localDeleted: result.local.deleted,
-    remoteDeleted: result.remote.deleted,
-    localReason: result.local.reason,
-    remoteReason: result.remote.reason,
-  };
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/dashboard-refresh.js

@@ -1,33 +0,0 @@
-/**
- * phases/dashboard-refresh.js — regenerate the dispatch manifest after
- * a Story merges into its Epic branch. Honors `--skip-dashboard` so
- * operators running an out-of-band close can suppress the I/O.
- */
-
-import { generateAndSaveManifest } from '../../../../dispatcher.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function dashboardRefreshPhase(ctx) {
-  const {
-    epicId,
-    provider,
-    skipDashboard,
-    progress,
-    generateManifestFn = generateAndSaveManifest,
-  } = ctx;
-  const log = reapPhaseLogger(progress);
-  if (skipDashboard) {
-    log(
-      'DASHBOARD',
-      '⏭️ Skipping dashboard refresh (--skip-dashboard flag set)',
-    );
-    return false;
-  }
-  log('DASHBOARD', 'Regenerating dispatch manifest...');
-  await generateManifestFn(epicId, true, { provider });
-  log('DASHBOARD', '✅ Dashboard manifest updated (temp/)');
-  return true;
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/notification.js

@@ -1,78 +0,0 @@
-/**
- * phases/notification.js — post-merge story-complete notification phase.
- *
- * Fires a single consolidated story-merged webhook, then a rolled-up
- * `epic-progress` webhook (comment-suppressed) so operators see the
- * Epic's stories-done count tick up at each story-close without
- * subscribing to the per-story `story-merged` channel. The rolled-up
- * dispatch is best-effort — a flaky webhook MUST NOT block story-close.
- */
-
-import { notify } from '../../../../notify.js';
-import { Logger } from '../../../Logger.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function notificationPhase(ctx, state) {
-  const {
-    epicId,
-    storyId,
-    story,
-    epicBranch,
-    config,
-    progress,
-    provider,
-    notifyFn = notify,
-    logger = Logger,
-  } = ctx;
-  const closedTickets = state.ticketClosure?.closedTickets ?? [];
-  const log = reapPhaseLogger(progress);
-  log('NOTIFY', `Sending story-complete notification for Story #${storyId}...`);
-  await notifyFn(
-    epicId,
-    {
-      severity: 'medium',
-      message: `✅ Story #${storyId} — *${story.title}* — has been completed and merged into \`${epicBranch}\`. ${closedTickets.length} ticket(s) closed.`,
-      event: 'story-merged',
-      level: 'story',
-      epicId,
-    },
-    { config },
-  );
-  // Fire a rolled-up `epic-progress` webhook so operators see the Epic's
-  // overall stories-done count tick up at each story-close, without
-  // subscribing to the per-story `story-merged` channel. Comment is
-  // suppressed (skipComment: true) — the operator-facing GitHub
-  // comment is owned by the wave-record path; this fire is webhook-only.
-  // Failures are swallowed by design (warn-then-continue) so a flaky
-  // webhook never blocks story-close.
-  if (provider && epicId) {
-    try {
-      const subs = (await provider.getSubTickets?.(epicId)) ?? [];
-      const stories = subs.filter(
-        (t) => Array.isArray(t.labels) && t.labels.includes('type::story'),
-      );
-      const total = stories.length;
-      const done = stories.filter((s) => s.state === 'closed').length;
-      const pct = total === 0 ? 0 : Math.round((done / total) * 100);
-      await notifyFn(
-        epicId,
-        {
-          severity: 'medium',
-          message: `Epic #${epicId} progress · ${done}/${total} stories done (${pct}%) · Story #${storyId} merged`,
-          event: 'epic-progress',
-          level: 'epic',
-          epicId,
-        },
-        { config, skipComment: true },
-      );
-    } catch (err) {
-      logger?.warn?.(
-        `[notificationPhase] rolled-up epic-progress dispatch failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-  log('NOTIFY', '✅ Notification sent');
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/temp-cleanup.js

@@ -1,68 +0,0 @@
-/**
- * phases/temp-cleanup.js — remove the per-Story manifest pair under
- * `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}` (Epic #1030
- * Story #1040). Falls back to the legacy flat
- * `temp/story-manifest-<id>.{md,json}` layout when `epicId` is unknown
- * — both paths are tried so partial migrations don't leak files in
- * either layout. All deletes are idempotent; ENOENT is silently
- * absorbed.
- */
-
-import path from 'node:path';
-import { storyArtifactPath } from '../../../config/temp-paths.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function tempCleanupPhase(ctx) {
-  const { storyId, epicId, projectRoot, progress, unlinkFn, config } = ctx;
-  const log = reapPhaseLogger(progress);
-  const unlink = unlinkFn ?? (await import('node:fs/promises')).unlink;
-
-  // Per-Epic layout (Epic #1030 Story #1040): `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}`.
-  // Legacy flat layout: `temp/story-manifest-<sid>.{md,json}`. The migration
-  // tolerates both — try the per-Epic path first when `epicId` is known,
-  // and always sweep the legacy path so a half-migrated cohort doesn't
-  // leave residue.
-  const targets = [];
-  if (epicId) {
-    const eid = Number(epicId);
-    const sid = Number(storyId);
-    targets.push(
-      {
-        path: storyArtifactPath(eid, sid, 'manifest.md', config),
-        label: `temp/epic-${epicId}/stories/story-${storyId}/manifest.md`,
-      },
-      {
-        path: storyArtifactPath(eid, sid, 'manifest.json', config),
-        label: `temp/epic-${epicId}/stories/story-${storyId}/manifest.json`,
-      },
-    );
-  }
-  // Legacy flat layout is rooted at the framework's projectRoot — this is
-  // a half-migrated-cohort sweep, not a configured-tempRoot target. Once
-  // the legacy paths can no longer exist on any live install, this block
-  // can be deleted entirely.
-  const legacyBase = path.join(
-    projectRoot,
-    'temp',
-    `story-manifest-${storyId}`,
-  );
-  targets.push(
-    { path: `${legacyBase}.md`, label: `temp/story-manifest-${storyId}.md` },
-    {
-      path: `${legacyBase}.json`,
-      label: `temp/story-manifest-${storyId}.json`,
-    },
-  );
-
-  for (const target of targets) {
-    try {
-      await unlink(target.path);
-      log('CLEANUP', `🗑️  Deleted ${target.label}`);
-    } catch {
-      // File may not exist — deletion is idempotent.
-    }
-  }
-}