mandrel 1.94.0 → 2.0.0

package/.agents/scripts/lib/orchestration/story-close/phases/code-review.js

@@ -2,10 +2,12 @@
  * phases/code-review.js — Story-scope code-review phase
  * (Story #2840, Epic #2815 — Pluggable Code Review + Story-Level Review).
  *
- * Sits between the close-validation gate chain and the merge into
- * `epic/<id>` inside `runStoryCloseLocked` (locked-pipeline.js). The
- * configured ReviewProvider runs against the
- * `epic/<id>`…`story-<id>` diff. The unified `verification-results`
+ * Sits between the close-validation gate chain and merge in the deleted
+ * pre-v2 Epic close path (`runStoryCloseLocked` / `locked-pipeline.js`,
+ * merge target `epic/<id>`). The v2 `/deliver` path
+ * (`single-story-close.js`) reviews `main`…`story-<id>` instead. The
+ * configured ReviewProvider runs against the supplied base…head diff. The
+ * unified `verification-results`
  * structured comment is posted to the Story issue (default
  * `commentTargetId === ticketId` inside `runCodeReview`). Outcomes:
  *
@@ -39,7 +41,7 @@ import {
 import { gitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
 import { runCodeReview } from '../../code-review.js';
-import { emitBlockedCloseResult } from '../merge-runner.js';
+import { emitBlockedCloseResult } from '../emit-blocked.js';
 
 /**
  * The review depth the Story-scope local-lens pass runs at. Shift-left
@@ -282,17 +284,18 @@ export async function runStoryReviewCore({
 }
 
 /**
- * Run a Story-scope code review against the `epic/<id>`…`story-<id>`
- * diff and post the structured `code-review` comment to the Story
- * issue. Returns `{ blocked }` where `blocked` is either `null`
- * (caller proceeds to merge) or the blocked-envelope (caller returns
- * it verbatim and the CLI exits 1).
+ * Run a Story-scope code review against the supplied base…head diff
+ * (v2: `main`…`story-<id>` via `single-story-close.js`; pre-v2 Epic
+ * close: `epic/<id>`…`story-<id>`) and post the structured
+ * `code-review` comment to the Story issue. Returns `{ blocked }` where
+ * `blocked` is either `null` (caller proceeds to open/merge the PR) or the
+ * blocked-envelope (caller returns it verbatim and the CLI exits 1).
  *
  * The optional `planningRisk` envelope (Story #3940) is the parent Epic's
  * judged risk, read best-effort off the `epic-plan-state` checkpoint by the
  * locked pipeline. It is forwarded into `runCodeReview` so the review depth is
- * resolved from BOTH the Epic-judged risk and the Story's own
- * `epic/<id>...story-<id>` changed-file count — a small Story under a
+ * resolved from BOTH the parent Epic's judged risk (pre-v2) and the Story's own
+ * base…head changed-file count — a small Story under a
  * high-risk Epic still earns `deep`, a small Story under a low-risk Epic gets
  * `light`, and an absent envelope resolves `standard` (today's behaviour).
  * Depth is input-only: it never changes `{ blocked }` or the posted comment.

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -0,0 +1,237 @@
+/**
+ * story-follow-ups.js — capture actionable follow-ups from a landed Story.
+ *
+ * Replaces the unwired Epic retro as the default closeout for v2: after a
+ * Story merges, read its standalone `signals.ndjson` friction stream, compose
+ * routed proposals, auto-file follow-up issues (when enabled), and upsert a
+ * structured `follow-ups` comment on the Story.
+ *
+ * @module lib/orchestration/story-follow-ups
+ */
+
+import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
+import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
+import { Logger } from '../Logger.js';
+import { forEachLine } from '../observability/signals-writer.js';
+import { composeRoutedProposals } from './retro-proposals.js';
+import { upsertStructuredComment } from './ticketing.js';
+
+export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
+
+/**
+ * @param {object} [config]
+ * @returns {{ frameworkRepo: string, consumerRepo: string, currentRepo: { owner: string, repo: string } }}
+ */
+export function resolveFollowUpRepos(config) {
+  const owner =
+    typeof config?.github?.owner === 'string' ? config.github.owner.trim() : '';
+  const repo =
+    typeof config?.github?.repo === 'string' ? config.github.repo.trim() : '';
+  const consumerRepo =
+    owner && repo ? `${owner}/${repo}` : DEFAULT_FRAMEWORK_REPO;
+  const frameworkRepo =
+    typeof config?.github?.frameworkRepo === 'string' &&
+    config.github.frameworkRepo.trim()
+      ? config.github.frameworkRepo.trim()
+      : DEFAULT_FRAMEWORK_REPO;
+  const [cOwner, cRepo] = consumerRepo.split('/');
+  return {
+    frameworkRepo,
+    consumerRepo,
+    currentRepo: {
+      owner: cOwner || 'unknown',
+      repo: cRepo || 'unknown',
+    },
+  };
+}
+
+/**
+ * @param {number} storyId
+ * @param {object} [config]
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer' }>>}
+ */
+export async function gatherStoryFrictionSignals(storyId, config) {
+  const signals = [];
+  await forEachLine(
+    null,
+    storyId,
+    (parsed) => {
+      if (!parsed || typeof parsed !== 'object') return;
+      const kind = parsed.kind;
+      if (kind !== 'friction' && kind !== undefined) {
+        // Prefer friction records; also accept category-bearing rows.
+      }
+      const category =
+        typeof parsed.category === 'string' ? parsed.category.trim() : '';
+      if (!category) return;
+      const source = parsed.source === 'framework' ? 'framework' : 'consumer';
+      signals.push({ category, source });
+    },
+    config,
+  );
+  return signals;
+}
+
+/**
+ * @param {{
+ *   storyId: number,
+ *   proposals: object,
+ *   graduated: object,
+ * }} args
+ * @returns {string}
+ */
+export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
+  const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
+  const framework = proposals?.framework ?? [];
+  const consumer = proposals?.consumer ?? [];
+  const discarded = proposals?.discarded ?? [];
+  const lines = [
+    '### follow-ups',
+    '',
+    `Actionable follow-ups captured from Story #${storyId} after merge.`,
+    '',
+  ];
+  if (filed.length > 0) {
+    lines.push('**Filed**');
+    for (const item of filed) {
+      lines.push(
+        `- ${item.source}: ${item.title}${item.url ? ` — ${item.url}` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+  if (framework.length + consumer.length > 0 && filed.length === 0) {
+    lines.push('**Actionable (not auto-filed)**');
+    for (const item of [...framework, ...consumer]) {
+      lines.push(`- ${item.source}: ${item.title}`);
+      lines.push('');
+      lines.push('```bash');
+      lines.push(item.command);
+      lines.push('```');
+    }
+    lines.push('');
+  }
+  if (discarded.length > 0) {
+    lines.push('**Single-occurrence (not filed)**');
+    for (const item of discarded) {
+      lines.push(`- ${item.source}: \`${item.category}\` ×${item.occurrences}`);
+    }
+    lines.push('');
+  }
+  if (
+    filed.length === 0 &&
+    framework.length === 0 &&
+    consumer.length === 0 &&
+    discarded.length === 0
+  ) {
+    lines.push('_No friction signals — nothing to follow up._');
+    lines.push('');
+  }
+  lines.push('```json');
+  lines.push(
+    JSON.stringify(
+      {
+        storyId,
+        framework: framework.map((i) => i.category),
+        consumer: consumer.map((i) => i.category),
+        discarded: discarded.map((i) => i.category),
+        filed: filed.map((i) => ({
+          category: i.category,
+          url: i.url ?? null,
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+  lines.push('```');
+  return lines.join('\n');
+}
+
+/**
+ * Capture and persist Story follow-ups. Never throws — close must not fail
+ * because follow-up filing flaked.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {object} args.provider
+ * @param {object} [args.config]
+ * @param {string} [args.cwd]
+ * @param {(tag: string, msg: string) => void} [args.progress]
+ * @returns {Promise<object>}
+ */
+/**
+ * Capture follow-ups only when merge confirm landed (`action === 'done'`).
+ * One-liner seam for the confirm-merge CLI.
+ */
+export async function captureFollowUpsAfterConfirm(confirmation, ctx) {
+  if (confirmation?.action !== 'done') return null;
+  return captureStoryFollowUps(ctx);
+}
+
+export async function captureStoryFollowUps({
+  storyId,
+  provider,
+  config,
+  cwd,
+  progress,
+}) {
+  const sid = Number(storyId);
+  if (!Number.isInteger(sid) || sid <= 0) {
+    return { ok: false, reason: 'invalid-story-id' };
+  }
+  try {
+    const signals = await gatherStoryFrictionSignals(sid, config);
+    const repos = resolveFollowUpRepos(config);
+    const proposals = composeRoutedProposals({
+      anchorId: sid,
+      anchorKind: 'story',
+      frameworkRepo: repos.frameworkRepo,
+      consumerRepo: repos.consumerRepo,
+      signals,
+      unresolvedBlockedEvents: [],
+    });
+    const graduated = await graduateRetroProposals({
+      epicId: sid,
+      provider,
+      config,
+      currentRepo: repos.currentRepo,
+      frameworkRepo: (() => {
+        const [owner, repo] = repos.frameworkRepo.split('/');
+        return { owner, repo };
+      })(),
+      routedProposals: proposals,
+      cwd,
+    });
+    const body = buildFollowUpsCommentBody({
+      storyId: sid,
+      proposals,
+      graduated,
+    });
+    await upsertStructuredComment(provider, sid, FOLLOW_UPS_COMMENT_TYPE, body);
+    progress?.(
+      'FOLLOW-UPS',
+      `Captured follow-ups for Story #${sid} (filed=${graduated.filed?.length ?? 0}).`,
+    );
+    return {
+      ok: true,
+      storyId: sid,
+      proposals,
+      graduated,
+      signalCount: signals.length,
+    };
+  } catch (err) {
+    Logger.warn(
+      `[story-follow-ups] capture failed for #${sid}: ${err?.message ?? err}`,
+    );
+    progress?.(
+      'FOLLOW-UPS',
+      `⚠️ Follow-up capture failed (close continues): ${err?.message ?? err}`,
+    );
+    return {
+      ok: false,
+      reason: 'capture-failed',
+      error: String(err?.message ?? err),
+    };
+  }
+}

package/.agents/scripts/lib/orchestration/story-init-remote.js

@@ -0,0 +1,47 @@
+import { Logger } from '../Logger.js';
+import { AGENT_LABELS } from '../label-constants.js';
+import { upsertStructuredComment } from './ticketing.js';
+
+/**
+ * Fail closed when the repository remote cannot be verified. The Story is
+ * blocked before lease/branch/worktree mutation so a host that misses the
+ * result envelope cannot strand an executing Story.
+ */
+export async function handleRemoteVerificationFailure({
+  provider,
+  storyId,
+  remote,
+  dryRun = false,
+}) {
+  if (remote?.remoteVerified) return;
+  const message =
+    `[single-story-init] remote verification failed for Story #${storyId}: ` +
+    `${remote?.detail ?? 'origin is unavailable'}`;
+  if (!dryRun) {
+    try {
+      await upsertStructuredComment(
+        provider,
+        storyId,
+        'friction',
+        `### Remote verification blocked delivery\n\n${message}`,
+      );
+    } catch (err) {
+      Logger.warn(
+        `[single-story-init] failed to post remote-verification friction: ${err?.message ?? err}`,
+      );
+    }
+    try {
+      await provider.updateTicket(storyId, {
+        labels: {
+          add: [AGENT_LABELS.BLOCKED],
+          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
+        },
+      });
+    } catch (err) {
+      Logger.warn(
+        `[single-story-init] failed to block Story after remote verification: ${err?.message ?? err}`,
+      );
+    }
+  }
+  throw new Error(message);
+}

package/.agents/scripts/lib/orchestration/story-plan-state.js

@@ -0,0 +1,48 @@
+import { parseFencedJsonComment } from './structured-comment-parser.js';
+import { findStructuredComment } from './ticketing.js';
+
+/**
+ * Read the v2 Story planning checkpoint. Missing/malformed comments degrade
+ * to null so unplanned Stories still receive the neutral review posture.
+ */
+export async function readStoryPlanState({
+  provider,
+  storyId,
+  findCommentFn = findStructuredComment,
+}) {
+  const comment = await findCommentFn(
+    provider,
+    Number(storyId),
+    'story-plan-state',
+  );
+  const state = parseFencedJsonComment(comment);
+  return state && typeof state === 'object' ? state : null;
+}
+
+export async function readStoryPlanningRisk(args) {
+  const state = await readStoryPlanState(args);
+  return state?.planningRisk ?? null;
+}
+
+export async function readStoryPlanningRiskSafe(args) {
+  try {
+    return await readStoryPlanningRisk(args);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prefer an explicit `planningRisk` override; otherwise load the Story
+ * checkpoint. Callers that omit the field (or pass `undefined`) get the
+ * persisted plan risk; callers that pass `null` keep the neutral posture.
+ */
+export async function resolveStoryPlanningRisk({
+  provider,
+  storyId,
+  planningRisk,
+  findCommentFn,
+}) {
+  if (planningRisk !== undefined) return planningRisk;
+  return readStoryPlanningRiskSafe({ provider, storyId, findCommentFn });
+}

package/.agents/scripts/lib/orchestration/{epic-runner → story-progress}/story-run-progress-writer.js

@@ -13,9 +13,9 @@
  *
  * The renderer survives because its `{ body, payload }` output still feeds
  * two non-comment contracts: the `renderedBody` markdown the `/deliver`
- * and `single-story-deliver` CLIs (`story-phase.js`, the inline `story-init.js` prepare step)
- * relay to chat so the operator sees the phase table inline, and the snapshot
- * payload returned in those CLIs' JSON envelopes. `upsertStoryRunProgress`
+ * workflow (`helpers/deliver-story.md`, `story-phase.js`) relays to chat so
+ * the operator sees the phase table inline, and the snapshot payload returned
+ * in those CLIs' JSON envelopes. `upsertStoryRunProgress`
  * therefore renders-only: it computes the body/payload and (optionally) mirrors
  * a low-severity webhook event, but writes no GitHub comment.
  *

package/.agents/scripts/lib/orchestration/structured-comment-parser.js

@@ -2,7 +2,7 @@
  * structured-comment-parser.js — shared parser for fenced-JSON structured
  * comments.
  *
- * Several callers (epic-runner Checkpointer, ProgressReporter
+ * Several callers (the deleted epic-runner Checkpointer/ProgressReporter,
  * `parseStoryRunProgressComment` / `parsePhaseTimingsComment`, wave-gate's
  * local `extractJsonBlock`) need to extract the `{...}` payload from the
  * fenced ```json``` block of a structured comment body. They had each open-

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -24,16 +24,14 @@
  * name at least one path-shaped token so vague verbs ("clean up",
  * "refactor") can't slip through.
  *
- * `body.changes` items may be either:
- *   1. A string bullet (legacy shape, e.g. `"src/foo.ts: extract handler"`).
- *   2. An object `{ path: string, assumption: enum }` (Story #2636 shape).
+ * `body.changes` items must be object-form `{ path: string, assumption: enum }`
+ * entries (Story #2636 shape). Plain string bullets are rejected at parse
+ * time and by this validator.
  *
  * Object-form items must declare an `assumption` ∈ `creates |
  * refactors-existing | exists | deletes`. The optional `body.references`
  * array uses the same object shape and is the home for paths the Story
  * reads but does not modify (test fixtures, sibling modules, etc.).
- * String-form `changes` items remain legal so legacy plans keep parsing,
- * but they emit a deprecation signal via `validateStoryFileAssumptions`.
  *
  * `body.verify` entries must either name a testing tier in parentheses
  * drawn from `VERIFY_TIER_VALUES` (e.g. `npm run test (unit)`) or be the
@@ -248,25 +246,17 @@ function collectChangesErrors(prefix, rawChanges) {
     return [`${prefix}: body.changes must list at least one bullet.`];
   }
   const errors = [];
-  // An entry "names a path" when it is either a path-shaped bullet
-  // string OR an object-form entry that passed the assumption schema.
-  const namesPath = (c) => {
-    if (typeof c === 'string') return bulletNamesPath(c);
-    return isObjectPathEntry(c);
-  };
+  const namesPath = (c) => isObjectPathEntry(c);
   if (changes.every((c) => !namesPath(c))) {
     errors.push(
-      `${prefix}: body.changes bullets name no path-shaped token. Use "<path>: <verb> <object>" — e.g. "src/components/Foo.tsx: extract handleSubmit". Object-form entries may also declare { path, assumption } directly.`,
+      `${prefix}: body.changes must declare at least one { path, assumption } object entry.`,
     );
   }
   for (const entry of changes) {
     if (typeof entry === 'string') {
-      const verb = vagueVerbWithoutTarget(entry);
-      if (verb) {
-        errors.push(
-          `${prefix}: body.changes bullet uses vague verb "${verb}" without a named target: "${entry}".`,
-        );
-      }
+      errors.push(
+        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".`,
+      );
       continue;
     }
     if (isMalformedObjectPathEntry(entry)) {

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -10,8 +10,7 @@ import { computeStoryReachability } from './story-reachability.js';
  *
  * The decomposer emits `body` as the canonical serialized **string**, but
  * the conflict passes (`indexConsumers`, `indexAssumptionEntries`,
- * `computeMissingBddScaffoldFindings`, the sibling-create scan in
- * `computeRegistryFindings`, and the legacy-bullet branch of
+ * `computeMissingBddScaffoldFindings`, and the producer path scan in
  * `collectStoryProducerPaths`) historically read `story.body` only when it
  * was already an object — so on the production string shape the
  * `implicit-cross-story-dep`, `fan-out`, registry, and `missing-bdd-scaffold`
@@ -144,71 +143,26 @@ const WRITE_IMPLYING_ASSUMPTIONS = Object.freeze(
   new Set(['creates', 'refactors-existing', 'deletes']),
 );
 
-/**
- * Extract the path-shaped head from a single legacy string-form
- * `body.changes` bullet.
- *
- * Conventional shape is `"<path>: <verb> <object>"`; we slice on the first
- * colon and return the head when it contains a slash or a dot, otherwise
- * `null`. Mirrors the heuristic in `ticket-validator-sizing.js` so producer
- * extraction and `fileCount` accounting agree on what counts as a path.
- *
- * Object-form entries (`{ path, assumption }`) are *not* handled here — they
- * are extracted via `collectStoryAssumptionEntries` in `indexProducers`. This
- * helper only understands the legacy string shape and returns `null` for any
- * non-string input.
- */
-function extractChangeBulletPath(bullet) {
-  if (typeof bullet !== 'string') return null;
-  const colonIdx = bullet.indexOf(':');
-  if (colonIdx <= 0) return null;
-  const head = bullet.slice(0, colonIdx).trim();
-  if (!/[\\/.]/.test(head)) return null;
-  return head;
-}
-
 /**
  * Collect the write-implying producer paths a single Story declares.
  *
- * Two shapes are honoured so the modern object-form `changes` contract and
- * the legacy string-bullet contract both feed the producer index:
- *
- *   - **Object form** (`{ path, assumption }`) — reuses
- *     `collectStoryAssumptionEntries` (the same extractor the Phase-8
- *     file-assumption gate uses), then keeps only `changes`-sourced entries
- *     whose assumption writes the path (`creates` / `refactors-existing` /
- *     `deletes`). `exists` reads and `references` entries are dropped.
- *   - **Legacy string bullets** (`"<path>: <verb> ..."`) — slice the
- *     colon-head via `extractChangeBulletPath`. Legacy bullets carry no
- *     assumption, so they are treated as writes (preserving pre-migration
- *     behaviour).
+ * Uses object-form `{ path, assumption }` entries via
+ * `collectStoryAssumptionEntries` (the same extractor the Phase-8
+ * file-assumption gate uses), keeping only `changes`-sourced entries
+ * whose assumption writes the path (`creates` / `refactors-existing` /
+ * `deletes`). `exists` reads and `references` entries are dropped.
  *
  * Returns a de-duplicated array of producer paths for the Story.
  */
 function collectStoryProducerPaths(story) {
   const paths = new Set();
 
-  // Object-form entries via the shared extractor. Only `changes`-sourced
-  // write-implying assumptions count as producers.
   for (const entry of collectStoryAssumptionEntries(story)) {
     if (entry.source !== 'changes') continue;
     if (!WRITE_IMPLYING_ASSUMPTIONS.has(entry.assumption)) continue;
     paths.add(entry.path);
   }
 
-  // Legacy string bullets — extract the colon-head path. Skip non-string
-  // entries (object-form already handled above).
-  const body = story?.body;
-  const changes =
-    body && typeof body === 'object' && Array.isArray(body.changes)
-      ? body.changes
-      : [];
-  for (const bullet of changes) {
-    if (typeof bullet !== 'string') continue;
-    const path = extractChangeBulletPath(bullet);
-    if (path) paths.add(path);
-  }
-
   return Array.from(paths);
 }
 
@@ -223,11 +177,9 @@ function storySlugOf(story) {
 
 /**
  * Build the producers index — `Map<path, Array<{storySlug, taskSlug}>>` —
- * by walking every Story's declared writes. Both object-form
- * `{ path, assumption }` entries and legacy `"<path>: <verb> ..."` string
- * bullets are honoured via `collectStoryProducerPaths`; only write-implying
- * assumptions (and legacy bullets, which carry no assumption) count as
- * producers.
+ * by walking every Story's declared writes. Only object-form
+ * `{ path, assumption }` entries count as producers via
+ * `collectStoryProducerPaths`; only write-implying assumptions count.
  *
  * `taskSlug` is retained in the entry shape for finding/render
  * compatibility; in the 2-tier model it carries the Story's own slug since
@@ -519,9 +471,8 @@ function computeRegistryFindings({
     existing.push(entry);
     perStory.set(entry.storySlug, existing);
   }
-  // (a) direct registry edits — accept both legacy string-form producers
-  // (from `indexProducers`) and modern object-form `{ path, assumption }`
-  // entries (from `indexAssumptionEntries`).
+  // (a) direct registry edits — object-form `{ path, assumption }` entries
+  // from `indexAssumptionEntries` (and the producer index built from them).
   for (const [path, entries] of producers.entries()) {
     if (!isRegistryPath(path, patterns)) continue;
     for (const e of entries) {
@@ -778,7 +729,6 @@ export function renderHardConflictError(finding) {
 
 // Internal helpers exposed for unit tests; not part of the public surface.
 export const _internal = {
-  extractChangeBulletPath,
   collectStoryProducerPaths,
   WRITE_IMPLYING_ASSUMPTIONS,
   indexProducers,