mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/run-scoped-config.js

@@ -1,49 +1,15 @@
 /**
- * run-scoped-config.js — pin the config values a delivery run was seeded
- * from, and fail closed when the file they came from changed underneath it.
- *
- * The problem this exists for: `single-story-init.js` resolves config and
- * seeds `story-<id>` from `project.baseBranch`; `single-story-close` used to
- * re-resolve the SAME key and run close-validation, format-autofix, the gate
- * baseline and base-sync against its own second answer. Nothing pinned the
- * first value and nothing checked the two agreed — and the window between
- * them is however long implementation takes. A concurrent session editing
- * `.agentrc.json` / `.agentrc.local.json` mid-run therefore base-synced a
- * Story against a base it was never seeded from, which surfaced only as an
- * ordinary content conflict with nothing pointing at config.
- *
- * The base a Story was seeded from is a property of **that run**, not of
- * whatever the config file says later. So init pins it and close reads the
- * pin back.
- *
- * ## Where the pin lives
- *
- * The `story-init` structured comment, not a temp log: the post-land tail
- * purges the temp tree, while the ticket comment survives every close re-run
- * and every recovery path. `single-story-init.js` already upserts that
- * comment; `pinRunScopedConfig` supplies the block it records, and
- * `resolveRunScopedConfig` reads it back through the existing
- * `findStructuredComment` seam.
- *
- * ## Adding another run-scoped key
- *
- * Add one row to `RUN_SCOPED_CONFIG_KEYS`. Both halves — the pin init writes
- * and the comparison close makes — enumerate that registry, so a new key
- * needs no second mechanism, no reader change and no writer change. Only
- * `baseBranch` is enforced today because only its corruption is destructive
- * (a wrong base merged into the Story branch permanently contaminates the
- * branch and its PR diff); ceremony profile, quality floors and the
- * concurrency cap are deliberately NOT pinned here.
+ * Pin the config a delivery run was seeded from (in the init envelope) and
+ * fail closed at close when the config changed underneath it — a concurrent
+ * edit would otherwise base-sync the Story onto a base it was never seeded
+ * from. A missing pin degrades to current config with a loud warning.
  */
 
-import { parseFencedJsonComment } from './structured-comment-parser.js';
-import { findStructuredComment } from './ticketing.js';
+import { readRunScopedPin } from './story-init-envelope.js';
 
 /**
- * The run-scoped config registry. One row per key whose value belongs to the
- * run that seeded the Story rather than to the current contents of the config
- * file. `read` resolves the key from a resolved config (including its
- * default); `label` is the dotted config path the operator has to go fix.
+ * Keys whose value belongs to the seeding run. Only `baseBranch`: a wrong base
+ * permanently contaminates the branch. Init and close both walk this registry.
  *
  * @type {Record<string, { read: (config: object) => unknown, label: string }>}
  */
@@ -55,14 +21,8 @@ const RUN_SCOPED_CONFIG_KEYS = {
 };
 
 /**
- * Snapshot the run-scoped config values from a resolved config. This is the
- * write half of the pin: `single-story-init.js` records the returned object
- * in the `story-init` receipt so close can compare against it later.
- *
- * @param {object} config Resolved config (`resolveConfig` output).
- * @param {typeof RUN_SCOPED_CONFIG_KEYS} [keys] Registry override — the
- *   default is the module registry; supplying one is how a caller (or a test)
- *   exercises the registry-driven property without a second mechanism.
+ * @param {object} config Resolved config.
+ * @param {typeof RUN_SCOPED_CONFIG_KEYS} [keys]
  * @returns {Record<string, unknown>} the pinned values, keyed by config key.
  */
 export function pinRunScopedConfig(config, keys = RUN_SCOPED_CONFIG_KEYS) {
@@ -74,71 +34,39 @@ export function pinRunScopedConfig(config, keys = RUN_SCOPED_CONFIG_KEYS) {
 }
 
 /**
- * Read the pinned block out of the run's `story-init` receipt.
- *
- * Three distinct non-success states, all reported rather than collapsed —
- * the whole point of this module is that a fallback is never silent:
- *   - `absent`: no `story-init` comment on the ticket. Real and expected —
- *     the upsert is best-effort (init logs and continues on failure), and a
- *     recovery path may close a Story whose init predates this receipt.
- *   - `unreadable`: the comment exists but carries no parseable JSON payload.
- *   - `provider-error`: the comment read itself failed.
+ * A row with no pinned value is `unpinned` (an older receipt), not a conflict.
  *
  * @param {{
- *   provider: object,
- *   storyId: number,
- *   findCommentFn?: typeof findStructuredComment,
+ *   pinned: Record<string, unknown>,
+ *   current: Record<string, unknown>,
+ *   keys: typeof RUN_SCOPED_CONFIG_KEYS,
  * }} args
- * @returns {Promise<{ status: string, values: Record<string, unknown>|null, detail: string|null }>}
+ * @returns {{
+ *   values: Record<string, unknown>,
+ *   conflicts: Array<{ label: string, pinned: unknown, current: unknown }>,
+ *   unpinned: string[],
+ * }}
  */
-async function readRunScopedConfigReceipt({
-  provider,
-  storyId,
-  findCommentFn = findStructuredComment,
-}) {
-  let comment;
-  try {
-    comment = await findCommentFn(provider, Number(storyId), 'story-init');
-  } catch (err) {
-    return {
-      status: 'provider-error',
-      values: null,
-      detail: `story-init comment could not be read (${err?.message ?? err})`,
-    };
-  }
-  if (!comment) {
-    return {
-      status: 'absent',
-      values: null,
-      detail: 'no story-init comment on the ticket',
-    };
-  }
-  const payload = parseFencedJsonComment(comment);
-  if (!payload || typeof payload !== 'object') {
-    return {
-      status: 'unreadable',
-      values: null,
-      detail: 'story-init comment carries no parseable JSON payload',
-    };
+function comparePinToCurrent({ pinned: pin, current, keys }) {
+  const values = {};
+  const conflicts = [];
+  const unpinned = [];
+  for (const [key, spec] of Object.entries(keys)) {
+    const pinned = pin?.[key];
+    if (pinned === undefined || pinned === null) {
+      unpinned.push(spec.label);
+      values[key] = current[key];
+      continue;
+    }
+    values[key] = pinned;
+    if (pinned !== current[key]) {
+      conflicts.push({ label: spec.label, pinned, current: current[key] });
+    }
   }
-  // Receipts written before the `runScopedConfig` block existed carry the
-  // pinned values as top-level payload fields (`baseBranch` has been recorded
-  // there since Story #831). Reading the payload itself as the fallback block
-  // is what lets a Story initialized by an older init still close against its
-  // own pinned base instead of degrading to the fallback warning.
-  const block =
-    payload.runScopedConfig && typeof payload.runScopedConfig === 'object'
-      ? payload.runScopedConfig
-      : payload;
-  return { status: 'found', values: block, detail: null };
+  return { values, conflicts, unpinned };
 }
 
 /**
- * Build the refusal message for a mid-run config change. Names BOTH values
- * for every conflicting key — the pinned one and the one config resolves to
- * now — because "which base was this branch actually seeded from" is the
- * question the operator could not previously answer.
- *
  * @param {{ storyId: number, conflicts: Array<{ label: string, pinned: unknown, current: unknown }> }} args
  * @returns {string}
  */
@@ -159,21 +87,14 @@ function formatRunScopedConflict({ storyId, conflicts }) {
 }
 
 /**
- * Resolve the run-scoped config for a close, preferring the run's pin over a
- * fresh resolution of the config file.
- *
- * Throws on disagreement — fail closed, before any gate, format-autofix or
- * base-sync has run, with both values named. Never silently prefers either
- * side: preferring the pin would base-sync correctly but hide a config change
- * the operator needs to know about, and preferring current config is the bug
- * this module exists to close.
+ * Throws on disagreement, before any gate or base-sync runs — silently
+ * preferring either side would hide the config change.
  *
  * @param {{
- *   provider: object,
  *   storyId: number,
  *   config: object,
  *   keys?: typeof RUN_SCOPED_CONFIG_KEYS,
- *   findCommentFn?: typeof findStructuredComment,
+ *   readPinFn?: typeof readRunScopedPin,
  *   progress?: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -181,57 +102,39 @@ function formatRunScopedConflict({ storyId, conflicts }) {
  *   confirmed: boolean,
  *   receiptStatus: string,
  *   warning: string|null,
- * }>} `confirmed` is true only when every key came from the receipt and
- *   agreed with current config — i.e. when downstream remediation may safely
- *   assume the pinned value is the one in play.
+ * }>} `confirmed` only when every key was pinned and agreed.
  */
 export async function resolveRunScopedConfig({
-  provider,
   storyId,
   config,
   keys = RUN_SCOPED_CONFIG_KEYS,
-  findCommentFn,
+  readPinFn = readRunScopedPin,
   progress,
 }) {
   const current = pinRunScopedConfig(config, keys);
-  const receipt = await readRunScopedConfigReceipt({
-    provider,
-    storyId,
-    findCommentFn,
-  });
+  const receipt = readPinFn({ storyId: Number(storyId), config });
 
-  if (receipt.status !== 'found') {
-    // A missing receipt is a real state, not an error — but the fallback is
-    // announced, because a silent one reintroduces exactly the bug above.
+  if (!receipt) {
+    // Not an error, but never a silent fallback.
     const warning =
-      `Run-scoped config could not be read from the run's init receipt ` +
-      `(${receipt.detail}); falling back to the currently-resolved config ` +
-      `(${describeValues(current, keys)}). This close cannot confirm the Story ` +
-      'was seeded from these values.';
+      `Run-scoped config could not be read from the run's init envelope ` +
+      `(no runScopedConfig pin for Story #${storyId}); falling back to the ` +
+      `currently-resolved config (${describeValues(current, keys)}). This close ` +
+      'cannot confirm the Story was seeded from these values.';
     progress?.('PIN', `⚠️ ${warning}`);
     return {
       values: current,
       confirmed: false,
-      receiptStatus: receipt.status,
+      receiptStatus: 'absent',
       warning,
     };
   }
 
-  const values = {};
-  const conflicts = [];
-  const unpinned = [];
-  for (const [key, spec] of Object.entries(keys)) {
-    const pinned = receipt.values?.[key];
-    if (pinned === undefined || pinned === null) {
-      unpinned.push(spec.label);
-      values[key] = current[key];
-      continue;
-    }
-    values[key] = pinned;
-    if (pinned !== current[key]) {
-      conflicts.push({ label: spec.label, pinned, current: current[key] });
-    }
-  }
+  const { values, conflicts, unpinned } = comparePinToCurrent({
+    pinned: receipt,
+    current,
+    keys,
+  });
 
   if (conflicts.length > 0) {
     throw new Error(formatRunScopedConflict({ storyId, conflicts }));
@@ -245,26 +148,19 @@ export async function resolveRunScopedConfig({
     return {
       values,
       confirmed: false,
-      receiptStatus: receipt.status,
+      receiptStatus: 'found',
       warning,
     };
   }
 
   progress?.(
     'PIN',
-    `📌 Run-scoped config pinned by the story-init receipt (${describeValues(values, keys)}).`,
+    `📌 Run-scoped config pinned by the init envelope (${describeValues(values, keys)}).`,
   );
-  return {
-    values,
-    confirmed: true,
-    receiptStatus: receipt.status,
-    warning: null,
-  };
+  return { values, confirmed: true, receiptStatus: 'found', warning: null };
 }
 
 /**
- * Render `label=value` pairs for the operator-facing lines above.
- *
  * @param {Record<string, unknown>} values
  * @param {typeof RUN_SCOPED_CONFIG_KEYS} keys
  * @returns {string}

package/.agents/scripts/lib/orchestration/single-story-close/close-note.js

@@ -1,45 +1,18 @@
 /**
- * close-note.js — the human-readable `note` on close's result record
- * (Story #5266).
+ * close-note.js — the human-readable `note` on close's result record.
  *
- * ## Why this is its own module
- *
- * The note used to branch on `waitedForMerge` — whether close *waited* — and
- * not on `merged`. A bounded wait that expired with the PR still open
- * therefore wrote "Close-and-land: PR merge confirmed … the issue closed"
- * into `story-close-result-<id>.log` **beside `merged: false`**, while the
- * schema-validated terminal envelope correctly reported
- * `status: pending, phase: confirm-merge`. That log is what close's summary
- * line points the operator at, so the contradiction is what gets read first:
- * a merge that never happened, reported as confirmed.
- *
- * The invariant this module exists to hold:
- *
- *   > **No note may assert a state the same object denies.**
- *
- * Every branch below is therefore derived from the result's OWN
- * `merged` / `directMerged` / `autoMergeEnabled` / `landCompleted` fields —
- * the ones the note ships next to — so no input can produce a note that
- * contradicts them. Story #5279 added the fourth, because `merged: true`
- * used to imply the flip, the issue close and the post-land tail: a direct
- * squash-merge under `--no-wait-merge`, and a merge whose `agent::done` write
- * failed, now reach it with none of the three, and reusing the confirmed
- * wording for them would reintroduce the defect above one field over. The
- * unmerged branches deliberately claim nothing about the Story's label state
- * either: close's ending may be `pending` OR `blocked` with the same
- * `merged: false`, and the terminal envelope is the authority on which. They
- * also avoid the merge-completion vocabulary entirely — no `agent::done`, no
- * "the merge confirms" — so that a reader skimming for those words cannot
- * take a next-step instruction for a report of what happened.
+ * Invariant: no note may assert a state the same object denies, so every
+ * branch derives from the result's own fields. A merge is not a completed
+ * land (`landCompleted`), and the unmerged branches claim nothing about label
+ * state and avoid merge-completion vocabulary — the terminal envelope is the
+ * authority on pending vs blocked.
  */
 
 /**
- * The one line the note is not allowed to get wrong.
- *
  * @param {{ merged?: boolean, directMerged?: boolean,
  *   autoMergeEnabled?: boolean, landCompleted?: boolean }} result
  *   `landCompleted` — did THIS run flip `agent::done`, close the issue and
- *   run the post-land tail? Defaults to `merged`, the pre-#5279 equivalence.
+ *   run the post-land tail? Defaults to `merged`.
  * @returns {string}
  */
 export function deriveCloseNote({

package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js

@@ -1,17 +1,7 @@
 /**
- * single-story-close/failed-terminal.js — the `failed` terminal a close
- * emits when a phase crashes, and the gate reconstruction it carries.
- *
- * Split out of `single-story-close.js` so the CLI entry stays an entry: it
- * parses args, dispatches the runner, and maps a terminal onto an exit code.
- * The reasoning about which gates had run by the time a phase died belongs
- * with the envelope it feeds, not in the file that owns process lifetime.
- *
- * The runner deliberately throws rather than returning a failure (a red gate
- * must not look like a return value), so without this the most common
- * non-happy ending — a failing close-validation gate — would emit **no
- * envelope at all**, exiting 1 with only a stderr line while the workflow
- * docs promise the agent a `failed` envelope naming the phase.
+ * single-story-close/failed-terminal.js — the `failed` envelope a close
+ * emits when a phase throws, so a crashed close still reports which phase
+ * died and which gates had run.
  */
 
 import { Logger } from '../../Logger.js';
@@ -21,16 +11,12 @@ import {
 } from '../story-deliver-terminal.js';
 
 /**
- * The close pipeline's phase order, as `setPhase` walks it. Only used to
- * decide whether a gate had already run when a later phase died.
+ * The phase order `setPhase` walks; it MUST track `runPrePushPhases`, since
+ * it decides which gates had cleared when a later phase died.
  */
 const PHASE_ORDER = Object.freeze([
   'init',
   'wrong-tree-guard',
-  // Story #5172 — base-sync now precedes close-validation, so the tree the
-  // gates validate is the tree the push sends. The order here is not
-  // decoration: it is how a failed terminal decides which gates had already
-  // cleared, so it MUST track `runPrePushPhases`.
   'base-sync',
   'close-validation',
   'push',
@@ -42,7 +28,6 @@ const PHASE_ORDER = Object.freeze([
   'done',
 ]);
 
-/** Each reported gate and the pipeline phase that decides it. */
 const GATE_PHASES = Object.freeze([
   ['validation', 'close-validation'],
   ['baseSync', 'base-sync'],
@@ -50,18 +35,9 @@ const GATE_PHASES = Object.freeze([
 ]);
 
 /**
- * The names the unified baselines gate can register under, mirrored from
- * `BASELINES_GATE_NAMES` in `lib/close-validation/gates.js` (Story #5172) —
- * all three, matching the projection the SUCCESS path applies in
- * `runner.js#baselinesEnvelopeGates`, so the two endings of one run cannot
- * key the same gate differently.
- *
- * Deliberately a local copy rather than an import: several close suites
- * replace that module wholesale via `t.mock.module`, and a named import here
- * would fail to link against a mock that does not re-export the constant —
- * turning an unrelated test's mock into a load error on the CLI's own entry
- * path. `tests/close-validation-gates-enum.test.js` pins the two lists
- * against each other so the copy cannot drift.
+ * Mirrors `BASELINES_GATE_NAMES` in `lib/close-validation/gates.js`. A local
+ * copy, not an import, because close suites mock that module wholesale and a
+ * named import would fail to link; a test pins the two lists equal.
  */
 const BASELINES_ENTRY_NAMES = Object.freeze([
   'check-baselines',
@@ -70,21 +46,8 @@ const BASELINES_ENTRY_NAMES = Object.freeze([
 ]);
 
 /**
- * Project the baselines entries out of the per-gate outcomes THIS run
- * observed (Story #5279).
- *
- * This used to RECONSTRUCT them: it inferred, from the phase the run died in
- * plus the name of the failing gate, what the two split entries "must have"
- * done — and it did so over a hardcoded pair, so every failed close reported
- * both split names whether or not the run had ever registered them. A repo
- * whose config resolves to the unsplit `check-baselines`, or to only one half
- * of the pair, got envelope keys for gates that did not exist; a run that
- * died at `init` got them too, reported as `skipped`, which reads as "the
- * gate was turned off" rather than "there was no such gate".
- *
- * Reporting instead of reconstructing removes the whole class: an outcome
- * appears only for a gate the run actually observed, and the runner tags
- * exactly that set onto the error (`err.closeGates`).
+ * Baselines outcomes the run actually observed (`err.closeGates`) — reported,
+ * never reconstructed, so a gate the run never registered cannot appear.
  *
  * @param {Record<string, string>|null|undefined} observedGates
  * @returns {Record<string, 'passed'|'failed'|'skipped'>}
@@ -98,30 +61,12 @@ function baselinesGatesObserved(observedGates) {
 }
 
 /**
- * Report every gate's outcome for a run that died at `phase`.
- *
- * The schema's contract: "A gate the run skipped … reports `skipped` rather
- * than being omitted, so a missing gate is never mistaken for a passing one."
- * The previous shape named only the gate that died and omitted the rest
- * entirely — exactly the ambiguity the contract forbids.
- *
- * Reconstructed from the phase order, which is sound because the pipeline is
- * strictly sequential: reaching phase N means every gate before it completed.
- * A gate whose phase the run never reached is `skipped`; one the operator
- * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
- * not pass — it never ran).
- *
- * Story #5172 — the reported set also carries the baselines entries under
- * their own names, so a failed close says WHICH half of the baselines gate
- * breached instead of a single generic verdict. Story #5279 — those names
- * are REPORTED from `observedGates`, never reconstructed, so only a gate the
- * run registered can appear.
+ * Every gate's outcome, never omitted (a missing gate would read as passing);
+ * an unreached or operator-skipped gate is `skipped`.
  *
  * @param {string} phase The phase the run died in.
  * @param {{ skipValidation?: boolean, skipSync?: boolean,
  *   observedGates?: Record<string, string>|null }} args
- *   Parsed CLI args, plus the per-gate outcomes the runner tagged onto the
- *   error.
  * @returns {Record<string, 'passed'|'failed'|'skipped'>}
  */
 export function gatesForFailedPhase(phase, args = {}) {
@@ -138,31 +83,13 @@ export function gatesForFailedPhase(phase, args = {}) {
 }
 
 /**
- * Build the `failed` terminal for a phase that crashed. Every close
- * invocation emits exactly one envelope; this is the path that keeps that
- * true when a phase dies.
- *
- * `err.closePhase` is tagged by the runner's phase tracker.
- *
- * **Never throws.** This runs on the path that already has one failure in
- * hand, so a second failure here must not REPLACE the first: an
- * envelope-build error surfacing as the run's cause sends the operator to
- * diagnose the wrong thing entirely — a close whose PR had already merged
- * once reported a schema `ENOENT` as its fatal error, because the worktree
- * holding the script had been reaped mid-run. On failure this returns null
- * and the caller rethrows the original.
- *
- * `err.closeGates` — tagged by the runner — carries the per-gate outcomes the
- * run observed, which is what lets the reported gates name the baselines
- * entries that actually ran (Story #5172 / #5279) instead of a hardcoded pair.
+ * Never throws: a build failure here must not replace the original error as
+ * the run's reported cause, so it returns null and the caller rethrows.
+ * `err.closePhase` and `err.closeGates` are tagged by the runner.
  *
  * @param {unknown} err
  * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
- *   Parsed CLI args — the story id the envelope reports on, plus the skip
- *   flags `gatesForFailedPhase` needs.
- * @returns {object|null} A validated envelope, or null when even the story id
- *   is unknown (a usage error — there is nothing to report an envelope about)
- *   or the envelope itself could not be assembled.
+ * @returns {object|null} null when the story id is unknown or assembly failed.
  */
 export function failedTerminalFor(err, args = {}) {
   const phase = err?.closePhase ?? 'init';