mandrel 1.92.0 → 1.94.0

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/single-story-close/phases/close-validation.js

@@ -129,6 +129,7 @@ export async function runCloseValidationPhase({
       config,
       epicBranch: baseBranch,
       cwd: worktreePath || cwd,
+      log: (m) => Logger.info(m),
     }),
     log: (m) => Logger.info(m),
     storyId,

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -140,6 +140,7 @@ export async function runPreMergeGates({
     config,
     epicBranch,
     cwd: worktreePath || cwd,
+    log: (m) => logger.info?.(m),
   });
   const gateCount = Array.isArray(gates) ? gates.length : 0;
   // Story #2250 — emit `close-validate.start` only when both an epicId

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

@@ -272,7 +272,7 @@ export function validateAcFreshness({
  * Epic #2501 introduced this guard after the legacy `baseline-refresh`
  * leading-token prescription created a wave of commit-msg hook failures
  * across story-deliver sub-agents. See
- * `.agents/skills/core/baseline-refresh/SKILL.md` for the canonical refresh
+ * `.agents/skills/core/gates-and-baselines/SKILL.md` for the canonical refresh
  * shape (Conventional-Commits subject + `baseline-refresh: true` body
  * trailer).
  */
@@ -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/lib/provider-factory.js

@@ -4,7 +4,7 @@
  * Accepts the canonical resolved config object (the wrapper returned by
  * `resolveConfig()` with `config.github` populated). The legacy
  * `orchestration`-shaped argument is no longer supported as part of the
- * Epic #2880 hard cutover; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ * Epic #2880 hard cutover; see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`.
  *
  * @see docs/v5-implementation-plan.md Sprint 1B
  */

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -88,7 +88,7 @@ Your job is to take an Epic (including its inline User Stories) and a Technical
 
 ### LABEL CONVENTIONS:
 - Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
-- Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
+- Every ticket must have a \`persona::[engineer|architect|qa-engineer|security-engineer|etc]\` label indicating WHO should execute it.
 
 ### OUTPUT FORMAT:
 You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.

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/post-structured-comment.js

@@ -22,6 +22,10 @@ import fs from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
+import {
+  outboxPathFor,
+  postCommentOrBuffer,
+} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   assertValidStructuredCommentType,
   upsertStructuredComment,
@@ -37,6 +41,11 @@ Flags:
                  retro, epic-run-state, wave-0-start) (required).
   --body-file    Path to a file containing the markdown body (required).
   --provider     Provider name (default: inferred from .agentrc.json github block).
+  --buffer       Headless mode: buffer this upsert to the per-Epic bookkeeping
+                 outbox instead of posting live. Requires --epic. Drained to
+                 GitHub once at finalize by bookkeeping-reconcile.js (Epic
+                 #4476). Omit for attended runs (posts live, unchanged).
+  --epic <id>    Epic id owning the outbox (required with --buffer).
   --help         Show this message.
 `;
 
@@ -64,6 +73,8 @@ export function parseArgv(argv) {
       marker: { type: 'string' },
       'body-file': { type: 'string' },
       provider: { type: 'string' },
+      buffer: { type: 'boolean' },
+      epic: { type: 'string' },
       help: { type: 'boolean' },
     },
     strict: false,
@@ -115,6 +126,33 @@ export async function main(argv = process.argv.slice(2)) {
     : config;
   const provider = createProvider(effectiveConfig);
 
+  // Headless buffering (Epic #4476 M5): route the upsert to the per-Epic
+  // outbox instead of a live GitHub round-trip. Requires --epic to locate the
+  // outbox; finalize's bookkeeping-reconcile.js drains it once. Attended runs
+  // (no --buffer) are unchanged.
+  if (values.buffer) {
+    const epicId = Number.parseInt(values.epic ?? '', 10);
+    if (!Number.isInteger(epicId) || epicId <= 0) {
+      process.stderr.write(
+        '[post-structured-comment] --buffer requires --epic <id>.\n',
+      );
+      process.exit(2);
+    }
+    assertValidStructuredCommentType(values.marker);
+    const { buffered } = await postCommentOrBuffer({
+      provider,
+      ticketId,
+      marker: values.marker,
+      body,
+      headless: true,
+      outboxPath: outboxPathFor(epicId, config),
+    });
+    process.stdout.write(
+      `${JSON.stringify({ success: true, ticketId, type: values.marker, buffered })}\n`,
+    );
+    return;
+  }
+
   const envelope = await runPostStructuredComment({
     ticketId,
     type: values.marker,