mandrel 1.92.0 → 1.93.0

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -15,7 +15,13 @@
  *
  * Rules (one error per mismatched path):
  *   - `creates`            + path **exists**  → error (Story would clobber).
- *   - `refactors-existing` + path **absent** → error (no target to refactor).
+ *   - `refactors-existing` (via `changes`) + path **absent** →
+ *     auto-normalized to `creates` with a logged warning (#4496 fix 5):
+ *     a refactor declaration against a base-untracked path is
+ *     deterministically a create, so rejecting it only forces a
+ *     reject→amend→re-persist cycle for a mechanical rewrite. Genuine
+ *     mismatches keep failing — a `references`-sourced `refactors-existing`
+ *     on an absent path is a missing read dependency and stays an error.
  *   - `exists`             + path **absent** → error (read dependency missing).
  *   - `deletes`            + path **absent** → error (nothing to delete).
  *
@@ -185,6 +191,18 @@ function renderMismatch({
   return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path already exists at the base branch.`;
 }
 
+/**
+ * Render an auto-normalization (#4496 fix 5) into a stable warning string.
+ * Kept pure and exported through the report so callers log a
+ * self-explanatory line rather than re-deriving the rationale.
+ *
+ * @param {{ slug: string, source: string, path: string, assumption: string }} normalization
+ * @returns {string}
+ */
+function renderNormalization({ slug, source, path, assumption }) {
+  return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path is untracked at the base branch — auto-normalized to "creates" (a refactor of a base-untracked path is deterministically a create). Declare assumption="creates" in the plan to silence this warning.`;
+}
+
 /**
  * Index, across every Story, which Stories declare a `creates` (and which
  * declare a `deletes`) for each `changes`-sourced path. The maps drive the
@@ -251,8 +269,11 @@ function predecessorMutator(index, path, predecessors) {
  *
  *   {
  *     errors:    string[]   // one entry per mismatch, batched per Story
- *     warnings:  string[]   // legacy/no-assumption deprecation nudges
+ *     warnings:  string[]   // legacy/no-assumption deprecation nudges +
+ *                           // auto-normalization notices (#4496 fix 5)
  *     mismatches: object[]  // structured payload for downstream tooling
+ *     normalizations: object[] // `refactors-existing`→`creates`
+ *                           // auto-normalizations on base-untracked paths
  *   }
  *
  * Under the 2-tier hierarchy the Story is the implementation unit, so the
@@ -283,6 +304,7 @@ export function validateStoryFileAssumptions(opts) {
   const errors = [];
   const warnings = [];
   const mismatches = [];
+  const normalizations = [];
   const probeCache = new Map();
 
   // Wave-aware setup (Story #3960): transitive predecessor sets over the
@@ -350,6 +372,14 @@ export function validateStoryFileAssumptions(opts) {
         predecessorCreator,
       });
       if (mismatch !== null) {
+        // Auto-normalization (#4496 fix 5): a deterministic
+        // `refactors-existing`→`creates` rewrite is a warning, never a
+        // rejection — genuine mismatches keep flowing to `errors`.
+        if (mismatch.normalizedTo === 'creates') {
+          normalizations.push(mismatch);
+          warnings.push(renderNormalization(mismatch));
+          continue;
+        }
         mismatches.push(mismatch);
         errors.push(renderMismatch(mismatch));
         continue;
@@ -384,7 +414,7 @@ export function validateStoryFileAssumptions(opts) {
       }
     }
   }
-  return { errors, warnings, mismatches };
+  return { errors, warnings, mismatches, normalizations };
 }
 
 /**
@@ -468,12 +498,43 @@ function checkAssumption({
       }
       return null;
     case 'refactors-existing':
+      // Validate against the simulated tree: a predecessor `creates` makes
+      // an otherwise-absent base path present, so `refactors-existing`
+      // against it is no longer a false-positive mismatch (Story #3960).
+      if (!simulatedExists) {
+        // Auto-normalization (#4496 fix 5): a `changes`-sourced refactor
+        // declaration on a path untracked at the base branch (and not
+        // produced by any predecessor) is deterministically a create —
+        // downgrade to a normalization warning instead of rejecting. Two
+        // genuine mismatches stay hard errors: a `references`-sourced entry
+        // (a read dependency this Story does not author cannot be "created"
+        // here), and a base-TRACKED path a predecessor deletes (the absence
+        // is a plan-shape conflict, not an untracked-path misdeclaration).
+        if (source === 'changes' && !baseExists) {
+          return {
+            slug,
+            source,
+            path,
+            assumption,
+            expected: 'creates',
+            actual: 'absent',
+            normalizedTo: 'creates',
+          };
+        }
+        return {
+          slug,
+          source,
+          path,
+          assumption,
+          expected: 'present',
+          actual: 'absent',
+        };
+      }
+      return null;
     case 'exists':
     case 'deletes':
-      // Validate against the simulated tree: a predecessor `creates` makes
-      // an otherwise-absent base path present, so `refactors-existing` /
-      // `exists` / `deletes` against it is no longer a false-positive
-      // mismatch (Story #3960).
+      // Same simulated-tree overlay as above (Story #3960); an absent path
+      // remains a genuine mismatch for both assumptions.
       if (!simulatedExists) {
         return {
           slug,

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -11,7 +11,7 @@
  * file instead of shim-scripting library imports (the bench measured
  * ~12–15 turns of shim-writing for the dup search alone).
  *
- * Two modes (the design's mode matrix):
+ * Three modes (the design's mode matrix + the #4496 seed entry):
  *   - `epic`      — the Epic exists. Carries `epic`, `clarity` (the Epic
  *                   Clarity Gate rubric — free, same body fetch), `replan`
  *                   (already-planned signals) and `planState`.
@@ -19,6 +19,14 @@
  *                   to the persist half). Carries `onePager` and
  *                   `duplicates[]` (cross-Epic dup search). Clarity is not
  *                   scored — the ideation path is definitionally clear.
+ *   - `seed`      — headless ideation entry (#4496 fix 1): the one-pager
+ *                   does not exist yet either. The dup search runs off the
+ *                   raw seed text, and the envelope additively carries
+ *                   `seed`, `scopeTriage` (the scope-triage rubric applied
+ *                   CLI-side — no skill Reads on the headless path) and
+ *                   `onePagerSpec` (the canonical one-pager sections, so
+ *                   the authoring pass writes the one-pager in the SAME
+ *                   batched write as the spec artifacts).
  *
  * All fields are JSON-serialisable; the module performs no GitHub writes.
  * The only I/O surfaces are the injected `provider` (reads) and the
@@ -79,6 +87,131 @@ export const TICKET_SCHEMA_DESCRIPTOR = Object.freeze({
     'validateAndNormalizeTickets (lib/orchestration/ticket-validator.js) at persist time',
 });
 
+/**
+ * Canonical one-pager authoring descriptor for the `seed` envelope
+ * (#4496 fix 1). The section names are the ones `plan-epic.md`'s ideation
+ * entry has always named, chosen so the authored headings parse against
+ * the `SECTION_RE` map in `lib/epic-plan-ideation.js` (which renders the
+ * Epic body from the one-pager at persist time via
+ * `.agents/templates/epic-from-idea.md`).
+ */
+export const ONE_PAGER_AUTHORING_SPEC = Object.freeze({
+  sections: Object.freeze([
+    'Problem Statement',
+    'Recommended Direction',
+    'Key Assumptions',
+    'MVP Scope',
+    'Not Doing',
+  ]),
+  instruction:
+    'Author the one-pager markdown (the canonical sections above, as `## ` ' +
+    'headings) in the SAME batched write as the other planning artifacts — ' +
+    'no separate ideation pass and no idea-refinement skill activation on ' +
+    'this path. Every unresolved unknown lands in Key Assumptions instead ' +
+    'of a question.',
+  consumedBy:
+    'plan-persist.js --one-pager (ideation Epic creation via ' +
+    '.agents/templates/epic-from-idea.md)',
+});
+
+/**
+ * Count top-level enumerated items (`- `, `* `, `1. `) anywhere in a
+ * free-form seed text. Unlike {@link countScopeItems} this does not require
+ * a scope-shaped heading — a raw `--idea` seed rarely has one.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countEnumeratedItems(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  return text
+    .split(/\r?\n/)
+    .filter((line) => /^\s*(?:[-*]|\d+\.)\s+\S/.test(line)).length;
+}
+
+/**
+ * Delta-shaped change-request verbs — the `core/scope-triage` skill's
+ * change-request rubric routes these to `story` by default when the
+ * footprint stays inside Story width.
+ */
+const DELTA_VERB_RE =
+  /\b(fix(?:es)?|tweak(?:s)?|extend(?:s)?|update(?:s)?|adjust(?:s)?|rename(?:s)?|correct(?:s)?|patch(?:es)?|bug|regression|flaky)\b/i;
+
+/**
+ * Deterministic, CLI-applied scope-triage verdict over a raw `--idea` seed
+ * (#4496 fix 6). Embedding the verdict in the `--seed` envelope removes the
+ * two skill Reads (`core/scope-triage` + the gate fragment's rubric pass)
+ * from the headless path; the attended path keeps the skill-based judgment.
+ *
+ * The heuristics anchor to the same sizing SSOT the skill anchors to —
+ * `DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING` in
+ * `ticket-validator-sizing.js` (one Story = one coherent capability slice;
+ * multiple independent capabilities = an Epic) — and to the skill's
+ * change-request delta rubric. Like the skill, the verdict is **advisory**:
+ * being wrong in the `epic` direction is cheap (the consolidation critic and
+ * the sizing validator catch an over-planned Story later), and `borderline`
+ * is a first-class output, not a forced call.
+ *
+ * @param {{ seedText?: string }} args
+ * @returns {{ verdict: 'epic'|'story'|'borderline', reasons: string[], advisory: true, appliedBy: 'cli' }}
+ */
+export function buildScopeTriageSignal({ seedText = '' } = {}) {
+  const advisory = /** @type {const} */ (true);
+  const appliedBy = /** @type {const} */ ('cli');
+  const text = typeof seedText === 'string' ? seedText : '';
+  const listItems = countEnumeratedItems(text);
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+
+  if (listItems >= 3) {
+    return {
+      verdict: 'epic',
+      reasons: [
+        `seed enumerates ${listItems} candidate capabilities — a genuine fan-out surface`,
+      ],
+      advisory,
+      appliedBy,
+    };
+  }
+  if (listItems >= 1) {
+    return {
+      verdict: 'story',
+      reasons: [
+        `seed enumerates ${listItems} capability item(s) — one coherent change with one reason to exist`,
+      ],
+      advisory,
+      appliedBy,
+    };
+  }
+  if (DELTA_VERB_RE.test(text) && wordCount <= 120) {
+    return {
+      verdict: 'story',
+      reasons: [
+        'delta-shaped seed (change-request verb, no capability enumeration) within Story width',
+      ],
+      advisory,
+      appliedBy,
+    };
+  }
+  if (wordCount >= 250) {
+    return {
+      verdict: 'epic',
+      reasons: [
+        `broad prose seed (~${wordCount} words) with no enumeration — plausibly multiple independent capabilities`,
+      ],
+      advisory,
+      appliedBy,
+    };
+  }
+  return {
+    verdict: 'borderline',
+    reasons: [
+      'no capability enumeration and no clear delta signal — could be one ambitious Story or a small Epic; the operator (or the --yes Recommended branch) decides',
+    ],
+    advisory,
+    appliedBy,
+  };
+}
+
 /**
  * Resolve the planning risk heuristics list from the canonical config
  * block (same resolution the decompose context uses).
@@ -449,14 +582,56 @@ async function buildOnePagerModeEnvelope({
   };
 }
 
+/**
+ * Build the seed-mode (headless ideation) envelope — #4496 fix 1. The
+ * one-pager does not exist yet: the dup search and the authoring-context
+ * fold both run off the raw seed text (the same builders the one-pager mode
+ * uses), and the envelope additively carries `seed`, the CLI-applied
+ * `scopeTriage` verdict (fix 6 — no skill Reads on the headless path), and
+ * `onePagerSpec` so the one-pager sections are authored in the same batched
+ * write as the spec artifacts.
+ */
+async function buildSeedModeEnvelope({
+  seedText,
+  provider,
+  config,
+  settings,
+  fullContext,
+  cwd,
+}) {
+  if (typeof seedText !== 'string' || seedText.trim().length === 0) {
+    throw new Error(
+      '[plan-context] --seed requires non-empty seed text — nothing to plan from.',
+    );
+  }
+  const base = await buildOnePagerModeEnvelope({
+    onePagerPath: undefined,
+    onePagerContent: seedText,
+    provider,
+    config,
+    settings,
+    fullContext,
+    cwd,
+  });
+  const { onePager: _onePager, ...rest } = base;
+  return {
+    ...rest,
+    mode: 'seed',
+    seed: { text: seedText },
+    scopeTriage: buildScopeTriageSignal({ seedText }),
+    onePagerSpec: ONE_PAGER_AUTHORING_SPEC,
+  };
+}
+
 /**
  * Build the single planner-context envelope.
  *
  * @param {{
- *   mode: 'epic'|'one-pager',
+ *   mode: 'epic'|'one-pager'|'seed',
  *   epicId?: number,
  *   onePagerPath?: string,
  *   onePagerContent?: string,
+ *   seedText?: string,
  *   provider: object,
  *   config: object,
  *   settings: object,
@@ -469,6 +644,7 @@ export async function buildPlanContext({
   epicId,
   onePagerPath,
   onePagerContent,
+  seedText,
   provider,
   config = {},
   settings = {},
@@ -504,7 +680,17 @@ export async function buildPlanContext({
       cwd,
     });
   }
+  if (mode === 'seed') {
+    return buildSeedModeEnvelope({
+      seedText,
+      provider,
+      config,
+      settings,
+      fullContext,
+      cwd,
+    });
+  }
   throw new Error(
-    `[plan-context] unknown mode "${mode}" — expected "epic" or "one-pager".`,
+    `[plan-context] unknown mode "${mode}" — expected "epic", "one-pager" or "seed".`,
   );
 }

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 };
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -130,6 +130,7 @@ import {
   read as readPlanState,
   write as writePlanState,
 } from '../epic-plan-state-store.js';
+import { evaluatePlanCritics } from '../plan-critics-evaluate.js';
 import {
   appendCriticSkip,
   readPlanMetrics,
@@ -426,9 +427,10 @@ export async function runPlanPersist({
   let validated = null;
   let amendPartition = null;
   let reachability = null;
+  let gateSet = null;
   if (mode !== 'single') {
     amendPartition = mode === 'amend' ? partitionAmendTickets(tickets) : null;
-    const gateSet = mode === 'amend' ? buildMergedTicketSet(tickets) : tickets;
+    gateSet = mode === 'amend' ? buildMergedTicketSet(tickets) : tickets;
     const maxTickets = getLimits(config).maxTickets;
     if (gateSet.length > maxTickets && !allowOverBudget) {
       throw new Error(
@@ -533,6 +535,40 @@ export async function runPlanPersist({
     );
   }
 
+  // ---- Step 4.7: folded critic dispatch evaluation (#4496 fix 6 — the
+  // former standalone `plan-critics.js` turn). Deterministic and git-local,
+  // still zero provider calls: the verdicts are printed (and returned on
+  // the result) as part of the pre-write phase, and every skip decision is
+  // appended to the plan-metrics ledger exactly as the standalone CLI did,
+  // so under-firing stays auditable without a separate invocation on the
+  // headless path. Advisory by construction — the deterministic validators
+  // above remain the unchanged hard gates. ----
+  const critics = evaluatePlanCritics({
+    techSpecContent,
+    riskVerdict,
+    tickets: gateSet,
+    config,
+  });
+  for (const decision of [critics.consolidation, critics.premortem]) {
+    Logger.info(
+      `[plan-persist] critic ${decision.critic}: ` +
+        `${decision.dispatch ? 'dispatch' : 'skip'} — ` +
+        decision.reasons.join('; '),
+    );
+    if (!decision.dispatch) {
+      // Best-effort by contract — a failed append never fails the persist.
+      await appendCriticSkip(
+        {
+          critic: decision.critic,
+          reasons: decision.reasons,
+          cli: 'plan-persist',
+          epicId: requestedEpicId,
+        },
+        config,
+      );
+    }
+  }
+
   // ---- Step 5: ideation fold / Epic resolution (first provider call). ----
   const { epicId, epic, created } = await resolveTargetEpic({
     epicId: requestedEpicId,
@@ -902,6 +938,7 @@ export async function runPlanPersist({
       freshness,
       healthcheck,
       reachability,
+      critics,
       reconcile,
       specPath: specFilePath,
       waveTable,

package/.agents/scripts/lib/orchestration/plan-persist/summary.js

@@ -89,10 +89,16 @@ function renderWaveTableLines(waveTable) {
  * record `{ deliveryShape, sliceCount, routingReasons }` (Epic #4474 PR4)
  * for the spec-only mode.
  *
+ * Every auto-waiver the persist derived is printed WITH its reason
+ * (#4496 fix 2) — e.g. the no-BDD-runner acceptance-disposition waiver
+ * (`planningRisk.acceptanceWaivedReason`) — so the summary is
+ * self-explanatory and a headless reader never has to re-derive a persist
+ * outcome from framework source.
+ *
  * @param {{
  *   epicId: number,
  *   ticketCount: number,
- *   planningRisk: { overallLevel?: string, gateDecision?: string },
+ *   planningRisk: { overallLevel?: string, gateDecision?: string, acceptanceDisposition?: string, acceptanceWaivedReason?: string },
  *   reviewRouting: { decision?: string },
  *   freshness?: { stale?: number, ambiguous?: number },
  *   healthcheck?: { ok?: boolean, waived?: boolean, skipped?: boolean },
@@ -137,6 +143,14 @@ export function buildPlanSummaryCommentBody({
       ? `- Single-delivery plan (\`delivery::single\`): no Story tree — the Delivery Slicing table is the audit trail.`
       : `- ${ticketCount} Story ticket(s) persisted across ${waveTable.length} wave(s).`;
 
+  // Auto-waivers always ship with their reason (#4496 fix 2): the summary
+  // is authoritative, so the line must be self-explanatory on its own.
+  const waiverLines = planningRisk?.acceptanceWaivedReason
+    ? [
+        `- ⚠️ Acceptance disposition auto-waived to \`not-applicable\` — ${planningRisk.acceptanceWaivedReason}`,
+      ]
+    : [];
+
   const amendLines = amend
     ? [
         `- Amend delta: ${amend.created.length} added, ${amend.recreated.length} modified (closed + recreated), ${amend.closed.length} closed, ${amend.keptCount} kept untouched.`,
@@ -176,6 +190,7 @@ export function buildPlanSummaryCommentBody({
     headLine,
     ...amendLines,
     `- Risk: ${planningRisk?.overallLevel ?? 'unknown'} · ${planningRisk?.gateDecision ?? 'unknown'} (review routing: ${reviewRouting?.decision ?? 'unknown'}).`,
+    ...waiverLines,
     freshnessLine,
     healthcheckLine,
     // G2 measurement receipt (Epic #4474 PR1/PR7): the plan-CLI invocation

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -589,8 +589,25 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
       gitRunner: sharedGitRunner,
       cwd: opts.cwd,
     });
+    // Auto-normalizations (#4496 fix 5) get their own prefix so the logged
+    // warning is self-explanatory; everything else on the warnings channel
+    // is a legacy-shape deprecation nudge.
+    const normalizationWarnings = new Set(
+      (assumptionReport.normalizations ?? []).map((n) => n.path),
+    );
     for (const warning of assumptionReport.warnings) {
-      Logger.warn(`[ticket-validator] assumption-deprecation: ${warning}`);
+      const isNormalization = warning.includes('auto-normalized to "creates"');
+      Logger.warn(
+        `[ticket-validator] ${isNormalization ? 'assumption-normalized' : 'assumption-deprecation'}: ${warning}`,
+      );
+    }
+    if (normalizationWarnings.size > 0) {
+      Logger.warn(
+        `[ticket-validator] ${normalizationWarnings.size} refactors-existing ` +
+          'declaration(s) on base-untracked path(s) auto-normalized to ' +
+          '"creates" — the gate proceeds; update the plan declarations at ' +
+          'the next amend.',
+      );
     }
     assumptionErrors = assumptionReport.errors;
   }

package/.agents/scripts/plan-context.js

@@ -11,7 +11,7 @@
  * stdout-pure JSON envelope. The PR7 cutover retired the delegate CLIs —
  * this is the only emit-context surface.
  *
- * Two entry forms (exactly one is required):
+ * Three entry forms (exactly one is required):
  *
  *   --epic <id>          Existing-Epic mode. Envelope carries `epic`,
  *                        `clarity` (Epic Clarity Gate rubric), `replan`
@@ -23,6 +23,15 @@
  *                        dup search). No clarity score: the ideation path
  *                        is definitionally clear.
  *
+ *   --seed "<text>"      Headless ideation entry (#4496 fix 1) — neither
+ *                        the Epic nor the one-pager exists yet. The dup
+ *                        search runs off the raw seed text, and the
+ *                        envelope additively carries `seed`, `scopeTriage`
+ *                        (the scope-triage rubric applied CLI-side — fix 6)
+ *                        and `onePagerSpec`, so the one-pager sections are
+ *                        authored in the same batched write as the spec
+ *                        artifacts.
+ *
  * Flags:
  *   --pretty         Pretty-print the JSON envelope.
  *   --full-context   Bypass the planning-context budget (unbounded body).
@@ -58,10 +67,11 @@ import { createProvider } from './lib/provider-factory.js';
  * captured output is exactly one `JSON.parse`-able payload.
  *
  * @param {{
- *   mode: 'epic'|'one-pager',
+ *   mode: 'epic'|'one-pager'|'seed',
  *   epicId?: number,
  *   onePagerPath?: string,
  *   onePagerContent?: string,
+ *   seedText?: string,
  *   provider: object,
  *   config: object,
  *   settings: object,
@@ -77,6 +87,7 @@ export async function emitPlanContext({
   epicId,
   onePagerPath,
   onePagerContent,
+  seedText,
   provider,
   config,
   settings,
@@ -90,6 +101,7 @@ export async function emitPlanContext({
     epicId,
     onePagerPath,
     onePagerContent,
+    seedText,
     provider,
     config,
     settings,
@@ -108,6 +120,7 @@ async function main() {
     options: {
       epic: { type: 'string' },
       'one-pager': { type: 'string' },
+      seed: { type: 'string' },
       pretty: { type: 'boolean', default: false },
       'full-context': { type: 'boolean', default: false },
     },
@@ -117,12 +130,16 @@ async function main() {
   const hasEpic = typeof values.epic === 'string' && values.epic.length > 0;
   const hasOnePager =
     typeof values['one-pager'] === 'string' && values['one-pager'].length > 0;
-  if (hasEpic === hasOnePager) {
+  const hasSeed = typeof values.seed === 'string' && values.seed.length > 0;
+  const entryForms = [hasEpic, hasOnePager, hasSeed].filter(Boolean).length;
+  if (entryForms !== 1) {
     throw new Error(
-      'Pass exactly one of --epic <id> or --one-pager <path>. ' +
-        '(--epic: existing-Epic mode; --one-pager: ideation mode.)',
+      'Pass exactly one of --epic <id>, --one-pager <path> or --seed "<text>". ' +
+        '(--epic: existing-Epic mode; --one-pager: ideation mode; ' +
+        '--seed: headless ideation entry.)',
     );
   }
+  const mode = hasEpic ? 'epic' : hasOnePager ? 'one-pager' : 'seed';
 
   let epicId;
   if (hasEpic) {
@@ -159,21 +176,22 @@ async function main() {
   const provider = createProvider(config);
 
   // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode so the folded
-  // emit surface is measured against the 12-phase baseline. One-pager mode
-  // has no Epic yet, so the record routes to the standalone stream
-  // (epicId null) exactly like `story-plan.js`.
+  // emit surface is measured against the 12-phase baseline. One-pager and
+  // seed modes have no Epic yet, so the record routes to the standalone
+  // stream (epicId null) exactly like `story-plan.js`.
   await recordPlanInvocation(
     {
       cli: 'plan-context',
-      mode: hasEpic ? 'epic' : 'one-pager',
+      mode,
       epicId: hasEpic ? epicId : null,
       config,
     },
     () =>
       emitPlanContext({
-        mode: hasEpic ? 'epic' : 'one-pager',
+        mode,
         epicId,
         onePagerPath: hasOnePager ? values['one-pager'] : undefined,
+        seedText: hasSeed ? values.seed : undefined,
         provider,
         config,
         settings,

package/.agents/scripts/plan-critics.js

@@ -5,15 +5,24 @@
  * author-step critics of the collapsed /plan flow (Epic #4474 PR6,
  * design §4).
  *
+ * **Thin shim (#4496 fix 6).** The evaluation itself now lives in
+ * `lib/orchestration/plan-critics-evaluate.js` and is folded into
+ * `plan-persist.js` as a pre-write phase, so the headless (`--yes`) path
+ * never pays a standalone CLI turn for the dispatch decision. This CLI
+ * survives one release for the attended pre-gate evaluation (the verdict
+ * folds into gate #2's view before the persist runs) and for any external
+ * scripting; it delegates to the shared module and keeps its exact output
+ * contract.
+ *
  * Runs between authoring and gate #2, entirely git-local (zero GitHub
  * calls): reads the authored artifacts, evaluates the risk/size dispatch
  * conditions for the consolidation (8.3) and pre-mortem (8.5) critics via
- * `lib/orchestration/plan-critic-conditions.js`, and emits one JSON
- * verdict on stdout. The workflow dispatches a fresh-context sub-agent
- * ONLY for critics with `dispatch: true`; every skip decision is appended
- * to the plan-metrics ledger (`kind: "critic-skip"`, with reasons) so
- * under-firing is auditable — the persist validators remain unchanged
- * hard gates regardless of what this gate decides.
+ * the shared evaluator, and emits one JSON verdict on stdout. The workflow
+ * dispatches a fresh-context sub-agent ONLY for critics with
+ * `dispatch: true`; every skip decision is appended to the plan-metrics
+ * ledger (`kind: "critic-skip"`, with reasons) so under-firing is
+ * auditable — the persist validators remain unchanged hard gates
+ * regardless of what this gate decides.
  *
  * Conditions (design §4 / §6 PR6):
  *   - Consolidation: the existing deterministic precondition
@@ -53,16 +62,12 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { epicArtifactPath } from './lib/config/temp-paths.js';
 import {
-  getLimits,
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
 import { routeAllOutputToStderr } from './lib/Logger.js';
 import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-import {
-  evaluateConsolidationDispatch,
-  evaluatePremortemDispatch,
-} from './lib/orchestration/plan-critic-conditions.js';
+import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
 import {
   appendCriticSkip,
   recordPlanInvocation,
@@ -72,20 +77,6 @@ const USAGE =
   'Usage: plan-critics.js (--epic <EpicId> | --tech-spec <file> ' +
   '--risk-verdict <file> [--tickets <file>]) [--pretty]';
 
-/**
- * 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 || [];
-}
-
 async function readOptional(filePath, { required }) {
   try {
     return await readFile(filePath, 'utf8');
@@ -172,30 +163,11 @@ async function main() {
         }
       }
 
-      const consolidation =
-        tickets === null
-          ? {
-              critic: 'consolidation',
-              dispatch: false,
-              reasons: [
-                'single-delivery shape — no draft tickets exist to consolidate.',
-              ],
-            }
-          : evaluateConsolidationDispatch({
-              draftStories: tickets,
-              specText: techSpecContent,
-            });
-
-      const premortem = evaluatePremortemDispatch({
+      const { consolidation, premortem } = evaluatePlanCritics({
+        techSpecContent,
         riskVerdict,
-        ticketCount: tickets?.length ?? 0,
-        maxTickets: getLimits(config).maxTickets,
-        riskHeuristics: resolveRiskHeuristics(config),
-        planText: [
-          techSpecContent,
-          ticketsRaw ?? '',
-          riskVerdict.summary ?? '',
-        ].join('\n'),
+        tickets,
+        config,
       });
 
       // Skip-audit trail (#4474 PR6): every non-dispatch is a ledger

package/.agents/workflows/helpers/plan-epic-reference.md

@@ -100,19 +100,30 @@ reseeding from live GitHub state when the file is missing — so only the
 genuinely-missing children are created; the existing tree is never
 duplicated.
 
-## Measurement — the G2 acceptance gate (Epic #4474)
+## Measurement — the G2 acceptance gate (Epic #4474, restated per #4496)
 
-The 3-step collapse is **measured, not asserted**. The acceptance bar the
-next benchmark cohort reads as the gate:
+The 3-step collapse is **measured, not asserted**. The gate is stated
+**per mode** (#4496 — adopted in the bench roadmap after the first measured
+headless run):
 
-- **Turns-per-plan ≤ ~15** at the epic rung (from the 55–72-turn 12-phase
-  baseline). The turns proxy is the plan-metrics invocation ledger
+- **Epic-mode** (`/plan <id> --yes`): **≤ ~12 turns / ≤ ~1.1M tokens**.
+- **Ideation-mode** (`/plan --idea --yes`): **≤ ~15 turns / ≤ ~1.5M
+  tokens** once the #4496 fixes (seed-mode ideation, authoritative persist
+  summaries, batched artifact writes) are in play; **interim smoke
+  threshold ≤ ~20 turns / ≤ ~2.0M tokens** for runs measured before/during
+  the rollout.
+- Verification is a cheap direct `/plan --idea --yes` probe reading the
+  plan-metrics ledger (~$3–4), not a full bench cell.
+
+Shared mechanics behind both rungs (from the 55–72-turn / 7.3–8.9M
+12-phase baseline):
+
+- The turns proxy is the plan-metrics invocation ledger
   (`temp/epic-<id>/plan-metrics.json`) plus the host session's turn
   accounting — ledger records count CLI invocations from the parent
   session's perspective, not sub-agent turns.
-- **Plan tokens ≤ ~1.5M** at the epic rung (from 7.3–8.9M) — owned by the
-  host's session accounting (mandrel-bench `modelUsage`), not by any
-  in-repo counter.
+- Plan tokens are owned by the host's session accounting (mandrel-bench
+  `modelUsage`), not by any in-repo counter.
 - **Unchanged validator coverage** — every deterministic gate of the
   retired pipeline still fires on the persist path: section gate, ticket
   validator, file-assumption, DAG, budget, draft reachability, inline

package/.agents/workflows/helpers/plan-epic.md

@@ -35,6 +35,9 @@ confirmed (gate #1).
 
 ### Ideation entry (`--idea "<seed>"` or no argument)
 
+**Attended (no `--yes`)** — the interactive grill loop is HITL by
+definition and stays:
+
 1. Activate the [`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md)
    skill with the seed. It returns a one-pager with the canonical sections
    (Problem Statement, Recommended Direction, Key Assumptions, MVP Scope,
@@ -64,6 +67,26 @@ confirmed (gate #1).
    operator either confirms the new Epic is distinct or folds the idea into
    an existing Epic (in which case `/plan` exits).
 
+**Headless (`--yes`) — seed entry (#4496 fix 1).** There is no one to
+grill, so the one-pager prelude is pure ceremony: do **not** activate the
+`idea-refinement` skill and do **not** write a separate one-pager file
+before authoring. Instead, emit the envelope directly off the seed:
+
+```bash
+node .agents/scripts/plan-context.js --seed "<seed text>" \
+  > temp/plan-ideation/<slug>/plan-context.json
+```
+
+(slug from the seed's leading phrase; the tree is gitignored). The seed envelope is the one-pager envelope plus three additive fields:
+`seed` (the raw text), `scopeTriage` (the scope-triage rubric applied
+CLI-side — no skill Reads on this path; a `story` / `borderline` verdict
+resolves to its Recommended handoff per
+[`scope-triage-gate.md`](scope-triage-gate.md)), and `onePagerSpec` (the
+canonical one-pager sections). The one-pager markdown is authored **in
+step 2's single batched write**, alongside the other artifacts — every
+unresolved unknown lands in its Key Assumptions section. `duplicates[]`
+resolves headlessly per gate #1's `--yes` note.
+
 ### Existing-Epic entry (`/plan <epicId>`)
 
 1. Emit the authoring envelope:
@@ -126,25 +149,38 @@ step 2 until the operator explicitly confirms.
 Read the envelope with the `Read` tool and write the planning artifacts to
 `temp/epic-[Epic_ID]/` (ideation: the `temp/plan-ideation/<slug>/` tree).
 The single `plan-context.json` envelope supersedes the per-phase
-`planner-context.json` / `decomposer-context.json` files the authoring
-skills name — read the envelope wherever a skill asks for either.
-
-1. **`techspec.md`** — activate the
-   [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
-   skill. The Tech Spec opens with `## Delivery Slicing` and never restates
-   the Epic's Context/Goal/Scope.
-2. **`risk-verdict.json`** — same skill; the schema-conformant verdict
+`planner-context.json` / `decomposer-context.json` files.
+
+**The envelope's `systemPrompts` ARE the authoring instructions on this
+path** (#4496 fix 4): `systemPrompts.spec` / `systemPrompts.acceptance`
+govern the Tech Spec, risk verdict, and Acceptance Spec;
+`systemPrompts.decompose` (with `ticketSchema` and `maxTickets`) governs
+the tickets. Do **not** read the
+[`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
+or
+[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+SKILL.md files here — they remain the reference source the prompts render
+from, but re-reading them double-pays instructions the envelope already
+carries.
+
+**Batched writes (#4496 fix 3).** Emit the artifact files as **parallel
+`Write` calls in ONE message** — `techspec.md`, `risk-verdict.json`,
+`acceptance-spec.md`, and `tickets.json` together (ideation: the one-pager
+markdown joins the same batch). Never write them one-per-turn.
+
+1. **`techspec.md`** — per `systemPrompts.spec`. The Tech Spec opens with
+   `## Delivery Slicing` and never restates the Epic's Context/Goal/Scope.
+2. **`risk-verdict.json`** — the schema-conformant verdict
    **plus `deliveryShape: "fan-out"|"single"`** and a one-line rationale.
    Seed the shape from the envelope's `deliveryShapeSignal` (advisory —
    the operator vetoes it at gate #2). `"single"` means one-pass-sized or a
    pure dependent chain: the plan ships as spec-only, with **no tickets**.
-3. **`acceptance-spec.md`** — same skill; omit only when the Epic carries
-   the `acceptance::n-a` waiver label.
-4. **`tickets.json`** — fan-out shape only: activate the
-   [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-   skill against the same envelope (its `systemPrompts.decompose`,
-   `ticketSchema`, and `maxTickets` fields). In single-delivery shape author
-   **no** tickets file — the Delivery Slicing table is the plan.
+3. **`acceptance-spec.md`** — per `systemPrompts.acceptance`; omit only
+   when the Epic carries the `acceptance::n-a` waiver label.
+4. **`tickets.json`** — fan-out shape only: author against the same
+   envelope (its `systemPrompts.decompose`, `ticketSchema`, and
+   `maxTickets` fields). In single-delivery shape author **no** tickets
+   file — the Delivery Slicing table is the plan.
 
 > **One-pass refinement contract (amend, don't regenerate).** When a critic
 > flags Stories or the step 3 persist rejects an artifact, apply **targeted
@@ -153,8 +189,12 @@ skills name — read the envelope wherever a skill asks for either.
 
 ### Conditional critics (between authoring and gate #2)
 
-Evaluate the dispatch conditions deterministically first — one git-local
-CLI call, zero GitHub reads:
+The evaluation is folded into `plan-persist.js` as a deterministic
+pre-write phase (#4496 fix 6) — the persist prints both verdicts, returns
+them on its result envelope, and ledger-logs every skip. **Attended runs**
+evaluate the dispatch conditions before gate #2 so the verdicts fold into
+its view — one git-local CLI call, zero GitHub reads, via the thin shim
+(kept one release over the shared evaluator):
 
 ```bash
 node .agents/scripts/plan-critics.js --epic [Epic_ID]
@@ -167,6 +207,14 @@ one-line note. Every skip decision is appended to the plan-metrics ledger
 (`kind: "critic-skip"`, with reasons) so under-firing is auditable — the
 persist validators remain unchanged hard gates either way.
 
+> **`--yes` (headless).** Do **not** run the standalone CLI and do **not**
+> dispatch critic sub-agents: the critics' findings would fold into a gate
+> that auto-proceeds, so a report nobody reviews is pure spend. The
+> persist's folded pre-write evaluation is the audit record — its verdicts
+> print in the persist output, a `dispatch: true` verdict surfaces as a
+> one-line advisory note in the run summary, and every skip still lands on
+> the plan-metrics ledger.
+
 Both critics are **fresh-context sub-agents** (`Agent` tool,
 `subagent_type: general-purpose`) — never inline skill activations, so they
 cannot grade their own homework. Both are report-only: they never write to
@@ -253,6 +301,24 @@ comment carrying the dry-run wave table → temp cleanup **only at terminal
 success**, so a failed run leaves the artifacts in place for `--force` /
 `--resume` reuse.
 
+Two deterministic softenings ride the gate list:
+
+- The file-assumption gate **auto-normalizes** a `refactors-existing`
+  declaration on a base-untracked path to `creates` with a logged warning
+  (#4496 fix 5) — a refactor of a path that does not exist is
+  deterministically a create, so no amend cycle is forced. Genuine
+  mismatches (an absent read dependency, a clobbering `creates`, a missing
+  `deletes` target) still reject.
+- Every auto-waiver the persist derives is printed **with its reason** in
+  the `plan-summary` comment and the result JSON (#4496 fix 2) — e.g. the
+  no-BDD-runner acceptance-disposition waiver.
+
+> **`--yes` (headless): persist outcomes are authoritative.** Read the
+> persist's result JSON and `plan-summary` receipts as the final word — do
+> **not** re-derive a waiver, disposition, or routing decision from
+> framework source. If a summary line seems surprising, its reason is on
+> the line itself; spend zero turns re-verifying it.
+
 ### Persist rejections and soft failures
 
 Each rejection names the artifact and the gap; apply the one-pass amend

package/.agents/workflows/helpers/scope-triage-gate.md

@@ -87,6 +87,15 @@ meanings; it only forces the Recommended resolution where the gate would
 otherwise STOP. See
 [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
 
+**Headless seed entry — the verdict is already in the envelope (#4496).**
+On the `--idea` `--yes` path the rubric is applied **CLI-side** by
+`plan-context.js --seed` and shipped as the envelope's `scopeTriage` field
+(`{ verdict, reasons, advisory: true, appliedBy: "cli" }`), anchored to the
+same sizing SSOT this skill anchors to. Do **not** Read the
+`core/scope-triage` skill headless — use the envelope verdict and resolve it
+per this section. The attended paths keep the skill-based judgment
+unchanged.
+
 ## No-re-triage rule
 
 A **scope-triage handoff** is a triage decision *already made*. When `/plan` is

package/.agents/workflows/plan.md

@@ -88,7 +88,10 @@ exactly **two** HITL STOP gates, and `--yes` deterministically auto-proceeds
    exactly one bounded pass**: no operator questions are asked — facts come
    from the codebase, and every unresolved unknown lands in the one-pager's
    **Key Assumptions** section instead of a question, so a headless driver
-   can never hang inside a free-form interrogation. The verdict / clarity
+   can never hang inside a free-form interrogation. On the `--idea` Epic
+   path this bounded pass IS the seed entry (#4496): `plan-context.js
+   --seed` replaces the idea-refinement prelude, and the one-pager is
+   authored in the same batched write as the spec artifacts. The verdict / clarity
    scoring is still recorded in chat (one line); only the *wait* is
    suppressed — the deterministic clarity *scoring* inside the
    `plan-context.js` envelope always runs.
@@ -126,15 +129,24 @@ advisory critic diffs — auto-proceed for the same headless reason.
 1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
    `--body` must be present; anything else is a usage error naming the four
    forms. A `--body` invocation routes to the story path (no triage).
-2. **Triage (idea path only).** Run the
+2. **Triage (idea path only).** Attended: run the
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
-   seed. Record the verdict in chat (one line).
+   seed. Record the verdict in chat (one line). **Under `--yes`, do not
+   Read the skill**: delegate straight to
+   [`helpers/plan-epic.md`](helpers/plan-epic.md)'s ideation entry — its
+   `plan-context.js --seed` envelope carries the rubric's verdict applied
+   CLI-side (`scopeTriage`), and a `story` / `borderline` verdict resolves
+   to the Recommended handoff from inside the helper (see
+   [`helpers/scope-triage-gate.md`](helpers/scope-triage-gate.md)).
 3. **Delegate.** Read the selected path helper **in full** and execute it
    from its entry, forwarding the absorbed flags (including `--yes`). The
    helper's steps, HITL gates, and scripts are the procedure — this router
    adds no step content. When `--yes` is present, the two HITL STOP gates
    auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
-   above; every deterministic gate still runs.
+   above; every deterministic gate still runs. **Under `--yes`, when the
+   helper content is already injected or present in context, execute it
+   directly — do not spend a separate read-in-full turn re-reading content
+   you already hold.**
 4. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.92.0...mandrel-v1.93.0) (2026-07-12)
+
+
+### Added
+
+* **plan:** close the measured turn gap — seed-mode ideation, authoritative summaries, batched writes (refs [#4496](https://github.com/dsj1984/mandrel/issues/4496)) ([#4497](https://github.com/dsj1984/mandrel/issues/4497)) ([ae98701](https://github.com/dsj1984/mandrel/commit/ae987014d68669eb0032a68000ed328c7a3c702d))
+
 ## [1.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.91.0...mandrel-v1.92.0) (2026-07-12)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.92.0",
+  "version": "1.93.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",