mandrel 2.9.0 → 2.10.0

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

@@ -20,10 +20,23 @@
  *     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). Story #4542 removed
- *     its third condition — the authored risk verdict's overall level — along
- *     with the verdict itself; both surviving conditions read the plan's own
- *     observable text and shape rather than a self-assessment.
+ *     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
+ * 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.
  *
  * Under-firing risk (design PR6 note): the persist validators are
  * unchanged hard gates and G2's cohort re-measures plan quality; every
@@ -107,8 +120,150 @@ export function evaluateConsolidationDispatch({ draftStories, specText }) {
 }
 
 /**
- * Decide the pre-mortem dispatch: size ≥ ½ budget, or a risk-heuristic
- * phrase match.
+ * Explicit npm scoped-package marker: `@scope/name`. Requires the leading `@`
+ * and an interior `/`, so bare GitHub handles (`@dsj1984`) and the
+ * `@[USERNAME]` operator-handle placeholder never match.
+ */
+const SCOPED_PACKAGE_MARKER = /@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*/gi;
+
+/** Explicit cross-repo marker: a `github.com/<owner>/<repo>` URL. */
+const GITHUB_REPO_MARKER =
+  /github\.com\/([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)/gi;
+
+/**
+ * Explicit external-service prerequisite marker: a prerequisite keyword
+ * followed, within the same clause, by an http(s) endpoint. The keyword gate
+ * is what keeps casual documentation links from matching — only an endpoint
+ * named as a precondition counts.
+ */
+const SERVICE_PREREQ_MARKER =
+  /\b(?:requires?|required|prerequisite|provision(?:ed|ing)?|depends?\s+on|credentials?\s+for)\b[^.\n]*?\bhttps?:\/\/([a-z0-9][a-z0-9.-]*)/gi;
+
+/** Order-preserving de-duplication. */
+function uniquePreserveOrder(values) {
+  return [...new Set(values)];
+}
+
+/** Quote each item for an evidence reason string. */
+function quoteList(values) {
+  return values.map((v) => `"${v}"`).join(', ');
+}
+
+/**
+ * Scoped packages named in the plan that no repo manifest declares.
+ *
+ * @param {string} planText
+ * @param {string[]} knownPackages - Package specifiers the repo's own
+ *   manifests declare (own name + dependency maps + workspace package names).
+ * @returns {string[]}
+ */
+function matchExternalScopedPackages(planText, knownPackages) {
+  const known = new Set(
+    knownPackages
+      .filter((n) => typeof n === 'string')
+      .map((n) => n.trim().toLowerCase()),
+  );
+  const matches = [];
+  for (const m of planText.matchAll(SCOPED_PACKAGE_MARKER)) {
+    if (!known.has(m[0].toLowerCase())) matches.push(m[0]);
+  }
+  return uniquePreserveOrder(matches);
+}
+
+/**
+ * `github.com/<owner>/<repo>` references outside the configured repo. When the
+ * owner is unknown (no `github.owner` configured) the arm stays silent rather
+ * than flag every URL as foreign.
+ *
+ * @param {string} planText
+ * @param {{ owner?: string|null, repo?: string|null }|null} ownerRepo
+ * @returns {string[]}
+ */
+function matchCrossRepoRefs(planText, ownerRepo) {
+  const owner =
+    typeof ownerRepo?.owner === 'string'
+      ? ownerRepo.owner.trim().toLowerCase()
+      : '';
+  if (!owner) return [];
+  const repo =
+    typeof ownerRepo?.repo === 'string'
+      ? ownerRepo.repo.trim().toLowerCase()
+      : '';
+  const matches = [];
+  for (const m of planText.matchAll(GITHUB_REPO_MARKER)) {
+    const internal =
+      m[1].toLowerCase() === owner && (!repo || m[2].toLowerCase() === repo);
+    if (!internal) matches.push(`${m[1]}/${m[2]}`);
+  }
+  return uniquePreserveOrder(matches);
+}
+
+/**
+ * Endpoints named as prerequisites in the plan text.
+ *
+ * @param {string} planText
+ * @returns {string[]}
+ */
+function matchExternalServicePrereqs(planText) {
+  const matches = [];
+  for (const m of planText.matchAll(SERVICE_PREREQ_MARKER)) {
+    matches.push(m[1]);
+  }
+  return uniquePreserveOrder(matches);
+}
+
+/**
+ * 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.
+ *
+ * @param {object} input
+ * @param {string} [input.planText] - Concatenated plan text (tech spec +
+ *   serialized tickets).
+ * @param {string[]} [input.knownPackages] - Package specifiers the repo's own
+ *   manifests declare, used to tell an external scoped package from a local one.
+ * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo] -
+ *   The configured `github.owner`/`github.repo` a cross-repo reference is
+ *   measured against.
+ * @returns {{ matched: boolean, reasons: string[] }}
+ */
+export function evaluateExternalDependencyProbe({
+  planText = '',
+  knownPackages = [],
+  ownerRepo = null,
+}) {
+  const text = String(planText);
+  const packages = matchExternalScopedPackages(text, knownPackages);
+  const crossRepo = matchCrossRepoRefs(text, ownerRepo);
+  const services = matchExternalServicePrereqs(text);
+
+  const reasons = [];
+  if (packages.length > 0) {
+    reasons.push(
+      `External-dependency probe: scoped package(s) named in the plan but absent from the repo's own manifests: ${quoteList(packages)}.`,
+    );
+  }
+  if (crossRepo.length > 0) {
+    const scope = ownerRepo.repo
+      ? `${ownerRepo.owner}/${ownerRepo.repo}`
+      : ownerRepo.owner;
+    reasons.push(
+      `External-dependency probe: cross-repo reference(s) outside ${scope}: ${quoteList(crossRepo)}.`,
+    );
+  }
+  if (services.length > 0) {
+    reasons.push(
+      `External-dependency probe: external service prerequisite endpoint(s): ${quoteList(services)}.`,
+    );
+  }
+
+  return { matched: reasons.length > 0, reasons };
+}
+
+/**
+ * Decide the pre-mortem dispatch: size ≥ ½ budget, a risk-heuristic phrase
+ * match, or an external-dependency probe match (Story #4700).
  *
  * @param {object} input
  * @param {number} input.ticketCount - Draft ticket count (0 in the
@@ -117,8 +272,15 @@ export function evaluateConsolidationDispatch({ draftStories, specText }) {
  *   (`getLimits(config).maxTickets`).
  * @param {string[]} [input.riskHeuristics] - `planning.riskHeuristics`
  *   phrases from the resolved config.
- * @param {string} [input.planText] - Concatenated plan text the heuristics
- *   match against (tech spec + serialized tickets).
+ * @param {string} [input.planText] - Concatenated plan text the heuristics and
+ *   the external-dependency probe match 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.
+ * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo] -
+ *   The configured `github.owner`/`github.repo`, passed to the
+ *   external-dependency probe's cross-repo arm.
  * @returns {CriticDispatchDecision}
  */
 export function evaluatePremortemDispatch({
@@ -126,6 +288,8 @@ export function evaluatePremortemDispatch({
   maxTickets,
   riskHeuristics = [],
   planText = '',
+  knownPackages = [],
+  ownerRepo = null,
 }) {
   if (!Number.isInteger(maxTickets) || maxTickets <= 0) {
     throw new TypeError(
@@ -154,6 +318,15 @@ export function evaluatePremortemDispatch({
     );
   }
 
+  const externalDeps = evaluateExternalDependencyProbe({
+    planText,
+    knownPackages,
+    ownerRepo,
+  });
+  if (externalDeps.matched) {
+    reasons.push(...externalDeps.reasons);
+  }
+
   if (reasons.length > 0) {
     return { critic: 'pre-mortem', dispatch: true, reasons };
   }
@@ -162,7 +335,7 @@ export function evaluatePremortemDispatch({
     critic: 'pre-mortem',
     dispatch: false,
     reasons: [
-      `Ticket count ${count} is under half the budget (maxTickets ${maxTickets}) and no planning.riskHeuristics phrase matches the plan text.`,
+      `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.`,
     ],
   };
 }

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

@@ -42,6 +42,20 @@ function resolveRiskHeuristics(config = {}) {
   return [];
 }
 
+/**
+ * Resolve the `{ owner, repo }` the external-dependency probe's cross-repo arm
+ * (Story #4700) measures references against, from the canonical `github` block.
+ *
+ * @param {object} config
+ * @returns {{ owner: string|null, repo: string|null }}
+ */
+function resolveOwnerRepo(config = {}) {
+  return {
+    owner: config.github?.owner ?? null,
+    repo: config.github?.repo ?? null,
+  };
+}
+
 /**
  * Evaluate the consolidation + pre-mortem critic dispatch conditions over
  * the authored planning artifacts (#4474 PR6 conditions, unchanged):
@@ -50,8 +64,12 @@ function resolveRiskHeuristics(config = {}) {
  *     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. Story #4542
- *     retired its authored-risk-level condition with the verdict itself.
+ *     `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
@@ -62,7 +80,13 @@ function resolveRiskHeuristics(config = {}) {
  *   techSpecContent: string,
  *   tickets?: Array<object>|null,
  *   config?: object,
+ *   knownPackages?: string[],
  * }} args
+ * @param {string[]} [args.knownPackages] - Package specifiers the repo's own
+ *   manifests declare, forwarded to the pre-mortem external-dependency probe
+ *   (Story #4700). The caller (the `plan-critics.js` CLI) owns the file I/O
+ *   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[] },
@@ -73,6 +97,7 @@ export function evaluatePlanCritics({
   techSpecContent,
   tickets = null,
   config = {},
+  knownPackages = [],
 }) {
   const ticketList = Array.isArray(tickets) ? tickets : null;
   const consolidation =
@@ -97,6 +122,8 @@ export function evaluatePlanCritics({
       techSpecContent ?? '',
       ticketList ? JSON.stringify(ticketList) : '',
     ].join('\n'),
+    knownPackages,
+    ownerRepo: resolveOwnerRepo(config),
   });
 
   const textHygiene = {

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

@@ -39,16 +39,15 @@
  * Robustness contract (mirrors `lib/observability/signals-writer.js`):
  *   - **Best-effort writes.** A failed append is a missing metric, not a
  *     failed plan phase — fs errors are swallowed after a `Logger.warn`.
- *   - **No buffering.** Each append opens, writes one line, closes.
+ *   - **No buffering / rotation.** The append tail (open → append one line →
+ *     rotate at the byte cap → close) is owned by the shared
+ *     `lib/observability/metrics-ledger.js` module (Story #4712); every
+ *     appender here routes through it. The close-domain findings-yield
+ *     entry point (Story #4699) lives there too, so the story-close review
+ *     spine never imports this plan-domain module.
  *   - **Malformed-line tolerance on read.** The reader skips unparseable
  *     lines (counting them) instead of throwing, so a torn write can never
  *     wedge the analyzer.
- *   - **Rotation.** When an append would push the ledger past
- *     `MAX_LEDGER_BYTES`, the current file is renamed to
- *     `plan-metrics.json.1` (replacing any prior rollover) and the append
- *     starts a fresh ledger, so a long-lived Epic cannot grow the file
- *     unboundedly. Readers only consume the active generation — the
- *     rollover exists for manual archaeology.
  *
  * `plan-metrics.json` is intentionally NOT in
  * `lib/plan-phase-cleanup.js#PHASE_TEMP_BASENAMES`: the ledger must survive
@@ -57,69 +56,17 @@
  */
 
 import fs from 'node:fs/promises';
-import path from 'node:path';
 
-import {
-  anchorTempRoot,
-  runArtifactPath,
-  tempRootFrom,
-} from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
-
-export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
-export const PLAN_METRICS_SCHEMA_VERSION = 1;
+import {
+  appendLedgerRecord,
+  PLAN_METRICS_SCHEMA_VERSION,
+  planMetricsPath,
+} from '../observability/metrics-ledger.js';
 
 /** Record kind for a logged critic skip decision (Epic #4474 PR6). */
 export const PLAN_METRICS_KIND_CRITIC_SKIP = 'critic-skip';
 
-/**
- * Rotation threshold. At ~200 bytes per record this is ~5000 invocations —
- * far beyond any real plan run, so rotation only fires on pathological
- * accumulation.
- */
-export const MAX_LEDGER_BYTES = 1024 * 1024;
-
-/**
- * Resolve the ledger path for an Epic (or the standalone stream when
- * `epicId` is `null` — the `story-plan.js` / Epic-less healthcheck case).
- *
- * @param {number|null} epicId
- * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).
- * @returns {string}
- */
-export function planMetricsPath(epicId, config) {
-  if (epicId === null || epicId === undefined) {
-    return path.join(
-      anchorTempRoot(tempRootFrom(config)),
-      'standalone',
-      PLAN_METRICS_BASENAME,
-    );
-  }
-  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
-}
-
-/**
- * Rotate the ledger when appending `incomingBytes` would exceed
- * `maxBytes`. Single-generation rollover: `plan-metrics.json` →
- * `plan-metrics.json.1` (any prior `.1` is replaced).
- *
- * @param {string} filePath
- * @param {number} incomingBytes
- * @param {number} [maxBytes]
- * @returns {Promise<boolean>} true when a rotation happened.
- */
-async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
-  let size = 0;
-  try {
-    size = (await fs.stat(filePath)).size;
-  } catch {
-    return false; // No existing ledger — nothing to rotate.
-  }
-  if (size + incomingBytes <= maxBytes) return false;
-  await fs.rename(filePath, `${filePath}.1`);
-  return true;
-}
-
 /**
  * Append one invocation record to the ledger. Best-effort: returns `false`
  * (after a `Logger.warn`) instead of throwing on any fs failure, so metric
@@ -165,15 +112,11 @@ export async function appendPlanMetric(entry, config, opts = {}) {
             ) || 0,
       ok: entry.ok === true,
     };
-    const filePath = planMetricsPath(epicId, config);
-    const line = `${JSON.stringify(record)}\n`;
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await rotateIfNeeded(
-      filePath,
-      Buffer.byteLength(line),
-      opts.maxBytes ?? MAX_LEDGER_BYTES,
-    );
-    await fs.appendFile(filePath, line, 'utf8');
+    await appendLedgerRecord(record, {
+      epicId,
+      config,
+      maxBytes: opts.maxBytes,
+    });
     return true;
   } catch (err) {
     Logger.warn(
@@ -198,9 +141,10 @@ export async function appendPlanMetric(entry, config, opts = {}) {
  *   epicId?: number|null,
  * }} entry
  * @param {object} [config]
+ * @param {{ maxBytes?: number }} [opts] Test seam for the rotation threshold.
  * @returns {Promise<boolean>} true when the line was written.
  */
-export async function appendCriticSkip(entry, config) {
+export async function appendCriticSkip(entry, config, opts = {}) {
   try {
     if (!entry || typeof entry !== 'object') {
       throw new TypeError('appendCriticSkip requires an entry object');
@@ -223,11 +167,11 @@ export async function appendCriticSkip(entry, config) {
       epicId,
       at: new Date().toISOString(),
     };
-    const filePath = planMetricsPath(epicId, config);
-    const line = `${JSON.stringify(record)}\n`;
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await rotateIfNeeded(filePath, Buffer.byteLength(line), MAX_LEDGER_BYTES);
-    await fs.appendFile(filePath, line, 'utf8');
+    await appendLedgerRecord(record, {
+      epicId,
+      config,
+      maxBytes: opts.maxBytes,
+    });
     return true;
   } catch (err) {
     Logger.warn(
@@ -348,14 +292,13 @@ export async function readPlanMetrics(epicId, config) {
  */
 /**
  * Timestamp a ledger record is ordered by: `startedAt` for invocation
- * records, `at` for critic-skip records.
+ * records, `at` for kinded records (critic-skip, findings-yield).
  *
  * @param {object} entry
  * @returns {string|null}
  */
 function recordTimestamp(entry) {
-  const stamp =
-    entry?.kind === PLAN_METRICS_KIND_CRITIC_SKIP ? entry.at : entry.startedAt;
+  const stamp = typeof entry?.kind === 'string' ? entry.at : entry?.startedAt;
   return typeof stamp === 'string' ? stamp : null;
 }
 
@@ -390,6 +333,12 @@ export function summarizePlanMetrics(ledger, opts = {}) {
       }
       continue;
     }
+    if (typeof e.kind === 'string') {
+      // Any other kinded record (e.g. `findings-yield`, Story #4699) is not
+      // an invocation — readers key on `kind`, never on absent fields, so it
+      // must not inflate the invocation/failure tallies.
+      continue;
+    }
     invocationEntries.push(e);
     byCli[e.cli] = (byCli[e.cli] ?? 0) + 1;
     if (typeof e.mode === 'string') byMode[e.mode] = (byMode[e.mode] ?? 0) + 1;

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

@@ -44,6 +44,7 @@ import { anchorTempRoot, tempRootFrom } from '../../config/temp-paths.js';
 import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
+import { applyPlannerDowngrade, LITE_ROUTE_LABEL } from '../complexity-gate.js';
 import {
   appendCriticSkip,
   readPlanMetrics,
@@ -261,6 +262,70 @@ async function renderRunScopedPlanMetricsLine({
   }
 }
 
+/**
+ * Resolve the plan's **effective** complexity route for persist
+ * (Story #4707).
+ *
+ * The deterministic verdict rides in on the captured plan-context envelope's
+ * `complexityRoute`. Layered on top is the audited planner downgrade: a
+ * `full` verdict downgrades to `lite` **only** when the operator/planner
+ * passed `--route-downgrade-reason` with a non-empty reason
+ * (`applyPlannerDowngrade` — absent a recorded reason the deterministic
+ * verdict stands, and the gate itself still fails toward `full`).
+ *
+ * The resolved route decides whether the created Stories carry the
+ * {@link LITE_ROUTE_LABEL} marker and a `route` block on their
+ * `story-plan-state` checkpoint — the persisted, ledgered record `/deliver`
+ * reads. A full route persists **no** marker and no checkpoint block:
+ * absence is the conservative default.
+ *
+ * Module-private: reachable end to end through {@link runPlanPersist}
+ * (whose result reports the resolved route), so there is no test-only
+ * export to leave production-dead.
+ *
+ * @param {{ planContextEnvelope?: object|null, routeDowngradeReason?: string|null }} args
+ * @returns {{ route: 'lite'|'full', reasons: string[], downgraded: { from: 'full', reason: string }|null }|null}
+ *   `null` when no envelope carried a verdict (nothing to persist).
+ */
+function resolveEffectiveRoute({
+  planContextEnvelope = null,
+  routeDowngradeReason = null,
+} = {}) {
+  const verdict = planContextEnvelope?.complexityRoute ?? null;
+  if (!verdict || typeof verdict !== 'object') {
+    if (
+      typeof routeDowngradeReason === 'string' &&
+      routeDowngradeReason.trim() !== ''
+    ) {
+      Logger.warn(
+        '[plan-persist] --route-downgrade-reason was passed but no captured ' +
+          'plan-context envelope carries a complexityRoute verdict — there ' +
+          'is no full verdict to downgrade, so the plan persists as full ' +
+          '(no route marker).',
+      );
+    }
+    return null;
+  }
+  const effective = applyPlannerDowngrade(verdict, {
+    reason: routeDowngradeReason,
+  });
+  if (
+    typeof routeDowngradeReason === 'string' &&
+    routeDowngradeReason.trim() !== '' &&
+    effective.downgraded == null
+  ) {
+    Logger.warn(
+      '[plan-persist] --route-downgrade-reason had no effect: the envelope ' +
+        `verdict is already "${verdict.route}" — nothing to downgrade.`,
+    );
+  }
+  return {
+    route: effective.route === 'lite' ? 'lite' : 'full',
+    reasons: Array.isArray(effective.reasons) ? effective.reasons : [],
+    downgraded: effective.downgraded ?? null,
+  };
+}
+
 /**
  * Age after which an abandoned `temp/plan-*` directory is reaped. A plan run
  * that is still being authored is minutes-to-hours old; a week is far past
@@ -328,6 +393,7 @@ export async function reapStalePlanDirs({
  *     stories: Array<object>,
  *     techSpecContent?: string|null,
  *     planAcceptance?: string[]|null,
+ *     planContextEnvelope?: object|null,
  *   },
  *   config?: object,
  *   settings?: object,
@@ -343,6 +409,7 @@ export async function reapStalePlanDirs({
  *     sourceTicketIds?: number[],
  *     sourceTicketOrigin?: 'flag'|'envelope'|'none',
  *     closeSuperseded?: boolean,
+ *     routeDowngradeReason?: string|null,
  *   },
  * }} input
  */
@@ -357,6 +424,7 @@ export async function runPlanPersist({
     stories: rawStories = null,
     techSpecContent = null,
     planAcceptance = null,
+    planContextEnvelope = null,
   } = artifacts ?? {};
   const {
     forceReview = false,
@@ -370,6 +438,7 @@ export async function runPlanPersist({
     sourceTicketIds = [],
     sourceTicketOrigin = 'none',
     closeSuperseded = true,
+    routeDowngradeReason = null,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -444,10 +513,29 @@ export async function runPlanPersist({
     sourceTicketIds,
   });
 
-  const { created } = await createStoryIssues({
+  // Effective complexity route (Story #4707): envelope verdict, plus the
+  // audited planner downgrade when --route-downgrade-reason was recorded.
+  // Lite persists the `route::lite` marker + a checkpoint block; full
+  // persists nothing.
+  const route = resolveEffectiveRoute({
+    planContextEnvelope,
+    routeDowngradeReason,
+  });
+  const isLiteRoute = route?.route === 'lite';
+  if (isLiteRoute) {
+    Logger.info(
+      `[plan-persist] ceremony-lite route: created Stories carry the ` +
+        `${LITE_ROUTE_LABEL} marker` +
+        (route.downgraded
+          ? ` (planner downgrade, recorded reason: ${route.downgraded.reason})`
+          : ' (deterministic gate verdict)'),
+    );
+  }
+
+  const { created, planRunLabel } = await createStoryIssues({
     provider,
     stories,
-    opts: { dryRun },
+    opts: { dryRun, routeLabel: isLiteRoute ? LITE_ROUTE_LABEL : null },
   });
 
   const primary = created[0];
@@ -498,6 +586,10 @@ export async function runPlanPersist({
             id: createdStory.id,
           })),
         },
+        // Ledger the lite route — including any planner downgrade and its
+        // recorded reason — on plan state (Story #4707). A full route writes
+        // no block: absence of the marker is the full path.
+        ...(isLiteRoute ? { route } : {}),
       });
     }
     await upsertStructuredComment(
@@ -551,10 +643,18 @@ export async function runPlanPersist({
   Logger.info(
     `[plan-persist] Deliver with: /deliver ${created.map((s2) => s2.id).join(' ')}`,
   );
+  // Metadata only — a GitHub filter for the cohort this run authored, never
+  // a delivery-resolution input (/deliver stays ids-only, Story #4540).
+  Logger.info(
+    `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
+      `label:${planRunLabel}`,
+  );
 
   return {
     stories: created,
     primaryStoryId: primary.id,
+    planRunLabel,
+    route,
     forceReview,
     reachability,
     freshness,