mandrel 2.9.0 → 2.11.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -30,11 +30,89 @@ import {
   normalizeSupersedes,
 } from './supersede-ops.js';
 
-// Story #4540 removed PLAN_RUN_LABEL_PREFIX / normalizePlanRunId /
-// planRunLabel from here. They minted an opaque random-hex label per N>1
-// plan that nothing ever deleted, and their only external consumer was the
-// (now deleted) `--run` resolver. Sibling order survives in the
-// `blocked by #N` body footers this module already writes.
+/**
+ * Label prefix grouping the Stories one plan-persist run authored.
+ *
+ * Reintroduced (Story #4692) after Story #4540 retired it: #4540 was right
+ * that batch identity is the wrong axis for *ordering delivery across runs*
+ * (`/deliver` takes ids and resolves the graph from live state — that stays),
+ * but it is the correct axis for *grouping the Stories one plan run created*
+ * so a cohort is filterable and traceable in the GitHub UI. The label is
+ * metadata only; nothing in persist or delivery reads it as a
+ * delivery-resolution input.
+ */
+export const PLAN_RUN_LABEL_PREFIX = 'plan-run::';
+
+/** Stable color for the cohort grouping label (`ensureLabels`). */
+const PLAN_RUN_LABEL_COLOR = '#C5DEF5';
+
+/**
+ * Stable color for the `route::lite` ceremony-route hint (Story #4707;
+ * hint-only since Story #4722 — `/deliver` re-derives the route from the
+ * Story body's shape).
+ */
+const LITE_ROUTE_LABEL_COLOR = '#D4C5F9';
+
+/** Length of the derived plan-run id (hex chars). */
+const PLAN_RUN_ID_LENGTH = 8;
+
+/**
+ * Normalize a caller-supplied plan-run token. Kept shared so human-readable
+ * ids map to one canonical label shape.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizePlanRunId(id) {
+  const token = String(id ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^plan-run::/, '')
+    .replace(/[^a-z0-9._-]+/g, '-');
+  if (!token) {
+    throw new Error('plan-run id requires a non-empty planRunId');
+  }
+  return token;
+}
+
+/**
+ * Build a `plan-run::<id>` label from an explicit id.
+ *
+ * Unlike the pre-#4540 shape, this never mints a random token — a random id
+ * would split a resumed persist's cohort across two labels. Derive the id
+ * from the authored artifacts via {@link derivePlanRunId} instead.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function planRunLabel(id) {
+  return `${PLAN_RUN_LABEL_PREFIX}${normalizePlanRunId(id)}`;
+}
+
+/**
+ * Derive the deterministic plan-run id for a cohort of assembled Stories.
+ *
+ * Hashes the **sorted** set of per-Story plan fingerprints (the same
+ * content identities the resumable-create contract adopts on), so the id is
+ * a pure function of the authored artifacts: the same `stories.json` yields
+ * the same `plan-run::<id>` on every run — a persist resumed after a
+ * mid-run failure applies the identical label to the newly-created
+ * remainder that the already-created (adopted) Stories carry — while a
+ * different plan derives a different label. Sorting makes the id
+ * independent of creation order.
+ *
+ * @param {string[]} fingerprints Per-Story plan fingerprints.
+ * @returns {string} Hex id, {@link PLAN_RUN_ID_LENGTH} chars.
+ */
+export function derivePlanRunId(fingerprints) {
+  const sorted = (Array.isArray(fingerprints) ? fingerprints : [])
+    .map(String)
+    .sort();
+  return createHash('sha256')
+    .update(sorted.join(' '))
+    .digest('hex')
+    .slice(0, PLAN_RUN_ID_LENGTH);
+}
 
 /**
  * Marker prefix for the per-Story plan fingerprint appended to every
@@ -113,13 +191,19 @@ function planFingerprintMarker(fingerprint) {
 /**
  * Labels the authoring pass is never allowed to set. The `agent::*` axis is
  * the runtime's lifecycle state (persist owns the terminal `agent::ready`
- * flip itself), `type::*` is fixed to `type::story` by the v2 hierarchy, and
- * `persona::*` is a retired axis.
+ * flip itself), `type::*` is fixed to `type::story` by the v2 hierarchy,
+ * `persona::*` is a retired axis, `plan-run::*` is the runtime-derived
+ * cohort grouping axis (Story #4692), and `route::*` is the runtime-derived
+ * ceremony-route axis (Story #4707) — a hand-authored entry on either
+ * derived axis would compete with the deterministic label persist applies
+ * itself.
  */
 const FORBIDDEN_LABEL_PREFIXES = Object.freeze([
   'agent::',
   'type::',
   'persona::',
+  PLAN_RUN_LABEL_PREFIX,
+  'route::',
 ]);
 
 /** GitHub's own label-name ceiling. */
@@ -607,6 +691,64 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
   }
 }
 
+/**
+ * Ensure a runtime-derived persist label (`plan-run::<id>` cohort grouping,
+ * `route::lite` route marker) exists before it is applied — GitHub's
+ * create-issue path does not auto-create unknown labels on every provider
+ * route, and an opaque derived label never exists yet.
+ *
+ * **Non-fatal by design**, matching the native-blocked_by mirroring posture:
+ * neither label is load-bearing for correctness (grouping is cosmetic, and
+ * the route label is a human-visible hint only — `/deliver` re-derives the
+ * route from the Story body's shape, Story #4722), so it is never a reason
+ * to fail persist. On an ensure
+ * failure (throw, or the label reported `missing` by the post-loop
+ * reconcile) the create loop proceeds **without** the label — applying an
+ * unensured label could fail the issue create itself, and the Stories matter
+ * more than their metadata. A provider that exposes no `ensureLabels` (test
+ * fakes, minimal providers) is assumed to accept arbitrary labels on create.
+ *
+ * @param {object} args
+ * @param {object} args.provider
+ * @param {string} args.label
+ * @param {string} args.color
+ * @param {string} args.description
+ * @param {string} args.role Human-readable role for the degrade warning.
+ * @returns {Promise<boolean>} Whether the create loop should apply the label.
+ */
+async function ensurePersistLabel({
+  provider,
+  label,
+  color,
+  description,
+  role,
+}) {
+  if (typeof provider?.ensureLabels !== 'function') {
+    return true;
+  }
+  try {
+    const result = await provider.ensureLabels([
+      { name: label, color, description },
+    ]);
+    if (Array.isArray(result?.missing) && result.missing.includes(label)) {
+      Logger.warn(
+        `[plan-persist] ${role} label "${label}" could not be verified ` +
+          'on the remote — creating the Stories without it. Add the label ' +
+          'by hand if you want it.',
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] ${role} label ensure failed (${err.message}) — ` +
+        'creating the Stories without it. Add the label by hand if you ' +
+        'want it.',
+    );
+    return false;
+  }
+}
+
 /**
  * Create Story issues via `provider.createIssue`, resumably.
  *
@@ -631,24 +773,43 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
  * is named in a warning. Adoption never rewrites a body, so keying it on
  * anything weaker than content would silently ship a stale one.
  *
- * Story #4540 retired the `plan-run::<id>` label this used to apply when
- * N>1. Batch identity was the wrong axis to encode: it could not express an
- * edge to a Story planned in a different run, and ordering already lives in
- * the `blocked by #N` footers written below — which `/deliver`'s resolver
- * reads directly, alongside native GitHub edges, from live state.
+ * **Every created Story carries the cohort's `plan-run::<id>` grouping
+ * label** (Story #4692, metadata only). The id is deterministic over the
+ * authored artifacts ({@link derivePlanRunId}), so a resumed persist derives
+ * the identical label its adopted Stories already carry from their original
+ * create — no relabel call is needed on the resume path, and the cohort is
+ * never split across two labels. The label is ensured to exist before the
+ * first POST, **non-fatally**: grouping is cosmetic and never fails the run
+ * (see `ensureCohortLabel`). `/deliver` never reads it — delivery stays
+ * ids-only over live state (Story #4540's actual point).
  *
  * **Sibling order is mirrored into native GitHub `blocked_by` edges** once
  * every id is known (Story #4544), so plan-created order stops depending on
  * prose. That pass is non-fatal — see `mirrorNativeDependencyEdges`.
  *
+ * **A lite-routed cohort carries the `route::lite` hint** (Story #4707,
+ * hint-only since Story #4722). When the caller resolves the plan's
+ * effective complexity route to `lite` (the planner's recorded verdict,
+ * upheld by the shape backstop), it passes the label via `opts.routeLabel`
+ * and every created Story carries it — a **human-visible hint only**, never
+ * the control signal: `/deliver` re-derives the route from each Story body's
+ * own shape (`resolveStoryDispatchMode`), so a lost or failed label write
+ * cannot misroute delivery. A full-routed plan passes nothing and its
+ * Stories carry **no** route label. Like the cohort label, the ensure is
+ * non-fatal — the label is cosmetic either way.
+ *
  * @param {object} args
  * @param {object} args.provider
  * @param {ReturnType<typeof assemblePlanStories>['stories']} args.stories
  * @param {object} [args.opts]
  * @param {boolean} [args.opts.dryRun=false]
+ * @param {string|null} [args.opts.routeLabel=null] Route marker label to
+ *   apply to every created Story (`route::lite`), or null for none.
  * @returns {Promise<{
  *   created: Array<{ slug: string, id: number, url?: string, title: string, adopted: boolean }>,
  *   dependencyEdges: { edgesAdded: number, edgesSkipped: number, edgesFailed: number, storiesProcessed: number }|null,
+ *   planRunLabel: string,
+ *   routeLabel: string|null,
  * }>}
  */
 export async function createStoryIssues({ provider, stories, opts = {} }) {
@@ -659,6 +820,17 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
   }
 
   const list = Array.isArray(stories) ? stories : [];
+  const routeLabel =
+    typeof opts.routeLabel === 'string' && opts.routeLabel.trim() !== ''
+      ? opts.routeLabel.trim()
+      : null;
+
+  // Derived once for the whole cohort, before any write — a pure function of
+  // the authored artifacts, so dry-run can report it write-free and a resume
+  // re-derives the identical label.
+  const cohortLabel = planRunLabel(
+    derivePlanRunId(list.map((story) => story.fingerprint)),
+  );
 
   if (opts.dryRun) {
     return {
@@ -670,9 +842,32 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
         adopted: false,
       })),
       dependencyEdges: null,
+      planRunLabel: cohortLabel,
+      routeLabel,
     };
   }
 
+  const applyCohortLabel = await ensurePersistLabel({
+    provider,
+    label: cohortLabel,
+    color: PLAN_RUN_LABEL_COLOR,
+    description:
+      'Groups the Stories one /plan persist run authored (metadata ' +
+      'only — /deliver stays ids-only).',
+    role: 'cohort',
+  });
+  const applyRouteLabel =
+    routeLabel !== null &&
+    (await ensurePersistLabel({
+      provider,
+      label: routeLabel,
+      color: LITE_ROUTE_LABEL_COLOR,
+      description:
+        'Ceremony-lite hint (human-visible only): /deliver re-derives the ' +
+        'route from the Story body shape; every close gate runs unchanged.',
+      role: 'route-marker',
+    }));
+
   const { byFingerprint, idsByTitle } = await indexExistingStories(provider);
   const created = [];
   const idBySlug = new Map();
@@ -681,6 +876,9 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     const already = byFingerprint.get(story.fingerprint);
     if (!already) warnOnDivergentSameTitleStory(story, idsByTitle);
     if (already) {
+      // Adopted Stories already carry the cohort label from their original
+      // create — the deterministic derivation guarantees it is the same
+      // label this run derived, so no relabel call is needed here.
       Logger.info(
         `[plan-persist] resuming: Story "${story.slug}" already exists as ` +
           `#${already.id} with byte-identical authored content ` +
@@ -700,7 +898,11 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     const result = await provider.createIssue({
       title: story.title,
       body: renderStoryBodyForCreate(story, idBySlug),
-      labels: [...story.labels],
+      labels: [
+        ...story.labels,
+        ...(applyCohortLabel ? [cohortLabel] : []),
+        ...(applyRouteLabel ? [routeLabel] : []),
+      ],
     });
     const id = result?.id ?? result?.number;
     if (!Number.isInteger(id)) {
@@ -727,7 +929,12 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     idBySlug,
   });
 
-  return { created, dependencyEdges };
+  return {
+    created,
+    dependencyEdges,
+    planRunLabel: cohortLabel,
+    routeLabel: applyRouteLabel ? routeLabel : null,
+  };
 }
 
 /**

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -34,6 +34,7 @@ import {
   extractChangePaths,
   parse as parseStoryBody,
 } from '../story-body/story-body.js';
+import { resolveStoryDispatchMode } from './complexity-gate.js';
 
 /** Labels/state that mean a blocker no longer gates its dependents. */
 const DONE_LABEL = 'agent::done';
@@ -306,17 +307,27 @@ export function buildStoriesEnvelope({
   nativeEdges = new Map(),
   foreignDone = [],
   warn,
+  config,
 }) {
   const sorted = [...stories].sort((a, b) => a.id - b.id);
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
   return {
     kind: 'stories',
-    stories: sorted.map(({ id, title, url, labels, state }) => ({
+    // `dispatchMode` (Story #4722): the resolver derives the per-Story
+    // execution mode from the fetched Story BODY's own shape (the shared
+    // shape function in `complexity-gate.js`) so `/deliver` reads one field —
+    // `inline` (lite-shaped: no story-worker / acceptance-critic sub-agent
+    // boots) or `subagent` (everything else, the conservative default). The
+    // `route::lite` label is a human-visible hint only, never the control
+    // signal: a lost label cannot misroute delivery. Model-side fan-out
+    // only; close gates are untouched.
+    stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,
       url,
       labels,
       state,
+      dispatchMode: resolveStoryDispatchMode({ body, labels, config }).mode,
     })),
     dag: storiesToDag(sorted, nativeEdges, warn),
     done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),

package/.agents/scripts/lib/orchestration/review-depth.js

@@ -74,10 +74,15 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
  * changed-file set intersect any sensitive-path class registered in
  * `audit-rules.json`?
  *
- * This is the **single source** of the derived level — both the review depth
- * ({@link resolveDepth}) and the acceptance-critic fresh-vs-inline routing
- * (`ceremony-routing.js#resolveCeremonyForRisk`) consume what this returns, so
- * the two ceremony decisions can never disagree about how risky a change is.
+ * This is the **single source** of the derived level — the review depth
+ * ({@link resolveDepth}), the acceptance-critic fresh-vs-inline routing
+ * (`ceremony-routing.js#resolveCeremonyForRisk`), and the dispatch-side
+ * complexity routing (`complexity-gate.js#deriveStoryShape`, Story #4722)
+ * all consume what this returns, so no ceremony decision can disagree about
+ * how risky a change is. Dispatch reads the **predicted** shape (the Story's
+ * declared `changes[]` footprint) and close reads the **actual** diff — one
+ * taxonomy, two read points, which is what keeps a lite-shaped Story whose
+ * footprint touches a sensitive path on the full route with its fresh critic.
  *
  * Returns `null` — the fail-safe "no derivable signal" level — when the change
  * set is empty/unknown or the manifest cannot be read. Both downstream

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -48,6 +48,10 @@ import {
   calculateReport,
   classifyReport,
 } from '../../maintainability-engine.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../observability/runtime-friction.js';
 import { PROJECT_ROOT } from '../../project-root.js';
 import { transpileIfNeeded } from '../../transpile.js';
 
@@ -456,8 +460,10 @@ export async function analyzeChangedFiles(
  * Pure: turn a lint summary into Finding(s). Lint errors collapse into a
  * single high-risk finding (the structured comment shows the count); lint
  * warnings collapse into a single suggestion. An `executionFailed` summary
- * produces one suggestion finding describing the runner failure rather than
- * a high-risk false positive.
+ * produces **zero** findings (Story #4699): a runner that could not execute
+ * is an operational degradation, not a code finding — the provider routes it
+ * to friction telemetry instead so severity counts reflect code findings
+ * only.
  *
  * @param {{ errors: number, warnings: number, parsed?: boolean, skipped?: boolean, mode?: string, executionFailed?: boolean, evidenceSkipped?: boolean }} lintSummary
  * @returns {Finding[]}
@@ -466,20 +472,7 @@ export function buildLintFindings(lintSummary) {
   if (lintSummary.mode === 'off') return [];
   if (lintSummary.evidenceSkipped) return [];
   if (lintSummary.skipped) return [];
-  if (lintSummary.executionFailed) {
-    return [
-      {
-        severity: 'suggestion',
-        title: 'Lint runner could not execute',
-        body:
-          'The scoped lint runner produced no parseable output (binary missing, ' +
-          'parse failure, or environment issue). Verify with the canonical ' +
-          '`npm run lint` before merging — treating as a suggestion to avoid a ' +
-          'false high-risk signal.',
-        category: 'lint',
-      },
-    ];
-  }
+  if (lintSummary.executionFailed) return [];
   const findings = [];
   if (lintSummary.errors > 0) {
     findings.push({
@@ -550,6 +543,7 @@ async function runLintPhase({
  *   runScopedLintFn?: typeof runScopedLint,
  *   analyzeChangedFilesFn?: typeof analyzeChangedFiles,
  *   buildLintFindingsFn?: typeof buildLintFindings,
+ *   emitToolDegradationFn?: typeof emitRuntimeFriction,
  *   logger?: { info?: Function, warn?: Function, error?: Function },
  *   scopeLint?: 'changed-only'|'off',
  * }} [deps]
@@ -561,6 +555,7 @@ export function createNativeProvider(deps = {}) {
     runScopedLintFn = runScopedLint,
     analyzeChangedFilesFn = analyzeChangedFiles,
     buildLintFindingsFn = buildLintFindings,
+    emitToolDegradationFn = emitRuntimeFriction,
     logger,
     scopeLint = 'changed-only',
   } = deps;
@@ -624,6 +619,29 @@ export function createNativeProvider(deps = {}) {
         logger,
       });
 
+      if (lintSummary.executionFailed) {
+        // Story #4699 — a tool that could not execute is an operational
+        // degradation, not a code finding. Route it to friction telemetry
+        // (best-effort) so severity counts reflect code findings only.
+        logger?.warn?.(
+          '[native-review] Lint runner could not execute — recorded as friction telemetry, no finding emitted. Verify with the canonical `npm run lint` before merging.',
+        );
+        try {
+          await emitToolDegradationFn({
+            storyId: ticketId,
+            category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
+            tool: 'native-review-lint',
+            details: {
+              surface: 'scoped-lint',
+              reason:
+                'lint runner produced no parseable output (binary missing, parse failure, or environment issue)',
+            },
+          });
+        } catch {
+          // Observability must never fail the review (best-effort contract).
+        }
+      }
+
       const lintFindings = buildLintFindingsFn(lintSummary);
 
       // Canonical ordering: critical (maintainability) first, then high

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js

@@ -80,6 +80,7 @@ async function invokeStoryReviewCore({
   provider,
   runCodeReviewFn,
   runLocalLensReviewFn,
+  appendFindingsYieldFn,
   progress,
 }) {
   return runStoryReviewCore({
@@ -91,10 +92,11 @@ async function invokeStoryReviewCore({
     progress,
     progressTag: 'REVIEW',
     runCodeReviewFn,
-    // Forward the seam only when the caller injects it; otherwise
-    // `runStoryReviewCore` uses its default local-lens pass. `undefined`
-    // deep-merges to the default via the destructuring default there.
+    // Forward the seams only when the caller injects them; otherwise
+    // `runStoryReviewCore` uses its defaults. `undefined` deep-merges to
+    // the default via the destructuring default there.
     ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
+    ...(appendFindingsYieldFn ? { appendFindingsYieldFn } : {}),
   });
 }
 
@@ -163,6 +165,7 @@ async function postStoryReviewCrossRef({
  *   provider: object,
  *   runCodeReviewFn: Function,
  *   runLocalLensReviewFn?: Function,
+ *   appendFindingsYieldFn?: Function,
  *   progress: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -185,6 +188,7 @@ export async function runStoryScopeReview({
   provider,
   runCodeReviewFn,
   runLocalLensReviewFn,
+  appendFindingsYieldFn,
   progress,
 }) {
   if (prNumber == null) {
@@ -208,6 +212,7 @@ export async function runStoryScopeReview({
     provider,
     runCodeReviewFn,
     runLocalLensReviewFn,
+    appendFindingsYieldFn,
     progress,
   });