mandrel 1.93.0 → 2.0.0

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

@@ -11,14 +11,9 @@ import {
 } from './ticket-validator-conflicts.js';
 import {
   computeSizingFindings,
-  DEFAULT_TASK_SIZING,
   renderHardFindingError,
 } from './ticket-validator-sizing.js';
 
-// Re-exported for callers that want the constants without reaching into the
-// sizing helper module directly.
-export { DEFAULT_TASK_SIZING };
-
 /**
  * Regex matching code-asset paths the freshness gate cares about. The three
  * roots — `.agents/scripts`, `lib`, and `tests` — cover the executable surface
@@ -272,7 +267,7 @@ export function validateAcFreshness({
  * Epic #2501 introduced this guard after the legacy `baseline-refresh`
  * leading-token prescription created a wave of commit-msg hook failures
  * across story-deliver sub-agents. See
- * `.agents/skills/core/baseline-refresh/SKILL.md` for the canonical refresh
+ * `.agents/skills/core/gates-and-baselines/SKILL.md` for the canonical refresh
  * shape (Conventional-Commits subject + `baseline-refresh: true` body
  * trailer).
  */
@@ -399,7 +394,7 @@ function renderMissLine({ slug, path }) {
  * @param {string}                     [opts.baseBranchRef] - When set, runs `validateAcFreshness` against this ref.
  * @param {Function}                   [opts.gitRunner]     - Optional git probe override.
  * @param {string}                     [opts.cwd]           - Repo cwd (forwarded to the freshness gate).
- * @param {object}                     [opts.taskSizing]    - Override the three-layer sizing thresholds. Defaults to `DEFAULT_TASK_SIZING`.
+ * @param {object}                     [opts.modelCapacity] - Programmatic override of `DEFAULT_MODEL_CAPACITY` (tests only — not read from `.agentrc.json`).
  * @param {object}                     [opts.conflictPolicy] - Severity controls for cross-Story conflict findings.
  * @param {boolean}                    [opts.conflictPolicy.failOnSharedEditors=false]          - Upgrade `shared-editor` findings to `hard`.
  * @param {boolean}                    [opts.conflictPolicy.requireExplicitCrossStoryDeps=false] - Upgrade `implicit-cross-story-dep` findings to `hard`.
@@ -614,7 +609,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   const sizingFindings = computeSizingFindings({
     stories,
-    sizing: opts.taskSizing,
+    capacity: opts.modelCapacity,
   });
   // Cross-Story path-conflict pass observes the story-level depends_on
   // graph. Findings are appended to the same `findings` array consumed by

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -20,7 +20,6 @@
  */
 
 import { Logger } from '../../Logger.js';
-import { TYPE_LABELS } from '../../label-constants.js';
 import { ALL_STATES, STATE_LABELS } from './reads.js';
 import {
   postStructuredComment,
@@ -290,30 +289,6 @@ async function processCascadeParentLocked(
     );
     if (!allDone) return { cascadedTo, failed };
 
-    // EXCLUSION: Epics do not auto-close via cascade. Epics close via
-    // formal /deliver (its own machinery handles branch merges,
-    // PR-driven `Closes #N` auto-close, and a recovery transition in
-    // `epic-deliver-finalize.js`).
-    //
-    // Legacy planning tickets (pre-#4324 `context::*` artifacts on
-    // historical Epics) DO close via cascade (Story #1951): leaving
-    // them open as native sub-issues of the Epic blocks GitHub from
-    // honoring the Epic's `Closes #N` footer. New Epics carry their
-    // planning content on the Epic body itself, so this branch is
-    // purely a legacy-hygiene path.
-    //
-    // Reuse the parentSnapshot from the idempotency check above — it is
-    // a fresh read (cache was invalidated before the getTicket call) and
-    // the parent's type label is invariant within a single cascade lock
-    // hold, so a second getTicket is wasteful and redundant.
-    const isEpic = parentSnapshot.labels.includes(TYPE_LABELS.EPIC);
-    if (isEpic) {
-      logger.warn(
-        `[Ticketing] Cascade reached Epic #${parentId}. Skipping auto-close (Epics close via the operator's PR merge).`,
-      );
-      return { cascadedTo, failed };
-    }
-
     // Retry the parent transition on transient `gh` failures (rate limit,
     // 5xx, transport timeouts). Permanent failures fall through to the
     // outer catch on the first attempt so the operator sees the real

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -12,7 +12,8 @@
  */
 
 import { AGENT_LABELS } from '../../label-constants.js';
-import { WAVE_MARKER_RE } from '../wave-marker.js';
+
+const WAVE_MARKER_RE = /^wave-([0-9]{1,3})-(start|end)$/;
 
 /**
  * Canonical agent-state label triad used by every state mutator. Kept on
@@ -23,7 +24,7 @@ export const STATE_LABELS = {
   READY: AGENT_LABELS.READY,
   EXECUTING: AGENT_LABELS.EXECUTING,
   // Story #2144 — intermediate state held by a Story between successful
-  // close-preflight and a confirmed merge into `epic/<id>`. Included in
+  // close-preflight and a confirmed Story PR merge into `main`. Included in
   // the state enum so `transitionTicketState` can apply the label via
   // the canonical one-state-at-a-time path (which removes every other
   // `agent::*` label in the same call) and so the read-side `ALL_STATES`
@@ -72,13 +73,17 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'verification-results',
   'retro',
   'retro-partial',
+  // v2 Story closeout — actionable follow-ups from friction signals
+  'follow-ups',
+  // v2 plan-run epilogue artifacts (posted on the primary Story)
+  'plan-run-audit-roster',
+  'plan-run-sibling-coherence',
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
   'parked-follow-ons',
-  'dispatch-manifest',
-  // Story #566 — per-phase wall-clock summary posted by story-close
-  // and consumed by the epic-runner progress reporter to surface median /
+  // Story #566 — per-phase wall-clock summary posted by single-story-close.js
+  // and consumed by analyze-execution / perf tooling to surface median /
   // p95 phase timings across completed stories.
   'phase-timings',
   // Story #831 — story-init upserts a `story-init` comment that
@@ -88,7 +93,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'story-init',
   // Story #908 — /deliver upserts a `story-run-progress` snapshot
   // on each Story per Task transition. The /deliver aggregator and
-  // the epic-runner progress reporter both read this comment to derive
+  // `analyze-execution.js` both read this comment to derive
   // Story-level state without re-fetching ticket labels.
   'story-run-progress',
   // Story #1123 — analyze-execution.js upserts perf summaries at close
@@ -98,9 +103,8 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // surface (Epic #1030).
   'story-perf-summary',
   'epic-perf-report',
-  // Story #2128 — Phase 6 Epic Clarity Gate. `epic-plan-clarity.js` upserts
-  // a `clarity-gate-update` comment on the Epic when the operator approves
-  // a sharpened body rewrite, recording the persistence event for audit.
+  // Story #2128 — Phase 6 Epic Clarity Gate (CLI retired). Historical
+  // `clarity-gate-update` comments may still exist on older tickets.
   'clarity-gate-update',
   // Story #2635 — Tech Spec freshness check. `plan-persist.js`
   // upserts a `spec-freshness` comment on the Epic listing any
@@ -126,24 +130,24 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // ticket. Re-invocations upsert the same marker rather than appending
   // duplicates.
   'epic-handoff',
-  // Story #2899 (Epic #2880, F13) — `epic-deliver-preflight.js` upserts a
-  // `delivery-preflight` comment on the Epic at the start of
-  // /deliver Phase 1, surfacing estimated story count, install cost,
+  // Story #2899 (Epic #2880, F13) — the deleted `epic-deliver-preflight.js`
+  // upserted a `delivery-preflight` comment on the Epic at the start of
+  // pre-v2 Epic `/deliver` Phase 1, surfacing estimated story count, install cost,
   // wave count, GitHub API request volume, Claude quota burn, and any
   // threshold breaches against `delivery.preflight.max*`. One entry per
   // Epic; re-runs replace prior content.
   'delivery-preflight',
-  // Story #3062 (Epic #3051) — `wave-tick.js` upserts a
+  // Story #3062 (Epic #3051) — the deleted `wave-tick.js` upserted a
   // `recurring-failure-class` comment on the Epic when the cross-Story
   // detector finds two or more Stories that hit the same `failedGate` in
   // `close-validate.end`. One entry per Epic; re-ticks with the same
   // findings upsert in place (`upsertStructuredComment` diffs by body).
   'recurring-failure-class',
-  // Story #3061 (Epic #3051) — the /deliver §2e Idle Watchdog
-  // subsection instructs the parent host LLM to upsert a `wave-stall`
-  // comment on the Epic whenever an in-flight Story has been silent for
-  // longer than the configured cadence. `wave-tick.js --check-idle`
-  // emits the matching envelope; registering the kind here is what makes
+  // Story #3061 (Epic #3051) — the pre-v2 `/deliver` idle-watchdog prose
+  // instructed the parent host LLM to upsert a `wave-stall` comment on the
+  // Epic whenever an in-flight Story had been silent for longer than the
+  // configured cadence. The deleted `wave-tick.js --check-idle` CLI emitted
+  // the matching envelope; registering the kind here keeps historical
   // the documented remediation actually executable
   // (assertValidStructuredCommentType would otherwise throw).
   'wave-stall',
@@ -171,15 +175,14 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="audit-results|code-review"` attr so the two graduators
   // upsert independent comments; re-runs upsert in place.
   'cross-repo-deferred',
-  // Epic #4474 (PR3) — `plan-persist.js` upserts a single `plan-summary`
-  // comment on the Epic at terminal persist success, carrying the risk /
-  // routing / freshness / healthcheck receipts and the dry-run wave table
-  // as closing text. Replaces the retired plan-time `dispatch-manifest`
-  // comment (whose claimed consumer did not exist — the live manifest is
-  // written at deliver time by `wave-record-io.js`) and the Phase 12
-  // notify round-trip. One entry per Epic; a --force/--resume re-persist
-  // upserts in place.
+  // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
+  // `plan-summary` comment on the primary Story at terminal persist
+  // success, carrying risk / routing receipts and the depends_on order
+  // table. One entry per plan; a re-persist upserts in place.
   'plan-summary',
+  // v2 Stage 3 — flat Story persist checkpoint on every created Story
+  // (replaces epic-plan-state for new plans). plan-summary stays primary-only.
+  'story-plan-state',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;

package/.agents/scripts/lib/orchestration/ticketing/transition.js

@@ -145,11 +145,11 @@ async function loadTicketSnapshot(provider, opts, ticketId) {
 /**
  * Mirror the post-flip label set onto the GitHub Projects v2 Status
  * column. Story #2548 — wiring this here makes every caller of
- * `transitionTicketState` (story-init, story-close, story-phase,
- * the LabelTransitioner lifecycle listener, the update-ticket-state CLI,
- * batch transitions) update the board automatically. Prior to #2548 the
- * sync was only wired from the epic-runner against the Epic ticket, so
- * Stories and Tasks never had their `agent::executing` /
+ * `transitionTicketState` (`single-story-init.js`, `single-story-close.js`,
+ * `story-phase.js`, the LabelTransitioner lifecycle listener, the
+ * update-ticket-state CLI, batch transitions) update the board automatically.
+ * Prior to #2548 the sync was only wired from the deleted epic-runner against
+ * the Epic ticket, so Stories and Tasks never had their `agent::executing` /
  * `agent::blocked` flips reflected on the board.
  *
  * Best-effort: a project-board misconfig, missing scope, or transient

package/.agents/scripts/lib/planning-corpus.js

@@ -2,7 +2,7 @@
  * planning-corpus.js — corpus-aware context for the standalone-Story
  * planning path (Story #4432).
  *
- * `/plan --idea` previously drafted a standalone Story from a blank
+ * `/plan --seed` previously drafted a standalone Story from a blank
  * slate: the seed, the body template, and a title-only duplicate scan.
  * For a change request that is really a small delta against an
  * already-delivered surface, that blank slate throws away context the
@@ -22,11 +22,10 @@
  *      with the seed, so the draft can build on prior art instead of
  *      re-deriving it.
  *
- * The Epic list surface (`provider.getEpics`) maps every issue through
- * `issueToEpicListItem`, which deliberately omits `body` (a list-scale
- * payload trim). Body content therefore requires an **explicit**,
- * bounded per-candidate fetch via `provider.getEpic(id)` — never a
- * silent assumption that the list response carries prose to score
+ * The historical Epic list surface (`provider.getEpics`) returns a
+ * list-scale payload with no `body`. Body content therefore requires an
+ * **explicit**, bounded per-candidate fetch via `provider.getEpic(id)` —
+ * never a silent assumption that the list response carries prose to score
  * against.
  *
  * Relevance scoring reuses the same `tokenize` / `overlapScore` Jaccard
@@ -36,9 +35,12 @@
  */
 
 import { overlapScore, tokenize } from './duplicate-search.js';
-import { extractEpicSection, hasEpicSection } from './epic-body-sections.js';
 import { Logger } from './Logger.js';
 import { buildDocsDigest } from './orchestration/docs-digest.js';
+import {
+  extractTicketSection,
+  hasTicketSection,
+} from './ticket-body-sections.js';
 
 /** Top-K Epics kept after the cheap title-only ranking pass. */
 const DEFAULT_CORPUS_MAX_CANDIDATES = 5;
@@ -71,8 +73,8 @@ const CORPUS_EPICS_PAGE_CAP = 5;
 
 /**
  * Rank open Epics by title-overlap with the seed. This is the cheap
- * first pass over the list surface (title only — `issueToEpicListItem`
- * has no `body`), used solely to pick the bounded top-K candidates
+ * first pass over the list surface (title only — no `body`), used solely
+ * to pick the bounded top-K candidates
  * worth an explicit body fetch. It is not the final relevance signal;
  * `extractRelevantSections` re-scores against actual section content.
  *
@@ -179,8 +181,11 @@ export async function fetchCandidateBodies({
  * @returns {{ kind:'techSpec'|'lede', content:string }}
  */
 function extractScoreableExcerpt(body) {
-  if (hasEpicSection(body, 'techSpec')) {
-    return { kind: 'techSpec', content: extractEpicSection(body, 'techSpec') };
+  if (hasTicketSection(body, 'techSpec')) {
+    return {
+      kind: 'techSpec',
+      content: extractTicketSection(body, 'techSpec'),
+    };
   }
   const lede = (body ?? '').split(/^##\s+/m)[0].trim();
   return { kind: 'lede', content: lede };

package/.agents/scripts/lib/preflight-runner.js

@@ -3,7 +3,7 @@
  *
  * This module is the single implementation of the "run the registry, fail
  * fast on blockers, log auto-fixes" pattern. The consumer entry points
- * (story-close.js, epic-deliver-preflight.js, the npm test wrapper, and
+ * (`single-story-close.js`, `mandrel-update-preflight.js`, the npm test wrapper, and
  * the bootstrap scripts) call `runPreflight({ scope })` instead of
  * re-implementing the same assemble+run+format+exit-2 dance.
  *
@@ -13,7 +13,7 @@
  *         auto-fixes. The wrapper prints a human-readable blocker table
  *         (`id · summary · fixCommand`) before returning. Code 2 is the
  *         project-wide "preflight refused" reservation — see
- *         .agents/workflows/helpers/deliver-epic.md for the rationale.
+ *         `.agents/workflows/helpers/deliver-story.md` for the rationale.
  *
  * Auto-fixes are logged via `logFixes` before the blocker check so the
  * operator sees the "we corrected X" line even when a separate blocker

package/.agents/scripts/lib/provider-factory.js

@@ -4,7 +4,7 @@
  * Accepts the canonical resolved config object (the wrapper returned by
  * `resolveConfig()` with `config.github` populated). The legacy
  * `orchestration`-shaped argument is no longer supported as part of the
- * Epic #2880 hard cutover; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ * Epic #2880 hard cutover; see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`.
  *
  * @see docs/v5-implementation-plan.md Sprint 1B
  */

package/.agents/scripts/lib/qa/coverage-verdict.js

@@ -9,8 +9,8 @@
 // `.agents/rules/testing-standards.md` (unit / contract / acceptance) are
 // PRESENT, and which are ABSENT — and why.
 //
-// A scenario that is skipped does not exercise anything — a `@skip` /
-// `@pending` Gherkin tag (or a runner equivalent such as `it.skip` / `xit` /
+// A scenario that is skipped does not exercise anything — a `@skip`
+// Gherkin tag (or a runner equivalent such as `it.skip` / `xit` /
 // `describe.skip`, or a `skipped: true` descriptor field) means the test is
 // inert at run time. This module therefore treats a skipped test as ABSENT
 // for its tier: it never bumps a tier into `present`, because a tier whose
@@ -49,10 +49,10 @@ export const TIERS = Object.freeze(['unit', 'contract', 'acceptance']);
 const PRESENT = 'present';
 const ABSENT = 'absent';
 
-/** True when `value` contains a `@skip` or `@pending` Gherkin-style tag. */
+/** True when `value` contains a `@skip` Gherkin-style tag. */
 function hasSkipTag(value) {
   if (typeof value !== 'string') return false;
-  return /(^|[\s,])@(skip|pending)\b/i.test(value);
+  return /(^|[\s,])@skip\b/i.test(value);
 }
 
 /** True when `value` contains a runner-level skip/pending marker. */
@@ -67,7 +67,7 @@ function hasRunnerSkipMarker(value) {
 /**
  * True when a test descriptor is marked skipped/pending and therefore must
  * NOT count toward its tier. Recognizes:
- *   - a `@skip` / `@pending` tag in a `tags` array or whitespace/comma string,
+ *   - a `@skip` tag in a `tags` array or whitespace/comma string,
  *   - the same tags embedded in a path or descriptor `name`,
  *   - explicit boolean flags (`skipped`, `pending`),
  *   - runner skip markers in a path/name (`it.skip`, `xit`, `xdescribe`,

package/.agents/scripts/lib/single-story/confirm-merge-follow-ups.js

@@ -0,0 +1,36 @@
+/**
+ * confirm-merge-follow-ups.js — post-land follow-up capture seam for
+ * `single-story-confirm-merge.js` (keeps the CLI entry under the MI ceiling).
+ */
+
+import { captureFollowUpsAfterConfirm } from '../orchestration/story-follow-ups.js';
+
+/**
+ * @param {object} args
+ * @param {object} args.confirmation
+ * @param {number} args.storyId
+ * @param {number|null} args.prNumber
+ * @param {object} args.provider
+ * @param {object} [args.config]
+ * @param {string} args.cwd
+ * @param {(tag: string, msg: string) => void} [args.progress]
+ * @returns {Promise<object>}
+ */
+export async function withConfirmFollowUps({
+  confirmation,
+  storyId,
+  prNumber,
+  provider,
+  config,
+  cwd,
+  progress,
+}) {
+  const followUps = await captureFollowUpsAfterConfirm(confirmation, {
+    storyId,
+    provider,
+    config,
+    cwd,
+    progress,
+  });
+  return { standalone: true, prNumber, ...confirmation, followUps };
+}

package/.agents/scripts/lib/single-story-sweep/protection-ctx.js

@@ -4,7 +4,7 @@
  * Shared builder for the `evaluateProtection` context the boot-sweep
  * engine ([`sweepMergedBranches`](../single-story-sweep.js)) threads into
  * every candidate protection check. Single-homed here so the three boot
- * callers — `single-story-init.js`, `epic-deliver-prepare.js`, and the
+ * callers — `single-story-init.js` and the
  * `boot-sweep.js` CLI — build an identical ctx instead of each re-wiring
  * the git/gh/ticket ports.
  *

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

@@ -1,27 +1,24 @@
 /**
  * lib/story-adjacency.js — the single story-level adjacency builder.
  *
- * Both Epic-path wave-computation wrappers bottom out in the shared
+ * Both pre-v2 Epic wave wrappers and the v2 `/deliver` ready-set path bottom out in the shared
  * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` / `computeWaves`),
  * but each historically re-implemented the step that turns a list of Story
  * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
- * This module is now the one home for that step; the consumers are:
+ * This module is now the one home for that step; the live consumer is:
  *
- *   - `lib/orchestration/epic-runner/phases/build-wave-dag.js`
- *     (`buildStoryDag` → `computeWaves`)
- *   - `lib/orchestration/dispatch-pipeline.js`
- *     (`buildStoryDispatchGraph` → `computeStoryWaves`)
  *   - `lib/wave-runner/ready-set.js` (`selectReadySet`, the path-agnostic
- *     continuous scheduler the standalone `stories-wave-tick.js` adapter
- *     and the Epic path both dispatch through)
+ *     continuous scheduler the `stories-wave-tick.js` adapter dispatches through)
  *   - `stories-wave-tick.js` (for cycle detection, before delegating
  *     selection to `selectReadySet`)
  *
- * Dependency source order (must stay aligned with manifest-builder.js so
- * the dispatch manifest and runtime wave scheduling never disagree):
+ * (Pre-v2: `epic-runner/phases/build-wave-dag.js` and `dispatch-pipeline.js`
+ * also called here; both entry seams were deleted.)
+ *
+ * Dependency source order (must stay aligned with `manifest-builder.js` and
+ * `helpers/deliver-story.md` so planning and runtime scheduling never disagree):
  *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the
- *      Story body via `parseBlockedBy` (the same parser the dispatcher
- *      uses).
+ *      Story body via `parseBlockedBy` (the same parser planning uses).
  *   2. Fallback: an explicit `dependencies` (ticket shape) or
  *      `dependsOn` (operator-DAG shape) array on the Story record.
  *
@@ -46,9 +43,9 @@ import { parseBlockedBy } from './dependency-parser.js';
  *   DAG nodes).
  * @param {object} [opts]
  * @param {boolean} [opts.dropForeign=true] When true (the default,
- *   matching the Epic-scoped wrappers), edges pointing at ids outside
+ *   matching pre-v2 Epic-scoped wrappers), edges pointing at ids outside
  *   the supplied story set are dropped so the DAG stays closed over the
- *   scheduled set. The standalone path (`stories-wave-tick.js` and the
+ *   scheduled set. The v2 `/deliver` path (`stories-wave-tick.js` and the
  *   `selectReadySet` core) passes `false` to preserve the operator-DAG
  *   contract, where a dependency on an id absent from the input is treated
  *   as not-yet-done and withholds the dependent until it completes.