mandrel 1.94.0 → 2.0.0

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

@@ -2,35 +2,20 @@
 /* node:coverage ignore file */
 
 /**
- * plan-context.js — step 1 of the collapsed `/plan` pipeline (Epic #4474,
- * M3 PR2): the single emit-context CLI.
+ * plan-context.js — step 1 of the collapsed `/plan` pipeline.
  *
- * Folds the retired 12-phase pipeline's two emit-context halves plus
- * the three previously-no-CLI library calls
- * (`findSimilarOpenEpics`, clarity scoring, re-plan detection) into ONE
- * stdout-pure JSON envelope. The PR7 cutover retired the delegate CLIs —
- * this is the only emit-context surface.
+ * Emits one stdout-pure JSON envelope for the `/plan` authoring middle.
  *
- * Three entry forms (exactly one is required):
+ * Two operator modes (exactly one is required):
  *
- *   --epic <id>          Existing-Epic mode. Envelope carries `epic`,
- *                        `clarity` (Epic Clarity Gate rubric), `replan`
- *                        (already-planned signals) and `planState`.
+ *   --seed "<text>"           Chat/text ideation. Dup search runs off the
+ *                             raw seed; envelope carries `seed`.
  *
- *   --one-pager <path>   Ideation mode — the Epic does not exist yet
- *                        (creation moves to the persist half). Envelope
- *                        carries `onePager` and `duplicates[]` (cross-Epic
- *                        dup search). No clarity score: the ideation path
- *                        is definitionally clear.
+ *   --seed-file <path>        Same as --seed, but the corpus is read from
+ *                             disk (audit-to-stories handoff, notes).
  *
- *   --seed "<text>"      Headless ideation entry (#4496 fix 1) — neither
- *                        the Epic nor the one-pager exists yet. The dup
- *                        search runs off the raw seed text, and the
- *                        envelope additively carries `seed`, `scopeTriage`
- *                        (the scope-triage rubric applied CLI-side — fix 6)
- *                        and `onePagerSpec`, so the one-pager sections are
- *                        authored in the same batched write as the spec
- *                        artifacts.
+ *   --tickets 123[,456…]      Analyze existing issue(s) into proper
+ *                             Stories. Envelope carries `sourceTickets[]`.
  *
  * Flags:
  *   --pretty         Pretty-print the JSON envelope.
@@ -60,34 +45,42 @@ import { buildPlanContext } from './lib/orchestration/plan-context.js';
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
+/**
+ * Parse a comma-/space-separated ticket id list into positive integers.
+ *
+ * @param {string} raw
+ * @returns {number[]}
+ */
+export function parseTicketIds(raw) {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error('--tickets requires one or more positive issue ids.');
+  }
+  const ids = raw
+    .split(/[,\s]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => Number(s));
+  if (ids.some((n) => !Number.isInteger(n) || n <= 0)) {
+    throw new Error(
+      `--tickets expects positive integer ids; got ${JSON.stringify(raw)}`,
+    );
+  }
+  return [...new Set(ids)];
+}
+
 /**
  * Build the envelope and write it to `stdout` as a single JSON line
- * (or pretty-printed with --pretty). Exported for tests: the stdout-purity
- * test injects a fake provider and a capture stream and asserts the
- * captured output is exactly one `JSON.parse`-able payload.
+ * (or pretty-printed with --pretty). Exported for tests.
  *
- * @param {{
- *   mode: 'epic'|'one-pager'|'seed',
- *   epicId?: number,
- *   onePagerPath?: string,
- *   onePagerContent?: string,
- *   seedText?: string,
- *   provider: object,
- *   config: object,
- *   settings: object,
- *   fullContext?: boolean,
- *   pretty?: boolean,
- *   cwd?: string,
- *   stdout?: { write: (chunk: string) => void },
- * }} args
+ * @param {object} args
  * @returns {Promise<object>} the emitted envelope.
  */
 export async function emitPlanContext({
   mode,
-  epicId,
-  onePagerPath,
-  onePagerContent,
+  seedFilePath,
+  seedFileContent,
   seedText,
+  ticketIds,
   provider,
   config,
   settings,
@@ -98,10 +91,10 @@ export async function emitPlanContext({
 }) {
   const envelope = await buildPlanContext({
     mode,
-    epicId,
-    onePagerPath,
-    onePagerContent,
+    seedFilePath,
+    seedFileContent,
     seedText,
+    ticketIds,
     provider,
     config,
     settings,
@@ -118,37 +111,38 @@ export async function emitPlanContext({
 async function main() {
   const { values } = parseArgs({
     options: {
-      epic: { type: 'string' },
-      'one-pager': { type: 'string' },
       seed: { type: 'string' },
+      'seed-file': { type: 'string' },
+      tickets: { type: 'string' },
       pretty: { type: 'boolean', default: false },
       'full-context': { type: 'boolean', default: false },
     },
     strict: true,
   });
 
-  const hasEpic = typeof values.epic === 'string' && values.epic.length > 0;
-  const hasOnePager =
-    typeof values['one-pager'] === 'string' && values['one-pager'].length > 0;
-  const hasSeed = typeof values.seed === 'string' && values.seed.length > 0;
-  const entryForms = [hasEpic, hasOnePager, hasSeed].filter(Boolean).length;
+  const seedText = values.seed || null;
+  const seedFilePath = values['seed-file'] || null;
+  const hasSeed = typeof seedText === 'string' && seedText.length > 0;
+  const hasSeedFile =
+    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;
   if (entryForms !== 1) {
     throw new Error(
-      'Pass exactly one of --epic <id>, --one-pager <path> or --seed "<text>". ' +
-        '(--epic: existing-Epic mode; --one-pager: ideation mode; ' +
-        '--seed: headless ideation entry.)',
+      'Pass exactly one of --seed "<text>", --seed-file <path>, or --tickets <ids>.',
     );
   }
-  const mode = hasEpic ? 'epic' : hasOnePager ? 'one-pager' : 'seed';
 
-  let epicId;
-  if (hasEpic) {
-    epicId = Number.parseInt(values.epic, 10);
-    if (!Number.isInteger(epicId)) {
-      throw new Error(
-        `--epic must be a numeric issue id (got "${values.epic}").`,
-      );
-    }
+  let mode;
+  let ticketIds;
+  if (hasTickets) {
+    mode = 'tickets';
+    ticketIds = parseTicketIds(values.tickets);
+  } else if (hasSeedFile) {
+    mode = 'seed-file';
+  } else {
+    mode = 'seed';
   }
 
   // stdout is reserved for the JSON envelope: flip every Logger sink that
@@ -175,23 +169,19 @@ async function main() {
   }
   const provider = createProvider(config);
 
-  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode so the folded
-  // emit surface is measured against the 12-phase baseline. One-pager and
-  // seed modes have no Epic yet, so the record routes to the standalone
-  // stream (epicId null) exactly like `story-plan.js`.
   await recordPlanInvocation(
     {
       cli: 'plan-context',
       mode,
-      epicId: hasEpic ? epicId : null,
+      epicId: null,
       config,
     },
     () =>
       emitPlanContext({
         mode,
-        epicId,
-        onePagerPath: hasOnePager ? values['one-pager'] : undefined,
-        seedText: hasSeed ? values.seed : undefined,
+        seedFilePath: hasSeedFile ? seedFilePath : undefined,
+        seedText: hasSeed ? seedText : undefined,
+        ticketIds,
         provider,
         config,
         settings,