mandrel 1.91.0 → 1.93.0

package/.agents/scripts/lib/orchestration/plan-critic-conditions.js

@@ -0,0 +1,177 @@
+/**
+ * plan-critic-conditions.js — risk/size-conditional dispatch decisions for
+ * the /plan author-step critics (Epic #4474 PR6, design §4).
+ *
+ * The collapsed plan flow keeps the consolidation (8.3) and pre-mortem
+ * (8.5) critics as fresh-context sub-agent dispatches, but makes each
+ * dispatch **conditional** instead of unconditional — the dominant plan
+ * cost is turns × standing context, and an unconditional critic pays a
+ * full sub-agent spawn even when it provably has nothing to find. This
+ * module computes those decisions deterministically so the workflow never
+ * judges its own dispatch conditions:
+ *
+ *   - **Consolidation (8.3)**: dispatch only when the existing
+ *     `evaluateConsolidationPrecondition` gate says `dispatch: true` AND
+ *     (the draft has more than `CONSOLIDATION_STORY_THRESHOLD` stories OR
+ *     the precondition confirmed a divergence from the Delivery Slicing
+ *     table). A fail-open precondition (missing/unparseable table) on a
+ *     small draft is NOT a confirmed divergence — it skips, because a
+ *     ≤-threshold draft is small enough for gate #2's single-view review
+ *     to catch a distorted shape without a dedicated sub-agent.
+ *   - **Pre-mortem (8.5)**: dispatch when the risk verdict's overall level
+ *     is `high`, OR the ticket count is at least half of `maxTickets`, OR
+ *     any configured `planning.riskHeuristics` phrase matches the plan
+ *     text (case-insensitive substring).
+ *
+ * Under-firing risk (design PR6 note): the persist validators are
+ * unchanged hard gates and G2's cohort re-measures plan quality; every
+ * skip decision this module produces is logged to the plan-metrics ledger
+ * (`appendCriticSkip`) by the callers so under-firing is auditable.
+ *
+ * Pure, synchronous, no I/O — the `plan-critics.js` CLI owns reading the
+ * authored artifacts and the resolved config.
+ */
+
+import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';
+import { deriveRiskEnvelope } from './planning-risk.js';
+
+/**
+ * Draft-story count above which the consolidation critic fires even
+ * without a confirmed slicing divergence (design §6 PR6: "> 5 stories").
+ */
+export const CONSOLIDATION_STORY_THRESHOLD = 5;
+
+/**
+ * @typedef {Object} CriticDispatchDecision
+ * @property {'consolidation'|'pre-mortem'} critic
+ * @property {boolean} dispatch
+ * @property {string[]} reasons Why the critic fires — or why it is safe to
+ *   skip. Never empty: a skip's reasons are the audit trail the
+ *   plan-metrics ledger records.
+ */
+
+/**
+ * Decide the 8.3 consolidation dispatch: precondition AND size/divergence.
+ *
+ * @param {object} input
+ * @param {object[]} input.draftStories - The draft `tickets.json` array
+ *   (raw Story objects with top-level `slug` / `depends_on` / `body`).
+ * @param {string} input.specText - The text carrying the `## Delivery
+ *   Slicing` table. At author time this is the authored `techspec.md`
+ *   content (the Epic body carries the same folded section post-persist).
+ * @returns {CriticDispatchDecision}
+ */
+export function evaluateConsolidationDispatch({ draftStories, specText }) {
+  const precondition = evaluateConsolidationPrecondition({
+    draftStories,
+    epicBody: specText,
+  });
+
+  if (!precondition.dispatch) {
+    return {
+      critic: 'consolidation',
+      dispatch: false,
+      reasons: precondition.reasons,
+    };
+  }
+
+  const storyCount = draftStories.length;
+  const oversized = storyCount > CONSOLIDATION_STORY_THRESHOLD;
+  const diverges = precondition.cause === 'divergence';
+
+  if (!oversized && !diverges) {
+    return {
+      critic: 'consolidation',
+      dispatch: false,
+      reasons: [
+        `Draft has ${storyCount} story(ies) (≤ ${CONSOLIDATION_STORY_THRESHOLD}) and no confirmed Delivery Slicing divergence — gate #2's single-view review covers a draft this small.`,
+        ...precondition.reasons,
+      ],
+    };
+  }
+
+  const reasons = [];
+  if (diverges) reasons.push(...precondition.reasons);
+  if (oversized) {
+    reasons.push(
+      `Draft has ${storyCount} stories (> ${CONSOLIDATION_STORY_THRESHOLD}) — large enough that a distorted shape can hide from the gate #2 single view.`,
+    );
+  }
+  if (!diverges && precondition.cause === 'fail-open') {
+    reasons.push(...precondition.reasons);
+  }
+  return { critic: 'consolidation', dispatch: true, reasons };
+}
+
+/**
+ * Decide the 8.5 pre-mortem dispatch: high risk, or size ≥ ½ budget, or a
+ * risk-heuristic phrase match.
+ *
+ * @param {object} input
+ * @param {import('./planning-risk.js').RiskVerdict} input.riskVerdict -
+ *   The authored `risk-verdict.json` payload; the overall level is derived
+ *   deterministically from its axes (`deriveRiskEnvelope`), never trusted
+ *   as a free-standing field.
+ * @param {number} input.ticketCount - Draft ticket count (0 in the
+ *   single-delivery shape — no tickets exist).
+ * @param {number} input.maxTickets - The reviewability budget
+ *   (`getLimits(config).maxTickets`).
+ * @param {string[]} [input.riskHeuristics] - `planning.riskHeuristics`
+ *   phrases from the resolved config.
+ * @param {string} [input.planText] - Concatenated plan text the heuristics
+ *   match against (tech spec + serialized tickets + risk summary).
+ * @returns {CriticDispatchDecision}
+ */
+export function evaluatePremortemDispatch({
+  riskVerdict,
+  ticketCount,
+  maxTickets,
+  riskHeuristics = [],
+  planText = '',
+}) {
+  if (!Number.isInteger(maxTickets) || maxTickets <= 0) {
+    throw new TypeError(
+      'evaluatePremortemDispatch: maxTickets must be a positive integer',
+    );
+  }
+  const reasons = [];
+
+  const { overallLevel } = deriveRiskEnvelope(riskVerdict);
+  if (overallLevel === 'high') {
+    reasons.push(
+      'Risk verdict overall level is high — predicted-rework findings are worth a fresh-context pass.',
+    );
+  }
+
+  const count = Number.isInteger(ticketCount) ? ticketCount : 0;
+  if (count * 2 >= maxTickets) {
+    reasons.push(
+      `Ticket count ${count} is at least half the reviewability budget (maxTickets ${maxTickets}).`,
+    );
+  }
+
+  const haystack = String(planText).toLowerCase();
+  const matched = riskHeuristics.filter(
+    (phrase) =>
+      typeof phrase === 'string' &&
+      phrase.trim().length > 0 &&
+      haystack.includes(phrase.trim().toLowerCase()),
+  );
+  if (matched.length > 0) {
+    reasons.push(
+      `planning.riskHeuristics match(es) in the plan text: ${matched.map((p) => `"${p.trim()}"`).join(', ')}.`,
+    );
+  }
+
+  if (reasons.length > 0) {
+    return { critic: 'pre-mortem', dispatch: true, reasons };
+  }
+
+  return {
+    critic: 'pre-mortem',
+    dispatch: false,
+    reasons: [
+      `Overall risk is ${overallLevel} (not high), ticket count ${count} is under half the budget (maxTickets ${maxTickets}), and no planning.riskHeuristics phrase matches the plan text.`,
+    ],
+  };
+}

package/.agents/scripts/lib/orchestration/plan-critics-evaluate.js

@@ -0,0 +1,99 @@
+/**
+ * plan-critics-evaluate.js — shared critic-dispatch evaluation for the
+ * collapsed /plan flow (#4496 fix 6; extracted from the `plan-critics.js`
+ * CLI so the persist surface folds the same evaluation in as a pre-write
+ * phase).
+ *
+ * Two consumers:
+ *   - `plan-persist.js` (via `runPlanPersist`) — evaluates the dispatch
+ *     conditions as a deterministic pre-write phase, prints the verdicts,
+ *     and records every skip on the plan-metrics ledger, so the headless
+ *     path never pays a standalone CLI turn for the same decision.
+ *   - `plan-critics.js` — the standalone CLI survives one release as a
+ *     thin shim over this module for the attended pre-gate evaluation
+ *     (the verdict folds into gate #2's view before the persist runs).
+ *
+ * Pure evaluation: no file I/O, no GitHub calls, no ledger writes — the
+ * callers own artifact loading and skip recording.
+ *
+ * @module lib/orchestration/plan-critics-evaluate
+ */
+
+import { getLimits } from '../config-resolver.js';
+import {
+  evaluateConsolidationDispatch,
+  evaluatePremortemDispatch,
+} from './plan-critic-conditions.js';
+
+/**
+ * Resolve the planning risk heuristics list from the canonical config
+ * block (same resolution `plan-context.js` and the decompose context use).
+ *
+ * @param {object} config
+ * @returns {string[]}
+ */
+function resolveRiskHeuristics(config = {}) {
+  if (Array.isArray(config.planning?.riskHeuristics)) {
+    return config.planning.riskHeuristics;
+  }
+  return config.agentSettings?.planning?.riskHeuristics || [];
+}
+
+/**
+ * Evaluate the consolidation + pre-mortem critic dispatch conditions over
+ * the authored planning artifacts (design §4 / #4474 PR6 conditions,
+ * unchanged):
+ *
+ *   - Consolidation: skipped outright when `tickets` is null/absent (the
+ *     single-delivery shape authors no draft tickets); otherwise the
+ *     deterministic precondition + size/divergence conditions.
+ *   - Pre-mortem: risk verdict overall level high, OR ticket count at least
+ *     half `maxTickets`, OR any `planning.riskHeuristics` phrase matching
+ *     the plan text.
+ *
+ * @param {{
+ *   techSpecContent: string,
+ *   riskVerdict: { summary?: string },
+ *   tickets?: Array<object>|null,
+ *   config?: object,
+ * }} args
+ * @returns {{
+ *   consolidation: { critic: string, dispatch: boolean, reasons: string[] },
+ *   premortem: { critic: string, dispatch: boolean, reasons: string[] },
+ * }}
+ */
+export function evaluatePlanCritics({
+  techSpecContent,
+  riskVerdict,
+  tickets = null,
+  config = {},
+}) {
+  const ticketList = Array.isArray(tickets) ? tickets : null;
+  const consolidation =
+    ticketList === null
+      ? {
+          critic: 'consolidation',
+          dispatch: false,
+          reasons: [
+            'single-delivery shape — no draft tickets exist to consolidate.',
+          ],
+        }
+      : evaluateConsolidationDispatch({
+          draftStories: ticketList,
+          specText: techSpecContent,
+        });
+
+  const premortem = evaluatePremortemDispatch({
+    riskVerdict,
+    ticketCount: ticketList?.length ?? 0,
+    maxTickets: getLimits(config).maxTickets,
+    riskHeuristics: resolveRiskHeuristics(config),
+    planText: [
+      techSpecContent ?? '',
+      ticketList ? JSON.stringify(ticketList) : '',
+      riskVerdict?.summary ?? '',
+    ].join('\n'),
+  });
+
+  return { consolidation, premortem };
+}