mandrel 2.8.0 → 2.10.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -5,6 +5,7 @@ import {
   DELIVERABLE_GRANULARITY_GUIDANCE,
   resolveCapacityCeilings,
 } from '../orchestration/ticket-validator-sizing.js';
+import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
 
 /**
  * Sole source of truth for the prompt's `maxTickets` cap is the resolved
@@ -63,6 +64,15 @@ function render2TierPrompt({ maxTickets }) {
     advisoryCaveat,
     newFileContract,
   } = AUTHORING_ALTITUDE_GUIDANCE;
+  // The deterministic body-format lints (structured `## Changes` bullet shape,
+  // verify-tier suffixes, …) rendered example-first from their single source
+  // (`lib/story-body/body-format-lints.js`) so an authored draft is lint-clean
+  // by construction rather than discovered as a persist dry-run failure and
+  // re-authored at resident-context prices (Story #4684).
+  const bodyFormatLintChecklist = BODY_FORMAT_LINTS.map(
+    (lint) =>
+      `- **${lint.id}** — ${lint.summary} Example: \`${lint.goodExample}\``,
+  ).join('\n');
   return `You are an expert Senior Project Manager and Orchestrator.
 Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
 
@@ -99,7 +109,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\` / \`estimated_test_files\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -128,10 +138,6 @@ The serialized \`body\` string renders these markdown sections (in order):
     - <exact command or test path> (<tier>)
     - ...
 
-    ## References
-    - {"path": "<read-only dependency path>", "assumption": "exists"}
-    - ...
-
     ## Non-Goals
     - <a capability or change this Story explicitly does NOT deliver>
     - ...
@@ -139,7 +145,7 @@ The serialized \`body\` string renders these markdown sections (in order):
 #### STORY BODY RULES:
 
 - **goal** (in body string): One sentence stating WHY this Story exists.
-- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
+- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only, at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
 - **slicing** (optional): Ordered intra-session checkpoints for one Story. Not a fan-out table and not a duplicate of Acceptance.
 - **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
@@ -152,6 +158,23 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Resolve the unknown before authoring, or restate it as a declarative Key Assumption the agent can act on.
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
+#### SPEC PROSE CONTRACT — state the contract, not the implementation:
+
+The Story is executed by a frontier-model deliverer that reads the codebase itself. Author \`## Spec\` (and Goal prose) at contract level:
+
+- **Spec states the contract and invariants**: interfaces, status codes, security invariants, and load-bearing constraints — each with its why. That is the whole job of the Spec.
+- **Implementation choices belong to the deliverer** unless a choice is load-bearing; a load-bearing choice is stated as a constraint (with why it binds), never as a walkthrough of how to code it.
+- **No per-file behavior paragraphs.** The \`## Changes\` list already names the footprint; do not narrate what each file will do.
+- **No current-state narration.** Do not describe how the codebase works today as scene-setting; the deliverer reads the code. The only current-state prose allowed is a claim a decision depends on, opening with \`Current state (verified <date>)\` per the observed-behavior rule above.
+- **Do not author a \`## References\` section.** Read-only context the deliverer needs is discoverable from the contract and the footprint.
+- **Acceptance criteria remain the binding contract** — the Spec constrains and explains; \`acceptance[]\` binds.
+
+#### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
+
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.
+
+${bodyFormatLintChecklist}
+
 #### AUTHORING ALTITUDE — BINDING ACCEPTANCE vs ADVISORY CHANGES:
 
 ${authoringAltitude}

package/.agents/scripts/lib/test-env.js

@@ -1,3 +1,62 @@
+import { mkdtempSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TEST_TEMP_ROOT_ENV } from './config/temp-paths.js';
+
+/**
+ * Per-process memo for the created scratch dir, so repeated calls in one
+ * runner process (e.g. building env bags for several chunks) share a single
+ * scratch tree instead of minting one dir per call.
+ */
+let _createdScratchDir = null;
+
+/**
+ * Test-only: clear the per-process scratch memo so a suite can exercise the
+ * creation branch repeatedly in one process.
+ */
+export function _clearTestScratchTempRootCache() {
+  _createdScratchDir = null;
+}
+
+/**
+ * Ensure an absolute per-process scratch tempRoot is available for the test
+ * run and return it (Story #4696).
+ *
+ * If `baseEnv` already carries an absolute `MANDREL_TEST_TEMP_ROOT` (the
+ * common case for a child process that inherits the parent runner's env),
+ * that value is reused verbatim so every chunk / worker of a single suite
+ * run shares one scratch dir. Otherwise a fresh `os.tmpdir()` directory is
+ * created once per process (memoized). Every stream writer that resolves a
+ * relative tempRoot then lands under this dir instead of the repo's real
+ * `temp/` telemetry tree — the regression that let 99% of friction records
+ * be test-fixture pollution.
+ *
+ * Directly unit-tested via the injectable `mkdtemp` seam in
+ * `tests/lib/test-env.test.js` (Story #4711).
+ *
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env]
+ * @param {{ mkdtemp?: typeof mkdtempSync }} [deps] Injectable for tests.
+ * @returns {string} absolute scratch tempRoot
+ */
+export function ensureTestScratchTempRoot(
+  baseEnv = process.env,
+  { mkdtemp = mkdtempSync } = {},
+) {
+  const existing = baseEnv?.[TEST_TEMP_ROOT_ENV];
+  if (
+    typeof existing === 'string' &&
+    existing.length > 0 &&
+    path.isAbsolute(existing)
+  ) {
+    return existing;
+  }
+  if (_createdScratchDir === null) {
+    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-'));
+  }
+  return _createdScratchDir;
+}
+
 /**
  * Build a webhook-safe child-process environment for test runners.
  *
@@ -27,6 +86,11 @@
  *     covered by `cleanGitEnv` in `git-utils.js`; this is the same scrub
  *     for test child processes, which may spawn git directly. Tests that
  *     need a `GIT_*` variable set it explicitly on their own spawn.
+ *   - `MANDREL_TEST_TEMP_ROOT` is set to an absolute per-process scratch
+ *     dir (Story #4696). Any test that reaches a stream writer without
+ *     injecting its own absolute tempRoot lands under scratch instead of
+ *     the repo's real `temp/` telemetry tree, so the suite can no longer
+ *     append fixture records to friction / lifecycle / trace streams.
  *
  * @param {NodeJS.ProcessEnv} baseEnv
  * @returns {NodeJS.ProcessEnv}
@@ -39,5 +103,6 @@ export function buildWebhookSafeTestEnv(baseEnv = process.env) {
   if (env.MANDREL_ALLOW_TEST_WEBHOOKS !== '1') {
     delete env.NOTIFICATION_WEBHOOK_URL;
   }
+  env[TEST_TEMP_ROOT_ENV] = ensureTestScratchTempRoot(baseEnv);
   return env;
 }

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

@@ -18,18 +18,21 @@
  *                             Stories. Envelope carries `sourceTickets[]`.
  *
  * Flags:
- *   --out <path>     Also write the envelope to <path> (parent dirs created).
+ *   --out <path>     Write the envelope to <path> (parent dirs created).
  *                    `/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.
- *   --pretty         Pretty-print the JSON envelope.
+ *                    `--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).
  *
- * stdout is reserved for the JSON envelope (Story #2278 discipline):
- * `routeAllOutputToStderr()` runs before any pipeline code so a captured
- * file is unconditionally parseable by `JSON.parse`.
+ * 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`.
  *
  * Exit codes:
  *   0 — envelope emitted.
@@ -49,7 +52,11 @@ import {
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { buildPlanContext } from './lib/orchestration/plan-context.js';
+import {
+  buildPlanContext,
+  renderStoriesTemplate,
+  STORIES_TEMPLATE_FILENAME,
+} from './lib/orchestration/plan-context.js';
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -111,8 +118,31 @@ export async function emitPlanContext({
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  stdout.write(`${json}\n`);
-  if (outPath) await writeEnvelopeFile(outPath, json);
+  if (outPath) {
+    // 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);
+    const resolved = path.resolve(outPath);
+    const digest = {
+      digest: 'plan-context',
+      mode: envelope.mode,
+      out: resolved,
+      storiesTemplate: path.join(
+        path.dirname(resolved),
+        'stories.template.json',
+      ),
+      bytes: Buffer.byteLength(json, 'utf8'),
+      sourceTickets: (envelope.sourceTickets ?? []).map((t) => t.id),
+      duplicates: (envelope.duplicates ?? []).length,
+      complexityRoute: envelope.complexityRoute?.route ?? null,
+    };
+    stdout.write(`${JSON.stringify(digest)}\n`);
+  } else {
+    stdout.write(`${json}\n`);
+  }
   return envelope;
 }
 
@@ -140,6 +170,33 @@ async function writeEnvelopeFile(outPath, json) {
   Logger.info(`[plan-context] wrote envelope to ${resolved}`);
 }
 
+/**
+ * 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
+ * does: a silently missing template re-opens the format-discovery loop it
+ * exists to close.
+ *
+ * @param {string} outPath The envelope `--out` path; the template lands in
+ *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
+ */
+async function writeStoriesTemplateFile(outPath) {
+  const resolved = path.resolve(
+    path.dirname(path.resolve(outPath)),
+    STORIES_TEMPLATE_FILENAME,
+  );
+  try {
+    await writeFile(resolved, renderStoriesTemplate(), 'utf8');
+  } catch (err) {
+    throw new Error(
+      `[plan-context] cannot write stories template to ${resolved}: ${err.message}`,
+    );
+  }
+  Logger.info(`[plan-context] wrote ready-to-fill template to ${resolved}`);
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {

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

@@ -9,6 +9,11 @@
  * act on it — dispatching a fresh-context critic sub-agent and folding its
  * findings into a re-author round **before** the plan is persisted.
  *
+ * The pre-mortem's external-dependency arm (Story #4700) needs the repo's own
+ * manifests to tell an external scoped package from a local one, so this CLI
+ * reads them (`collectRepoPackages`) and passes the specifier set down — the
+ * pure evaluation modules never touch the filesystem.
+ *
  * Why here and nowhere else. The evaluation used to run inside
  * `run-plan-persist.js`, after authoring was finished and immediately before
  * `createStoryIssues` — the one point in the flow where nothing can act on a
@@ -43,7 +48,7 @@
  * Exit codes: 0 success (any verdict); 1 usage/IO error.
  */
 
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -63,6 +68,101 @@ const USAGE = 'Usage: plan-critics.js --stories <file> [--tech-spec <file>]';
 /** The `cli` discriminator every ledger record from this surface carries. */
 export const PLAN_CRITICS_CLI = 'plan-critics';
 
+/** Dependency maps a manifest can declare a package under. */
+const DEP_MAP_KEYS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+];
+
+/** Add a manifest's own name and every declared dependency to `names`. */
+function collectPackageIdentity(names, pkg) {
+  if (typeof pkg?.name === 'string') names.add(pkg.name);
+  for (const key of DEP_MAP_KEYS) {
+    const map = pkg?.[key];
+    if (map && typeof map === 'object') {
+      for (const dep of Object.keys(map)) names.add(dep);
+    }
+  }
+}
+
+/** Best-effort JSON read: a missing or malformed file yields `null`. */
+async function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Normalize the `workspaces` field (array or `{ packages: [] }`) to a list. */
+function workspacePatterns(pkg) {
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) return ws;
+  if (Array.isArray(ws?.packages)) return ws.packages;
+  return [];
+}
+
+/**
+ * Resolve `workspaces` patterns to child `package.json` paths. Handles the two
+ * common shapes — a `dir/*` glob (expanded one level) and a literal path — and
+ * never throws: an unreadable base directory is skipped.
+ *
+ * @param {string} rootDir
+ * @param {string[]} patterns
+ * @returns {Promise<string[]>}
+ */
+async function resolveWorkspaceManifestPaths(rootDir, patterns) {
+  const paths = [];
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string') continue;
+    if (!pattern.endsWith('/*')) {
+      paths.push(path.resolve(rootDir, pattern, 'package.json'));
+      continue;
+    }
+    const base = path.resolve(rootDir, pattern.slice(0, -2));
+    let entries;
+    try {
+      entries = await readdir(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        paths.push(path.join(base, entry.name, 'package.json'));
+      }
+    }
+  }
+  return paths;
+}
+
+/**
+ * Gather the package specifiers the repo's own manifests declare — the set the
+ * pre-mortem external-dependency probe (Story #4700) measures a scoped-package
+ * reference against. Includes the root manifest's own name and dependency maps
+ * plus every workspace manifest's. Best-effort: a repo with no `package.json`
+ * yields `[]`, which only widens what the probe treats as external.
+ *
+ * @param {{ rootDir?: string }} [opts]
+ * @returns {Promise<string[]>}
+ */
+export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
+  const root = await readJsonIfPresent(path.join(rootDir, 'package.json'));
+  if (!root) return [];
+  const names = new Set();
+  collectPackageIdentity(names, root);
+  const wsPaths = await resolveWorkspaceManifestPaths(
+    rootDir,
+    workspacePatterns(root),
+  );
+  for (const wsPath of wsPaths) {
+    const pkg = await readJsonIfPresent(wsPath);
+    if (pkg) collectPackageIdentity(names, pkg);
+  }
+  return [...names];
+}
+
 /**
  * Read the draft artifacts the critics evaluate.
  *
@@ -155,21 +255,32 @@ export async function recordCriticSkips(
  *   storiesPath: string,
  *   techSpecPath?: string|null,
  *   config?: object,
+ *   knownPackages?: string[],
  *   append?: typeof appendCriticSkip,
  * }} args
+ * @param {string[]} [args.knownPackages] - Package specifiers the repo's own
+ *   manifests declare, forwarded to the pre-mortem external-dependency probe
+ *   (Story #4700). `main()` resolves them via `collectRepoPackages`; tests may
+ *   pass an explicit set or omit it (defaults to `[]`).
  * @returns {Promise<{ consolidation: object, premortem: object, textHygiene: object }>}
  */
 export async function evaluateCriticArtifacts({
   storiesPath,
   techSpecPath = null,
   config = {},
+  knownPackages = [],
   append = appendCriticSkip,
 }) {
   const { tickets, techSpecContent } = await loadCriticArtifacts({
     storiesPath,
     techSpecPath,
   });
-  const verdict = evaluatePlanCritics({ techSpecContent, tickets, config });
+  const verdict = evaluatePlanCritics({
+    techSpecContent,
+    tickets,
+    config,
+    knownPackages,
+  });
   await recordCriticSkips(verdict, config, { append });
   return verdict;
 }
@@ -191,9 +302,10 @@ async function main() {
       ? path.resolve(values['tech-spec'])
       : null,
     config: resolveConfig(),
+    knownPackages: await collectRepoPackages(),
   });
 
-  process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(verdict)}\n`);
   return 0;
 }
 

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

@@ -34,6 +34,13 @@
  *                             ids, for hand-driven runs. Each id must be
  *                             claimed by exactly one Story's `supersedes[]`;
  *                             they are commented on and closed as superseded
+ *   --route-downgrade-reason <text>
+ *                             Audited planner downgrade (Story #4707): treat
+ *                             the envelope's `full` complexity verdict as
+ *                             `lite`, recording <text> on every Story's
+ *                             story-plan-state checkpoint. Absent this flag
+ *                             the deterministic verdict stands; the gate
+ *                             itself still fails toward `full`
  *   --no-close-superseded     Keep the source tickets open (no comment, no
  *                             close) — for a genuinely partial supersede
  *   --dry-run                 Assemble + validate without GitHub writes
@@ -100,6 +107,7 @@ const CLI_OPTIONS = {
   'plan-context': { type: 'string' },
   'plan-acceptance': { type: 'string' },
   'source-tickets': { type: 'string' },
+  'route-downgrade-reason': { type: 'string' },
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
@@ -113,6 +121,7 @@ const USAGE =
   '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
   '[--plan-acceptance <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
+  '[--route-downgrade-reason <text>] ' +
   '[--dry-run] [--force-review] ' +
   '[--allow-over-budget] [--allow-large-fan-out]';
 
@@ -204,6 +213,7 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
     skipCleanup: values['dry-run'],
     sourceTicketIds: source.ids,
     sourceTicketOrigin: source.origin,
+    routeDowngradeReason: values['route-downgrade-reason'] ?? null,
     // Default-on: `--no-close-superseded` is the explicit escape and always
     // wins over the (default `true`) `--close-superseded`.
     closeSuperseded:
@@ -328,7 +338,7 @@ async function main() {
 
   await attachPlanMetrics(result, config, metricsSince);
 
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
 }
 
 runAsCli(import.meta.url, main, { source: 'plan-persist' });

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

@@ -67,7 +67,7 @@ export async function main(argv = process.argv.slice(2)) {
   });
   warnOnUnresolvedBase(result);
   warnOnEmptyRollup(result);
-  Logger.info(JSON.stringify(result, null, 2));
+  Logger.info(JSON.stringify(result));
   if (result.errors?.length) {
     process.exitCode = 1;
   }

package/.agents/scripts/providers/github/issues.js

@@ -15,16 +15,38 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { GhRateLimitError } from '../../lib/gh-exec.js';
 import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { isNotFoundError } from './branch-protection.js';
-import { withTransientRetry } from './errors.js';
+import { classifyGithubError, withTransientRetry } from './errors.js';
 import { issueToEpic } from './mappers.js';
 import {
   defaultRetryWarn,
   paginateRest,
   parseApiJson,
 } from './request-helpers.js';
+import {
+  searchBudget as defaultSearchBudget,
+  parseRateLimitResetMs,
+} from './search-budget.js';
+import { composeBoundedQuery } from './search-query.js';
+
+/**
+ * Retry classifier for the `searchIssues` call site. A rate-limit error is
+ * non-transient **here** — the shared search budget (not `withTransientRetry`)
+ * owns the wait, so the call must fail fast rather than burn its retry budget
+ * re-issuing into an empty window. Every other error keeps the global
+ * classification, so a 5xx/network blip still retries. `classifyGithubError`
+ * itself is unchanged: other endpoints legitimately retry on rate-limit.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function classifySearchRetry(err) {
+  if (err instanceof GhRateLimitError) return 'rate-limited';
+  return classifyGithubError(err);
+}
 
 /**
  * Concurrency budget for the `getSubTickets` fan-out — preserved from
@@ -51,11 +73,15 @@ export class IssuesGateway {
    *   },
    * }} deps
    */
-  constructor({ gh, owner, repo, hooks = {} } = {}) {
+  constructor({ gh, owner, repo, hooks = {}, searchBudget } = {}) {
     this._gh = gh;
     this.owner = owner;
     this.repo = repo;
     this._hooks = hooks;
+    // The `/search/issues` fan-out budget. Defaults to the process-wide
+    // singleton so every gateway instance shares one 30/min window; injectable
+    // so unit tests drive it deterministically (Story #4678).
+    this._searchBudget = searchBudget ?? defaultSearchBudget;
   }
 
   /**
@@ -132,14 +158,35 @@ export class IssuesGateway {
     // Constrain the search to this repo and to issues (not PRs). The
     // fingerprint sha is the free-text term; GitHub matches it against the
     // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
+    // The composed `q` is bounded to GitHub Search's 256-char limit here — the
+    // only place that knows both the free text and the qualifiers it appends —
+    // truncating the free-text portion on a whole-token boundary (Story #4678).
     const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
-    const q = `${query.trim()} ${qualifiers.join(' ')}`;
+    const q = composeBoundedQuery(query, qualifiers);
     const params = new URLSearchParams({ q, per_page: '100' });
     const endpoint = `/search/issues?${params}`;
-    const result = await withTransientRetry(
-      () => this._gh.api({ method: 'GET', endpoint }),
-      { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
-    );
+    // Await the shared 30/min budget before every call so the whole scan's
+    // fan-out is throttled at the endpoint, not per caller (Story #4678).
+    await this._searchBudget.take();
+    let result;
+    try {
+      result = await withTransientRetry(
+        () => this._gh.api({ method: 'GET', endpoint }),
+        {
+          label: `searchIssues ${query}`,
+          onRetry: defaultRetryWarn,
+          classify: classifySearchRetry,
+        },
+      );
+    } catch (err) {
+      // A rate limit means the window is empty: drain the budget until the
+      // reported reset so the *next* call pauses once, rather than every call
+      // retrying independently into the exhausted window.
+      if (err instanceof GhRateLimitError) {
+        this._searchBudget.noteRateLimited(parseRateLimitResetMs(err));
+      }
+      throw err;
+    }
     const json = parseApiJson(result);
     const items = Array.isArray(json?.items) ? json.items : [];
     return items.map((item) => ({