mandrel 1.92.0 → 1.94.0

package/.agents/scripts/lib/orchestration/lifecycle/emit-slice-lifecycle.js

@@ -0,0 +1,270 @@
+/**
+ * emit-slice-lifecycle.js — Epic #4475 (M4-A).
+ *
+ * Programmatic emitters for the three single-delivery slice lifecycle events
+ * (`slice.start`, `slice.end`, `slice.heartbeat`) — the single-delivery
+ * analogues of the per-Story `story.dispatch.start` / `story.dispatch.end` /
+ * `story.heartbeat` events. They append one schema-validated NDJSON record to
+ * `temp/epic-<id>/lifecycle.ndjson`, mirroring `emit-story-heartbeat.js`.
+ *
+ * A single-delivery run collapses the whole Epic into one long guarded
+ * session walking the `## Delivery Slicing` table on `epic/<id>`. Without a
+ * per-Story heartbeat the `/deliver` idle watchdog cannot tell a live session
+ * from a dead one, so these events give the long session an inspectable
+ * forward-progress signal (`slice.heartbeat`) plus per-slice boundaries
+ * (`slice.start` / `slice.end`) the resume path reads back.
+ *
+ * Introduced INERT in M4-A: the executor that emits these lands in M4-B
+ * (`deliver-epic-single.md`). Shipping the emitters + schemas now keeps that
+ * PR the flip-only change.
+ *
+ * The emit is best-effort at the call site (a failure to append MUST NOT
+ * block the slice transition itself); callers catch and log via the script's
+ * Logger, exactly as the story-heartbeat callers do. These functions still
+ * throw on a programming error (bad argument / schema mismatch) so the bug
+ * surfaces in tests.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { epicLedgerPath } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+const VALID_PHASES = new Set([
+  'init',
+  'implementing',
+  'closing',
+  'blocked',
+  'done',
+]);
+
+const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
+
+/** Lazily-compiled AJV validators, one per event schema. */
+const _validators = new Map();
+
+function getValidator(event) {
+  let validator = _validators.get(event);
+  if (!validator) {
+    const schema = JSON.parse(
+      readFileSync(path.join(SCHEMA_DIR, `${event}.schema.json`), 'utf8'),
+    );
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    validator = ajv.compile(schema);
+    _validators.set(event, validator);
+  }
+  return validator;
+}
+
+function assertEpicId(epicId) {
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new Error('emit-slice-lifecycle: epicId must be a positive integer');
+  }
+}
+
+function assertSliceId(sliceId) {
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new Error('emit-slice-lifecycle: sliceId must be a non-empty string');
+  }
+}
+
+/**
+ * Validate `payload` against `<event>.schema.json`, then append it as a single
+ * NDJSON `emitted` record to the Epic ledger. Shared tail of all three
+ * emitters.
+ *
+ * @param {string} event
+ * @param {object} payload
+ * @param {{ epicId: number, timestamp: string, config?: object, ledgerPath?: string }} ctx
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+function appendSliceEvent(
+  event,
+  payload,
+  { epicId, timestamp, config, ledgerPath: ledgerPathOverride },
+) {
+  const validator = getValidator(event);
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `emit-slice-lifecycle: ${event} payload failed schema validation: ${detail}`,
+    );
+  }
+
+  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = { kind: 'emitted', ts: timestamp, event, payload };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}
+
+/**
+ * Append one `slice.start` record as the executor begins implementing a slice.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId       Stable slice-map key (e.g. `slice-1`).
+ * @param {number} [opts.sliceIndex]  Zero-based position in the Delivery
+ *                                    Slicing table.
+ * @param {string} [opts.title]       Human-readable slice label.
+ * @param {string} [opts.timestamp]   ISO-8601 wall clock. Defaults to now().
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]  Override for tests.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceStart(opts) {
+  const {
+    epicId,
+    sliceId,
+    sliceIndex,
+    title,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+
+  const payload = {
+    event: 'slice.start',
+    epicId,
+    sliceId,
+    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+    ...(typeof title === 'string' ? { title } : {}),
+    timestamp,
+  };
+  return appendSliceEvent('slice.start', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}
+
+/**
+ * Append one `slice.end` record when a slice finishes. A `done` outcome is
+ * what the slice-map checkpoint flips `slices[id].status` to before the walk
+ * advances.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId
+ * @param {'done'|'blocked'|'failed'|'skipped'} opts.outcome
+ * @param {number} [opts.sliceIndex]
+ * @param {number} [opts.durationMs]
+ * @param {string} [opts.timestamp]
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceEnd(opts) {
+  const {
+    epicId,
+    sliceId,
+    outcome,
+    sliceIndex,
+    durationMs,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+  if (!VALID_OUTCOMES.has(outcome)) {
+    throw new Error(
+      `emit-slice-lifecycle: slice.end outcome "${outcome}" must be one of: ${[...VALID_OUTCOMES].join(', ')}`,
+    );
+  }
+
+  const payload = {
+    event: 'slice.end',
+    epicId,
+    sliceId,
+    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+    outcome,
+    ...(Number.isInteger(durationMs) ? { durationMs } : {}),
+    timestamp,
+  };
+  return appendSliceEvent('slice.end', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}
+
+/**
+ * Append one `slice.heartbeat` record from inside a slice's implementation
+ * loop — the forward-progress signal the idle watchdog reads for the single
+ * long session.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId
+ * @param {string} opts.sliceId
+ * @param {string} [opts.phase='implementing']  init|implementing|closing|blocked|done.
+ * @param {string} [opts.timestamp]
+ * @param {string} [opts.operator]  Optional lease-owner handle; included only
+ *                                  when a non-empty string is supplied.
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitSliceHeartbeat(opts) {
+  const {
+    epicId,
+    sliceId,
+    phase = 'implementing',
+    timestamp = new Date().toISOString(),
+    operator,
+    config,
+    ledgerPath,
+  } = opts ?? {};
+  assertEpicId(epicId);
+  assertSliceId(sliceId);
+  if (!VALID_PHASES.has(phase)) {
+    throw new Error(
+      `emit-slice-lifecycle: slice.heartbeat phase "${phase}" must be one of: ${[...VALID_PHASES].join(', ')}`,
+    );
+  }
+  if (
+    operator !== undefined &&
+    (typeof operator !== 'string' || operator.length === 0)
+  ) {
+    throw new Error(
+      'emit-slice-lifecycle: operator, when supplied, must be a non-empty string',
+    );
+  }
+
+  const payload = {
+    event: 'slice.heartbeat',
+    epicId,
+    sliceId,
+    phase,
+    timestamp,
+    ...(operator !== undefined ? { operator } : {}),
+  };
+  return appendSliceEvent('slice.heartbeat', payload, {
+    epicId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}

package/.agents/scripts/lib/orchestration/lifecycle/listeners/acceptance-reconciler.js

@@ -34,6 +34,47 @@
  */
 
 import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../../../../acceptance-spec-reconciler.js';
+import { DELIVERY_SINGLE_LABEL } from '../../deliver-route.js';
+import { read as readEpicRunState } from '../../epic-run-state-store.js';
+
+/**
+ * Default single-delivery resolver (Epic #4475, M4-B, design §2c). Decides
+ * whether the Epic under reconciliation is the single-delivery shape — the
+ * signal that flips a `waived` reconcile into a hard failure (the back gate
+ * of the non-waivable epic-level acceptance contract). Two sources, primary
+ * first:
+ *
+ *   1. `epic-run-state.deliveryShape === 'single'` — the durable checkpoint
+ *      the single-delivery prepare writes.
+ *   2. The `delivery::single` label on the Epic ticket — the plan-time marker.
+ *
+ * Best-effort + fail-open-to-fan-out: any probe failure (null provider in a
+ * unit fixture, a GitHub read error) degrades to `false` (treat as fan-out),
+ * so the defence-in-depth back gate never *invents* a block — the front gate
+ * (prepare refusing `acceptance::n-a`) is the primary guard. Tests inject
+ * `resolveSingleFn` directly to bypass the probes.
+ *
+ * @param {{ provider?: object|null, epicId: number, config?: object|null }} args
+ * @returns {Promise<boolean>}
+ */
+export async function defaultResolveSingle({ provider, epicId }) {
+  if (!provider) return false;
+  try {
+    const checkpoint = await readEpicRunState({ provider, epicId });
+    if (checkpoint?.deliveryShape === 'single') return true;
+  } catch {
+    // Fall through to the label probe.
+  }
+  try {
+    const epic = await provider.getTicket(epicId);
+    const labels = Array.isArray(epic?.labels) ? epic.labels : [];
+    return labels.some(
+      (l) => (typeof l === 'string' ? l : l?.name) === DELIVERY_SINGLE_LABEL,
+    );
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Classify a `reconcileAcceptanceSpec` result envelope into the typed
@@ -49,6 +90,16 @@ import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../..
  *                       `.waived` and route waived Epics through to PR
  *                       creation, while empty-spec Epics still
  *                       terminate without a PR via `.skipped`.
+ *                       **Non-waivable under single delivery (Epic #4475,
+ *                       M4-B, design §2c):** when `opts.single` is true the
+ *                       epic-level reconcile is the ONLY acceptance gate
+ *                       left, so a `waived` status is treated as a hard
+ *                       `failed` (reason `single-delivery-non-waivable`)
+ *                       instead of passing through — the back gate that
+ *                       forecloses the cohort's dilution (waived reconcile
+ *                       as the sole gate). The front gate (prepare refusing
+ *                       `acceptance::n-a`) already blocks this at seed time;
+ *                       this is defence in depth.
  *   - `'empty-spec'` → the linked spec exists but declares zero AC IDs.
  *                       Treated as "no work to do"; emit `.skipped` with
  *                       reason `'empty-spec'` so operators see the
@@ -61,14 +112,23 @@ import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../..
  *                       the Epic ticket.
  *
  * @param {object|undefined|null} result reconciler envelope.
+ * @param {{ single?: boolean }} [opts] `single: true` flips a `waived` status
+ *   into a hard `failed` (the non-waivable epic reconcile back gate).
  * @returns {{ outcome: 'ok'|'waived'|'skipped'|'failed', reason?: string }}
  */
-export function classifyReconcileResult(result) {
+export function classifyReconcileResult(result, opts = {}) {
+  const single = opts?.single === true;
   if (!result || typeof result !== 'object') {
     return { outcome: 'failed', reason: 'reconciler-no-result' };
   }
   const status = result.status;
   if (status === 'waived') {
+    if (single) {
+      return {
+        outcome: 'failed',
+        reason: 'single-delivery-non-waivable',
+      };
+    }
     return { outcome: 'waived', reason: 'waiver' };
   }
   if (status === 'empty-spec') {
@@ -112,6 +172,9 @@ export class AcceptanceReconciler {
    *   injected for the same reason.
    * @param {Function} [opts.reconcileAcceptanceSpecFn] Override of the
    *   helper for tests; defaults to the production export.
+   * @param {Function} [opts.resolveSingleFn] Override of the single-delivery
+   *   resolver for tests (Epic #4475, M4-B); defaults to `defaultResolveSingle`
+   *   (checkpoint `deliveryShape` → `delivery::single` label).
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -134,6 +197,7 @@ export class AcceptanceReconciler {
     this.config = opts.config ?? null;
     this.reconcileAcceptanceSpecFn =
       opts.reconcileAcceptanceSpecFn ?? defaultReconcileAcceptanceSpec;
+    this.resolveSingleFn = opts.resolveSingleFn ?? defaultResolveSingle;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` keys we've handled. */
     this._seen = new Set();
@@ -256,7 +320,24 @@ export class AcceptanceReconciler {
       return;
     }
 
-    const classification = classifyReconcileResult(result);
+    // Resolve the delivery shape before classifying: under single delivery a
+    // `waived` reconcile is non-waivable (design §2c). Best-effort — a probe
+    // failure degrades to `false` (fan-out pass-through), never inventing a
+    // block.
+    let single = false;
+    try {
+      single = await this.resolveSingleFn({
+        provider: this.provider,
+        epicId,
+        config: this.config,
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AcceptanceReconciler] single-delivery probe failed (treating as fan-out): ${err?.message ?? err}`,
+      );
+    }
+
+    const classification = classifyReconcileResult(result, { single });
     if (classification.outcome === 'ok') {
       await this._emitOk({ event, seqId, baseRead });
       return;

package/.agents/scripts/lib/orchestration/lifecycle/listeners/checkpoint-pointer-writer.js

@@ -81,6 +81,12 @@ export const SUBSCRIBED_END_EVENTS = Object.freeze([
   'epic.snapshot.end',
   'epic.watch.end',
   'retro.end',
+  // Epic #4475 (M4-A) — single-delivery slice boundary. A completed slice is
+  // a resume checkpoint for the one long guarded session (the analogue of
+  // story.dispatch.end for fan-out). Subscribed now so the pointer updates
+  // once the M4-B executor emits slice.end through the bus; inert until then
+  // (nothing emits it in M4-A).
+  'slice.end',
   'story.dispatch.end',
 ]);
 

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-critic-conditions.js

@@ -28,8 +28,9 @@
  * 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.
+ * Pure, synchronous, no I/O — the folded pre-write phase inside
+ * `plan-persist.js` owns reading the authored artifacts and the resolved
+ * config.
  */
 
 import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';