mandrel 2.9.0 → 2.11.0

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/resolve-stories.js

@@ -209,6 +209,7 @@ async function main() {
     stories,
     nativeEdges,
     warn: (m) => Logger.warn(m),
+    config,
   });
   const foreignDone = await resolveForeignDone({
     provider,
@@ -220,6 +221,7 @@ async function main() {
     nativeEdges,
     foreignDone,
     warn: () => {},
+    config,
   });
 
   process.stdout.write(

package/.agents/scripts/single-story-confirm-merge.js

@@ -27,7 +27,8 @@
  * short-circuits to a `noop` envelope.
  *
  * Usage:
- *   node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>]
+ *   node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait]
+ *                                      [--max-wait-seconds <n>]
  *                                      [--cwd <main-repo>]
  *
  * Exit codes: 0 ok (merged, pending, or noop), 1 error.
@@ -40,12 +41,13 @@ import { parseSprintArgs } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { formatCliError } from './lib/error-redactor.js';
-import { gh as defaultGh } from './lib/gh-exec.js';
+import { createGh } from './lib/gh-exec.js';
 import { getStoryBranch } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
 import { emitTerseResult } from './lib/observability/terse-result.js';
 import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
+import { MERGE_WAIT_GH_TIMEOUT_MS } from './lib/orchestration/merge-poll.js';
 import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
 import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
@@ -64,6 +66,25 @@ const progress = Logger.createProgress('single-story-confirm-merge', {
   stderr: true,
 });
 
+/**
+ * Default `gh` facade for this CLI, bound to the merge wait's spawn-level
+ * timeout (Story #4710). This CLI is the resume surface async mode hands the
+ * merge wait to — a background invocation with no host tool ceiling — so an
+ * un-timeboxed `gh pr list` / `gh pr view` here could strand the resume the
+ * same way an un-timeboxed probe stranded the in-close wait.
+ */
+const defaultGh = createGh(undefined, { timeoutMs: MERGE_WAIT_GH_TIMEOUT_MS });
+
+/** One usage string for the throw path and `--help` (Story #4710). */
+const USAGE =
+  'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] ' +
+  '[--max-wait-seconds <n>] [--cwd <main-repo>]\n\n' +
+  '  --wait              resume the bounded merge wait instead of probing once\n' +
+  '  --max-wait-seconds  per-invocation wait bound override, threaded to\n' +
+  '                      resolveMergeWaitConfig exactly as the close does (wins\n' +
+  '                      over delivery.mergeWatch.maxWaitSeconds and the async\n' +
+  '                      probe-window cap; only meaningful with --wait)';
+
 /**
  * Read the `--pr <n>` flag from `process.argv` for the direct-CLI path.
  * Injection callers pass `pr` directly and never reach this. Returns the
@@ -106,6 +127,33 @@ function readWaitFlag() {
   }
 }
 
+/**
+ * `--max-wait-seconds <n>`: per-invocation wait-bound override for the
+ * `--wait` resume path (Story #4710). The close CLI already accepted this
+ * flag, but the resume CLI — the exact command async mode's `pending`
+ * terminal hands off to — did not, so the documented per-run override was
+ * unreachable where it mattered most and a slow-CI landing depended on an
+ * unbounded chain of short invocations. Threaded to `runConfirmMergePhase`
+ * (and thence `resolveMergeWaitConfig`) exactly as close threads its own
+ * flag. Returns `undefined` when absent or not a positive integer — the
+ * phase's config/default resolution owns that case.
+ *
+ * @returns {number|undefined}
+ */
+function readMaxWaitSecondsFlag() {
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: { 'max-wait-seconds': { type: 'string' } },
+      strict: false,
+    });
+    const parsed = Number.parseInt(String(values['max-wait-seconds']), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the PR number for the Story branch when one was not passed on
  * the CLI. Probes `gh pr list --head <branch> --state all` (the merged PR
@@ -262,6 +310,7 @@ export async function runConfirmMerge({
   cwd: cwdParam,
   pr: prParam,
   wait: waitParam,
+  maxWaitSeconds: maxWaitSecondsParam,
   injectedProvider,
   injectedConfig,
   injectedGh,
@@ -275,11 +324,10 @@ export async function runConfirmMerge({
   });
 
   if (!storyId) {
-    throw new Error(
-      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] [--cwd <main-repo>]',
-    );
+    throw new Error(USAGE);
   }
   const wait = waitParam ?? readWaitFlag();
+  const maxWaitSeconds = maxWaitSecondsParam ?? readMaxWaitSecondsFlag();
 
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd });
@@ -346,6 +394,10 @@ export async function runConfirmMerge({
       // The close already armed it; this CLI is resuming that wait, not
       // deciding whether to arm.
       autoMergeEnabled: true,
+      // The per-run override (`--max-wait-seconds`), resolved by
+      // `resolveMergeWaitConfig` exactly as the close resolves its own flag —
+      // it wins over the config value and the async probe-window cap.
+      maxWaitSeconds,
       provider,
       config,
       progress,
@@ -450,6 +502,14 @@ export async function runConfirmMerge({
  * or none at all; "none at all" is what Story #4543 removes.
  */
 async function main() {
+  if (process.argv.includes('--help')) {
+    // Print usage (including --max-wait-seconds) and exit cleanly — the
+    // resume-path override is only discoverable if the CLI can say it exists.
+    // `process.stdout.write` (not console.log) keeps the CLI within the
+    // no-console repo invariant while still writing help to stdout.
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
   try {
     const outcome = await runConfirmMerge();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });

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

@@ -862,7 +862,7 @@ async function main(argv) {
           inFlight: values['in-flight'],
         });
 
-  process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
 
   if (exitCode !== 0) {
     Logger.error(