mandrel 2.59.0 → 2.60.0

package/.agents/scripts/plan-context.js

@@ -24,21 +24,22 @@
  *                             scratch (Story #4741). Envelope carries `amends`.
  *
  * Flags:
- *   --out <path>     Write the envelope to <path> (parent dirs created).
- *                    `/mandrel-plan` points this at `<plan-dir>/plan-context.json`,
- *                    which is where `plan-persist.js` auto-discovers the
- *                    `--tickets` source ids from (Story #4554). Without a
- *                    captured envelope persist cannot know a `--tickets` run
- *                    happened, and superseding degrades to the
- *                    `--source-tickets` flag. With --out, stdout carries a
- *                    compact digest naming the artifact instead of the full
- *                    envelope (Story #4708 script-output contract).
- *   --pretty         Pretty-print the JSON envelope (no-op with --out).
+ *   --out <path>     Override where the envelope is written (parent dirs
+ *                    created). **Optional since Story #5342** — with no
+ *                    `--out` the envelope lands at
+ *                    `<tempRoot>/plan-<slug>/plan-context.json`, the plan
+ *                    directory `/mandrel-plan` would have named by hand, and
+ *                    `stories.template.json` lands beside it. That is where
+ *                    `plan-persist.js` auto-discovers the `--tickets` source
+ *                    ids from (Story #4554); without a captured envelope
+ *                    persist cannot know a `--tickets` run happened, and
+ *                    superseding degrades to the `--source-tickets` flag.
+ *   --pretty         Pretty-print the written JSON envelope.
  *
  * stdout is reserved for a single JSON payload (Story #2278 discipline) —
- * the envelope, or the digest when --out captures it:
- * `routeAllOutputToStderr()` runs before any pipeline code so the stream
- * is unconditionally parseable by `JSON.parse`.
+ * the compact digest naming the written artifacts (Story #4708
+ * script-output contract): `routeAllOutputToStderr()` runs before any
+ * pipeline code so the stream is unconditionally parseable by `JSON.parse`.
  *
  * Exit codes:
  *   0 — envelope emitted.
@@ -54,6 +55,8 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import {
+  getPaths,
+  PROJECT_ROOT,
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
@@ -66,6 +69,77 @@ import {
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
+/** Longest slug segment a default plan directory carries. */
+const PLAN_SLUG_MAX_LENGTH = 48;
+
+/**
+ * Reduce free text to the hyphen-case segment a plan directory is named by.
+ *
+ * Deliberately lossy: the slug is a human-readable handle on a temp
+ * directory, not an identity — two runs from the same seed land in the same
+ * directory and the second overwrites the first, which is the idempotent
+ * behaviour the operator already got from typing the same `--out` twice.
+ *
+ * @param {string} raw
+ * @returns {string} A non-empty hyphen-case slug (`plan` when nothing survives).
+ */
+export function slugifyPlanLabel(raw) {
+  const slug = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, PLAN_SLUG_MAX_LENGTH)
+    .replace(/-+$/, '');
+  return slug === '' ? 'plan' : slug;
+}
+
+/**
+ * Resolve where the envelope is written when the operator passed no `--out`
+ * (Story #5342).
+ *
+ * `--out` was mandatory in practice and optional in the CLI: persist
+ * auto-discovers the envelope and the `stories.template.json` beside it from
+ * the plan directory, so a run without it silently lost superseding and the
+ * authoring skeleton. The path it always pointed at is derivable — the
+ * configured `tempRoot`, a `plan-<slug>` directory named for what is being
+ * planned — so the CLI derives it rather than asking.
+ *
+ * Exported for tests: this is the join where a missing flag stops costing
+ * the plan its source ids.
+ *
+ * @param {object} args
+ * @param {string} args.mode One of `seed` | `seed-file` | `tickets` | `amends`.
+ * @param {string} [args.seedText]
+ * @param {string} [args.seedFilePath]
+ * @param {number[]} [args.ticketIds]
+ * @param {number} [args.amendsId]
+ * @param {object} [args.config] Resolved config (for `project.paths.tempRoot`).
+ * @param {string} [args.cwd]
+ * @returns {string} Absolute path to the envelope file.
+ */
+export function resolveDefaultOutPath({
+  mode,
+  seedText,
+  seedFilePath,
+  ticketIds,
+  amendsId,
+  config,
+  cwd = PROJECT_ROOT,
+}) {
+  const byMode = {
+    amends: () => `amends-${amendsId}`,
+    tickets: () => `tickets-${(ticketIds ?? []).join('-')}`,
+    'seed-file': () => path.parse(String(seedFilePath ?? '')).name,
+  };
+  const label = (byMode[mode] ?? (() => String(seedText ?? '')))();
+  return path.resolve(
+    cwd,
+    getPaths(config).tempRoot,
+    `plan-${slugifyPlanLabel(label)}`,
+    'plan-context.json',
+  );
+}
+
 /**
  * Parse a comma-/space-separated ticket id list into positive integers.
  *
@@ -109,8 +183,10 @@ export function parseAmendsId(raw) {
 }
 
 /**
- * Build the envelope and write it to `stdout` as a single JSON line
- * (or pretty-printed with --pretty). Exported for tests.
+ * Build the envelope, write it (plus the `stories.template.json` skeleton)
+ * to `outPath` — or to the derived default when none was passed
+ * (Story #5342) — and print the compact digest on stdout. Exported for
+ * tests.
  *
  * @param {object} args
  * @returns {Promise<object>} the emitted envelope.
@@ -145,14 +221,26 @@ export async function emitPlanContext({
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  if (outPath) {
+  const resolvedOut =
+    outPath ??
+    resolveDefaultOutPath({
+      mode,
+      seedText,
+      seedFilePath,
+      ticketIds,
+      amendsId,
+      config,
+      cwd: cwd ?? undefined,
+    });
+  {
     // Script-output contract (Story #4708, AC-5): the full envelope is a
     // ~40KB artifact that would ride resident in the transcript for every
-    // later turn. When it is captured to disk anyway, stdout carries a
-    // compact digest naming the artifact instead of the payload itself.
-    await writeEnvelopeFile(outPath, json);
-    await writeStoriesTemplateFile(outPath, envelope);
-    const resolved = path.resolve(outPath);
+    // later turn. It is always captured to disk (Story #5342 derives the
+    // path when `--out` is absent), so stdout carries a compact digest
+    // naming the artifacts instead of the payload itself.
+    await writeEnvelopeFile(resolvedOut, json);
+    await writeStoriesTemplateFile(resolvedOut, envelope);
+    const resolved = path.resolve(resolvedOut);
     const digest = {
       digest: 'plan-context',
       mode: envelope.mode,
@@ -182,8 +270,6 @@ export async function emitPlanContext({
       amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
-  } else {
-    stdout.write(`${json}\n`);
   }
   return envelope;
 }
@@ -216,8 +302,8 @@ async function writeEnvelopeFile(outPath, json) {
  * Emit the ready-to-fill Story authoring template next to the captured
  * envelope (Story #4707 — one-shot authoring). The planner copies it to
  * `stories.json` and fills the placeholders; no step of the authoring path
- * requires reading `story-body.js` source. Written whenever `--out` is
- * passed, and throwing on failure for the same reason the envelope write
+ * requires reading `story-body.js` source. Written on every run (Story
+ * #5342), and throwing on failure for the same reason the envelope write
  * does: a silently missing template re-opens the format-discovery loop it
  * exists to close. The envelope's advisory `complexitySignals` are threaded
  * through so the skeleton's `changes[]` arrive pre-resolved to
@@ -346,14 +432,17 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-context.js (--seed "<text>" | --seed-file <path> | --tickets <ids> | --amends <id>) [--out <path>] [--pretty]',
     summary:
-      'Build the /mandrel-plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
+      'Build the /mandrel-plan authoring-context envelope. Writes it (and stories.template.json) under <tempRoot>/plan-<slug>/ and prints the digest on stdout. Exactly one entry form must be supplied.',
     flags: [
       ['--seed "<text>"', 'Inline seed prose.'],
       ['--seed-file <path>', 'Seed document to read.'],
       ['--tickets <ids>', 'Comma-separated existing ticket ids to re-plan.'],
       ['--amends <id>', 'Amend the Spec of an existing Story.'],
-      ['--out <path>', 'Write the envelope to a file instead of stdout.'],
-      ['--pretty', 'Pretty-print the JSON envelope.'],
+      [
+        '--out <path>',
+        'Override the derived <tempRoot>/plan-<slug>/plan-context.json path.',
+      ],
+      ['--pretty', 'Pretty-print the written JSON envelope.'],
     ],
   },
 });

package/.agents/scripts/plan-persist.js

@@ -10,8 +10,8 @@
  *   changes[] repair → ticket validator / DAG → reachability →
  *   split-policy partition → fold Spec into each Story body →
  *   createIssue(s) with type::story, resumably by plan fingerprint (NOT
- *   agent::ready) → story-plan-state on every Story;
- *   plan-summary on the primary → flip every Story to agent::ready →
+ *   agent::ready) → one `story-plan-state` comment (the plan summary) on
+ *   every Story → flip every Story to agent::ready →
  *   comment + close superseded source tickets → temp cleanup + stale reap.
  *
  * Story #4542 retired the authored risk verdict: persist neither requires nor
@@ -36,20 +36,16 @@
  *   --no-close-superseded     Keep the source tickets open (no comment, no
  *                             close) — for a genuinely partial supersede
  *   --dry-run                 Assemble + validate without GitHub writes
- *   --chain-on-clean          Fast path (Story #4741; any plan since Story
- *                             #5312): run the write-free dry-run first, and
- *                             when it passes clean chain straight into the
- *                             real persist in the SAME invocation, collapsing
- *                             the two operator round-trips into one. A
- *                             dry-run failure stops before any createIssue.
- *                             Ignored when `--dry-run` is also set
  *   --force-review            Operator-forced review stop before persist lands
  *
- * Run `--dry-run` first. It exercises every gate — the changes[] repair, the
- * validator, DAG, reachability, split/supersede partition, Spec fold —
- * write-free, and lists every warning (a footprint probe that disagrees with
- * the base branch, an open question in a body) so an authoring mistake
- * surfaces before a single issue exists.
+ * **Persist is one command (Story #5342).** Without `--dry-run` the CLI runs
+ * the write-free dry-run first — the
+ * changes[] repair, the validator, DAG, reachability, split/supersede
+ * partition, Spec fold — and, when the gate list comes back clean, chains
+ * straight into the real persist in the SAME invocation. A dry-run failure
+ * stops before any `createIssue`, and the run lists every warning (a
+ * footprint probe that disagrees with the base branch, an empty `verify[]`,
+ * an open question in a body) either way. `--dry-run` still creates nothing.
  *
  * stdout is reserved for the JSON result (Story #2278 discipline, extended to
  * this CLI by Story #4541): `routeAllOutputToStderr()` runs before any
@@ -82,12 +78,11 @@ import {
 } from './lib/orchestration/plan-persist/plan-context-source.js';
 import {
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 } from './lib/orchestration/plan-persist/run-plan-persist.js';
 import {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
 } from './lib/orchestration/plan-persist/summary.js';
 import { resolveSourceTicketIds } from './lib/orchestration/plan-persist/supersede-ops.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -95,9 +90,8 @@ import { createProvider } from './lib/provider-factory.js';
 export {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 };
 
 const CLI_OPTIONS = {
@@ -109,7 +103,6 @@ const CLI_OPTIONS = {
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
-  'chain-on-clean': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'epic-title': { type: 'string' },
   'epic-goal': { type: 'string' },
@@ -120,7 +113,7 @@ const USAGE =
   'Usage: plan-persist.js --stories <file> ' +
   '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
-  '[--dry-run] [--chain-on-clean] [--force-review] ' +
+  '[--dry-run] [--force-review] ' +
   '[--epic-title <text> --epic-goal <text> | --epic <id>]';
 
 async function readOptional(filePath, { required }) {
@@ -320,8 +313,9 @@ async function runPersistInvocation({
 }
 
 /**
- * Fast path (Story #4741 AC-1/AC-3; widened to any plan by Story #5312):
- * chain a clean dry-run into the real persist in ONE operator invocation.
+ * The default persist path (Story #4741 AC-1/AC-3; widened to any plan by
+ * Story #5312; made the default by Story #5342): chain a clean dry-run into
+ * the real persist in ONE operator invocation.
  *
  * Two passes over the **same** loaded artifacts:
  *
@@ -334,6 +328,14 @@ async function runPersistInvocation({
  *      to gate this step went with the plan-side lite claim: a clean dry-run
  *      is the review the chain exists to fold.
  *
+ * The caller reads the **second** pass's envelope, so the first pass's
+ * evidence has to be carried onto it (Story #5361). The repair pass mutates
+ * the loaded tickets in place, which is what makes replaying the identical
+ * artifacts possible at all — and it is also why pass 2 recomputes an empty
+ * `repairs[]`: by then there is nothing left to repair. The evidence is
+ * preserved rather than re-derived, because re-running the repair pass would
+ * report repairs the persisting pass did not make.
+ *
  * Exported for tests — this is where the round-trip collapse lives, so a
  * regression here silently re-opens the second operator round-trip (or
  * worse, persists a plan the dry-run never gated).
@@ -366,6 +368,14 @@ export async function runPersistChain({
     metricsSince,
     dryRun: false,
   });
+  persistResult.repairs = mergeEvidence(
+    dryResult.repairs,
+    persistResult.repairs,
+  );
+  persistResult.warnings = mergeEvidence(
+    dryResult.warnings,
+    persistResult.warnings,
+  );
   persistResult.chain = {
     attempted: true,
     persisted: true,
@@ -374,6 +384,51 @@ export async function runPersistChain({
   return persistResult;
 }
 
+/**
+ * Union two evidence lists, dry-run first, dropping an entry the second pass
+ * reported identically. Order is the operator's reading order; the dedupe is
+ * by rendered content because a repair is a plain record and a warning is a
+ * string, so two passes that noticed the same thing noticed it byte-for-byte.
+ *
+ * @param {unknown} first
+ * @param {unknown} second
+ * @returns {unknown[]}
+ */
+function mergeEvidence(first, second) {
+  const merged = [];
+  const seen = new Set();
+  for (const entry of [
+    ...(Array.isArray(first) ? first : []),
+    ...(Array.isArray(second) ? second : []),
+  ]) {
+    const key = JSON.stringify(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+  }
+  return merged;
+}
+
+/**
+ * Decide whether this invocation persists after its gates, or only validates.
+ *
+ * Story #5342: chaining is the default, not a flag. Every invocation that is
+ * not an explicit `--dry-run` runs the gate list and then persists what it
+ * passed, so the two operator round-trips collapse without anyone having to
+ * remember an opt-in. Story #5361 removed the no-op alias Story #5342 had
+ * kept for existing call-sites, rather than accepting and ignoring it: a flag
+ * that cannot change an outcome is a shim, and `parseArgs` refuses an unknown
+ * option, so passing it now fails loudly instead of reading as honoured.
+ *
+ * Exported for tests: this one predicate is what makes the CLI one command.
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ * @returns {boolean} `true` to run the gates and then persist.
+ */
+export function shouldChainPersist(values) {
+  return values?.['dry-run'] !== true;
+}
+
 /**
  * Attach the plan-metrics roll-up for **this** invocation.
  *
@@ -440,10 +495,7 @@ async function main() {
   const paths = resolveInputPaths(values);
   const artifacts = await loadArtifacts(paths);
 
-  // `--chain-on-clean` collapses the dry-run + persist operator round-trips
-  // (Story #4741). `--dry-run` always wins — an explicit dry-run never writes.
-  const useChain =
-    values['chain-on-clean'] === true && values['dry-run'] !== true;
+  const useChain = shouldChainPersist(values);
 
   let result;
   try {
@@ -482,7 +534,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-persist.js --stories <file> [--tech-spec <file>] [--dry-run] [options]',
     summary:
-      'Validate an authored plan and persist it as GitHub Stories. Prints the result envelope as JSON on stdout.',
+      'Validate an authored plan and persist it as GitHub Stories in one invocation (pass --dry-run to validate only). Prints the result envelope as JSON on stdout.',
     flags: [
       ['--stories <file>', 'Authored stories.json (required).'],
       ['--tech-spec <file>', 'Optional companion techspec.md.'],
@@ -493,7 +545,6 @@ runAsCli(import.meta.url, main, {
       ],
       ['--source-tickets <ids>', 'Ticket ids this plan supersedes.'],
       ['--dry-run', 'Validate and report; create nothing.'],
-      ['--chain-on-clean', 'Persist immediately when the dry run is clean.'],
       ['--no-close-superseded', 'Leave superseded source tickets open.'],
       [
         '--force-review',

package/.agents/scripts/plan-run-epilogue.js

@@ -25,6 +25,8 @@ import { expandIdList } from './lib/util/parse-id-list.js';
 const CLI_OPTIONS = {
   stories: { type: 'string' },
   cwd: { type: 'string' },
+  /** Story #5343 — opt-in; see `run-epilogue.js` RUN_EPILOGUE_STEP_KINDS. */
+  'audit-roster': { type: 'boolean', default: false },
 };
 
 /**
@@ -51,15 +53,10 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     options: CLI_OPTIONS,
     strict: false,
   });
-  const hasStoriesFlag =
-    typeof values.stories === 'string' && values.stories.trim().length > 0;
-  if (!hasStoriesFlag) {
+  if (typeof values.stories !== 'string' || !values.stories.trim()) {
     throw new Error('Usage: node plan-run-epilogue.js --stories 1,2,3');
   }
-  const cwd =
-    typeof values.cwd === 'string' && values.cwd.trim()
-      ? values.cwd.trim()
-      : process.cwd();
+  const cwd = values.cwd?.trim() || process.cwd();
   const config = resolveConfigImpl({ cwd });
   const provider = createProviderImpl(config);
 
@@ -87,6 +84,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     provider,
     config,
     cwd,
+    auditRoster: values['audit-roster'] === true,
   });
   warnOnUnresolvedBase(result, logger);
   warnOnEmptyRollup(result, logger);
@@ -99,6 +97,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 
 /**
  * Surface an unresolvable combined landed diff as a loud operator warning.
+ * Only reachable under `--audit-roster`: a default run enumerates no roster.
  *
  * The roster's changed-file set is the input the host walks its audit lenses
  * against; a silent absence would read as "nothing changed" and the lens walk
@@ -167,7 +166,7 @@ function warnOnEmptyRollup(result, logger = Logger) {
 await runAsCli(import.meta.url, main, {
   usage: {
     invocation:
-      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>]',
+      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>] [--audit-roster]',
     summary:
       'Close out a delivery run: roll up the delivered Stories’ signals and report the run’s loop health.',
     flags: [
@@ -176,6 +175,10 @@ await runAsCli(import.meta.url, main, {
         'Comma-separated delivered Story ids, singles or A-B ranges (required).',
       ],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
+      [
+        '--audit-roster',
+        'Also select the cross-Story audit lens roster and post plan-run-audit-roster (off by default; the host then walks every listed lens).',
+      ],
     ],
   },
 });

package/.agents/scripts/pr-watch-with-update.js

@@ -458,12 +458,19 @@ async function evaluateGreenWatch({
   }
   const headSha = headShaFn({ prRef, cwd });
   const { verdict, reason } = classifyGreenVerdict({ digest, headSha });
-  if (verdict === 'fix-at-source') {
+  if (verdict === 'fix-at-source' || verdict === 'rerun-permitted') {
+    // Story #5343 — `rerun-permitted` is the one same-SHA green the rule
+    // admits: `file-ci-gap.js` recorded a proven `capacity` /
+    // `unreproducible-tier` verdict for THIS head, so there is no fix at
+    // source to make. Retiring the digest spends the allowance with it, which
+    // is what makes it exactly one: a second red writes a fresh digest that
+    // carries none.
     retireDigestFn({ storyId, tempRoot, cwd });
     const reArm = await reArmFn({ cwd, prNumber });
     const reArmed = Boolean(reArm?.enabled);
     logger.info?.(
-      `[pr-watch] green on a NEW head SHA (${reason}) — fix at source; digest retired, ` +
+      `[pr-watch] ${verdict === 'rerun-permitted' ? 'green admitted on the SAME head SHA' : 'green on a NEW head SHA'} ` +
+        `(${reason}) — digest retired, ` +
         `auto-merge ${reArmed ? 're-armed' : `NOT re-armed (${reArm?.reason ?? 'unknown'})`}.`,
     );
     return { verdict, reason, exitCode: 0, headSha, reArmed };

package/.agents/scripts/run-verify.js

@@ -7,7 +7,8 @@
  *
  * Order: audit (SCA) → lint (includes docs:check + the arch-cycles ratchet) →
  * full test suite → unified baselines → the standalone ratchets
- * (dead-exports ×2, context-budget, cyclomatic, schema-references).
+ * (dead-exports ×2, context-budget, workflow-citations, cyclomatic,
+ * schema-references).
  *
  * The `audit` step runs `npm audit --audit-level=high`, matching CI's
  * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
@@ -33,9 +34,14 @@
  * being added here, so a green `verify` still hid both. Like their neighbours
  * they are pure-Node and cost milliseconds.
  *
- * Still NOT mirrored: `check-workflow-citations.js` and
- * `check-baseline-scope.js` run in CI's `baselines` job only —
- * `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
+ * Story #5340 closed the `check-workflow-citations.js` gap the same way, once
+ * demoting it to a report made it free: it had been exempted here because
+ * `tests/check-workflow-citations.test.js` re-ran the same ratchet, so a
+ * `verify` step would have double-paid it. That test now asserts the report,
+ * not a ceiling, so the step is the only local surface that prints the count.
+ *
+ * Still NOT mirrored: `check-baseline-scope.js` runs in CI's `baselines` job
+ * only — `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
  * coverage table. (`prune-baseline-orphans.js --check` used to sit in that
  * list; it no longer runs in CI at all — the un-attributed duplicate of the
  * scope gate's `extra` direction reds every open PR on inherited rows.) Nor are the CI gates this command structurally cannot
@@ -50,8 +56,8 @@ import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 
 /**
- * A gate step: `node .agents/scripts/<script>` plus any extra args. Seven of
- * the ten steps share exactly that shape, so spelling it once leaves the list
+ * A gate step: `node .agents/scripts/<script>` plus any extra args. Eight of
+ * the eleven steps share exactly that shape, so spelling it once leaves the list
  * below readable as what it actually is — a gate *order* — instead of a wall
  * of spawn tuples.
  *
@@ -79,6 +85,7 @@ const STEPS = [
   gate('dead-exports', 'check-dead-exports.js'),
   gate('dead-exports-production', 'check-dead-exports.js', '--production'),
   gate('context-budget', 'check-context-budget.js'),
+  gate('workflow-citations', 'check-workflow-citations.js'),
   gate('cyclomatic', 'check-cyclomatic.js'),
   gate('schema-references', 'check-schema-references.js'),
 ];

package/.agents/scripts/single-story-init.js

@@ -70,7 +70,6 @@ import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-
 import {
   STATE_LABELS,
   transitionTicketState,
-  upsertStructuredComment,
 } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
@@ -770,28 +769,13 @@ export async function runSingleStoryInit({
     remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
-  // Upsert the `story-init` structured comment (no-op under --dry-run). The
-  // `agent::executing` flip already happened above, before provisioning, so the
-  // claim is label-visible during the install window (see `flipStoryToExecuting`).
-  if (!dryRun) {
-    try {
-      await upsertStructuredComment(
-        provider,
-        storyId,
-        'story-init',
-        renderSingleStoryInitComment(result),
-      );
-      progress(
-        'COMMENT',
-        `📝 Upserted story-init structured comment on #${storyId}.`,
-      );
-    } catch (err) {
-      Logger.error(
-        `[single-story-init] ⚠️ Failed to upsert story-init structured comment: ${err?.message ?? err}`,
-      );
-    }
-  }
-
+  // Story #5343 — init posts no `story-init` comment. It was one GitHub write
+  // per Story restating what its own envelope already carries; the envelope is
+  // on stdout and on disk (below), `deliver-recover.js` classifies state from
+  // labels, the PR probe and disk artifacts, and `run-scoped-config.js` reads
+  // the base-branch pin off that same envelope. The `agent::executing` flip
+  // above is what makes the claim visible during the install window.
+  //
   // Story #4685 — route the full result to a temp log and emit a single-line
   // summary carrying the fields the orchestrating agent acts on (workCwd,
   // remoteVerified). The `## Spec` names this the hot-path stdout to quiet.
@@ -820,40 +804,6 @@ export async function runSingleStoryInit({
   return { success: true, result };
 }
 
-export function renderSingleStoryInitComment(result) {
-  const payload = {
-    storyId: result.storyId,
-    epicId: null,
-    standalone: true,
-    storyBranch: result.storyBranch,
-    baseBranch: result.baseBranch,
-    runScopedConfig: result.runScopedConfig,
-    worktreeEnabled: result.worktreeEnabled,
-    workCwd: result.workCwd,
-    worktreeCreated: result.worktreeCreated,
-    dependenciesInstalled: result.dependenciesInstalled,
-    installStatus: result.installStatus,
-    remoteVerified: result.remoteVerified,
-    remoteProbe: result.remoteProbe,
-  };
-  return [
-    '## Story init (standalone)',
-    '',
-    `- **standalone:** \`true\``,
-    `- **storyBranch:** \`${result.storyBranch}\``,
-    `- **baseBranch:** \`${result.baseBranch}\``,
-    `- **workCwd:** \`${result.workCwd}\``,
-    `- **worktreeEnabled:** \`${result.worktreeEnabled}\``,
-    `- **remoteVerified:** \`${result.remoteVerified}\``,
-    `- **dependenciesInstalled:** \`${result.dependenciesInstalled}\``,
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-    '',
-  ].join('\n');
-}
-
 runAsCli(import.meta.url, runSingleStoryInit, {
   source: 'single-story-init',
   usage: {