mandrel 2.56.0 → 2.58.0

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

@@ -1,124 +1,50 @@
 /**
- * plan-critic-conditions.js — size/heuristic-conditional dispatch decisions for
- * the /mandrel-plan author-step critics (Epic #4474 PR6, design §4).
+ * plan-critic-conditions.js — the pre-mortem critic's dispatch decision for
+ * the `/mandrel-plan` critic CLI (Epic #4474 PR6, design §4; narrowed to one
+ * arm by Story #5312).
  *
- * The collapsed plan flow keeps the consolidation and pre-mortem 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:
+ * The critic is a fresh-context sub-agent dispatch, and the dispatch is
+ * **conditional**: 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 the decision deterministically so
+ * the workflow never judges its own dispatch condition.
  *
- *   - **Consolidation**: 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**: dispatch when the ticket count is at least half
- *     of `maxTickets`, OR any configured `planning.riskHeuristics` phrase
- *     matches the plan text (case-insensitive substring), OR the
- *     **external-dependency probe** (Story #4700) finds an out-of-repo marker
- *     in the plan text. Story #4542 removed the authored-risk-verdict condition
- *     along with the verdict itself; every surviving condition reads the plan's
- *     own observable text and shape rather than a self-assessment.
- *
- * The external-dependency probe (Story #4700) is what gives the default N=1
- * path a cheap viability check: on that path the size condition is unreachable
- * (`count*2 >= maxTickets` never holds at one ticket) and a repo whose resolved
- * `planning.riskHeuristics` is empty has no phrase to match, so a plan-time
- * discoverable blocker — a scoped package the plan names that no manifest
- * declares, a cross-repo reference, an external service prerequisite — reached
+ * One trigger survives: the **external-dependency probe** (Story #4700),
+ * which finds an out-of-repo marker in the plan text — a scoped package the
+ * plan names that no manifest declares, a cross-repo reference, an external
+ * service prerequisite — so a plan-time discoverable blocker does not reach
  * delivery unquestioned (the swarm-os #757 shape). The probe is deliberately
- * **conservative**: it matches only explicit markers (npm scoped-package specs,
- * `github.com/<owner>/<repo>` URLs, prerequisite-keyword-anchored endpoints),
- * never NLP guesswork, so a plan with no such marker dispatches exactly as it
- * did before.
+ * **conservative**: it matches only explicit markers (npm scoped-package
+ * specs, `github.com/<owner>/<repo>` URLs, prerequisite-keyword-anchored
+ * endpoints), never NLP guesswork.
+ *
+ * Story #5312 deleted the two triggers that sat beside it — the ticket count
+ * reaching half a `maxTickets` budget, and a `planning.riskHeuristics` phrase
+ * matching the plan text — with the constants they read. The count trigger
+ * was unreachable at the default N=1; the phrase list was empty in every
+ * consumer that resolved it. The consolidation critic went with them: its
+ * one deterministic input was a `## Delivery Slicing` table no Story carries.
  *
- * 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 caller so under-firing is auditable.
+ * Under-firing risk (design PR6 note): the persist validators are unchanged
+ * hard gates; every skip decision this module produces is logged to the
+ * plan-metrics ledger (`appendCriticSkip`) by the caller so under-firing is
+ * auditable.
  *
  * Pure, synchronous, no I/O. The single caller is `plan-critics-evaluate.js`,
- * driven by the `plan-critics.js` CLI that `/mandrel-plan` runs between Author and
- * Persist (Story #4592); the CLI owns reading the authored artifacts and the
- * resolved config.
- */
-
-import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';
-
-/**
- * Draft-story count above which the consolidation critic fires even
- * without a confirmed slicing divergence (#4474 PR6: "> 5 stories").
+ * driven by the `plan-critics.js` CLI the operator runs between Author and
+ * Persist when they want the critic; the CLI owns reading the authored
+ * artifacts and the resolved config.
  */
-export const CONSOLIDATION_STORY_THRESHOLD = 5;
 
 /**
  * @typedef {Object} CriticDispatchDecision
- * @property {'consolidation'|'pre-mortem'} critic
+ * @property {'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 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 };
-}
-
 /**
  * Explicit npm scoped-package marker: `@scope/name`. Requires the leading `@`
  * and an interior `/`, so bare GitHub handles (`@dsj1984`) and the
@@ -215,8 +141,8 @@ function matchExternalServicePrereqs(planText) {
 /**
  * The external-dependency probe (Story #4700): a conservative, marker-only
  * scan of the draft plan text for artifacts outside the current repo that the
- * plan depends on. A match is the pre-mortem's third dispatch condition; a
- * no-match plan behaves exactly as it did before this probe existed.
+ * plan depends on. A match is the pre-mortem's dispatch condition; a no-match
+ * plan skips the critic.
  *
  * @param {object} input
  * @param {string} [input.planText] - Concatenated plan text (tech spec +
@@ -262,19 +188,12 @@ export function evaluateExternalDependencyProbe({
 }
 
 /**
- * Decide the pre-mortem dispatch: size ≥ ½ budget, a risk-heuristic phrase
- * match, or an external-dependency probe match (Story #4700).
+ * Decide the pre-mortem dispatch: an external-dependency probe match
+ * (Story #4700) — the one deterministic trigger left after Story #5312.
  *
  * @param {object} input
- * @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 and
- *   the external-dependency probe match against (tech spec + serialized
- *   tickets).
+ * @param {string} [input.planText] - Concatenated plan text the probe
+ *   matches against (tech spec + serialized tickets).
  * @param {string[]} [input.knownPackages] - Package specifiers the repo's own
  *   manifests declare (own name + dependency maps + workspace package names),
  *   passed to the external-dependency probe.
@@ -284,58 +203,28 @@ export function evaluateExternalDependencyProbe({
  * @returns {CriticDispatchDecision}
  */
 export function evaluatePremortemDispatch({
-  ticketCount,
-  maxTickets,
-  riskHeuristics = [],
   planText = '',
   knownPackages = [],
   ownerRepo = null,
 }) {
-  if (!Number.isInteger(maxTickets) || maxTickets <= 0) {
-    throw new TypeError(
-      'evaluatePremortemDispatch: maxTickets must be a positive integer',
-    );
-  }
-  const reasons = [];
-
-  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(', ')}.`,
-    );
-  }
-
   const externalDeps = evaluateExternalDependencyProbe({
     planText,
     knownPackages,
     ownerRepo,
   });
   if (externalDeps.matched) {
-    reasons.push(...externalDeps.reasons);
-  }
-
-  if (reasons.length > 0) {
-    return { critic: 'pre-mortem', dispatch: true, reasons };
+    return {
+      critic: 'pre-mortem',
+      dispatch: true,
+      reasons: externalDeps.reasons,
+    };
   }
 
   return {
     critic: 'pre-mortem',
     dispatch: false,
     reasons: [
-      `Ticket count ${count} is under half the budget (maxTickets ${maxTickets}), no planning.riskHeuristics phrase matches the plan text, and the external-dependency probe found no out-of-repo markers.`,
+      'The external-dependency probe found no out-of-repo markers in the plan text.',
     ],
   };
 }

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

@@ -1,13 +1,13 @@
 /**
  * plan-critics-evaluate.js — shared critic-dispatch evaluation for the
- * collapsed /mandrel-plan flow (#4496 fix 6).
+ * collapsed /mandrel-plan flow (#4496 fix 6; pre-mortem only since Story #5312).
  *
- * One consumer: the `plan-critics.js` CLI, which `/mandrel-plan` runs between its
- * Author and Persist steps. The CLI loads the draft artifacts, calls this
- * module, prints the verdict as JSON, and records every skip on the
- * plan-metrics ledger; the workflow dispatches a fresh-context critic
- * sub-agent on a `dispatch: true` verdict and folds the findings into a
- * re-author round before persist.
+ * One consumer: the `plan-critics.js` CLI, which the operator runs between
+ * Author and Persist when they want the pre-mortem. The CLI loads the draft
+ * artifacts, calls this module, prints the verdict as JSON, and records a
+ * skip on the plan-metrics ledger; the workflow dispatches a fresh-context
+ * critic sub-agent on a `dispatch: true` verdict and folds the findings into
+ * a re-author round before persist.
  *
  * Story #4592 moved that evaluation here from `run-plan-persist.js`, which
  * ran it after authoring was finished and immediately before
@@ -21,26 +21,7 @@
  * @module lib/orchestration/plan-critics-evaluate
  */
 
-import { getLimits } from '../config-resolver.js';
-import {
-  evaluateConsolidationDispatch,
-  evaluatePremortemDispatch,
-} from './plan-critic-conditions.js';
-import { evaluateTextHygiene } from './plan-text-hygiene.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 [];
-}
+import { evaluatePremortemDispatch } from './plan-critic-conditions.js';
 
 /**
  * Resolve the `{ owner, repo }` the external-dependency probe's cross-repo arm
@@ -57,24 +38,11 @@ function resolveOwnerRepo(config = {}) {
 }
 
 /**
- * Evaluate the consolidation + pre-mortem critic dispatch conditions over
- * the authored planning artifacts (#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: ticket count at least half `maxTickets`, OR any
- *     `planning.riskHeuristics` phrase matching the plan text, OR the
- *     external-dependency probe (Story #4700) matching an out-of-repo marker
- *     — a scoped package absent from `knownPackages`, a cross-repo
- *     `github.com/<owner>/<repo>` reference, or a named external service
- *     prerequisite. Story #4542 retired its authored-risk-level condition with
- *     the verdict itself.
- *   - Text hygiene (Story #4599, advisory-only): deterministic body lints
- *     (dangling-citation / open-question / slicing-mass) over the draft
- *     stories. It has no `dispatch` semantics and spawns nothing — its
- *     `findings[]` are re-author-round input, and the consolidation /
- *     premortem dispatch verdicts are untouched by it.
+ * Evaluate the pre-mortem critic's dispatch condition over the authored
+ * planning artifacts: the external-dependency probe (Story #4700) matching an
+ * out-of-repo marker — a scoped package absent from `knownPackages`, a
+ * cross-repo `github.com/<owner>/<repo>` reference, or a named external
+ * service prerequisite.
  *
  * @param {{
  *   techSpecContent: string,
@@ -88,9 +56,7 @@ function resolveOwnerRepo(config = {}) {
  *   that gathers them; this module stays pure. Empty when unresolved, which
  *   only widens what the probe treats as external.
  * @returns {{
- *   consolidation: { critic: string, dispatch: boolean, reasons: string[] },
  *   premortem: { critic: string, dispatch: boolean, reasons: string[] },
- *   textHygiene: { critic: string, findings: Array<object> },
  * }}
  */
 export function evaluatePlanCritics({
@@ -100,24 +66,7 @@ export function evaluatePlanCritics({
   knownPackages = [],
 }) {
   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({
-    ticketCount: ticketList?.length ?? 0,
-    maxTickets: getLimits(config).maxTickets,
-    riskHeuristics: resolveRiskHeuristics(config),
     planText: [
       techSpecContent ?? '',
       ticketList ? JSON.stringify(ticketList) : '',
@@ -126,10 +75,5 @@ export function evaluatePlanCritics({
     ownerRepo: resolveOwnerRepo(config),
   });
 
-  const textHygiene = {
-    critic: 'text-hygiene',
-    findings: evaluateTextHygiene({ draftStories: ticketList }).findings,
-  };
-
-  return { consolidation, premortem, textHygiene };
+  return { premortem };
 }

package/.agents/scripts/lib/orchestration/plan-persist/acceptance-handle-repair.js

@@ -0,0 +1,107 @@
+/**
+ * acceptance-handle-repair.js — repair-before-judging for the `AC-<n>:`
+ * presentation handle on authored acceptance items (Story #5323).
+ *
+ * The handle belongs to the body renderer, which numbers each checkbox from
+ * its position in `acceptance[]` (`story-body.js`). An author planning from
+ * an existing ticket reads that rendered body as a template and carries the
+ * handle forward, so the persisted checkbox reads `- [ ] AC-1: AC-1: …`; a
+ * lettered handle copied out of a hand-edited source (`AC-14a:`) misnumbers
+ * the rest of the list against its own text.
+ *
+ * The correction is mechanical and total — strip the handle the renderer
+ * will re-apply — so this module applies it and **reports** it, exactly as
+ * `changes-repair.js` does for the `{ path, assumption }` formality. Charging
+ * the author a re-draft round to paste back text the strip already produced
+ * buys nothing.
+ *
+ * It lives beside the validator rather than inside it for the same reason
+ * `changes-repair.js` does: the validator's job is to judge, and mixing a
+ * mutating repair pass into a module of pure collectors muddies both.
+ * `persist-helpers.js#validateTickets` calls this first, then the validators.
+ *
+ * @module lib/orchestration/plan-persist/acceptance-handle-repair
+ */
+
+import { stripAcceptanceHandle } from '../../story-body/story-body.js';
+import { renderChangeRepair } from './changes-repair.js';
+
+/**
+ * Strip the handle off one surface's `acceptance[]`, recording each distinct
+ * strip on `repairs`.
+ *
+ * @param {object} surface An object that may carry an `acceptance` array.
+ * @param {string} slug
+ * @param {Set<string>} reported Items already reported for this ticket.
+ * @param {object[]} repairs Accumulator, mutated.
+ * @returns {void}
+ */
+function repairSurface(surface, slug, reported, repairs) {
+  if (!Array.isArray(surface.acceptance)) return;
+  surface.acceptance = surface.acceptance.map((item) => {
+    const { text, stripped } = stripAcceptanceHandle(item);
+    if (!stripped) return item;
+    const from = String(item ?? '');
+    if (!reported.has(from)) {
+      reported.add(from);
+      repairs.push({ kind: 'acceptance-handle', slug, from, to: text });
+    }
+    return text;
+  });
+}
+
+/**
+ * Strip the presentation `AC-<n>:` handle off every authored `acceptance[]`
+ * item, on both surfaces that can carry one: the ticket's top-level array
+ * (the machine contract) and a structured body's.
+ *
+ * A serialized **string** body needs no pass of its own — `parse()` strips
+ * the handle with the same grammar this does, so the two surfaces converge
+ * on one list whichever carried the handle, and the contract sync (which
+ * fails closed on a disagreement) sees them agree.
+ *
+ * Mutates `tickets` in place — the persist pipeline threads this same array
+ * on to assembly. Total: a non-array argument and non-Story tickets are
+ * no-ops.
+ *
+ * @param {object[]} tickets
+ * @returns {Array<{ kind: 'acceptance-handle', slug: string, from: string, to: string }>}
+ */
+export function normalizeAcceptanceHandles(tickets) {
+  const repairs = [];
+  for (const ticket of Array.isArray(tickets) ? tickets : []) {
+    if (!ticket || typeof ticket !== 'object' || ticket.type !== 'story') {
+      continue;
+    }
+    const slug = ticket.slug ?? ticket.title ?? '<unknown>';
+    // A ticket normally carries the same list on both surfaces, so report
+    // each distinct item once — the operator reads one correction, not two.
+    const reported = new Set();
+    repairSurface(ticket, slug, reported, repairs);
+    const body = ticket.body;
+    if (body && typeof body === 'object') {
+      repairSurface(body, slug, reported, repairs);
+    }
+  }
+  return repairs;
+}
+
+/**
+ * Render one entry of the dry-run's mixed repair list.
+ *
+ * The list carries two kinds — a `changes[]` entry repaired by probing base,
+ * and an `acceptance[]` item whose handle was normalised off — and both are
+ * mechanical corrections the run applied on the author's behalf, so both
+ * belong on the one list the operator reads. This module owns the dispatch
+ * because it owns the newer kind: it renders its own line and delegates
+ * every other kind to `changes-repair.js`, so neither producer has to know
+ * the other's shape.
+ *
+ * @param {{ kind?: string, slug: string, from: string, to?: string }} repair
+ * @returns {string}
+ */
+export function renderRepair(repair) {
+  if (repair.kind !== 'acceptance-handle') return renderChangeRepair(repair);
+  const { slug, from, to } = repair;
+  return `Story "${slug}": acceptance[] item "${from}" carried an AC-<n> handle — normalised to "${to}"; the body renderer numbers the checkboxes.`;
+}