mandrel 2.59.0 → 2.61.0

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

@@ -2,58 +2,24 @@
 /* node:coverage ignore file */
 
 /**
- * plan-context.js — step 1 of the collapsed `/mandrel-plan` pipeline.
+ * plan-context.js — build the `/mandrel-plan` authoring-context envelope from
+ * exactly one entry form (`--seed`, `--seed-file`, `--tickets`, `--amends`),
+ * write it with `stories.template.json` under `<tempRoot>/plan-<slug>/`
+ * (where `plan-persist.js` discovers the `--tickets` source ids), and print a
+ * compact JSON digest as the only stdout.
  *
- * Emits one stdout-pure JSON envelope for the `/mandrel-plan` authoring middle.
- *
- * Two operator modes (exactly one is required):
- *
- *   --seed "<text>"           Chat/text ideation. Dup search runs off the
- *                             raw seed; envelope carries `seed`.
- *
- *   --seed-file <path>        Same as --seed, but the corpus is read from
- *                             disk (audit-to-stories handoff, notes).
- *
- *   --tickets 123[,456…]      Analyze existing issue(s) into proper
- *                             Stories. Envelope carries `sourceTickets[]`.
- *
- *   --amends 123 | #123       Amendment (delta) planning. Composes a DELTA
- *                             envelope from the prior Story's body, its
- *                             acceptance criteria, and its delivered file map
- *                             instead of re-interrogating the repo from
- *                             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).
- *
- * 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.
- *   1 — fatal error (see stderr).
+ * Exit codes: 0 envelope emitted; 1 fatal.
  */
 
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
+// Must be the first import: fail fast before any third-party import runs.
 import './lib/runtime-deps/ensure-installed.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 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,9 +32,63 @@ import {
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
+const PLAN_SLUG_MAX_LENGTH = 48;
+
 /**
- * Parse a comma-/space-separated ticket id list into positive integers.
+ * Deliberately lossy: a handle, not an identity — the same seed reuses (and
+ * overwrites) the same directory.
  *
+ * @param {string} raw
+ * @returns {string} `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;
+}
+
+/**
+ * Envelope path when no `--out` is given. Always written, because persist
+ * discovers source ids and the template from this directory.
+ *
+ * @param {object} args
+ * @param {string} args.mode
+ * @param {string} [args.seedText]
+ * @param {string} [args.seedFilePath]
+ * @param {number[]} [args.ticketIds]
+ * @param {number} [args.amendsId]
+ * @param {object} [args.config]
+ * @param {string} [args.cwd]
+ * @returns {string} Absolute path.
+ */
+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',
+  );
+}
+
+/**
  * @param {string} raw
  * @returns {number[]}
  */
@@ -90,8 +110,6 @@ export function parseTicketIds(raw) {
 }
 
 /**
- * Parse a single `--amends` id, tolerating a leading `#` (`#123` or `123`).
- *
  * @param {string} raw
  * @returns {number}
  */
@@ -109,9 +127,6 @@ 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.
- *
  * @param {object} args
  * @returns {Promise<object>} the emitted envelope.
  */
@@ -145,14 +160,23 @@ export async function emitPlanContext({
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  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, envelope);
-    const resolved = path.resolve(outPath);
+  const resolvedOut =
+    outPath ??
+    resolveDefaultOutPath({
+      mode,
+      seedText,
+      seedFilePath,
+      ticketIds,
+      amendsId,
+      config,
+      cwd: cwd ?? undefined,
+    });
+  {
+    // The ~40KB envelope goes to disk; stdout carries only a digest so it
+    // does not ride resident in the transcript.
+    await writeEnvelopeFile(resolvedOut, json);
+    await writeStoriesTemplateFile(resolvedOut, envelope);
+    const resolved = path.resolve(resolvedOut);
     const digest = {
       digest: 'plan-context',
       mode: envelope.mode,
@@ -164,10 +188,7 @@ export async function emitPlanContext({
       bytes: Buffer.byteLength(json, 'utf8'),
       sourceTickets: (envelope.sourceTickets ?? []).map((t) => t.id),
       duplicates: (envelope.duplicates ?? []).length,
-      // Advisory only: signals, no route. `uiSurface` is the recorded
-      // /prototype offer — advisory, never an automatic reroute. It rides the
-      // digest because with `--out` the digest is the only thing the planner
-      // reads.
+      // Advisory signals only, never a reroute.
       complexitySignals: envelope.complexitySignals
         ? {
             artifactCount: envelope.complexitySignals.artifactCount,
@@ -176,25 +197,18 @@ export async function emitPlanContext({
             uiSurface: envelope.complexitySignals.uiSurface ?? null,
           }
         : null,
-      // Story #5312: an envelope over the planner-context ceiling is written
-      // truncated, and the digest names what was cut.
+      // Names what was cut when the envelope exceeded the context ceiling.
       truncated: envelope.truncated ?? null,
       amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
-  } else {
-    stdout.write(`${json}\n`);
   }
   return envelope;
 }
 
 /**
- * Persist the envelope to `--out` so `plan-persist.js` can derive the
- * `--tickets` source ids from it without an operator re-typing them.
- *
- * Writing is part of emitting, not a best-effort extra: a failed write means
- * persist will silently see no source tickets, so it throws rather than
- * warning past the problem.
+ * Throws on failure: a missing envelope makes persist silently see no source
+ * tickets.
  *
  * @param {string} outPath
  * @param {string} json
@@ -213,19 +227,11 @@ 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
- * 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
- * creates-vs-refactors against the repo snapshot (Story #4723).
+ * Write the ready-to-fill authoring template beside the envelope, with
+ * `changes[]` pre-resolved from `complexitySignals`. Throws on failure.
  *
- * @param {string} outPath The envelope `--out` path; the template lands in
- *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
- * @param {object} [envelope] The emitted plan-context envelope.
+ * @param {string} outPath
+ * @param {object} [envelope]
  */
 async function writeStoriesTemplateFile(outPath, envelope = {}) {
   const resolved = path.resolve(
@@ -294,18 +300,14 @@ async function main() {
     mode = 'seed';
   }
 
-  // stdout is reserved for the JSON envelope: flip every Logger sink that
-  // could land on stdout to stderr BEFORE any pipeline code runs
-  // (Story #2278 — the same stdout-purity guarantee the retired pipeline
-  // gives; this CLI is emit-only so the flip is unconditional).
+  // stdout is reserved for the JSON digest.
   routeAllOutputToStderr();
 
   let config;
   let settings;
   try {
     config = resolveConfig();
-    // `settings` retains the legacy bag shape `buildAuthoringContext` and
-    // friends consume: `{ baseBranch, paths, planning, docsContextFiles }`.
+    // The bag shape `buildAuthoringContext` consumes.
     settings = {
       baseBranch: config.project?.baseBranch,
       paths: config.project?.paths,
@@ -346,14 +348,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-critics.js

@@ -1,45 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * plan-critics.js — the /mandrel-plan pre-mortem dispatch verdict CLI
- * (Story #4592; pre-mortem only since Story #5312).
- *
- * The operator runs this between Author and Persist when they want the
- * pre-mortem — it is no longer a step of the `/mandrel-plan` spine. It
- * evaluates the pre-mortem dispatch condition against the draft
- * `stories.json` and prints the verdict as JSON on stdout so the workflow can
- * 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
- * `dispatch: true` verdict, because the artifacts are about to become live
- * issues. It logged the verdict and moved on. This CLI is now the **single**
- * evaluation point, sited where a re-author loop actually exists.
- *
- * Advisory by contract: a `dispatch: true` verdict routes work to the
- * workflow, it does not gate the run. This CLI exits 0 on any verdict; only a
- * usage/IO error is a failure. Every `dispatch: false` decision is recorded to
- * the plan-metrics ledger (`appendCriticSkip`) so under-firing stays auditable.
- *
- * CLI:
- *   --stories <file>     Required. The draft Story ticket array (JSON).
- *   --tech-spec <file>   Optional. Shared Tech Spec, folded into the plan
- *                        text the external-dependency probe scans.
- *
- * stdout is reserved for the verdict JSON (Story #2278 discipline):
- *
- *   {
- *     "premortem": { "critic": "pre-mortem", "dispatch": true, "reasons": [...] }
- *   }
- *
- * Human-readable log lines go to stderr, matching the sibling `plan-persist`.
+ * plan-critics.js — operator-run pre-mortem dispatch verdict for a draft plan,
+ * evaluated between Author and Persist, where a re-author loop can still act
+ * on it. Advisory: exits 0 on any verdict; each skip is recorded to the
+ * plan-metrics ledger so under-firing stays auditable. stdout carries only
+ * `{ "premortem": { critic, dispatch, reasons } }`.
  *
  * Exit codes: 0 success (any verdict); 1 usage/IO error.
  */
@@ -61,10 +27,8 @@ const CLI_OPTIONS = {
 
 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',
@@ -72,7 +36,6 @@ const DEP_MAP_KEYS = [
   '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) {
@@ -92,7 +55,6 @@ async function readJsonIfPresent(filePath) {
   }
 }
 
-/** Normalize the `workspaces` field (array or `{ packages: [] }`) to a list. */
 function workspacePatterns(pkg) {
   const ws = pkg?.workspaces;
   if (Array.isArray(ws)) return ws;
@@ -101,9 +63,7 @@ function workspacePatterns(pkg) {
 }
 
 /**
- * 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.
+ * Handles `dir/*` (one level) and literal paths; never throws.
  *
  * @param {string} rootDir
  * @param {string[]} patterns
@@ -134,11 +94,9 @@ async function resolveWorkspaceManifestPaths(rootDir, patterns) {
 }
 
 /**
- * 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.
+ * Package specifiers the repo's own manifests (root + workspaces) declare, so
+ * the external-dependency probe can tell local from external. No manifest
+ * yields `[]`, which only widens what counts as external.
  *
  * @param {{ rootDir?: string }} [opts]
  * @returns {Promise<string[]>}
@@ -160,8 +118,6 @@ export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
 }
 
 /**
- * Read the draft artifacts the critics evaluate.
- *
  * @param {{ storiesPath: string, techSpecPath?: string|null }} paths
  * @returns {Promise<{ tickets: object[], techSpecContent: string }>}
  */
@@ -188,9 +144,7 @@ export async function loadCriticArtifacts({
 }
 
 /**
- * Log the decision and record a skip on the plan-metrics ledger. The
- * ledger write is best-effort by `appendCriticSkip`'s own contract — it can
- * never fail the plan step.
+ * The ledger write is best-effort and never fails the plan step.
  *
  * @param {{ premortem: object }} verdict
  * @param {object} config
@@ -221,10 +175,6 @@ export async function recordCriticSkips(
 }
 
 /**
- * Load the artifacts, evaluate the pre-mortem, record a skip, and return the
- * verdict. Exported as the CLI's whole body so tests drive it in-process with
- * an explicit config and ledger seam.
- *
  * @param {{
  *   storiesPath: string,
  *   techSpecPath?: string|null,
@@ -232,10 +182,7 @@ export async function recordCriticSkips(
  *   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 `[]`).
+ * @param {string[]} [args.knownPackages]
  * @returns {Promise<{ premortem: object }>}
  */
 export async function evaluateCriticArtifacts({
@@ -266,8 +213,7 @@ async function main() {
     throw new Error(USAGE);
   }
 
-  // stdout is reserved for the verdict JSON — flip every Logger sink that
-  // could land on stdout to stderr before any evaluation runs.
+  // stdout is reserved for the verdict JSON.
   routeAllOutputToStderr();
 
   const verdict = await evaluateCriticArtifacts({