mandrel 2.12.0 → 2.13.0

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

@@ -21,6 +21,7 @@ import { readFile } from 'node:fs/promises';
 import { getLimits } from '../config-resolver.js';
 import { findSimilarOpenStories } from '../duplicate-search.js';
 import { Logger } from '../Logger.js';
+import { parse as parseStoryBody } from '../story-body/story-body.js';
 import {
   renderAcceptanceSpecSystemPrompt,
   renderTechSpecSystemPrompt,
@@ -353,6 +354,111 @@ function resolveRiskHeuristics(config = {}) {
   return [];
 }
 
+/**
+ * Ceilings a seed's advisory complexity signals must fit for the plan
+ * workflow to **suggest** `/deliver-light` at Gate #1 (Story #4741 R3 plan-side
+ * handshake). Framework constants, not operator knobs — mirroring the
+ * conservative intent of `complexity-gate.js`'s `STORY_SHAPE_CEILINGS`
+ * (small, mostly-additive, non-sensitive) but read against the *seed-time*
+ * signals rather than an authored Story shape.
+ *
+ * The suggestion is **advisory only and never an automatic reroute**: it
+ * surfaces at Gate #1 for the operator to decide, and under `--yes` it is
+ * recorded on the envelope while planning proceeds unchanged. `/deliver-light`
+ * is a sibling Story; these ceilings define the plan side of the routing
+ * handshake independently of it.
+ *
+ *   - `maxArtifacts`           — enumerated seed items (one artifact each).
+ *   - `maxRiskHeuristicHits`   — any risk-heuristic hit disqualifies: risk
+ *                                is exactly what a light path should not carry.
+ *   - `maxSensitivePathClasses`— any sensitive-path class disqualifies, the
+ *                                same taxonomy close applies to a landed diff.
+ */
+const DELIVER_LIGHT_SUGGESTION_CEILINGS = Object.freeze({
+  maxArtifacts: 2,
+  maxRiskHeuristicHits: 0,
+  maxSensitivePathClasses: 0,
+});
+
+/**
+ * Derive the advisory `/deliver-light` suggestion from a seed's complexity
+ * signals (Story #4741 AC-6). Pure and total: a malformed / missing signal
+ * bag fails conservative (not suggested), never throws.
+ *
+ * `automatic: false` is part of the contract — the suggestion is surfaced for
+ * the operator, never a silent reroute of a non-interactive run.
+ *
+ * @param {object|null|undefined} complexitySignals
+ * @returns {{
+ *   suggested: boolean,
+ *   automatic: false,
+ *   advisory: true,
+ *   ceilings: typeof DELIVER_LIGHT_SUGGESTION_CEILINGS,
+ *   reasons: string[],
+ * }}
+ */
+export function buildDeliverLightSuggestion(complexitySignals) {
+  const ceilings = DELIVER_LIGHT_SUGGESTION_CEILINGS;
+  const advisory = /** @type {const} */ (true);
+  const automatic = /** @type {const} */ (false);
+  const s = complexitySignals ?? {};
+  const artifactCount = Number.isInteger(s.artifactCount)
+    ? s.artifactCount
+    : Number.POSITIVE_INFINITY;
+  const riskHits = Array.isArray(s.riskHeuristicHits)
+    ? s.riskHeuristicHits.length
+    : Number.POSITIVE_INFINITY;
+  const sensitive = Array.isArray(s.sensitivePathClasses)
+    ? s.sensitivePathClasses.length
+    : Number.POSITIVE_INFINITY;
+
+  const reasons = [];
+  if (artifactCount > ceilings.maxArtifacts) {
+    reasons.push(
+      `seed enumerates ${artifactCount} artifacts (> ${ceilings.maxArtifacts})`,
+    );
+  }
+  if (riskHits > ceilings.maxRiskHeuristicHits) {
+    reasons.push(`seed hits ${riskHits} risk-heuristic phrase(s)`);
+  }
+  if (sensitive > ceilings.maxSensitivePathClasses) {
+    reasons.push(
+      `predicted footprint touches ${sensitive} sensitive-path class(es)`,
+    );
+  }
+
+  const suggested = reasons.length === 0;
+  return {
+    suggested,
+    automatic,
+    advisory,
+    ceilings,
+    reasons: suggested
+      ? [
+          `seed fits the /deliver-light ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
+            'no risk-heuristic hits, no sensitive-path classes) — the operator ' +
+            'may prefer /deliver-light for this scope',
+        ]
+      : reasons,
+  };
+}
+
+/**
+ * Attach the advisory `/deliver-light` suggestion to a complexity-signals bag
+ * as a **nested** field (Story #4741). Nesting — rather than a new top-level
+ * envelope key — keeps every existing per-mode envelope key set byte-stable
+ * (AC-5): the suggestion is derived from the signals it rides on.
+ *
+ * @param {object} complexitySignals
+ * @returns {object} the same signals plus `deliverLightSuggestion`.
+ */
+function withDeliverLightSuggestion(complexitySignals) {
+  return {
+    ...complexitySignals,
+    deliverLightSuggestion: buildDeliverLightSuggestion(complexitySignals),
+  };
+}
+
 /**
  * Count top-level enumerated items (`- `, `* `, `1. `) under the first
  * scope-shaped `## ` heading (Scope / MVP Scope / Proposed Scope / Work
@@ -588,13 +694,17 @@ async function buildSeedFileModeEnvelope({
     seed: { path: seedFilePath ?? null, content },
     // Advisory complexity signals only (Story #4722): no route, no routing
     // authority. The planner authors the trivial-vs-standard verdict; persist
-    // validates a lite claim against the authored Story's shape.
-    complexitySignals: buildComplexitySignals({
-      seedText: content,
-      config,
-      riskHeuristics: heuristics,
-      cwd,
-    }),
+    // validates a lite claim against the authored Story's shape. The nested
+    // `deliverLightSuggestion` is the advisory plan-side routing handshake
+    // (Story #4741 AC-6) — never an automatic reroute.
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: content,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -748,12 +858,14 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexitySignals: buildComplexitySignals({
-      seedText: seed,
-      config,
-      riskHeuristics: heuristics,
-      cwd,
-    }),
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: seed,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -779,6 +891,122 @@ async function buildTicketsModeEnvelope({
   };
 }
 
+/**
+ * Parse a prior Story body into its acceptance criteria and delivered file
+ * map. Total: an unparseable body degrades to empty lists (a delta envelope
+ * grounded on whatever survived), never a throw.
+ *
+ * @param {string} priorBody
+ * @returns {{ priorAcceptance: string[], deliveredFiles: string[] }}
+ */
+function extractPriorArtifacts(priorBody) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(priorBody).body;
+  } catch {
+    return { priorAcceptance: [], deliveredFiles: [] };
+  }
+  const priorAcceptance = Array.isArray(parsed.acceptance)
+    ? parsed.acceptance.filter((a) => typeof a === 'string' && a.length > 0)
+    : [];
+  const deliveredFiles = Array.isArray(parsed.changes)
+    ? parsed.changes
+        .map((c) => (c && typeof c === 'object' ? c.path : c))
+        .filter((p) => typeof p === 'string' && p.length > 0)
+    : [];
+  return { priorAcceptance, deliveredFiles };
+}
+
+/**
+ * Build the amendment (delta) envelope — `plan-context --amends #<id>`
+ * (Story #4741 AC-4, R3-A). The heavy-amendment counterpart to routing a
+ * light amendment through `/deliver-light`: instead of re-interrogating the
+ * repo from scratch (`buildAuthoringContext`'s codebase snapshot and the BDD /
+ * memory / feedback probes), the envelope composes a DELTA from what already
+ * exists — the prior Story's body, its acceptance criteria (the real
+ * contract), and its delivered file map — so a follow-up change plans from the
+ * shape already shipped.
+ *
+ * The semantic steps that reach the ticket are preserved: the open-Story
+ * duplicate search (excluding the amended Story itself), the risk heuristics,
+ * and the authoring system prompts all still ride the envelope. What is
+ * dropped is only the from-scratch repo interrogation the prior artifacts
+ * already stand in for — that is the round-trip diet, not an amputation.
+ *
+ * @param {{
+ *   amendsId: number,
+ *   provider: object,
+ *   config: object,
+ *   settings: object,
+ *   cwd?: string,
+ * }} args
+ * @returns {Promise<object>}
+ */
+async function buildAmendmentModeEnvelope({
+  amendsId,
+  provider,
+  config,
+  settings: _settings,
+  cwd,
+}) {
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new Error(
+      '[plan-context] --amends requires provider.getTicket() to load the prior Story.',
+    );
+  }
+  const prior = await provider.getTicket(amendsId);
+  if (!prior) {
+    throw new Error(
+      `[plan-context] --amends #${amendsId}: prior Story not found — nothing to amend.`,
+    );
+  }
+  const priorBody = typeof prior.body === 'string' ? prior.body : '';
+  const { priorAcceptance, deliveredFiles } = extractPriorArtifacts(priorBody);
+
+  const heuristics = resolveRiskHeuristics(config);
+  const limits = getLimits(config);
+  const duplicates = await searchStoryDuplicates({
+    seed: priorBody,
+    provider,
+    config,
+    excludeIds: [amendsId],
+  });
+
+  return {
+    mode: 'amends',
+    amends: {
+      id: Number(prior.id ?? prior.number ?? amendsId),
+      title: prior.title ?? '',
+      priorBody,
+      priorAcceptance,
+      deliveredFiles,
+    },
+    // The prior body is the seed the delta is authored against.
+    seed: { text: priorBody, path: null },
+    complexitySignals: withDeliverLightSuggestion(
+      buildComplexitySignals({
+        seedText: priorBody,
+        config,
+        riskHeuristics: heuristics,
+        cwd,
+      }),
+    ),
+    duplicates,
+    // No plan temp dir and no from-scratch repo interrogation — the prior
+    // artifacts are the grounding, so there is no docs digest to anchor.
+    docsContext: null,
+    ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
+    maxTickets: limits.maxTickets,
+    riskHeuristics: heuristics,
+    systemPrompts: buildSystemPrompts({
+      heuristics,
+      maxTickets: limits.maxTickets,
+    }),
+    planState: null,
+    planProfile: 'story-amendment',
+  };
+}
+
 /**
  * Build the single planner-context envelope.
  *
@@ -787,11 +1015,12 @@ async function buildTicketsModeEnvelope({
  * bound it (see {@link assertPlanContextWithinCeiling}).
  *
  * @param {{
- *   mode: 'seed-file'|'seed'|'tickets',
+ *   mode: 'seed-file'|'seed'|'tickets'|'amends',
  *   seedFilePath?: string,
  *   seedFileContent?: string,
  *   seedText?: string,
  *   ticketIds?: number[],
+ *   amendsId?: number,
  *   provider: object,
  *   config: object,
  *   settings: object,
@@ -805,6 +1034,7 @@ export async function buildPlanContext({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config = {},
   settings = {},
@@ -817,6 +1047,7 @@ export async function buildPlanContext({
       seedFileContent,
       seedText,
       ticketIds,
+      amendsId,
       provider,
       config,
       settings,
@@ -835,11 +1066,21 @@ async function buildPlanContextEnvelope({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config,
   settings,
   cwd,
 }) {
+  if (mode === 'amends') {
+    return buildAmendmentModeEnvelope({
+      amendsId,
+      provider,
+      config,
+      settings,
+      cwd,
+    });
+  }
   if (mode === 'seed-file') {
     if (!seedFilePath && typeof seedFileContent !== 'string') {
       throw new Error(
@@ -875,6 +1116,6 @@ async function buildPlanContextEnvelope({
     });
   }
   throw new Error(
-    `[plan-context] unknown mode "${mode}" — expected "seed", "seed-file", or "tickets".`,
+    `[plan-context] unknown mode "${mode}" — expected "seed", "seed-file", "tickets", or "amends".`,
   );
 }

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

@@ -17,6 +17,12 @@
  *   --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).
  *                    `/plan` points this at `<plan-dir>/plan-context.json`,
@@ -83,6 +89,25 @@ export function parseTicketIds(raw) {
   return [...new Set(ids)];
 }
 
+/**
+ * Parse a single `--amends` id, tolerating a leading `#` (`#123` or `123`).
+ *
+ * @param {string} raw
+ * @returns {number}
+ */
+export function parseAmendsId(raw) {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error('--amends requires a single prior Story id.');
+  }
+  const id = Number(raw.trim().replace(/^#/, ''));
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `--amends expects a positive integer Story id; got ${JSON.stringify(raw)}`,
+    );
+  }
+  return id;
+}
+
 /**
  * Build the envelope and write it to `stdout` as a single JSON line
  * (or pretty-printed with --pretty). Exported for tests.
@@ -96,6 +121,7 @@ export async function emitPlanContext({
   seedFileContent,
   seedText,
   ticketIds,
+  amendsId,
   provider,
   config,
   settings,
@@ -110,6 +136,7 @@ export async function emitPlanContext({
     seedFileContent,
     seedText,
     ticketIds,
+    amendsId,
     provider,
     config,
     settings,
@@ -139,14 +166,19 @@ export async function emitPlanContext({
       duplicates: (envelope.duplicates ?? []).length,
       // Advisory only (Story #4722): signals, no route — the planner owns
       // the trivial-vs-standard verdict and persist validates it by shape.
+      // The nested `deliverLightSuggestion` is the recorded plan-side routing
+      // handshake (Story #4741 AC-6) — advisory, never an automatic reroute.
       complexitySignals: envelope.complexitySignals
         ? {
             artifactCount: envelope.complexitySignals.artifactCount,
             riskHeuristicHits: envelope.complexitySignals.riskHeuristicHits,
             sensitivePathClasses:
               envelope.complexitySignals.sensitivePathClasses,
+            deliverLightSuggestion:
+              envelope.complexitySignals.deliverLightSuggestion ?? null,
           }
         : null,
+      amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
   } else {
@@ -221,6 +253,7 @@ async function main() {
       seed: { type: 'string' },
       'seed-file': { type: 'string' },
       tickets: { type: 'string' },
+      amends: { type: 'string' },
       out: { type: 'string' },
       pretty: { type: 'boolean', default: false },
     },
@@ -234,16 +267,24 @@ async function main() {
     typeof seedFilePath === 'string' && seedFilePath.length > 0;
   const hasTickets =
     typeof values.tickets === 'string' && values.tickets.trim().length > 0;
-  const entryForms = [hasSeed, hasSeedFile, hasTickets].filter(Boolean).length;
+  const hasAmends =
+    typeof values.amends === 'string' && values.amends.trim().length > 0;
+  const entryForms = [hasSeed, hasSeedFile, hasTickets, hasAmends].filter(
+    Boolean,
+  ).length;
   if (entryForms !== 1) {
     throw new Error(
-      'Pass exactly one of --seed "<text>", --seed-file <path>, or --tickets <ids>.',
+      'Pass exactly one of --seed "<text>", --seed-file <path>, --tickets <ids>, or --amends <id>.',
     );
   }
 
   let mode;
   let ticketIds;
-  if (hasTickets) {
+  let amendsId;
+  if (hasAmends) {
+    mode = 'amends';
+    amendsId = parseAmendsId(values.amends);
+  } else if (hasTickets) {
     mode = 'tickets';
     ticketIds = parseTicketIds(values.tickets);
   } else if (hasSeedFile) {
@@ -288,6 +329,7 @@ async function main() {
         seedFilePath: hasSeedFile ? seedFilePath : undefined,
         seedText: hasSeed ? seedText : undefined,
         ticketIds,
+        amendsId,
         provider,
         config,
         settings,

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

@@ -44,6 +44,15 @@
  *   --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          Plan-diet fast path (Story #4741): run the
+ *                             write-free dry-run first, and — only when it
+ *                             passes clean AND the plan resolves to the `lite`
+ *                             route — 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; a full-route plan keeps
+ *                             its review round-trip (the chain declines, no
+ *                             writes). Ignored when `--dry-run` is also set
  *   --force-review            Operator-forced review stop before persist lands
  *   --allow-over-budget / --allow-large-fan-out
  *
@@ -111,6 +120,7 @@ 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 },
   'allow-over-budget': { type: 'boolean', default: false },
   'allow-large-fan-out': { type: 'boolean', default: false },
@@ -122,7 +132,7 @@ const USAGE =
   '[--plan-acceptance <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
   '[--route-downgrade-reason <text>] ' +
-  '[--dry-run] [--force-review] ' +
+  '[--dry-run] [--chain-on-clean] [--force-review] ' +
   '[--allow-over-budget] [--allow-large-fan-out]';
 
 async function readOptional(filePath, { required }) {
@@ -229,8 +239,11 @@ async function runPersistInvocation({
   provider,
   artifacts,
   metricsSince,
+  dryRun,
 }) {
   const paths = resolveInputPaths(values);
+  const effectiveDryRun =
+    typeof dryRun === 'boolean' ? dryRun : values['dry-run'] === true;
   const settings = {
     baseBranch: config.project?.baseBranch,
     paths: config.project?.paths,
@@ -241,7 +254,7 @@ async function runPersistInvocation({
   return recordPlanInvocation(
     {
       cli: 'plan-persist',
-      mode: values['dry-run'] ? 'dry-run' : 'persist',
+      mode: effectiveDryRun ? 'dry-run' : 'persist',
       config,
     },
     () =>
@@ -252,12 +265,83 @@ async function runPersistInvocation({
         settings,
         opts: {
           ...buildPersistOptions(values, paths, artifacts.planContextEnvelope),
+          dryRun: effectiveDryRun,
+          skipCleanup: effectiveDryRun,
           metricsSince,
         },
       }),
   );
 }
 
+/**
+ * Plan-diet fast path (Story #4741 AC-1/AC-3): chain the lite dry-run into the
+ * real persist in ONE operator invocation.
+ *
+ * Two passes over the **same** loaded artifacts:
+ *
+ *   1. A write-free dry-run. Every gate runs before any `createIssue` can
+ *      happen, so a validation failure — which throws or returns reachability
+ *      orphans — stops here, before a single issue exists (AC-3).
+ *   2. The real write, run **only** when the dry-run passed clean AND resolved
+ *      to the `lite` route. Because it replays the identical artifacts, the
+ *      persisted output is byte-identical to what the dry-run validated
+ *      (AC-1). A full-route plan keeps its review round-trip: the chain
+ *      declines and returns the dry-run result, mutating nothing.
+ *
+ * Exported for tests — this is where the round-trip collapse and its
+ * fail-closed guard live, so a regression here silently re-opens the second
+ * operator round-trip (or worse, persists a plan the dry-run never gated).
+ *
+ * @param {{ values: object, config: object, provider: object,
+ *   artifacts: object, metricsSince: string }} args
+ * @returns {Promise<object>} the persist result, plus a `chain` receipt.
+ */
+export async function runPersistChain({
+  values,
+  config,
+  provider,
+  artifacts,
+  metricsSince,
+}) {
+  const dryResult = await runPersistInvocation({
+    values,
+    config,
+    provider,
+    artifacts,
+    metricsSince,
+    dryRun: true,
+  });
+
+  if (dryResult.route?.route !== 'lite') {
+    dryResult.chain = {
+      attempted: true,
+      persisted: false,
+      reason: 'route-not-lite',
+    };
+    Logger.info(
+      '[plan-persist] --chain-on-clean: dry-run clean but the plan did not ' +
+        'resolve to the lite route — declining the auto-persist; run persist ' +
+        'explicitly after review.',
+    );
+    return dryResult;
+  }
+
+  const persistResult = await runPersistInvocation({
+    values,
+    config,
+    provider,
+    artifacts,
+    metricsSince,
+    dryRun: false,
+  });
+  persistResult.chain = {
+    attempted: true,
+    persisted: true,
+    reason: 'lite-dry-run-clean',
+  };
+  return persistResult;
+}
+
 /**
  * Attach the plan-metrics roll-up for **this** invocation.
  *
@@ -318,15 +402,28 @@ 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;
+
   let result;
   try {
-    result = await runPersistInvocation({
-      values,
-      config,
-      provider,
-      artifacts,
-      metricsSince,
-    });
+    result = useChain
+      ? await runPersistChain({
+          values,
+          config,
+          provider,
+          artifacts,
+          metricsSince,
+        })
+      : await runPersistInvocation({
+          values,
+          config,
+          provider,
+          artifacts,
+          metricsSince,
+        });
   } catch (err) {
     if (err?.code === 'PLAN_REACHABILITY_ORPHANS') {
       process.stdout.write(`${err.message}\n`);