mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/epic-plan-clarity.js

@@ -1,181 +0,0 @@
-/**
- * epic-plan-clarity.js — Phase 6 Epic Clarity Gate scoring.
- *
- * Pure, deterministic rubric: parse the Epic body for the five canonical
- * sections defined by `.agents/templates/epic-from-idea.md` (Context,
- * Goal, Non-Goals, Scope, Acceptance Criteria) and emit a verdict of
- * `clear` or `needs-refinement` along with a gap list for the refinement
- * loop seed.
- *
- * Verdict rule: `clear` requires **both** (a) ≥ 4 of 5 canonical sections
- * present, **and** (b) the **Acceptance Criteria** section present. The
- * Acceptance-Criteria requirement is load-bearing: a downstream
- * `/deliver` start gate and the close-time acceptance-spec reconciler
- * both assume the Epic carries acceptance criteria, so a gate that passed an
- * Epic with no Acceptance Criteria (the pre-Story-#3910 `≥ 4 of 5` behaviour)
- * advertised a clarity guarantee it did not provide. AC is now a required
- * section, not one of the four optional passers.
- *
- * Heading variants accepted per canonical section (back-compat with the
- * pre-canonical-headings ideation shape):
- *   - `## Context`, `## Background`, `## Problem`, `## Problem Statement`,
- *     `## Context & Problem`
- *   - `## Goal`, `## Goals`, `## Objective`, `## Objectives`,
- *     `## Direction`, `## Recommended Direction`
- *   - `## Non-Goals`, `## Non Goals`, `## Out of Scope`, `## Not Doing`,
- *     `## Not Doing (and Why)`
- *   - `## Scope`, `## Scope (...)`, `## MVP Scope`, `## Proposed Scope`,
- *     `## Work Breakdown`
- *   - `## Acceptance Criteria`, `## Acceptance`, `## AC`
- *
- * Story #4324 folded the Tech Spec and Acceptance Spec into the Epic body
- * as managed sections (`## Delivery Slicing`-led spec sections and the
- * `## Acceptance Table`). The gate *recognises* those planning sections —
- * reporting their presence under `planningSections[]` so a post-fold Epic
- * body scores exactly as its ideation content deserves — but they never
- * count toward (or against) the five-ideation-section verdict: Phase 6
- * runs before Phase 7 authors them, and a re-planned Epic that already
- * carries them must not be penalised or auto-passed by their presence.
- *
- * Pure ESM, no I/O.
- */
-
-import { DELIVERY_SLICING_RE } from './epic-body-sections.js';
-
-const SECTION_RE = {
-  context:
-    /^##\s+(?:Context(?:\s+&\s+Problem)?|Background|Problem(?:\s+Statement)?)\s*$/im,
-  goal: /^##\s+(?:Goals?|Objectives?|(?:Recommended\s+)?Direction)\s*$/im,
-  nonGoals:
-    /^##\s+(?:Non[\s-]?Goals|Out\s+of\s+Scope|Not\s+Doing(?:\s+\(and\s+Why\))?)\s*$/im,
-  scope:
-    /^##\s+(?:MVP\s+|Proposed\s+)?Scope(?:\s+\([^)]+\))?\s*$|^##\s+Work\s+Breakdown\s*$/im,
-  acceptanceCriteria: /^##\s+(?:Acceptance(?:\s+Criteria)?|AC)\s*$/im,
-};
-
-/**
- * Canonical section names, in document order. Exported so callers (CLI,
- * tests, downstream tooling) can iterate without re-deriving the list.
- */
-export const SECTION_NAMES = Object.freeze([
-  'context',
-  'goal',
-  'nonGoals',
-  'scope',
-  'acceptanceCriteria',
-]);
-
-/**
- * Post-fold planning sections (Story #4324) — recognised and reported,
- * never scored. `deliverySlicing` accepts the same heading variants as
- * `spec-section-validator.js`.
- */
-const PLANNING_SECTION_RE = {
-  deliverySlicing: DELIVERY_SLICING_RE,
-  acceptanceTable: /^##\s+Acceptance\s+Table\s*$/im,
-};
-
-/**
- * Names of the recognised (unscored) planning sections, in document order.
- * Module-private: consumers read the reported `planningSections[]` rows on
- * the scoreEpicBody result rather than importing the name list.
- */
-const PLANNING_SECTION_NAMES = Object.freeze([
-  'deliverySlicing',
-  'acceptanceTable',
-]);
-
-const CLEAR_THRESHOLD = 4;
-const PLACEHOLDER_PATTERN = /^_\(not\s+specified\)_$/i;
-
-/**
- * Classify a section's content as `present`, `placeholder`, or `missing`.
- *
- * @param {string|null} content - The text between this heading and the next
- *   `## ` heading (or EOF). `null` when the heading was not found.
- * @returns {'present' | 'placeholder' | 'missing'}
- */
-function classify(content) {
-  if (content === null) return 'missing';
-  const trimmed = content.trim();
-  if (trimmed.length === 0) return 'placeholder';
-  if (PLACEHOLDER_PATTERN.test(trimmed)) return 'placeholder';
-  return 'present';
-}
-
-/**
- * Score an Epic body against the five canonical sections.
- *
- * @param {{ body: string }} args
- * @returns {{
- *   verdict: 'clear' | 'needs-refinement',
- *   sections: Array<{ name: string, status: 'present' | 'placeholder' | 'missing' }>,
- *   missingOrPlaceholder: string[],
- *   planningSections: Array<{ name: string, status: 'present' | 'missing' }>,
- * }}
- */
-const REQUIRED_SECTION = 'acceptanceCriteria';
-
-export function scoreEpicBody({ body } = {}) {
-  const source = typeof body === 'string' ? body : '';
-
-  // First pass: locate every canonical heading and its byte offset so we
-  // can slice the section body up to the next `## ` heading or EOF.
-  const headingHits = [];
-  for (const name of SECTION_NAMES) {
-    const re = SECTION_RE[name];
-    const m = source.match(re);
-    if (m && typeof m.index === 'number') {
-      headingHits.push({
-        name,
-        start: m.index,
-        headingLength: m[0].length,
-      });
-    }
-  }
-  headingHits.sort((a, b) => a.start - b.start);
-
-  // Generic next-heading regex (any `## ` heading, including non-canonical
-  // ones the author may have added between canonical sections).
-  const NEXT_HEADING_RE = /^##\s+/m;
-
-  /** @type {Map<string, string>} */
-  const contentByName = new Map();
-  for (const hit of headingHits) {
-    const sliceStart = hit.start + hit.headingLength;
-    const rest = source.slice(sliceStart);
-    const nextMatch = rest.match(NEXT_HEADING_RE);
-    const sliceEnd =
-      nextMatch && typeof nextMatch.index === 'number'
-        ? sliceStart + nextMatch.index
-        : source.length;
-    contentByName.set(hit.name, source.slice(sliceStart, sliceEnd));
-  }
-
-  const sections = SECTION_NAMES.map((name) => {
-    const content = contentByName.has(name) ? contentByName.get(name) : null;
-    return { name, status: classify(content ?? null) };
-  });
-
-  const missingOrPlaceholder = sections
-    .filter((s) => s.status !== 'present')
-    .map((s) => s.name);
-
-  const presentCount = sections.filter((s) => s.status === 'present').length;
-  const requiredPresent = sections.some(
-    (s) => s.name === REQUIRED_SECTION && s.status === 'present',
-  );
-  const verdict =
-    presentCount >= CLEAR_THRESHOLD && requiredPresent
-      ? 'clear'
-      : 'needs-refinement';
-
-  // Informational only: presence of the post-fold planning sections
-  // (Story #4324). Never feeds the verdict.
-  const planningSections = PLANNING_SECTION_NAMES.map((name) => ({
-    name,
-    status: PLANNING_SECTION_RE[name].test(source) ? 'present' : 'missing',
-  }));
-
-  return { verdict, sections, missingOrPlaceholder, planningSections };
-}

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -1,261 +0,0 @@
-/**
- * epic-plan-ideation.js — Phase 3/4 helpers for /plan
- *
- * Phase 3: render an Epic body from a sharpened ideation one-pager
- * using the canonical template at `.agents/templates/epic-from-idea.md`.
- * Phase 4: open the GitHub Issue via an injected provider with the
- * `type::epic` label only — no `state::draft` (the Epic carries only
- * `type::epic` until spec authoring writes `agent::review-spec`).
- *
- * The template is parsed from a string the caller has already loaded
- * (typically via `fs.readFile`). The renderer is pure — no I/O — and
- * the opener takes a tiny `createIssue` port so the test suite can
- * mock the provider call without touching the GitHub HTTP client.
- */
-
-import {
-  extractFrameworkStamp,
-  stampFrameworkVersion,
-} from './framework-version.js';
-import { TYPE_LABELS } from './label-constants.js';
-
-// Canonical section keys match the rendered template at
-// `.agents/templates/epic-from-idea.md`. The regex accepts both the
-// new canonical headings and the pre-canonical-headings ideation shape
-// so an in-flight one-pager parses cleanly during the transition. The
-// older `assumptions` key is accepted as input but is no longer a
-// canonical rendered section — it lands implicitly in `context` if the
-// one-pager carries one.
-const SECTION_RE = {
-  context:
-    /^##\s+(?:Context(?:\s+&\s+Problem)?|Background|Problem(?:\s+Statement)?)\s*$/im,
-  goal: /^##\s+(?:Goals?|Objectives?|(?:Recommended\s+)?Direction)\s*$/im,
-  nonGoals:
-    /^##\s+(?:Non[\s-]?Goals|Out\s+of\s+Scope|Not\s+Doing(?:\s+\(and\s+Why\))?)\s*$/im,
-  scope:
-    /^##\s+(?:MVP\s+|Proposed\s+)?Scope(?:\s+\([^)]+\))?\s*$|^##\s+Work\s+Breakdown\s*$/im,
-  // Story #4314 — the PRD's one novel section (User Stories) now folds into
-  // the Epic body as a canonical section.
-  userStories: /^##\s+(?:User\s+Stories|Stories|Personas?\s+&\s+Stories)\s*$/im,
-  acceptanceCriteria: /^##\s+(?:Acceptance(?:\s+Criteria)?|AC)\s*$/im,
-};
-
-const ORDER = [
-  'context',
-  'goal',
-  'nonGoals',
-  'scope',
-  'userStories',
-  'acceptanceCriteria',
-];
-
-/**
- * Extract the six canonical sections from an idea-refinement one-pager.
- *
- * @param {string} onePager - Markdown produced by Phase 3 of the
- *   `idea-refinement` skill.
- * @returns {{
- *   title: string,
- *   context: string,
- *   goal: string,
- *   nonGoals: string,
- *   scope: string,
- *   userStories: string,
- *   acceptanceCriteria: string,
- * }}
- */
-export function parseOnePager(onePager) {
-  if (!onePager || typeof onePager !== 'string') {
-    throw new Error('parseOnePager: onePager must be a non-empty string');
-  }
-
-  const titleMatch = onePager.match(/^#\s+(.+?)\s*$/m);
-  const title = titleMatch ? titleMatch[1].trim() : 'Untitled Epic';
-
-  // Build a map of section name -> [headingMatch.index, headingLength].
-  const positions = [];
-  for (const key of ORDER) {
-    const m = onePager.match(SECTION_RE[key]);
-    if (m && typeof m.index === 'number') {
-      positions.push({ key, start: m.index, headingLength: m[0].length });
-    }
-  }
-  positions.sort((a, b) => a.start - b.start);
-
-  const sections = {
-    context: '',
-    goal: '',
-    nonGoals: '',
-    scope: '',
-    userStories: '',
-    acceptanceCriteria: '',
-  };
-
-  // Generic next-heading regex — slice up to the next `## ` heading,
-  // not just the next canonical one, so non-canonical sections the
-  // author included (e.g. "Open Questions") don't get folded into the
-  // preceding canonical section.
-  const NEXT_HEADING_RE = /^##\s+/m;
-  for (let i = 0; i < positions.length; i += 1) {
-    const cur = positions[i];
-    const sliceStart = cur.start + cur.headingLength;
-    const rest = onePager.slice(sliceStart);
-    const nextMatch = rest.match(NEXT_HEADING_RE);
-    const sliceEnd =
-      nextMatch && typeof nextMatch.index === 'number'
-        ? sliceStart + nextMatch.index
-        : onePager.length;
-    sections[cur.key] = onePager.slice(sliceStart, sliceEnd).trim();
-  }
-
-  return { title, ...sections };
-}
-
-/**
- * Render the Epic body from a parsed one-pager and a template string.
- * Substitutes `{{key}}` tokens for the matching section. Missing
- * sections are rendered as `_(not specified)_` so the operator can spot
- * gaps during the HITL review (Phase 3).
- *
- * Story #4382 — the rendered body is stamped with the Mandrel framework
- * version + authoring date (hidden `mandrel_version` / `authored_at` meta
- * field + a visible `> 🏷️ Authored with Mandrel …` marker) via
- * {@link stampFrameworkVersion}. Pass `stamp` to preserve a
- * previously-authored version on re-render (the Epic edit path does this);
- * omit it to stamp the running version and today's date.
- *
- * @param {{
- *   onePager: string,
- *   template: string,
- *   stamp?: { version?: string, authoredAt?: string },
- * }} args
- * @returns {{ title: string, body: string }}
- */
-export function renderEpicBody({ onePager, template, stamp }) {
-  if (!template || typeof template !== 'string') {
-    throw new Error('renderEpicBody: template must be a non-empty string');
-  }
-  const parsed = parseOnePager(onePager);
-
-  const rendered = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
-    if (key === 'title') return parsed.title;
-    const value = parsed[key];
-    return value && value.length > 0 ? value : '_(not specified)_';
-  });
-
-  const body = stampFrameworkVersion(rendered, stamp ?? {});
-  return { title: parsed.title, body };
-}
-
-/**
- * Open a new GitHub Issue for the Epic. The label set is exactly
- * `[type::epic]` — no `state::*` label is added at creation time.
- *
- * The `createIssue` port matches the shape
- * `({ title, body, labels }) => Promise<{ id, nodeId?, url? }>` so the
- * unit test can pass an in-memory mock and assert on the captured
- * payload. In production the port delegates to the ticketing provider's
- * `createIssue` (GitHub: `TicketGateway.createIssue`), which adds the
- * new issue to the configured Projects V2 board via the shared
- * `addIssueToBoard` helper — idempotent, non-fatal, and a no-op when no
- * project number is configured (Story #3822) — so the Epic lands on the
- * board without relying on GitHub's "Auto-add to project" workflow. The
- * created issue's GraphQL `node_id` is surfaced as `nodeId` on the
- * returned envelope for observability and follow-up board operations.
- *
- * @param {{
- *   onePager: string,
- *   template: string,
- *   createIssue: (payload: { title: string, body: string, labels: string[] }) => Promise<{ id: number, nodeId?: string, url?: string }>,
- * }} args
- * @returns {Promise<{ id: number, nodeId: string|null, title: string, body: string, labels: string[], url?: string, payload: { title: string, body: string, labels: string[] } }>}
- */
-export async function openEpicFromOnePager({
-  onePager,
-  template,
-  createIssue,
-}) {
-  if (typeof createIssue !== 'function') {
-    throw new Error('openEpicFromOnePager: createIssue must be a function');
-  }
-  const { title, body } = renderEpicBody({ onePager, template });
-  const labels = [TYPE_LABELS.EPIC];
-  const payload = { title, body, labels };
-  const created = await createIssue(payload);
-  if (!created || typeof created.id !== 'number') {
-    throw new Error(
-      'openEpicFromOnePager: createIssue must return { id: number, nodeId?, url? }',
-    );
-  }
-  return {
-    id: created.id,
-    nodeId: created.nodeId ?? null,
-    title,
-    body,
-    labels,
-    url: created.url,
-    payload,
-  };
-}
-
-/**
- * Update an existing Epic Issue's body from a sharpened one-pager. The
- * single persistence path used by the Phase 6 Epic Clarity Gate.
- *
- * The `editIssue` port matches the shape
- * `({ epicId, body }) => Promise<void|object>` so unit tests can pass an
- * in-memory mock. Idempotent: when `currentBody` exactly matches the
- * freshly rendered body, the port is **not** called and the function
- * returns `{ changed: false }`.
- *
- * @param {{
- *   epicId: number,
- *   onePager: string,
- *   template: string,
- *   editIssue: (payload: { epicId: number, body: string }) => Promise<unknown>,
- *   currentBody?: string|null,
- * }} args
- * @returns {Promise<{
- *   epicId: number,
- *   title: string,
- *   body: string,
- *   changed: boolean,
- *   payload?: { epicId: number, body: string },
- * }>}
- */
-export async function updateEpicFromOnePager({
-  epicId,
-  onePager,
-  template,
-  editIssue,
-  currentBody = null,
-}) {
-  if (typeof editIssue !== 'function') {
-    throw new Error('updateEpicFromOnePager: editIssue must be a function');
-  }
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new Error(
-      'updateEpicFromOnePager: epicId must be a positive integer',
-    );
-  }
-
-  // Story #4382 — preserve the originally-authored version stamp on edit
-  // rather than bumping it to whatever version is running now. When the
-  // current body carries no stamp (legacy Epic), a fresh stamp is applied.
-  const priorStamp = extractFrameworkStamp(currentBody ?? '');
-  const stamp = priorStamp
-    ? { version: priorStamp.version, authoredAt: priorStamp.authoredAt }
-    : undefined;
-
-  const { title, body } = renderEpicBody({ onePager, template, stamp });
-
-  if (typeof currentBody === 'string' && currentBody === body) {
-    return { epicId, title, body, changed: false };
-  }
-
-  const payload = { epicId, body };
-  await editIssue(payload);
-  return { epicId, title, body, changed: true, payload };
-}
-
-export const __test = { ORDER, SECTION_RE };