mandrel 2.24.0 → 2.25.0

package/.agents/scripts/quality-preview.js

@@ -191,6 +191,29 @@ export function mergeEnvelopes(miEnvelope, crapEnvelope) {
   };
 }
 
+/**
+ * Render the named diagnostics a gate envelope carries, or `null` when it
+ * carries none (Story #4866).
+ *
+ * A diagnostic is what a gate emits *instead of* per-method verdicts when it
+ * has established that no verdict it could produce would be meaningful — an
+ * incomparable baseline, or a comparison basis whose drifted-row ratio proves
+ * the two sides disagree on line coordinates. It must reach the operator
+ * verbatim: the gate exits 0, so silence would read as a clean run.
+ *
+ * @param {Array<{ envelope: { diagnostics?: Array<{name: string, message: string}> } | null }>} results
+ * @returns {string | null}
+ */
+export function renderDiagnostics(results) {
+  const lines = [];
+  for (const { envelope } of results ?? []) {
+    for (const d of envelope?.diagnostics ?? []) {
+      lines.push(`[${d.name}] ${d.message}`);
+    }
+  }
+  return lines.length === 0 ? null : lines.join('\n');
+}
+
 /**
  * Compute the CLI exit code from a merge result + per-gate exit codes. Pure.
  *
@@ -320,6 +343,8 @@ export async function runCli({
         : `scope=diff ref=${ref}\n\n`,
     );
     stdout.write(`${renderTable(merged)}\n`);
+    const diagnostics = renderDiagnostics([miResult, crapResult]);
+    if (diagnostics) stdout.write(`\n${diagnostics}\n`);
     if (miExit !== 0 || crapExit !== 0) {
       stderr.write(
         `\n[quality:preview] gate exits: mi=${miExit} crap=${crapExit}\n`,

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

@@ -32,6 +32,7 @@ import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
@@ -165,6 +166,7 @@ export function runTestSuite({
   cleanup = cleanupRepoTestTempArtifacts,
   listTargets = listTestFilesForTier,
   maxTargetChars = resolveMaxTargetChars(),
+  fixtureStreamGuard = assertNoReservedIdStreams,
 } = {}) {
   const { tier, rest } = parseTierArgv(argv);
   const targets = listTargets(tier, cwd);
@@ -192,6 +194,14 @@ export function runTestSuite({
 
   cleanup({ repoRoot: cwd });
 
+  // A test that spawns a real CLI at the repository root inherits the real
+  // state directory, so its fixture telemetry can land in the operator's live
+  // signals tree — where the retro graduator counts it as recurrence evidence
+  // and files a ticket citing a fixture Story id. Fail the run that caused it
+  // rather than discovering it from that ticket.
+  const polluted = fixtureStreamGuard({ cwd });
+  if (polluted !== 0 && status === 0) status = polluted;
+
   if (spawnError) {
     throw spawnError;
   }

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

@@ -90,6 +90,7 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { resolveRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
 import {
   failedTerminalFor,
   gatesForFailedPhase,
@@ -123,12 +124,17 @@ export const enableAutoMerge = enableAutoMergeWith;
 // `gatesForFailedPhase` now lives beside the envelope it feeds
 // (`single-story-close/failed-terminal.js`); it is re-exported here so the
 // CLI's public surface is unchanged by that move.
+// `resolveRunScopedConfig` (Story #4891) is the run-scoped config pin the
+// pipeline reads before its first phase; it is part of this CLI's surface for
+// the same reason the sync helpers are — the runner reaches it only through a
+// dynamic import, so this file is where it is statically visible.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
   gatesForFailedPhase,
   handleSyncFailure,
   parsePrNumber,
+  resolveRunScopedConfig,
   runStoryScopeReview,
 };
 

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

@@ -61,6 +61,7 @@ import {
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
 import { verifyRemote } from './lib/orchestration/remote-verifier.js';
+import { pinRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
 import {
   acquireStoryLease,
   releaseStoryLease,
@@ -735,6 +736,11 @@ export async function runSingleStoryInit({
     standalone: true,
     storyBranch,
     baseBranch,
+    // The write half of the run-scoped config pin. `baseBranch` above is the
+    // legacy field close still reads as a fallback; this block is the
+    // registry-driven form a second run-scoped key joins without a second
+    // mechanism (`lib/orchestration/run-scoped-config.js`).
+    runScopedConfig: pinRunScopedConfig(config),
     storyTitle: story.title,
     worktreeEnabled: runtime.worktreeEnabled,
     workCwd,
@@ -805,6 +811,7 @@ export function renderSingleStoryInitComment(result) {
     standalone: true,
     storyBranch: result.storyBranch,
     baseBranch: result.baseBranch,
+    runScopedConfig: result.runScopedConfig,
     worktreeEnabled: result.worktreeEnabled,
     workCwd: result.workCwd,
     worktreeCreated: result.worktreeCreated,

package/.agents/scripts/stories-wave-tick.js

@@ -75,7 +75,9 @@
  * `/deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
- * overrides the config-resolved value for that run only. This shares one
+ * overrides the config-resolved value for that run only, and the envelope's
+ * `capPrecedence` names which source won so the override is never silent
+ * (Story #4875). This shares one
  * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
  * one scheduling kernel with every `/deliver` multi-Story invocation.
  *
@@ -167,7 +169,10 @@ Options:
   --concurrency <n>  Override the per-beat concurrency cap for this run only.
                      Must be a positive integer. When omitted, the cap is
                      resolved from delivery.deliverRunner.concurrencyCap in
-                     .agentrc.json / .agentrc.local.json (default 3).
+                     .agentrc.json / .agentrc.local.json (default 3). The flag
+                     WINS over the configured value, and the envelope's
+                     capPrecedence records that it did — including when the
+                     request exceeds the configured cap.
   --done <csv>       Comma-separated Story IDs already completed this run.
                      Their dependents become eligible; they are never
                      re-dispatched. Defaults to empty.
@@ -181,6 +186,14 @@ Output envelope:
     "ready": [101],
     "totalStories": 2,
     "concurrencyCap": 3,
+    "capPrecedence": {
+      "cap": 3,
+      "source": "config",
+      "configuredCap": 3,
+      "requestedCap": null,
+      "exceedsConfigured": false,
+      "note": "..."
+    },
     "inFlight": 0,
     "cycleError": null,
     "wedged": null
@@ -214,6 +227,7 @@ function inputErrorResult(message, concurrencyCap = null, inFlightValue = 0) {
       ready: [],
       totalStories: 0,
       concurrencyCap,
+      capPrecedence: null,
       inFlight: inFlightValue,
       cycleError: null,
       wedged: null,
@@ -394,13 +408,69 @@ export function parseConcurrencyOverride(raw) {
  *                                   `--concurrency`; wins over config.
  * @returns {number} The resolved positive-integer concurrency cap.
  */
-export function resolveConcurrencyCap({ cwd, config, override } = {}) {
-  if (override != null) {
-    return override;
-  }
+export function resolveConcurrencyCap(opts = {}) {
+  return resolveCapPrecedence(opts).cap;
+}
+
+/**
+ * Resolve the per-beat cap **and the precedence that produced it** (Story
+ * #4875).
+ *
+ * `--concurrency` wins over `delivery.deliverRunner.concurrencyCap`, and that
+ * is the intended contract — a flag an operator typed for one run should not be
+ * outranked by a checked-in default. What was wrong is that it won *silently*:
+ * the envelope reported a single `concurrencyCap` number with no record of
+ * which source set it, so a run at 8 when the project configured 3 was
+ * indistinguishable from a project configured at 8. A reader could not tell an
+ * override from a default, and an override that ran the repo above its own
+ * configured ceiling left no trace at all.
+ *
+ * So the flag still wins, but never quietly: the source is named, the
+ * configured value is carried alongside the requested one, and a request that
+ * exceeds the configured cap is called out as such. Reporting rather than
+ * refusing is deliberate — the configured cap is a project default, not a
+ * safety limit, and refusing a deliberate operator escalation would trade a
+ * silent override for a silent stall.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]      Repo root for config resolution.
+ * @param {object} [opts.config]   Pre-resolved config (test injection).
+ * @param {number} [opts.override] Validated positive integer from
+ *                                 `--concurrency`.
+ * @returns {{
+ *   cap: number,
+ *   source: 'flag'|'config',
+ *   configuredCap: number,
+ *   requestedCap: number|null,
+ *   exceedsConfigured: boolean,
+ *   note: string,
+ * }}
+ */
+export function resolveCapPrecedence({ cwd, config, override } = {}) {
   const resolved = config ?? resolveConfig({ cwd });
   const { deliverRunner } = getRunners(resolved);
-  return deliverRunner.concurrencyCap;
+  const configuredCap = deliverRunner.concurrencyCap;
+  if (override == null) {
+    return {
+      cap: configuredCap,
+      source: 'config',
+      configuredCap,
+      requestedCap: null,
+      exceedsConfigured: false,
+      note: `cap ${configuredCap} from delivery.deliverRunner.concurrencyCap (no --concurrency given)`,
+    };
+  }
+  const exceedsConfigured = override > configuredCap;
+  return {
+    cap: override,
+    source: 'flag',
+    configuredCap,
+    requestedCap: override,
+    exceedsConfigured,
+    note: exceedsConfigured
+      ? `cap ${override} from --concurrency, which OVERRIDES and EXCEEDS the configured delivery.deliverRunner.concurrencyCap ${configuredCap} — this run is deliberately above the project default`
+      : `cap ${override} from --concurrency, which overrides the configured delivery.deliverRunner.concurrencyCap ${configuredCap}`,
+  };
 }
 
 /**
@@ -418,6 +488,8 @@ export function resolveConcurrencyCap({ cwd, config, override } = {}) {
  * @param {Array<{id: number, dependsOn: number[]}>} nodes
  * @param {object} args
  * @param {number} args.concurrencyCap Resolved per-beat concurrency cap.
+ * @param {object|null} [args.capPrecedence] The {@link resolveCapPrecedence}
+ *   record explaining which source set the cap.
  * @param {Set<number>} [args.doneIds] Story IDs already completed this run.
  * @param {number} [args.inFlight]     Stories already occupying a slot.
  * @returns {{
@@ -434,7 +506,7 @@ export function resolveConcurrencyCap({ cwd, config, override } = {}) {
  */
 export function buildReadySetEnvelope(
   nodes,
-  { concurrencyCap, doneIds = new Set(), inFlight = 0 },
+  { concurrencyCap, capPrecedence = null, doneIds = new Set(), inFlight = 0 },
 ) {
   const totalStories = nodes.length;
 
@@ -443,6 +515,10 @@ export function buildReadySetEnvelope(
     ready: [],
     totalStories,
     concurrencyCap,
+    // Which source set `concurrencyCap`, and whether it outranks the project's
+    // configured value (Story #4875). Never omitted on a resolved beat: a
+    // missing precedence record is what made a silent override possible.
+    capPrecedence,
     inFlight,
     cycleError: null,
     wedged: null,
@@ -484,6 +560,11 @@ export function buildReadySetEnvelope(
       labels: doneIds.has(node.id) ? [AGENT_LABELS.DONE] : (node.labels ?? []),
     };
     if (node.files !== undefined) rec.files = node.files;
+    // Probe-mode nodes carry the Story body so the overlap guard can widen a
+    // declared footprint from the paths the Story's own text names (Story
+    // #4875). Flag-mode nodes carry none — `parseDag` accepts no body — so
+    // this is inert there and the legacy contract is unchanged.
+    if (typeof node.body === 'string') rec.body = node.body;
     return rec;
   });
 
@@ -600,7 +681,8 @@ export function runStoriesWaveTick({
     return inputErrorResult(doneError, null, inFlightValue);
   }
 
-  const concurrencyCap = resolveConcurrencyCap({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const concurrencyCap = capPrecedence.cap;
 
   let rawJson;
 
@@ -642,6 +724,7 @@ export function runStoriesWaveTick({
 
   return buildReadySetEnvelope(nodes, {
     concurrencyCap,
+    capPrecedence,
     doneIds,
     inFlight: inFlightValue,
   });
@@ -705,7 +788,8 @@ export async function runProbedStoriesWaveTick({
     return inputErrorResult(dispatchedError);
   }
 
-  const concurrencyCap = resolveConcurrencyCap({ cwd, config, override });
+  const capPrecedence = resolveCapPrecedence({ cwd, config, override });
+  const concurrencyCap = capPrecedence.cap;
 
   let probed;
   try {
@@ -738,6 +822,7 @@ export async function runProbedStoriesWaveTick({
   } = probed;
   const { envelope, exitCode } = buildReadySetEnvelope(nodes, {
     concurrencyCap,
+    capPrecedence,
     doneIds,
     inFlight,
   });

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

@@ -32,6 +32,7 @@ import {
   rankDuplicateCandidates,
   readTechStackSummary,
   shouldRefine,
+  synthesizeContractSections,
   validateStoryBody,
 } from './lib/story-plan.js';
 
@@ -40,7 +41,8 @@ Usage:
   story-plan.js --emit-context (--seed "<seed>" | --seed-file <file>) \\
     [--refine | --no-refine] [--pretty]
 
-  story-plan.js --body <file> [--dry-run]
+  story-plan.js --body <file> [--acceptance <file>] [--verify <file>] \\
+    [--dry-run]
 
   story-plan.js --help
 
@@ -48,9 +50,18 @@ Modes:
   --emit-context   Build the host-LLM authoring envelope and print it as
                    JSON on stdout. Use this first; the host LLM authors a
                    draft body using the envelope and the body template.
-  --body <file>    Persist a pre-authored body. Validates shape (required
-                   sections, no Epic: ref, AC checklist non-empty) and
-                   calls \`gh issue create\` with type::story.
+  --body <file>    Persist a pre-authored body. Validates shape (## Goal
+                   and ## Changes present, no Epic: ref, an acceptance +
+                   verify contract) and calls \`gh issue create\` with
+                   type::story.
+  --acceptance <file>
+                   JSON string[] of the Story's top-level acceptance
+                   criteria. Authored once here — NOT mirrored into the
+                   body by hand; the \`## Acceptance\` section is
+                   synthesized from it, matching the story-author prompt.
+  --verify <file>  JSON string[] of the Story's top-level verify entries,
+                   each ending in a (unit|contract|e2e|validate) tier.
+                   Synthesized into \`## Verify\` the same way.
   --dry-run        With --body: print the body and the gh argv that would
                    be invoked, then exit 0. No GitHub mutations.
 
@@ -101,8 +112,13 @@ async function fetchOpenStories(provider) {
  * array; the caller decides whether to execute it (persist) or print
  * it (--dry-run).
  */
-function renderGhArgv({ title, bodyPath, labels }) {
-  const argv = ['issue', 'create', '--title', title, '--body-file', bodyPath];
+function renderGhArgv({ title, bodyPath, labels, body = null }) {
+  // `--body-file` streams the authored file untouched; an inline `--body` is
+  // used only when persist synthesized sections into it (Story #4874), so the
+  // file on disk is no longer what gets created.
+  const source =
+    typeof body === 'string' ? ['--body', body] : ['--body-file', bodyPath];
+  const argv = ['issue', 'create', '--title', title, ...source];
   for (const label of labels) {
     argv.push('--label', label);
   }
@@ -180,6 +196,31 @@ async function runEmitContext({
   write(`${json}\n`);
 }
 
+/**
+ * Read an optional top-level contract array (`--acceptance` / `--verify`)
+ * from a JSON file. Absent flag → an empty list, so the flags stay optional
+ * for a body that already carries its own sections.
+ *
+ * @param {string|undefined} filePath
+ * @param {'acceptance'|'verify'} label
+ * @returns {Promise<string[]>}
+ */
+async function readContractList(filePath, label) {
+  if (!filePath) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `Cannot read --${label} file "${filePath}": ${err.message}`,
+    );
+  }
+  if (!Array.isArray(parsed) || parsed.some((v) => typeof v !== 'string')) {
+    throw new Error(`--${label} file "${filePath}" must be a JSON string[].`);
+  }
+  return parsed;
+}
+
 async function runPersist({
   values,
   provider,
@@ -193,17 +234,30 @@ async function runPersist({
   if (!bodyPath) {
     throw new Error('--body <file> is required in persist mode.');
   }
-  const body = await readFile(bodyPath, 'utf8');
-  const validation = validateStoryBody(body);
+  const authored = await readFile(bodyPath, 'utf8');
+  const contract = {
+    acceptance: await readContractList(values.acceptance, 'acceptance'),
+    verify: await readContractList(values.verify, 'verify'),
+  };
+  const validation = validateStoryBody(authored, contract);
   if (!validation.ok) {
     throw new Error(
       `Drafted body failed validation:\n  - ${validation.errors.join('\n  - ')}`,
     );
   }
 
+  // Story #4874: the author writes acceptance[] / verify[] once, at the
+  // ticket's top level, and persist renders their sections — never the
+  // author by hand.
+  const body = synthesizeContractSections(authored, contract);
   const title = extractTitle(body);
   const labels = [TYPE_LABELS.STORY];
-  const argv = renderGhArgv({ title, bodyPath, labels });
+  const argv = renderGhArgv({
+    title,
+    bodyPath,
+    labels,
+    body: body === authored ? null : body,
+  });
 
   if (dryRun) {
     Logger.info('--- DRY RUN ---');
@@ -255,6 +309,8 @@ async function main() {
       seed: { type: 'string' },
       'seed-file': { type: 'string' },
       body: { type: 'string' },
+      acceptance: { type: 'string' },
+      verify: { type: 'string' },
       refine: { type: 'boolean', default: false },
       'no-refine': { type: 'boolean', default: false },
       pretty: { type: 'boolean', default: false },

package/.agents/scripts/update-crap-baseline.js

@@ -5,6 +5,7 @@ import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import {
   getBaselines,
@@ -44,6 +45,40 @@ import { Logger } from './lib/Logger.js';
  * "no baseline yet".
  */
 
+/**
+ * Usage block for `--help` (Story #4872). This CLI *writes* on invocation, so
+ * the help branch must short-circuit before `main` runs rather than inside it —
+ * `runAsCli` answers help first, which makes "a usage probe never mutates a
+ * baseline" structural instead of a check `main` has to remember.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-crap-baseline.js [--baseline <path>] [--coverage <path>] [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Scan → score → write the CRAP baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--baseline <path>',
+      'Write to this path instead of `delivery.quality.baselines.crap.path`.',
+    ],
+    [
+      '--coverage <path>',
+      'Read coverage from this path (default `coverage/coverage-final.json`).',
+    ],
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+  notes: [
+    'Run `npm run test:coverage` first — without a coverage artifact every file is skipped.',
+  ],
+};
+
 function parseCliArgs(argv = process.argv.slice(2)) {
   const out = {
     baselinePath: undefined,
@@ -183,8 +218,11 @@ async function main() {
   );
 }
 
-// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
-main().catch((err) => {
-  Logger.error(`[CRAP] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'crap-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[CRAP] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`);
+    process.exitCode = 1;
+  },
 });

package/.agents/scripts/update-maintainability-baseline.js

@@ -43,10 +43,34 @@ import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import { getBaselines, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 
+/**
+ * Usage block for `--help` (Story #4872). This CLI *writes* on invocation, so
+ * the help branch must short-circuit before `main` runs rather than inside it —
+ * `runAsCli` answers help first, which makes "a usage probe never mutates a
+ * baseline" structural instead of a check `main` has to remember.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-maintainability-baseline.js [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Score → write the maintainability baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+};
+
 /**
  * Parse `--full-scope` (boolean opt-out flag).
  *
@@ -119,8 +143,11 @@ async function main() {
   );
 }
 
-// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
-main().catch((err) => {
-  Logger.error(`[Maintainability] ❌ Fatal error: ${err.message}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'maintainability-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[Maintainability] ❌ Fatal error: ${err.message}`);
+    process.exitCode = 1;
+  },
 });

package/.agents/templates/single-story-body.md

@@ -1,17 +1,25 @@
 # {{title}}
 
-## Context
+## Goal
 
-{{context}}
+{{goal}}
 
-## Acceptance Criteria
+## Spec
 
-{{acceptanceCriteria}}
+{{spec}}
 
-## Out of Scope
+## Changes
 
-{{outOfScope}}
+{{changes}}
 
-## Notes
+## Non-Goals
 
-{{notes}}
+{{nonGoals}}
+
+<!--
+  `acceptance[]` and `verify[]` are the ticket's top-level machine contract.
+  Author each list ONCE, at the top level (`--acceptance` / `--verify`); do
+  NOT mirror them into this body — persist synthesizes the `## Acceptance`
+  and `## Verify` sections from those arrays so the issue still reads as a
+  complete executable document.
+-->