mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/dead-exports-mode.js

@@ -0,0 +1,51 @@
+/**
+ * dead-exports-mode.js — the two passes of the dead-export ratchet.
+ *
+ * The gate runs twice with different reachability assumptions, and each pass
+ * needs a matched triple: which knip invocation to make, which baseline to
+ * ratchet against, and how to label its output. Resolving that triple in one
+ * place keeps the three from drifting apart — a pass that ran production knip
+ * against the default baseline would report every test-only export as newly
+ * dead and fail the build for no reason.
+ *
+ * - **default** — `tests/**` are knip entry points, so an export imported only
+ *   by a test reads as used. This is the historical gate.
+ * - **production** — knip's `--production` drops the test entries, so an export
+ *   no production code reaches reads as dead. Depends on the `!` pattern
+ *   suffixes in `knip.json`; without them production mode has no entry points
+ *   and silently reports nothing.
+ *
+ * The two ratchet against separate baselines on purpose. This repo sanctions
+ * exporting purely for a test (`.agents/rules/test-seams.md`), so the
+ * production row set is large and mostly intentional; merging it into the
+ * default baseline would destroy that baseline's meaning.
+ *
+ * @module lib/dead-exports-mode
+ */
+
+import path from 'node:path';
+
+/** Baseline for the default pass (test entry points included). */
+const DEFAULT_BASELINE = path.join('baselines', 'dead-exports.json');
+
+/** Baseline for the `--production` pass (test-only-importer discount). */
+const PRODUCTION_BASELINE = path.join(
+  'baselines',
+  'dead-exports-production.json',
+);
+
+/**
+ * Resolve the baseline / label / mode-tag triple for a pass.
+ *
+ * @param {boolean} production
+ * @returns {{ mode: 'production'|'default', label: string, baseline: string }}
+ */
+export function resolveDeadExportsMode(production) {
+  return production
+    ? {
+        mode: 'production',
+        label: 'dead-exports:production',
+        baseline: PRODUCTION_BASELINE,
+      }
+    : { mode: 'default', label: 'dead-exports', baseline: DEFAULT_BASELINE };
+}

package/.agents/scripts/lib/duplicate-search.js

@@ -10,8 +10,17 @@
  *  - Prefer `provider.searchIssues` to narrow open Stories server-side
  *    (`label:"type::story" state:open` + top seed tokens), capped at
  *    ~100 hits, then rank that set. Fall back to `listIssuesByLabel`
- *    when search errors or is unavailable (same try/catch pattern as
- *    `TicketGateway.getTickets`).
+ *    when search errors, is unavailable, or returns **nothing** (same
+ *    try/catch pattern as `TicketGateway.getTickets`).
+ *  - The narrowing query is deliberately weak (Story #4541). GitHub ANDs
+ *    free-text terms, so the former 8-token query demanded that a candidate
+ *    contain all eight of a multi-sentence seed's longest words — which no
+ *    real Story does. Gate #1 duplicate triage therefore reported "no
+ *    candidates" on every realistic seed while looking perfectly healthy.
+ *    Search is now a cheap best-case narrowing over a handful of tokens; an
+ *    empty result is treated as "search did not help", not "no duplicates",
+ *    and falls through to the label listing whose Jaccard ranker has real
+ *    recall.
  *  - Scoring is intentionally simple (token Jaccard over title + body).
  *    It is a triage signal, not a semantic-search replacement.
  *  - Provider errors on the list fallback propagate verbatim — the
@@ -79,8 +88,17 @@ const STOPWORDS = new Set([
 
 const DEFAULT_MIN_SCORE = 0.15;
 const DEFAULT_MAX_RESULTS = 5;
-/** How many seed tokens to pass as free-text search terms. */
-const DEFAULT_SEARCH_TOKEN_CAP = 8;
+/**
+ * How many seed tokens to pass as free-text search terms.
+ *
+ * GitHub ANDs these, so the cap is a precision/recall dial pointing the
+ * wrong way: every extra token shrinks the candidate set. Three is a
+ * best-case narrowing that can plausibly hit on a focused seed; anything
+ * beyond that reliably matched nothing on a multi-sentence one (Story
+ * #4541). Recall does not rest on this number — an empty result falls back
+ * to label-listing plus client-side ranking.
+ */
+const DEFAULT_SEARCH_TOKEN_CAP = 3;
 /** Hard cap on search hits ranked client-side (~one Search API page). */
 const SEARCH_RESULT_CAP = 100;
 
@@ -269,8 +287,16 @@ async function fetchOpenStoriesViaList(provider) {
 }
 
 /**
- * Fetch open-Story candidates: prefer Search API narrowing, fall back to
- * `listIssuesByLabel` when search errors or is unavailable.
+ * Fetch open-Story candidates: try Search API narrowing first, fall back to
+ * `listIssuesByLabel` when search errors, is unavailable, or **returns no
+ * hits**.
+ *
+ * The empty-result fallback is the load-bearing one (Story #4541). The
+ * narrowing query ANDs seed tokens, so on any real multi-sentence seed it
+ * matches nothing — and treating that as an authoritative "no duplicates
+ * exist" is what made Gate #1 triage report a clean bill of health while
+ * never actually looking. An empty search is evidence about the *query*, not
+ * about the backlog.
  *
  * @param {object} provider
  * @param {string} seed
@@ -291,7 +317,12 @@ async function fetchOpenStoryCandidates(provider, seed) {
 
   if (hasSearch) {
     try {
-      return await fetchOpenStoriesViaSearch(provider, seed);
+      const hits = await fetchOpenStoriesViaSearch(provider, seed);
+      if (hits.length > 0 || !hasList) return hits;
+      Logger.info(
+        '[duplicate-search] narrowed search matched no open Stories; ' +
+          'falling back to listIssuesByLabel + client-side ranking',
+      );
     } catch (err) {
       if (!hasList) throw err;
       const msg = typeof err?.message === 'string' ? err.message : String(err);

package/.agents/scripts/lib/findings/promote-finding.js

@@ -6,7 +6,7 @@
  * session's ledger items (see `.agents/schemas/qa-ledger.schema.json` and
  * `lib/qa/qa-session.js`), the still-untriaged backlog is clustered and each
  * cluster is promoted to a follow-up ticket — a single Story (via `/plan`)
- * for a tight, one-deliverable cluster, or an Epic (via `/plan --seed`) for
+ * for a tight, one-deliverable cluster, or a multi-Story plan-seed (via `/plan --seed`) for
  * a broad cluster that spans multiple coverage surfaces. Each contributing
  * ledger item then has the resulting `routedTo` issue link written back onto it
  * so a resume run sees the item as filed rather than re-promoting it.
@@ -32,15 +32,24 @@ import { highestSeverity as highestSeverityOf } from './severity.js';
 /** Triaged dispositions, mirrored from the `disposition` enum in the schema. */
 const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
 
-/** The two promotion targets a cluster routes to. */
+/**
+ * The two promotion targets a cluster routes to.
+ *
+ * `PLAN_SEED` promotes a broad cluster by seeding a multi-Story `/plan`
+ * run (`/plan --seed`). Its persisted wire token is the legacy string
+ * `'epic'`: archived qa-ledger records (and the distributed
+ * `qa-ledger.schema.json` `routedTo.kind` enum) still carry `'epic'`, so
+ * the value is kept read-compatible while the write-side constant name is
+ * modernised.
+ */
 export const PROMOTION_TARGETS = Object.freeze({
   STORY: 'story',
-  EPIC: 'epic',
+  PLAN_SEED: 'epic',
 });
 
 /**
  * A cluster of more than this many distinct coverage surfaces is broad enough
- * to warrant an Epic (`/plan --seed`) rather than a single Story
+ * to warrant a plan-seed (`/plan --seed`) rather than a single Story
  * (`/plan`). One or two surfaces is a tight, single-deliverable cluster.
  */
 const EPIC_COVERAGE_THRESHOLD = 2;
@@ -70,7 +79,7 @@ export function isPromotable(item) {
  * Stable cluster key for a ledger item: its `class`. Items sharing a class
  * describe the same kind of signal (a product bug, a tooling-DX gap, …) and
  * merge into one follow-up ticket. A class whose items span many distinct
- * coverage surfaces is broad enough to promote to an Epic (see
+ * coverage surfaces is broad enough to promote to a plan-seed (see
  * {@link targetForCluster}); a class confined to one or two surfaces is a
  * single-deliverable Story. Coverage is therefore a *secondary* signal that
  * sizes the cluster rather than splitting it.
@@ -159,7 +168,7 @@ export function clusterLedgerItems(items) {
 /**
  * Decide a cluster's promotion target. A cluster that spans more than
  * {@link EPIC_COVERAGE_THRESHOLD} distinct coverage surfaces is broad enough to
- * warrant an Epic (`/plan --seed`); otherwise it is a single-deliverable
+ * warrant a plan-seed (`/plan --seed`); otherwise it is a single-deliverable
  * Story (`/plan`).
  *
  * @param {{ coverages: string[] }} cluster
@@ -170,7 +179,7 @@ export function targetForCluster(cluster) {
     ? cluster.coverages.length
     : 0;
   return surfaces > EPIC_COVERAGE_THRESHOLD
-    ? PROMOTION_TARGETS.EPIC
+    ? PROMOTION_TARGETS.PLAN_SEED
     : PROMOTION_TARGETS.STORY;
 }
 
@@ -224,7 +233,7 @@ function routedToLink(issue, kind) {
 }
 
 /**
- * Promote the clustered untriaged ledger items into Stories / Epics via the
+ * Promote the clustered untriaged ledger items into Stories / plan-seeds via the
  * shared findings/route logic, then write the resulting `routedTo` issue link
  * back onto each contributing ledger item.
  *
@@ -233,7 +242,7 @@ function routedToLink(issue, kind) {
  *      shared `routeFinding` against existing Issues (via the injected search
  *      port). This dedups against work already filed.
  *   2. On a `new` decision, open the follow-up ticket through the injected
- *      `createStory` (`/plan`) or `createEpic` (`/plan --seed`) port,
+ *      `createStory` (`/plan`) or `createPlanSeed` (`/plan --seed`) port,
  *      chosen by {@link targetForCluster}. On any other decision, link back to
  *      the matched Issue rather than creating a duplicate.
  *   3. Stamp the resolved `routedTo` link onto every contributing ledger item
@@ -251,8 +260,8 @@ function routedToLink(issue, kind) {
  *   Optional semantic candidate search, forwarded to `routeFinding`.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createStory
  *   Opens a single Story (`/plan`) for a tight cluster.
- * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createEpic
- *   Opens an Epic (`/plan --seed`) for a broad cluster.
+ * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createPlanSeed
+ *   Opens a plan-seed (`/plan --seed`) run for a broad cluster.
  * @returns {Promise<{
  *   promotions: Array<{
  *     clusterKey: string,
@@ -268,7 +277,7 @@ function routedToLink(issue, kind) {
  * @throws {Error} when a required create port is missing for a routed cluster.
  */
 export async function promoteFindings(ledgerItems, ports = {}) {
-  const { searchIssues, searchCandidates, createStory, createEpic } = ports;
+  const { searchIssues, searchCandidates, createStory, createPlanSeed } = ports;
   if (
     typeof searchCandidates !== 'function' &&
     typeof searchIssues !== 'function'
@@ -294,10 +303,10 @@ export async function promoteFindings(ledgerItems, ports = {}) {
 
     if (route.decision === 'new') {
       const createPort =
-        target === PROMOTION_TARGETS.EPIC ? createEpic : createStory;
+        target === PROMOTION_TARGETS.PLAN_SEED ? createPlanSeed : createStory;
       if (typeof createPort !== 'function') {
         throw new Error(
-          `promoteFindings: a ${target === PROMOTION_TARGETS.EPIC ? 'createEpic' : 'createStory'} port is required to promote cluster ${cluster.key}`,
+          `promoteFindings: a ${target === PROMOTION_TARGETS.PLAN_SEED ? 'createPlanSeed' : 'createStory'} port is required to promote cluster ${cluster.key}`,
         );
       }
       issue = await createPort(cluster);

package/.agents/scripts/lib/format-generated-json.js

@@ -0,0 +1,97 @@
+/**
+ * format-generated-json.js — run generated JSON through the project
+ * formatter (Biome) so a generator's output matches what the repo's
+ * commit-time formatting would have produced anyway.
+ *
+ * Why this exists. Generators serialize with `JSON.stringify`, which
+ * expands every array across multiple lines. Biome collapses short ones
+ * that fit inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`), and
+ * lint-staged runs `biome format --write` over staged JSON at commit
+ * time — so the committed artifact is Biome-shaped while a fresh
+ * generator run is not. The gap means regenerating on a clean tree
+ * always leaves format drift, and a `<generate>` → `lint` sequence fails
+ * on `biome ci` even when the generator's own `--check` reports the
+ * artifact semantically fresh (Story #4546).
+ *
+ * Running the real formatter, rather than hand-matching its array
+ * collapsing, keeps this correct by construction across future formatter
+ * and `lineWidth` changes.
+ *
+ * Stdin mode is deliberate: Biome's configured `formatWrite` command is
+ * whole-tree (`biome format --write .`), which is a far broader side
+ * effect than a generator should have. `--stdin-file-path` makes this a
+ * pure content transform with no filesystem writes.
+ */
+
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { Logger } from './Logger.js';
+
+/** Wall-clock ceiling for the formatter spawn, so a hung child cannot wedge a generator run. */
+const FORMATTER_TIMEOUT_MS = 30_000;
+
+/**
+ * Warn once about a fallback and return null for the caller to act on.
+ * Owning the message here keeps every caller's write path a single
+ * `formatGeneratedJson(...) ?? serialized` expression.
+ */
+function fallback(filename) {
+  Logger.warn(
+    `project formatter (biome) unavailable — writing unformatted ${filename}; ` +
+      'run your formatter over it if a format gate rejects it',
+  );
+  return null;
+}
+
+/**
+ * Format `source` as JSON using the project formatter.
+ *
+ * Best-effort by design: `.agents/` is materialized into consumer
+ * projects that need not have Biome installed, so an unavailable or
+ * failing formatter warns and returns `null` for the caller to fall back
+ * on its own serialization rather than failing the generator. That is
+ * safe wherever the artifact's freshness check compares parsed objects
+ * rather than bytes — formatting carries no semantic content.
+ *
+ * `--no` keeps npx from reaching the network to install a missing Biome.
+ * `filename` is passed as a bare basename: Biome only needs it to infer
+ * the language and match config overrides, and a basename cannot carry
+ * the spaces that would break arg quoting under the Windows `shell:
+ * true` spawn.
+ *
+ * @param {string} source Text to format.
+ * @param {object} opts
+ * @param {string} opts.cwd Directory to resolve the formatter and its config from.
+ * @param {string} [opts.filename] Basename Biome attributes the stdin text to.
+ * @param {typeof spawnSync} [opts.spawn] Injection seam for tests.
+ * @returns {string|null} Formatted text with a trailing newline, or null to fall back.
+ */
+export function formatGeneratedJson(
+  source,
+  { cwd, filename = 'generated.json', spawn = spawnSync },
+) {
+  let result;
+  try {
+    result = spawn(
+      'npx',
+      ['--no', 'biome', 'format', `--stdin-file-path=${filename}`],
+      {
+        cwd,
+        input: source,
+        encoding: 'utf8',
+        // npm/npx ship as `.cmd` shims on Windows, which Node refuses to
+        // spawn without a shell since CVE-2024-27980.
+        shell: process.platform === 'win32',
+        timeout: FORMATTER_TIMEOUT_MS,
+      },
+    );
+  } catch {
+    return fallback(filename);
+  }
+  if (!result || result.error || result.status !== 0) return fallback(filename);
+  const stdout = result.stdout;
+  if (typeof stdout !== 'string' || stdout.trim() === '') {
+    return fallback(filename);
+  }
+  return stdout.endsWith('\n') ? stdout : `${stdout}\n`;
+}

package/.agents/scripts/lib/framework-version.js

@@ -1,107 +1,35 @@
 // .agents/scripts/lib/framework-version.js
 /**
- * framework-version.js — single source of truth for the running Mandrel
- * framework version and the ticket-body authoring stamp.
+ * framework-version.js — the visible authoring-marker surface for the legacy
+ * ticket-body provenance stamp.
  *
- * Two concerns live here:
+ * Tickets authored under v1 carry a hybrid stamp: a hidden
+ * `<!-- meta: {"mandrel_version":"…","authored_at":"…"} -->` block plus a
+ * single visible footer line
+ * `> 🏷️ Authored with Mandrel v<version> · <YYYY-MM-DD>`. The producer of
+ * new stamps was retired with the Epic write surface (#4574) — nothing stamps
+ * a new ticket — but bodies already stamped are live in the backlog, so the
+ * Story-body serializer/parser must keep round-tripping them:
  *
- * 1. **Version resolution.** Under npm distribution the root `package.json`
- *    is the canonical version marker. {@link resolveFrameworkVersion} reads it
- *    and degrades to `'unknown'` (never throws) so a missing/unreadable
- *    manifest can never crash an authoring path. All ticket-body stamp
- *    producers delegate here (DRY — one manifest reader).
+ * - {@link AUTHORED_MARKER_LINE_RE} lets the parser skip the marker line during
+ *   section parsing so it never pollutes the last structured section.
+ * - {@link authoredMarkerLine} lets the serializer re-emit a byte-identical
+ *   marker line for a stamp it parsed, preserving provenance verbatim.
  *
- * 2. **Ticket-body stamp.** Epics and Stories are stamped **once at authoring
- *    time** with the running version and the authoring date, via a hybrid
- *    surface:
- *      - a hidden machine-readable field in the trailing
- *        `<!-- meta: {"mandrel_version":"…","authored_at":"…"} -->` block
- *        (the source of truth, queryable by tooling), and
- *      - a single visible footer line
- *        `> 🏷️ Authored with Mandrel v<version> · <YYYY-MM-DD>` so a human
- *        reading the raw GitHub issue sees the provenance without any tooling.
- *
- *    The stamp is **immutable**: {@link stampFrameworkVersion} is a no-op when
- *    the body already carries a `mandrel_version`, so a later re-render or
- *    Epic-body edit preserves the originally-authored version verbatim rather
- *    than bumping it to whatever version happens to be running.
- *
- * This module imports only Node builtins so it can be pulled in from the
- * story-body serializer, the ticket provider, and the Epic ideation renderer
- * without risking an import cycle.
+ * This module imports nothing so it can be pulled in from the story-body
+ * serializer without risking an import cycle.
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/** Returned when the package manifest is absent or unreadable. */
-export const FALLBACK_VERSION = 'unknown';
-
-/**
- * Trailing machine-metadata comment block: `<!-- meta: {...} -->`. Mirrors the
- * regex the Story-body parser uses so both surfaces recognise the same block.
- */
-const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
-
 /**
  * The visible authoring marker line. A blockquote so GitHub renders it as a
- * callout. Used both to detect an already-emitted marker (for the strip step)
- * and, in the Story-body parser, to skip the line during section parsing so it
- * never pollutes the last structured section.
+ * callout. Used in the Story-body parser to skip the line during section
+ * parsing so it never pollutes the last structured section.
  */
 export const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
 
 /**
- * Compute the default path to the root `package.json`. This module ships inside
- * the `mandrel` package at `<pkgRoot>/.agents/scripts/lib/framework-version.js`,
- * so the manifest sits three directories up — the same layout in the dev repo
- * and the published tarball.
- *
- * @returns {string}
- */
-function defaultPkgPath() {
-  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(moduleDir, '../../..', 'package.json');
-}
-
-/**
- * Resolve the running framework version from the root `package.json`. Degrades
- * to {@link FALLBACK_VERSION} (never throws) on any read or parse failure so a
- * missing/unreadable manifest can never crash an authoring or hydration path.
- *
- * @param {{ pkgPath?: string }} [opts] - `pkgPath` override (test seam).
- * @returns {string}
- */
-export function resolveFrameworkVersion({ pkgPath } = {}) {
-  try {
-    const resolved = typeof pkgPath === 'string' ? pkgPath : defaultPkgPath();
-    const parsed = JSON.parse(fs.readFileSync(resolved, 'utf8'));
-    return typeof parsed.version === 'string' && parsed.version.trim()
-      ? parsed.version.trim()
-      : FALLBACK_VERSION;
-  } catch {
-    return FALLBACK_VERSION;
-  }
-}
-
-/**
- * Format an authoring date as `YYYY-MM-DD` (UTC). Matches the date shape the
- * rest of the authoring path uses (e.g. `qa-session`).
- *
- * @param {Date} [date=new Date()]
- * @returns {string}
- */
-export function formatAuthoredDate(date = new Date()) {
-  const d =
-    date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
-  return d.toISOString().slice(0, 10);
-}
-
-/**
- * Build the visible authoring marker line for a given stamp. Centralised so
- * the string is byte-identical across the two producers (the Story-body
- * serializer and {@link stampFrameworkVersion}).
+ * Build the visible authoring marker line for a given stamp. The Story-body
+ * serializer uses this to re-emit a legacy stamp it parsed, byte-identically.
  *
  * @param {{ version: string, authoredAt: string }} stamp
  * @returns {string}
@@ -109,101 +37,3 @@ export function formatAuthoredDate(date = new Date()) {
 export function authoredMarkerLine({ version, authoredAt }) {
   return `> 🏷️ Authored with Mandrel v${version} · ${authoredAt}`;
 }
-
-/**
- * Read the framework stamp from a body's trailing meta block. Returns
- * `{ version, authoredAt }` when a non-empty `mandrel_version` is present, or
- * `null` when the body carries no stamp (or the meta block is malformed).
- * `authoredAt` is `null` when the version is present but the date is absent.
- *
- * @param {string} markdown
- * @returns {{ version: string, authoredAt: string|null }|null}
- */
-export function extractFrameworkStamp(markdown) {
-  if (typeof markdown !== 'string') return null;
-  const match = markdown.match(META_BLOCK_RE);
-  if (!match) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(match[1]);
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return null;
-  }
-  const version =
-    typeof parsed.mandrel_version === 'string' && parsed.mandrel_version.trim()
-      ? parsed.mandrel_version.trim()
-      : null;
-  if (version === null) return null;
-  const authoredAt =
-    typeof parsed.authored_at === 'string' && parsed.authored_at.trim()
-      ? parsed.authored_at.trim()
-      : null;
-  return { version, authoredAt };
-}
-
-/**
- * Stamp a ticket body (Epic or Story markdown) with the framework version and
- * authoring date — **once**. When the body already carries a `mandrel_version`
- * the body is returned verbatim (immutability: never re-derive or bump an
- * already-authored stamp). Otherwise the version keys are merged into (or
- * create) the trailing `<!-- meta -->` block — appended **last** so the key
- * order stays stable with the Story-body serializer — and the visible marker
- * line is (re)emitted just above it.
- *
- * The `version` / `authoredAt` overrides let a caller (e.g. the Epic edit path)
- * preserve a previously-authored stamp; both default to the running version and
- * today's date when omitted.
- *
- * @param {string} markdown
- * @param {{ version?: string, authoredAt?: string }} [stamp]
- * @returns {string}
- */
-export function stampFrameworkVersion(markdown, stamp = {}) {
-  const body = typeof markdown === 'string' ? markdown : '';
-
-  // Immutability: a body that already carries a version is preserved verbatim.
-  if (extractFrameworkStamp(body) !== null) return body;
-
-  const version =
-    typeof stamp?.version === 'string' && stamp.version.trim()
-      ? stamp.version.trim()
-      : resolveFrameworkVersion();
-  const authoredAt =
-    typeof stamp?.authoredAt === 'string' && stamp.authoredAt.trim()
-      ? stamp.authoredAt.trim()
-      : formatAuthoredDate();
-
-  // Merge into any existing (version-less) meta block, appending the version
-  // keys last for stable key order.
-  const metaMatch = body.match(META_BLOCK_RE);
-  const meta = {};
-  if (metaMatch) {
-    try {
-      const parsed = JSON.parse(metaMatch[1]);
-      if (
-        parsed !== null &&
-        typeof parsed === 'object' &&
-        !Array.isArray(parsed)
-      ) {
-        Object.assign(meta, parsed);
-      }
-    } catch {
-      // Malformed meta comment — drop it and re-emit a clean block.
-    }
-  }
-  meta.mandrel_version = version;
-  meta.authored_at = authoredAt;
-
-  // Strip any existing meta block / marker so both re-append canonically.
-  const head = body
-    .replace(META_BLOCK_RE, '')
-    .replace(new RegExp(AUTHORED_MARKER_LINE_RE.source, 'm'), '')
-    .replace(/\n{3,}/g, '\n\n')
-    .trimEnd();
-
-  const marker = authoredMarkerLine({ version, authoredAt });
-  return `${head}\n\n${marker}\n\n<!-- meta: ${JSON.stringify(meta)} -->`;
-}

package/.agents/scripts/lib/gh-exec.js

@@ -505,6 +505,14 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
       execWithDefaults({ args: ['pr', 'edit', idStr(id), ...flags] }),
     merge: (id, flags = []) =>
       execWithDefaults({ args: ['pr', 'merge', idStr(id), ...flags] }),
+    /**
+     * Bring a `mergeStateStatus: BEHIND` PR up to date with its base
+     * (Story #4543). The close-and-land merge wait calls this a bounded
+     * number of times rather than waiting out its budget behind a base it
+     * could have caught up to.
+     */
+    updateBranch: (id, flags = []) =>
+      execWithDefaults({ args: ['pr', 'update-branch', idStr(id), ...flags] }),
     list: (flags = [], fields) =>
       execWithDefaults({
         args: ['pr', 'list', ...flags, ...jsonFlag(fields)],