mandrel 2.31.0 → 2.32.0

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

@@ -1,379 +0,0 @@
-/**
- * story-plan.js — helpers for `/plan`.
- *
- * Pure functions used by `.agents/scripts/story-plan.js` (the CLI).
- * Kept side-effect-free so the CLI stays a thin orchestrator and these
- * helpers are easy to unit-test.
- *
- * Surfaces:
- *   - DEFAULT_REFINE_THRESHOLD     — seed length below which refinement
- *                                    is auto-suggested.
- *   - REQUIRED_SECTIONS            — canonical section headings the body
- *                                    must carry itself. Story #4874: the
- *                                    `## Acceptance` / `## Verify` sections
- *                                    are deliberately NOT among them —
- *                                    those lists are the ticket's top-level
- *                                    machine contract and persist
- *                                    synthesizes their sections, exactly as
- *                                    the story-author prompt instructs.
- *   - rankDuplicateCandidates({ seed, openStories, maxResults })
- *                                  — Jaccard-overlap ranking of open
- *                                    Stories whose titles fuzzy-match
- *                                    the seed.
- *   - validateStoryBody(body, contract)
- *                                  — schema-light shape check against the
- *                                    canonical Story-body contract: `##
- *                                    Goal` / `## Changes` present, no
- *                                    `Epic:` reference, and an
- *                                    acceptance/verify contract resolvable
- *                                    from the top-level arrays or the body.
- *   - buildContextEnvelope(opts)   — assemble the context envelope the
- *                                    host LLM consumes.
- */
-
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { overlapScore, tokenize } from './duplicate-search.js';
-import { parse as parseStoryBody } from './story-body/story-body.js';
-
-export const DEFAULT_REFINE_THRESHOLD = 200;
-export const DEFAULT_DUPLICATE_MAX_RESULTS = 5;
-export const DEFAULT_DUPLICATE_MIN_SCORE = 0.15;
-
-/**
- * The sections the authored body must carry itself. Story #4874 reconciled
- * this list with the story-author prompt: the prompt tells the author to
- * write `acceptance[]` / `verify[]` **once** at the ticket's top level and
- * omit the matching body sections, so demanding those sections here made a
- * prompt-faithful body unpersistable and cost a re-author round.
- */
-export const REQUIRED_SECTIONS = ['Goal', 'Changes'];
-
-/** The contract lists persist synthesizes into the body from the top level. */
-const CONTRACT_FIELDS = /** @type {const} */ (['acceptance', 'verify']);
-
-const EPIC_REF_PATTERN = /^\s*Epic:\s*#\d+/m;
-
-/**
- * Rank open Stories by title-overlap with the seed. Reuses the same
- * tokenize + Jaccard primitives that `duplicate-search.js` exposes for
- * Epic-level dedupe — Stories are a different ticket type but the
- * scoring shape is the same.
- *
- * @param {{ seed: string, openStories: Array<{ id:number, title:string, url?:string, body?:string }>, maxResults?: number, minScore?: number }} opts
- * @returns {Array<{ id:number, title:string, url?:string, score:number }>}
- */
-export function rankDuplicateCandidates({
-  seed,
-  openStories,
-  maxResults = DEFAULT_DUPLICATE_MAX_RESULTS,
-  minScore = DEFAULT_DUPLICATE_MIN_SCORE,
-}) {
-  if (!seed || typeof seed !== 'string') {
-    throw new Error('rankDuplicateCandidates: seed must be a non-empty string');
-  }
-  if (!Array.isArray(openStories)) {
-    throw new Error('rankDuplicateCandidates: openStories must be an array');
-  }
-  const seedTokens = tokenize(seed);
-  if (seedTokens.size === 0) return [];
-
-  const ranked = [];
-  for (const story of openStories) {
-    if (!story || typeof story.title !== 'string') continue;
-    const corpus = `${story.title}\n${story.body ?? ''}`;
-    const candTokens = tokenize(corpus);
-    const score = overlapScore(seedTokens, candTokens);
-    if (score >= minScore) {
-      ranked.push({
-        id: story.id,
-        title: story.title,
-        url: story.url,
-        score: Number(score.toFixed(4)),
-      });
-    }
-  }
-  ranked.sort((a, b) => b.score - a.score);
-  return ranked.slice(0, maxResults);
-}
-
-/**
- * Decide whether the seed warrants a Phase-2 idea-refinement pass.
- * The default rule: refine when the seed is shorter than
- * `DEFAULT_REFINE_THRESHOLD` chars. Operator overrides via
- * `--refine` / `--no-refine` short-circuit the heuristic.
- *
- * @param {{ seed:string, override?:'on'|'off'|null, threshold?:number }} opts
- * @returns {{ refine:boolean, reason:string }}
- */
-export function shouldRefine({
-  seed,
-  override = null,
-  threshold = DEFAULT_REFINE_THRESHOLD,
-}) {
-  if (override === 'on') return { refine: true, reason: 'operator-forced-on' };
-  if (override === 'off')
-    return { refine: false, reason: 'operator-forced-off' };
-  if (typeof seed !== 'string' || seed.trim().length === 0) {
-    return { refine: true, reason: 'empty-seed' };
-  }
-  if (seed.trim().length < threshold) {
-    return {
-      refine: true,
-      reason: `seed-shorter-than-${threshold}-chars`,
-    };
-  }
-  return { refine: false, reason: `seed-meets-${threshold}-char-threshold` };
-}
-
-/**
- * Collect the violations for one contract list (`acceptance` / `verify`).
- *
- * The list may be authored at the ticket's top level (the shape the
- * story-author prompt prescribes) or written into the body as a section —
- * either satisfies the contract, and the top level is preferred because
- * persist synthesizes the section from it. Only two shapes are violations:
- * the list is nowhere, or it is in both places and the two disagree (fail
- * closed rather than guess which is authoritative, mirroring
- * `plan-persist`'s `syncContractFieldFromTopLevel`).
- *
- * @param {'acceptance'|'verify'} field
- * @param {unknown} bodyList  The parsed body's section entries.
- * @param {unknown} topLevel  The ticket's top-level array.
- * @returns {string[]}
- */
-function collectContractErrors(field, bodyList, topLevel) {
-  const inBody = (Array.isArray(bodyList) ? bodyList : []).map(String);
-  const inTicket = (Array.isArray(topLevel) ? topLevel : []).map(String);
-  if (inBody.length === 0 && inTicket.length === 0) {
-    return [
-      `${field} must list at least one entry — author it as the ticket's top-level ${field}[] array; persist synthesizes the "## ${field[0].toUpperCase()}${field.slice(1)}" section from it`,
-    ];
-  }
-  if (
-    inBody.length > 0 &&
-    inTicket.length > 0 &&
-    (inBody.length !== inTicket.length ||
-      inBody.some((v, i) => v !== inTicket[i]))
-  ) {
-    return [
-      `${field} disagrees between the body section and the top-level ${field}[] array — author it once, at the top level`,
-    ];
-  }
-  return [];
-}
-
-/**
- * Schema-light validator for a standalone-Story body, stated against the
- * same authoring shape the story-author prompt prescribes (Story #4874).
- *
- * It parses the body with the canonical Story-body parser and asserts:
- * a non-empty `## Goal`, at least one `## Changes` entry, no leaking
- * `Epic: #N` reference (the standalone contract), and an acceptance +
- * verify contract resolvable from the ticket's top-level arrays **or** the
- * body's own sections. It deliberately does not demand the `## Acceptance`
- * / `## Verify` sections of the author — persist synthesizes them.
- *
- * @param {string} body
- * @param {{ acceptance?: string[], verify?: string[] }} [contract]
- *   The ticket's top-level contract arrays, when the caller has them.
- * @returns {{ ok:boolean, errors:string[] }}
- */
-export function validateStoryBody(body, contract = {}) {
-  if (typeof body !== 'string' || body.trim().length === 0) {
-    return { ok: false, errors: ['body is empty'] };
-  }
-
-  let parsed;
-  try {
-    parsed = parseStoryBody(body).body;
-  } catch (err) {
-    return {
-      ok: false,
-      errors: [`body is not a parseable Story body: ${err.message}`],
-    };
-  }
-
-  const errors = [];
-  if (typeof parsed.goal !== 'string' || parsed.goal.trim() === '') {
-    errors.push('missing required section: "## Goal"');
-  }
-  if (!Array.isArray(parsed.changes) || parsed.changes.length === 0) {
-    errors.push('missing required section: "## Changes"');
-  }
-  if (EPIC_REF_PATTERN.test(body)) {
-    errors.push(
-      'body contains an "Epic: #N" reference — standalone Stories must not link to an Epic',
-    );
-  }
-  for (const field of CONTRACT_FIELDS) {
-    errors.push(
-      ...collectContractErrors(field, parsed[field], contract?.[field]),
-    );
-  }
-
-  return { ok: errors.length === 0, errors };
-}
-
-/**
- * Render the canonical `## Acceptance` / `## Verify` sections into a body
- * that omits them, from the ticket's top-level arrays (Story #4874).
- *
- * This is the synthesis the story-author prompt promises: the author writes
- * each list once at top level, and the persisted GitHub issue still reads as
- * a complete executable document. A body that already carries a section is
- * returned untouched — `validateStoryBody` has already refused the case
- * where the two disagree.
- *
- * @param {string} body
- * @param {{ acceptance?: string[], verify?: string[] }} [contract]
- * @returns {string}
- */
-export function synthesizeContractSections(body, contract = {}) {
-  let parsed;
-  try {
-    parsed = parseStoryBody(body).body;
-  } catch {
-    return body;
-  }
-  const blocks = [];
-  if (
-    (parsed.acceptance ?? []).length === 0 &&
-    Array.isArray(contract.acceptance) &&
-    contract.acceptance.length > 0
-  ) {
-    const items = contract.acceptance
-      .map((a, i) => `- [ ] AC-${i + 1}: ${a}`)
-      .join('\n');
-    blocks.push(`## Acceptance\n${items}`);
-  }
-  if (
-    (parsed.verify ?? []).length === 0 &&
-    Array.isArray(contract.verify) &&
-    contract.verify.length > 0
-  ) {
-    blocks.push(
-      `## Verify\n${contract.verify.map((v) => `- ${v}`).join('\n')}`,
-    );
-  }
-  if (blocks.length === 0) return body;
-  return `${body.trimEnd()}\n\n${blocks.join('\n\n')}\n`;
-}
-
-/**
- * Load the body-template file from disk. Resolves relative to a project
- * root so callers (CLI, tests) can pin the lookup deterministically.
- *
- * @param {string} projectRoot
- * @returns {Promise<string>}
- */
-export async function loadBodyTemplate(projectRoot) {
-  const tpl = path.join(
-    projectRoot,
-    '.agents',
-    'templates',
-    'single-story-body.md',
-  );
-  return readFile(tpl, 'utf8');
-}
-
-/**
- * Assemble the context envelope the host LLM consumes to author a draft
- * Story body. Pure — no I/O beyond what the caller passed in.
- *
- * @param {{
- *   seed: string,
- *   refine: { refine:boolean, reason:string },
- *   persona: string,
- *   bodyTemplate: string,
- *   duplicateCandidates: Array<object>,
- *   techStack?: string|null,
- *   corpusContext?: { docsDigest: string|null, relevantSections: Array<object> }|null,
- *   maxResults?: number,
- * }} opts
- */
-export function buildContextEnvelope({
-  seed,
-  refine,
-  bodyTemplate,
-  duplicateCandidates,
-  techStack = null,
-  corpusContext = null,
-  maxResults = DEFAULT_DUPLICATE_MAX_RESULTS,
-}) {
-  return {
-    kind: 'story-plan-context',
-    version: 1,
-    seed,
-    refine,
-    bodyTemplate,
-    requiredSections: [...REQUIRED_SECTIONS],
-    duplicateCandidates: {
-      maxResults,
-      candidates: duplicateCandidates,
-    },
-    techStack,
-    corpusContext,
-    deliverContract: {
-      workflow: '.agents/workflows/helpers/deliver-story.md',
-      requiredLabels: ['type::story'],
-      forbidden: ['Epic: #N references in the body'],
-    },
-  };
-}
-
-/**
- * Extract the "Tech Stack" `##` section from a markdown document.
- *
- * Tolerates a numbered / decorated heading (`## 1. Tech Stack`,
- * `## Tech Stack`, etc.) and a section that is the final `##` in the
- * file (the terminator matches the next `##` heading **or** end-of-file).
- * Returns the matched section text (re-headed to a clean `## Tech Stack`)
- * or `null` when no Tech Stack heading is present.
- *
- * @param {string} content
- * @returns {string|null}
- */
-function extractTechStackSection(content) {
-  const match = content.match(
-    /^##\s+(?:\d+[.)]\s+)?Tech Stack\s*$([\s\S]*?)(?=^##\s+|(?![\s\S]))/m,
-  );
-  return match ? `## Tech Stack${match[1]}`.trim() : null;
-}
-
-/**
- * Resolve the project's Tech Stack inventory for the host LLM, in order:
- *
- *   1. A dedicated `docs/tech-stack.md` when present (the emerging
- *      single-ownership convention — WHAT in tech-stack.md, HOW in
- *      architecture.md, WHY in the ADRs). Its full body is returned.
- *   2. Otherwise, the `## Tech Stack` section of `docs/architecture.md`,
- *      tolerating a numbered/decorated heading and a final-section
- *      heading (no following `##` required).
- *
- * Returns `null` when neither source yields an inventory.
- *
- * @param {string} projectRoot
- * @returns {Promise<string|null>}
- */
-export async function readTechStackSummary(projectRoot) {
-  const dedicatedPath = path.join(projectRoot, 'docs', 'tech-stack.md');
-  try {
-    const dedicated = await readFile(dedicatedPath, 'utf8');
-    const trimmed = dedicated.trim();
-    if (trimmed) {
-      return trimmed;
-    }
-  } catch {
-    // No dedicated tech-stack.md — fall through to architecture.md.
-  }
-
-  const archPath = path.join(projectRoot, 'docs', 'architecture.md');
-  let content;
-  try {
-    content = await readFile(archPath, 'utf8');
-  } catch {
-    return null;
-  }
-  return extractTechStackSection(content);
-}

package/.agents/scripts/lib/util/phase-timer-state.js

@@ -1,72 +0,0 @@
-/**
- * lib/util/phase-timer-state.js — Cross-process persistence for phase-timer
- *
- * A Story Mode run spans two Node processes — `story-init` creates the
- * timer and opens the `implement` phase; the operator (or a headless
- * `claude -p` sub-agent) does the work; `story-close` reads the
- * timer back, appends `lint` / `test` / `close` / `api-sync` marks, and
- * emits the `phase-timings` structured comment.
- *
- * Snapshots land in the main-repo `.git/` (which every process in the story
- * lifecycle can see — init writes from the main checkout, close invokes with
- * `--cwd <main-repo>` per the worktree contract). `.git/` is deliberately
- * chosen over the worktree root so the file is never accidentally checked
- * into the story branch and never ships in a PR.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-function filePath(mainCwd, storyId) {
-  return path.join(mainCwd, '.git', `story-${storyId}-phase-timer.json`);
-}
-
-/**
- * Persist the current timer snapshot to disk. Writes atomically via a
- * temp-file rename so a crash mid-write cannot leave a truncated JSON file
- * that the close process would fail to parse.
- *
- * @param {{ snapshot: () => object }} timer
- * @param {{ mainCwd: string, storyId: number }} opts
- */
-export function savePhaseTimerState(timer, { mainCwd, storyId }) {
-  const target = filePath(mainCwd, storyId);
-  const tmp = `${target}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(timer.snapshot(), null, 2), 'utf8');
-  fs.renameSync(tmp, target);
-}
-
-/**
- * Load a timer snapshot from disk if present. Returns `null` when the file
- * is missing or unparseable — both cases are treated as "no prior timer",
- * which lets close fall back to creating a fresh timer and emitting only
- * the phases it observes.
- *
- * @param {{ mainCwd: string, storyId: number }} opts
- * @returns {object | null}
- */
-export function loadPhaseTimerState({ mainCwd, storyId }) {
-  const p = filePath(mainCwd, storyId);
-  if (!fs.existsSync(p)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Remove the on-disk snapshot once the close has consumed it. Missing file
- * is not an error — the close path may run without a prior init (e.g.
- * operator invoking close manually after an init failure).
- *
- * @param {{ mainCwd: string, storyId: number }} opts
- */
-export function clearPhaseTimerState({ mainCwd, storyId }) {
-  const p = filePath(mainCwd, storyId);
-  try {
-    fs.unlinkSync(p);
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-  }
-}

package/.agents/scripts/lib/util/phase-timer.js

@@ -1,163 +0,0 @@
-import { Logger } from '../Logger.js';
-/**
- * lib/util/phase-timer.js — Per-phase wall-clock timer for the Story lifecycle.
- *
- * A single Story Mode run spans two Node processes (`story-init` →
- * implement → `story-close`), so the timer supports snapshot/restore so
- * close can pick up where init left off. Phase names are drawn from a fixed
- * enum (tech spec #555 §Data Models) so the emitted `[phase-timing]` log
- * lines and the `phase-timings` structured comment share one schema.
- *
- * Semantics
- * ---------
- *  - `mark(name)` closes the current open phase (if any) at `now()` and opens
- *    a new phase at the same instant. The just-closed phase's
- *    `elapsedMs = now() - openedAt` is appended to the ordered `phases` list
- *    and a single `[phase-timing]` log line is emitted for it.
- *  - `finish()` closes the current open phase at `now()` and returns the
- *    full summary `{ storyId, totalMs, phases: [{ name, elapsedMs }, ...] }`.
- *    Idempotent — subsequent calls return the cached summary.
- *  - `snapshot()` returns a plain-object that `createPhaseTimer({ restore })`
- *    can round-trip. Used by `story-init` to hand the timer state to
- *    `story-close` via a small on-disk file in the main repo `.git/`.
- *
- * Invariants
- * ----------
- *  - Unknown phase names throw. The enum is frozen at `ALLOWED_PHASE_NAMES`.
- *  - `mark()` after `finish()` throws — caller bug, not runtime drift.
- *  - `totalMs` is wall clock from `createdAt` to `finish()` time, not a sum
- *    of `phases[].elapsedMs`. Gaps before the first `mark()` (or between
- *    restore and the next mark) are therefore captured in `totalMs` even
- *    though they are not attributable to a named phase.
- */
-
-export const ALLOWED_PHASE_NAMES = Object.freeze([
-  'worktree-create',
-  'bootstrap',
-  'install',
-  'implement',
-  'lint',
-  'test',
-  'close',
-  'api-sync',
-]);
-
-const ALLOWED_SET = new Set(ALLOWED_PHASE_NAMES);
-
-/**
- * @typedef {typeof ALLOWED_PHASE_NAMES[number]} PhaseName
- * @typedef {{ name: PhaseName, elapsedMs: number }} PhaseEntry
- * @typedef {{
- *   storyId: number,
- *   totalMs: number,
- *   phases: PhaseEntry[],
- * }} PhaseTimingSummary
- * @typedef {{
- *   storyId: number,
- *   createdAt: number,
- *   phases: PhaseEntry[],
- *   current: { name: PhaseName, openedAt: number } | null,
- *   finished: PhaseTimingSummary | null,
- * }} PhaseTimerSnapshot
- */
-
-/**
- * Create a phase timer for a single Story lifecycle.
- *
- * @param {number} storyId - Numeric Story id; baked into log lines and summary.
- * @param {{
- *   now?: () => number,
- *   logger?: (line: string) => void,
- *   restore?: PhaseTimerSnapshot,
- * }} [opts]
- * @returns {{
- *   mark: (name: PhaseName) => void,
- *   finish: () => PhaseTimingSummary,
- *   snapshot: () => PhaseTimerSnapshot,
- * }}
- */
-export function createPhaseTimer(storyId, opts = {}) {
-  const now = opts.now ?? Date.now;
-  const logger = opts.logger ?? ((line) => Logger.info(line));
-
-  let createdAt;
-  let phases;
-  let current;
-  let finished;
-  let timerStoryId;
-
-  if (opts.restore) {
-    const snap = opts.restore;
-    timerStoryId = snap.storyId;
-    createdAt = snap.createdAt;
-    phases = Array.isArray(snap.phases)
-      ? snap.phases.map((p) => ({ ...p }))
-      : [];
-    current = snap.current ? { ...snap.current } : null;
-    finished = snap.finished
-      ? {
-          ...snap.finished,
-          phases: snap.finished.phases.map((p) => ({ ...p })),
-        }
-      : null;
-  } else {
-    timerStoryId = storyId;
-    createdAt = now();
-    phases = [];
-    current = null;
-    finished = null;
-  }
-
-  function closeCurrent(endAt) {
-    if (!current) return;
-    const elapsedMs = Math.max(0, endAt - current.openedAt);
-    const entry = { name: current.name, elapsedMs };
-    phases.push(entry);
-    logger(
-      `[phase-timing] story=${timerStoryId} phase=${entry.name} elapsedMs=${elapsedMs}`,
-    );
-    current = null;
-  }
-
-  function mark(name) {
-    if (finished) {
-      throw new Error(
-        `createPhaseTimer: cannot mark('${name}') after finish() on story #${timerStoryId}`,
-      );
-    }
-    if (!ALLOWED_SET.has(name)) {
-      throw new Error(
-        `createPhaseTimer: unknown phase '${name}'. Allowed: ${ALLOWED_PHASE_NAMES.join(', ')}`,
-      );
-    }
-    const t = now();
-    closeCurrent(t);
-    current = { name, openedAt: t };
-  }
-
-  function finish() {
-    if (finished) return finished;
-    const t = now();
-    closeCurrent(t);
-    finished = {
-      storyId: timerStoryId,
-      totalMs: Math.max(0, t - createdAt),
-      phases: phases.map((p) => ({ ...p })),
-    };
-    return finished;
-  }
-
-  function snapshot() {
-    return {
-      storyId: timerStoryId,
-      createdAt,
-      phases: phases.map((p) => ({ ...p })),
-      current: current ? { ...current } : null,
-      finished: finished
-        ? { ...finished, phases: finished.phases.map((p) => ({ ...p })) }
-        : null,
-    };
-  }
-
-  return { mark, finish, snapshot };
-}