mandrel 2.55.0 → 2.57.0

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -1,97 +0,0 @@
-/**
- * Fan-out / soft-conflict gates used by plan-persist (extracted from the
- * retired epic-plan-decompose persist phase in Stage 5).
- *
- * @module lib/orchestration/plan-persist/fan-out-gate
- */
-
-import { Logger } from '../../Logger.js';
-import {
-  CONFLICT_KINDS,
-  renderFanOutEvidence,
-  renderFanOutRemedy,
-  renderHardConflictError,
-} from '../ticket-validator-conflicts.js';
-
-/**
- * @param {object[]} findings
- * @param {boolean} allowLargeFanOut
- * @param {string} [tag]
- */
-export function enforceFanOutGate(
-  findings,
-  allowLargeFanOut,
-  tag = 'plan-persist',
-) {
-  const fanOut = (findings ?? []).filter((f) => f.kind === 'fan-out-warning');
-  if (fanOut.length === 0) return;
-  if (allowLargeFanOut) {
-    for (const f of fanOut) {
-      Logger.warn(
-        `[${tag}] Persisting a large-fan-out deletion: ` +
-          `Story "${f.storySlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
-          `importer(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.` +
-          renderFanOutEvidence(f),
-      );
-    }
-    return;
-  }
-  const lines = fanOut
-    .map(
-      (f) =>
-        `  - Story "${f.storySlug}" deletes "${f.path}" — ` +
-        `${f.callSiteCount} importer(s) (threshold ${f.threshold})` +
-        renderFanOutEvidence(f),
-    )
-    .join('\n');
-  // Each finding carries its own remedy — a rename-shaped deletion has no
-  // subsystems to split across, so a blanket "split it up" footer would be
-  // wrong advice for it (Story #4547).
-  const remedies = [...new Set(fanOut.map((f) => renderFanOutRemedy(f)))];
-  throw new Error(
-    `[${tag}] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
-      remedies.join('\n\n'),
-  );
-}
-
-/**
- * Report every soft finding the validator produced, each under its own kind.
- *
- * Only the {@link CONFLICT_KINDS} are cross-Story conflicts. The advisory
- * kinds — `spec-word-budget` and the sizing findings — are single-Story
- * nudges, and announcing them as conflicts overstated them and taught readers
- * to discount the whole channel (Story #4907). `fan-out-warning` is excluded
- * throughout: {@link enforceFanOutGate} owns it and has already either thrown
- * or logged the override.
- *
- * @param {object[]} findings
- * @param {string} [tag]
- */
-export function surfaceSoftConflictFindings(findings, tag = 'plan-persist') {
-  const soft = (findings ?? []).filter(
-    (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
-  );
-  if (soft.length === 0) return;
-  const conflicts = soft.filter((f) => CONFLICT_KINDS.has(f?.kind));
-  const advisories = soft.filter((f) => !CONFLICT_KINDS.has(f?.kind));
-  if (conflicts.length > 0) {
-    Logger.warn(
-      `[${tag}] ${conflicts.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
-    );
-    for (const finding of conflicts) {
-      Logger.warn(
-        `[${tag}] soft conflict: ${renderHardConflictError(finding)}`,
-      );
-    }
-  }
-  if (advisories.length > 0) {
-    Logger.warn(
-      `[${tag}] ${advisories.length} advisory finding(s) — the persist proceeds:`,
-    );
-    for (const finding of advisories) {
-      Logger.warn(
-        `[${tag}] advisory (${finding.kind}): ${renderHardConflictError(finding)}`,
-      );
-    }
-  }
-}

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

@@ -1,26 +0,0 @@
-/**
- * decomposer-context.js — system-prompt builder for the `/mandrel-plan` authoring
- * pass (Story #2466; v2 keeps the prompt helper, drops the Epic-fetch
- * decomposition envelope).
- *
- * `buildDecomposerSystemPrompt` is the live surface consumed by
- * `plan-context.js#buildSystemPrompts`. The retired
- * `buildDecompositionContext` Epic-fetch path lived here until the
- * Story-only cutover removed every caller.
- */
-
-import { renderDecomposerSystemPrompt } from '../../templates/decomposer-prompts.js';
-
-export function buildDecomposerSystemPrompt(
-  heuristics = [],
-  { maxTickets } = {},
-) {
-  const base = renderDecomposerSystemPrompt({
-    maxTickets,
-  });
-  const heuristicsStr =
-    heuristics.length > 0
-      ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
-      : '';
-  return `${base}${heuristicsStr ? `\n\n${heuristicsStr}` : ''}`;
-}

package/.agents/scripts/lib/orchestration/spec-budget.js

@@ -1,89 +0,0 @@
-/**
- * lib/orchestration/spec-budget.js — the soft `## Spec` word-budget pass
- * (Story #4723), extracted from `ticket-validator.js` so the advisory
- * length nudge lives beside neither the hard validators nor their error
- * channel: everything here is `'soft'` by construction and can never fail
- * a persist.
- */
-
-import { parse as parseStoryBody } from '../story-body/story-body.js';
-
-/**
- * Warn threshold (words) for a Story's inline `## Spec` (Story #4723,
- * retuned by Story #4907). The budget carries **two distinct numbers**, and
- * both belong in any surface that documents it:
- *
- * - **~250 words — the authoring target.** The #4707 contract-level-prose
- *   aim: interfaces, invariants, and load-bearing constraints, not
- *   route-by-route behavior narration. It lives in the story-author template
- *   placeholder (`plan-context.js`), which is what an author actually reads.
- * - **350 words — this warn threshold.** Deliberately slack against the
- *   target so the warning marks a real outlier rather than ordinary
- *   authoring variance. Measured over the 45 most recent Stories carrying a
- *   Spec, a 250-word threshold fired on 22% of *accepted* work (median 233,
- *   p75 249) — a warning that common trains its readers to ignore it.
- *
- * Distinct again from the hard ~1500-token fail-closed ceiling in
- * `spec-spill.js`: this budget only warns; it never fails the persist.
- */
-export const SPEC_SOFT_WORD_BUDGET = 350;
-
-/**
- * Resolve a Story's Spec prose across both authoring shapes: the canonical
- * serialized string body (parsed; `## Spec` text block) and the
- * pre-serialize structured object body (`body.spec`). Returns `''` when
- * absent — or when a string body does not parse: this pass is advisory, so
- * an unreadable body contributes no finding here and is left to the hard
- * parse gate (`assertStoryBodiesParse`) to reject.
- *
- * @param {object} story
- * @returns {string}
- */
-function resolveSpecText(story) {
-  const body = story?.body;
-  if (typeof body === 'string' && body.trim().length > 0) {
-    let spec;
-    try {
-      spec = parseStoryBody(body).body.spec;
-    } catch {
-      return '';
-    }
-    return typeof spec === 'string' ? spec : '';
-  }
-  if (body !== null && typeof body === 'object') {
-    return typeof body?.spec === 'string' ? body.spec : '';
-  }
-  return '';
-}
-
-/**
- * Advisory `## Spec` length pass (Story #4723). Emits one `'soft'` finding
- * per Story whose Spec prose exceeds {@link SPEC_SOFT_WORD_BUDGET} words,
- * nudging the author toward contract-level prose (#4707). Soft only — the
- * findings never reach the validator's `errors[]` channel, so an
- * over-budget Spec never fails the persist.
- *
- * @param {{ stories: object[] }} opts
- * @returns {object[]} Zero or more `spec-word-budget` findings.
- */
-export function computeSpecBudgetFindings({ stories }) {
-  const findings = [];
-  for (const story of stories ?? []) {
-    const words = resolveSpecText(story).split(/\s+/).filter(Boolean).length;
-    if (words <= SPEC_SOFT_WORD_BUDGET) continue;
-    findings.push({
-      kind: 'spec-word-budget',
-      severity: 'soft',
-      ticketSlug: story.slug ?? '<unknown>',
-      words,
-      budget: SPEC_SOFT_WORD_BUDGET,
-      message:
-        `Story "${story.slug ?? '<unknown>'}" ## Spec is ~${words} words ` +
-        `(soft budget ${SPEC_SOFT_WORD_BUDGET}). Prefer contract-level prose ` +
-        '(interfaces, invariants, load-bearing constraints with their why) ' +
-        'over per-file behavior narration — advisory only; the persist ' +
-        'proceeds.',
-    });
-  }
-  return findings;
-}

package/.agents/scripts/lib/orchestration/spec-spill.js

@@ -1,74 +0,0 @@
-/**
- * v2 Story `## Spec` budget gate.
- *
- * The Story body is the single executable document: Tech Spec prose stays
- * inline under `## Spec`. There is no spill-to-`docs/` path — an over-budget
- * Spec is treated as a sizing smell (the Story should be split or the Spec
- * tightened), not as a reason to write temporary product docs.
- *
- * This module also **owns** the §2 FinOps token estimator
- * ({@link estimateTokens}, ~4 chars/token) — the one shared approximation every
- * fixed framework ceiling speaks in (the Spec budget below, the plan-time
- * sizing ceilings in `ticket-validator-sizing.js`, and the audit checklist
- * threading budget). It used to live in a `context-envelope.js` SDK whose
- * remaining surface had no live caller; the estimator is all that survived.
- *
- * @module lib/orchestration/spec-spill
- */
-
-/**
- * Rough token estimate: ~4 characters per token. Deliberately cheap and
- * deterministic — every ceiling that quotes "tokens" is quoting this number,
- * so the approximation matters far less than every caller sharing one.
- *
- * @param {string} text
- * @returns {number}
- */
-export function estimateTokens(text) {
-  return Math.ceil(String(text ?? '').length / 4);
-}
-
-/**
- * Soft budget (estimated tokens) for an inline `## Spec`. ~1500 tokens ≈ 6KB —
- * enough for a real approach section, well under issue-body bloat.
- */
-export const DEFAULT_SPEC_BODY_TOKEN_BUDGET = 1500;
-
-/**
- * @typedef {object} SpecBudgetResult
- * @property {number} estimatedTokens
- * @property {string} content
- */
-
-/**
- * Keep Spec inline when it fits; throw when it exceeds the budget so the
- * planner splits or tightens instead of writing docs/.
- *
- * @param {object} args
- * @param {string} args.storyId  Story slug/id for error context.
- * @param {string} args.spec     Folded Tech Spec markdown.
- * @param {object} [opts]
- * @param {number} [opts.tokenBudget=DEFAULT_SPEC_BODY_TOKEN_BUDGET]
- * @returns {SpecBudgetResult}
- */
-export function assertSpecWithinBudget({ storyId, spec }, opts = {}) {
-  const { tokenBudget = DEFAULT_SPEC_BODY_TOKEN_BUDGET } = opts;
-  const content = typeof spec === 'string' ? spec : '';
-  const estimatedTokens = estimateTokens(content);
-
-  if (estimatedTokens <= tokenBudget) {
-    return { estimatedTokens, content };
-  }
-
-  const label =
-    typeof storyId === 'string' && storyId.trim() !== ''
-      ? storyId.trim()
-      : 'unknown';
-
-  throw new Error(
-    `[plan-persist] Story "${label}" ## Spec is ~${estimatedTokens} tokens ` +
-      `(budget ${tokenBudget}). An over-budget Spec usually means the Story ` +
-      `is too large — split it, or tighten ## Spec so the Story body stays ` +
-      `the single executable document. Specs are never written to docs/.`,
-  );
-}

package/.agents/scripts/lib/orchestration/verify-tier-repair.js

@@ -1,107 +0,0 @@
-/**
- * verify-tier-repair.js — repair-before-judging for the `verify[]` tier suffix
- * (Story #5005).
- *
- * The tier suffix (`… (unit)`) is a deterministic, mechanically-derivable
- * formality. `task-body-validator.js` already computed the corrected entry in
- * order to print it as a "Suggested fix" — then rejected the plan anyway and
- * charged the author a full re-drafting round to paste that exact string back.
- * This module applies the inference the validator already trusts, so the hard
- * error is reserved for the entries only the author can resolve.
- *
- * It lives beside the validator rather than inside it because the validator's
- * job is to *judge*: mixing a mutating repair pass into a module of pure
- * collectors muddies both. `persist-helpers.js#validateTickets` calls this
- * first, then `validateTaskBodies`.
- *
- * @module lib/orchestration/verify-tier-repair
- */
-
-import { suggestVerifyFix } from '../story-body/body-format-lints.js';
-import {
-  parse as parseStoryBody,
-  serialize as serializeStoryBody,
-} from '../story-body/story-body.js';
-import { VERIFY_TIER_VALUES } from './task-body-validator.js';
-
-/** A parenthesised tier drawn from the canonical vocabulary, at end of entry. */
-const VERIFY_TIER_RE = new RegExp(
-  `\\((?:${VERIFY_TIER_VALUES.join('|')})\\)\\s*$`,
-);
-
-/**
- * Rewrite one `verify[]` list, appending the inferable testing tier to any
- * entry missing one. Returns `null` when nothing changed, so callers can keep
- * an already-compliant list byte-identical (and skip re-serializing the body
- * it came from).
- *
- * @param {unknown} rawVerify
- * @returns {string[]|null} The corrected list, or `null` when no fix applied.
- */
-function repairVerifyList(rawVerify) {
-  if (!Array.isArray(rawVerify)) return null;
-  let changed = false;
-  const next = rawVerify.map((entry) => {
-    if (typeof entry !== 'string') return entry;
-    if (entry.startsWith('manual:') || VERIFY_TIER_RE.test(entry)) return entry;
-    const fix = suggestVerifyFix(entry);
-    if (fix === null) return entry;
-    changed = true;
-    return fix;
-  });
-  return changed ? next : null;
-}
-
-/**
- * Repair the `## Verify` section of a serialized (string) body, in place on
- * the ticket. Only re-serializes when a fix actually applied, so a compliant
- * body is never round-tripped through `parse → serialize`.
- *
- * Leaving the body untouched while the top level was repaired would be worse
- * than not repairing at all: `syncContractFieldFromTopLevel` fails closed on a
- * body section that disagrees with its top-level array, so both sides must be
- * repaired by the same rule or neither.
- *
- * @param {object} ticket
- */
-function repairStringBodyVerify(ticket) {
-  let parsed;
-  try {
-    parsed = parseStoryBody(ticket.body).body;
-  } catch {
-    // An unparseable body is already a hard error in `validateTaskBodyShape`;
-    // there is nothing to repair and nothing to report twice.
-    return;
-  }
-  const repaired = repairVerifyList(parsed.verify);
-  if (repaired === null) return;
-  ticket.body = serializeStoryBody({ ...parsed, verify: repaired });
-}
-
-/**
- * Auto-append the testing tier to `verify[]` entries that omit one, wherever
- * `suggestVerifyFix` can infer it from the command. An entry whose tier cannot
- * be inferred is left untouched and still hard-errors downstream.
- *
- * Mutates `tickets` in place (the persist pipeline threads this same array on
- * to assembly) and returns it. Already-compliant tickets are untouched, so
- * their persisted output stays byte-identical. Total — a non-array argument
- * and non-Story tickets are no-ops.
- *
- * @param {object[]} tickets
- * @returns {object[]} `tickets`
- */
-export function normalizeVerifyTiers(tickets) {
-  for (const ticket of Array.isArray(tickets) ? tickets : []) {
-    if (!ticket || ticket.type !== 'story' || ticket.body == null) continue;
-    const topLevel = repairVerifyList(ticket.verify);
-    if (topLevel !== null) ticket.verify = topLevel;
-    if (typeof ticket.body === 'string') {
-      repairStringBodyVerify(ticket);
-      continue;
-    }
-    const bodyLevel = repairVerifyList(ticket.body.verify);
-    if (bodyLevel !== null) ticket.body.verify = bodyLevel;
-  }
-  return tickets;
-}