mandrel 1.57.0

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

@@ -0,0 +1,246 @@
+/**
+ * story-plan.js — helpers for `/story-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 to be accepted by
+ *                                    /single-story-deliver.
+ *   - rankDuplicateCandidates({ seed, openStories, maxResults })
+ *                                  — Jaccard-overlap ranking of open
+ *                                    Stories whose titles fuzzy-match
+ *                                    the seed.
+ *   - validateStoryBody(body)      — schema-light shape check:
+ *                                    required sections present, no
+ *                                    `Epic:` reference, AC checklist
+ *                                    non-empty.
+ *   - 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';
+
+export const DEFAULT_REFINE_THRESHOLD = 200;
+export const DEFAULT_DUPLICATE_MAX_RESULTS = 5;
+export const DEFAULT_DUPLICATE_MIN_SCORE = 0.15;
+
+export const REQUIRED_SECTIONS = [
+  'Context',
+  'Acceptance Criteria',
+  'Out of Scope',
+  'Notes',
+];
+
+const EPIC_REF_PATTERN = /^\s*Epic:\s*#\d+/m;
+const AC_HEADING_PATTERN = /^##\s+Acceptance Criteria\s*$/m;
+const CHECKLIST_PATTERN = /^\s*-\s*\[\s?\]/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` };
+}
+
+/**
+ * Schema-light validator for a standalone-Story body. Used by the persist
+ * path *and* by tests asserting `--dry-run` output stability. The check
+ * is deliberately tolerant of authoring whitespace: it asserts the
+ * canonical headings are present, that no `Epic: #N` reference leaks
+ * (the standalone contract), and that the Acceptance Criteria section
+ * carries at least one unchecked checklist item.
+ *
+ * @param {string} body
+ * @returns {{ ok:boolean, errors:string[] }}
+ */
+export function validateStoryBody(body) {
+  const errors = [];
+  if (typeof body !== 'string' || body.trim().length === 0) {
+    return { ok: false, errors: ['body is empty'] };
+  }
+
+  for (const section of REQUIRED_SECTIONS) {
+    const pattern = new RegExp(`^##\\s+${escapeRegex(section)}\\s*$`, 'm');
+    if (!pattern.test(body)) {
+      errors.push(`missing required section: "## ${section}"`);
+    }
+  }
+
+  if (EPIC_REF_PATTERN.test(body)) {
+    errors.push(
+      'body contains an "Epic: #N" reference — standalone Stories must not link to an Epic',
+    );
+  }
+
+  // AC checklist non-empty: extract from "## Acceptance Criteria" to the
+  // next "## " heading (or EOF) and assert at least one checklist item.
+  const acStart = body.search(AC_HEADING_PATTERN);
+  if (acStart !== -1) {
+    const rest = body.slice(acStart);
+    const nextHeading = rest.slice(1).search(/^##\s+/m);
+    const acBlock = nextHeading === -1 ? rest : rest.slice(0, nextHeading + 1);
+    if (!CHECKLIST_PATTERN.test(acBlock)) {
+      errors.push(
+        'Acceptance Criteria section has no unchecked checklist items (`- [ ] ...`)',
+      );
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * 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,
+ *   maxResults?: number,
+ * }} opts
+ */
+export function buildContextEnvelope({
+  seed,
+  refine,
+  persona,
+  bodyTemplate,
+  duplicateCandidates,
+  techStack = null,
+  maxResults = DEFAULT_DUPLICATE_MAX_RESULTS,
+}) {
+  return {
+    kind: 'story-plan-context',
+    version: 1,
+    seed,
+    refine,
+    persona,
+    bodyTemplate,
+    requiredSections: [...REQUIRED_SECTIONS],
+    duplicateCandidates: {
+      maxResults,
+      candidates: duplicateCandidates,
+    },
+    techStack,
+    deliverContract: {
+      workflow: '.agents/workflows/helpers/single-story-deliver.md',
+      requiredLabels: ['type::story', `persona::${persona}`],
+      forbidden: ['Epic: #N references in the body'],
+    },
+  };
+}
+
+/**
+ * Strip the leading "Tech Stack" section of `docs/architecture.md` for
+ * the host LLM. Returns `null` when the file or section is missing.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+export async function readTechStackSummary(projectRoot) {
+  const archPath = path.join(projectRoot, 'docs', 'architecture.md');
+  let content;
+  try {
+    content = await readFile(archPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const match = content.match(/^##\s+Tech Stack\s*$([\s\S]*?)(?=^##\s+\S)/m);
+  return match ? `## Tech Stack${match[1]}`.trim() : null;
+}

package/.agents/scripts/lib/task-utils.js

@@ -0,0 +1,26 @@
+/**
+ * task-utils.js
+ *
+ * Shared utilities for inspecting task objects throughout the pipeline.
+ * Centralises the bookend-detection predicate so that any future addition of a
+ * new bookend type only requires a change in one place.
+ */
+
+/**
+ * Returns true when the given task is a bookend (lifecycle-management) task.
+ *
+ * Bookend tasks are distinguished from regular development tasks by one of the
+ * following flags being truthy:
+ *   - isQA           — automated testing phase
+ *   - isCodeReview   — architectural review phase
+ *   - isRetro        — retrospective phase
+ *   - isCloseSprint  — sprint close-out + tagging phase
+ *
+ * @param {object} task - A task object from the sprint manifest.
+ * @returns {boolean}
+ */
+export function isBookendTask(task) {
+  return Boolean(
+    task.isQA || task.isCodeReview || task.isRetro || task.isCloseSprint,
+  );
+}

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -0,0 +1,168 @@
+import { LIMITS_DEFAULTS } from '../config/limits.js';
+import {
+  DEFAULT_TASK_SIZING,
+  DELIVERABLE_GRANULARITY_GUIDANCE,
+  SOFT_STORIES_PER_FEATURE,
+} from '../orchestration/ticket-validator-sizing.js';
+
+/**
+ * Sole source of truth for the prompt's `maxTickets` cap is the resolved
+ * limits block (see {@link LIMITS_DEFAULTS}). The previous standalone
+ * `DEFAULT_MAX_TICKETS = 40` literal allowed the prompt to drift out of sync
+ * with `planning.maxTickets` when call sites forgot to pass the
+ * resolved value; importing it here means a fallback path (no caller-supplied
+ * value) still tracks the framework default in `lib/config/limits.js`.
+ *
+ * 3-tier is the only published hierarchy after Task #3154 deleted the
+ * `planning.hierarchy` flag: the prompt omits the Task layer entirely and
+ * asks the planner to inline acceptance/verify on the Story body.
+ */
+export function renderDecomposerSystemPrompt({
+  maxTickets = LIMITS_DEFAULTS.maxTickets,
+} = {}) {
+  return render3TierPrompt({ maxTickets });
+}
+
+/**
+ * 3-tier prompt (Epic #3078). Decomposes to Feature → Story only — no Task
+ * layer. Acceptance criteria and verification commands live inline on the
+ * Story body so the executing agent has everything it needs in one ticket.
+ */
+function render3TierPrompt({ maxTickets }) {
+  // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
+  // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
+  const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
+    DEFAULT_TASK_SIZING;
+  // Deliverable-granularity definition + single-consumer merge rule are
+  // sourced from the single DELIVERABLE_GRANULARITY_GUIDANCE constant
+  // (ticket-validator-sizing.js) so the prompt and the authoring SKILL
+  // cannot drift (Story #3777).
+  const { definition: granularityDefinition, singleConsumerRule } =
+    DELIVERABLE_GRANULARITY_GUIDANCE;
+  return `You are an expert Senior Project Manager and Orchestrator.
+Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a highly-granular 2-level ticket hierarchy for an AI Agent to execute.
+
+### HIERARCHY RULES:
+1. **Features**: Large functional milestones (e.g., "Authentication Provider Integration").
+2. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
+   - MUST be nested under a Feature.
+   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. There is NO Task layer in this hierarchy — acceptance criteria and verification commands live inline on the Story body (see STORY BODY SCHEMA below).
+
+### LABEL CONVENTIONS:
+- Every ticket must have a \`type::[feature|story]\` label. The \`type::task\` label is FORBIDDEN under this hierarchy.
+- Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
+
+### OUTPUT FORMAT:
+You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.
+
+### JSON SCHEMA:
+[
+  {
+    "slug": "unique_string_id",
+    "type": "feature" | "story",
+    "title": "Short descriptive title",
+    "body": <string for features; see STORY BODY SCHEMA below for stories>,
+    "labels": ["type::...", "persona::..."],
+    "parent_slug": "slug_of_parent_ticket" (leave empty for features to nest under epic),
+    "depends_on": ["slug_of_blocking_dependency"] (optional array of slugs that block execution)
+  }
+]
+
+### FEATURE BODY:
+For Features, \`body\` is a brief string under 2 sentences. Features are navigational — the work happens at the Story level — so dense bodies waste output budget.
+
+#### FEATURE GROUPING — CAPABILITY/STAKEHOLDER, NOT EXECUTION SHAPE:
+
+- **Do not group Stories by technical execution shape (cron jobs, middleware, scripts). Group by the capability or stakeholder they serve.** Two Stories that happen to share a delivery mechanism — both are cron sweeps, both are Express middleware, both are CLI scripts — do NOT belong in the same Feature just because of that shared shape. The Feature axis is the user-facing capability or the stakeholder served, never the implementation vehicle.
+- **Operational/compliance work gets its own Feature.** Retention purges, audit-log sweeps, scheduled cleanups, observability emitters, and other operational/compliance chores serve operators and compliance, not end users. Place them in a dedicated \`compliance-and-observability\` or \`data-retention\` Feature — do NOT fold them into a user-facing Feature (e.g. notification flows) merely because they share a cron/scheduled execution shape with user-facing Stories.
+- **Smell test:** if the only thing two Stories have in common is *how* they run (a scheduled job, a request interceptor, a build step) rather than *whom* they serve or *what* capability they deliver, they are mis-grouped. Re-home the operational/compliance Story into its own capability Feature.
+
+### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
+For stories, \`body\` is a STRUCTURED OBJECT, not a string. Stories are consumed by non-interactive sub-agents that must self-verify from the Story body alone — there is no Task layer below — so the Story itself must carry everything an agent needs to execute and self-verify.
+
+  "body": {
+    "goal":                  "<one sentence — tie this story to the parent Feature slug, naming the slug>",
+    "changes":               ["<file path>: <verb> <object>", ...],
+    "acceptance":            ["<testable, observable criterion>", ...],
+    "verify":                ["<exact command or test path> (<tier>)", ...],
+    "estimated_test_files":  <integer — number of test files this Story is expected to create or modify; omit when not estimable>
+  }
+
+#### STORY BODY RULES:
+
+- **goal**: One sentence stating WHY this story exists. MUST name the parent Feature slug.
+- **changes**: Each bullet MUST be \`<path-or-glob>: <concrete verb> <object>\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Vague verbs ("clean up", "refactor", "improve", "polish", "tighten") are FORBIDDEN unless paired with a named target — "refactor src/x.ts: extract handleSubmit" is fine, "refactor the form" is not.
+- **acceptance**: Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
+- **verify**: Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
+- **estimated_test_files** (optional): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
+
+#### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
+
+**Decompose at deliverable granularity, not module/task level.** ${granularityDefinition}
+
+The primary question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial ${softFiles}-file rename from a hard 3-file parser+caller+config change — so lead with the change's reason, not its size.
+
+- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one.
+- ${singleConsumerRule}
+- **Split independent, parallelizable work** into sibling Stories under the same Feature — but only when the pieces genuinely have separate reasons to exist.
+- **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.
+- **Every Feature MUST decompose into at least TWO Stories.** A Feature with a single Story is the work of a Story, not a Feature — collapse it (drop the Feature wrapper and attach its lone Story to a sibling Feature, or merge the Feature into another). The validator HARD-rejects a Feature with fewer than two Stories.
+- **Features typically decompose into ≤${SOFT_STORIES_PER_FEATURE} Stories; otherwise split into a sibling Feature.** A Feature stretching past ${SOFT_STORIES_PER_FEATURE} Stories is a sign the Feature scope is two features.
+
+**Numeric backstop (validator-enforced).** These thresholds are sourced from the single \`DEFAULT_TASK_SIZING\` constant in \`ticket-validator-sizing.js\` — there is no second copy to drift:
+
+- A Story touching more than **${softFiles} files** (\`softFiles\`) emits an advisory width finding — a nudge to check cohesion or declare \`wide\`.
+- A Story touching more than **${hardFiles} files** (\`hardFiles\`) is **rejected** unless it declares \`wide\` with a reason.
+- A Story with more than **${maxAcceptance} acceptance items** (\`maxAcceptance\`) is **rejected**; more than ${softAcceptanceCount} (\`softAcceptanceCount\`) emits an advisory warning.
+
+#### \`wide\` DECLARATION (optional — for legitimately broad changes):
+
+A Story whose footprint is legitimately broad declares \`body.wide\` carrying a one-line human-readable reason:
+
+\`\`\`json
+"wide": { "reason": "hard contract cutover: migrate every <X> call site in one PR" }
+\`\`\`
+
+Declaring \`wide\` with a non-empty reason **lifts the \`hardFiles\` rejection** — no Story is rejected for width when it states why it is broad. Omit \`wide\` for ordinary Stories; a wide footprint with no \`wide\` declaration emits only an advisory nudge (check cohesion or declare \`wide\`), never a rejection on its own.
+
+**Glob entries** in \`changes[]\` (bullets containing \`*\`) mark the Story footprint as \`unknown-width\`: the numeric ceiling cannot bound a glob, so it is skipped. A Story carrying glob changes with no \`wide\` declaration emits an advisory nudge.
+
+#### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
+
+- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST end \`changes\` with one of:
+  - \`data-testid invariance: <list of testids that MUST be preserved>\`, or
+  - \`data-testid changes: <old> -> <new>\` paired with a corresponding \`tests/e2e/*.spec.ts\` edit in the same story or a depends_on Story.
+- Renaming a testid without the matching e2e edit is FORBIDDEN.
+
+#### BRAND / COPY / STYLE WORK:
+
+- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in PRD §2"]\`. Silence on style sourcing is a smell.
+
+### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
+The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
+
+When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
+
+- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against, for parent Feature <slug>").
+- **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
+- **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
+- **acceptance**: MUST assert (a) every new \`.feature\` file exists, and (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
+- **verify**: a grep/validate command (tier \`validate\`), NOT an e2e runner — verifying that a file exists with a tag needs no browser/playwright run. Example: \`grep -rL '@skip' tests/features/<area>/*.feature (validate)\` paired with an existence check.
+- Each implementation Story whose \`verify[]\` references one of these scaffolded \`.feature\` paths MUST \`depends_on\` the scaffold Story (so the scaffold lands in an earlier wave). Omitting the link trips the soft \`missing-bdd-scaffold\` validator finding.
+
+When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
+
+### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story \`body.acceptance\` by appending an item of the form:
+"Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
+This prevents the executing agent from redoing work the upstream Story already merged.
+
+CRITICAL: Dependencies should follow execution blockers. For hierarchical grouping, strictly use 'parent_slug' (Story parent MUST be a Feature). Features should have no 'parent_slug' (they attach to Epic).
+IMPORTANT DEPENDENCY RULE: Cross-Feature Story dependencies are allowed via \`depends_on\` at the Story level (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
+
+### REVIEWABILITY BUDGET (Story #2798):
+\`maxTickets = ${maxTickets}\` is a **reviewability budget**, not a hard authoring cap. It marks the count of tickets a human operator can comfortably review in one planning pass; emitting more than this overflows the operator's review window. Default behaviour:
+- **Stay at or under the budget when possible.** Merge narrow, single-module stories into larger, cohesive capability stories before splitting; small Stories should merge back into siblings rather than spawn their own container.
+- **Do NOT truncate or over-compress to fit.** If the plan genuinely needs more tickets than the budget, emit the full plan anyway and add a compact \`over_budget_rationale\` string at the top of the FIRST Feature's \`body\` explaining (a) why the plan exceeds the budget and (b) what was already merged to keep the count down. The operator will then either accept the plan by re-running the decompose with the explicit \`--allow-over-budget\` override flag, or push back and ask for a re-scope.
+- **Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
+}

package/.agents/scripts/lib/test-env.js

@@ -0,0 +1,30 @@
+/**
+ * Build a webhook-safe child-process environment for test runners.
+ *
+ * Operators keep a real `NOTIFICATION_WEBHOOK_URL` in `.env` for development
+ * (the production `notify()` path reads it via `process.env` after
+ * `resolveConfig()` calls `loadEnv()`). Without scrubbing, any test that
+ * transitively reaches `notify()` POSTs to the live endpoint.
+ *
+ * This helper produces the env bag that test child processes inherit:
+ *
+ *   - `NOTIFICATION_WEBHOOK_URL` is deleted unless the operator opted in
+ *     via `MANDREL_ALLOW_TEST_WEBHOOKS=1` (e.g., a contract test
+ *     deliberately exercising a sandbox endpoint). With the URL scrubbed,
+ *     `resolveWebhookUrl()` returns nothing and `notify()` never POSTs.
+ *   - `NODE_ENV=test` is set for the rest of the suite's environment
+ *     expectations. (It no longer gates `notify()`'s webhook delivery —
+ *     the NODE_ENV band-aid was removed in Story #3342. Tests that need to
+ *     exercise the webhook POST inject `opts.fetchImpl` instead, so the
+ *     request never reaches the real network even if a URL resolves.)
+ *
+ * @param {NodeJS.ProcessEnv} baseEnv
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function buildWebhookSafeTestEnv(baseEnv = process.env) {
+  const env = { ...baseEnv, NODE_ENV: baseEnv.NODE_ENV ?? 'test' };
+  if (env.MANDREL_ALLOW_TEST_WEBHOOKS !== '1') {
+    delete env.NOTIFICATION_WEBHOOK_URL;
+  }
+  return env;
+}

package/.agents/scripts/lib/test-isolate/env-snapshot-loader.js

@@ -0,0 +1,52 @@
+/* node:coverage ignore file */
+/**
+ * Preload module for `test-isolate`. Snapshots `process.env` at module load
+ * time and writes a diff envelope to the file named in
+ * `TEST_ISOLATE_ENV_OUT` when the process exits. Used to surface env-var
+ * mutations a test made and failed to restore.
+ */
+
+import fs from 'node:fs';
+
+const OUT_PATH = process.env.TEST_ISOLATE_ENV_OUT;
+if (OUT_PATH) {
+  const beforeSnapshot = { ...process.env };
+  // NODE_OPTIONS propagates this loader into every node process spawned
+  // beneath the runner (including node:test's per-file child workers). We
+  // write to a per-pid sidecar file so the parent runner can pick the
+  // child's diff and ignore its own empty one.
+  const pidPath = `${OUT_PATH}.${process.pid}.json`;
+  process.on('exit', () => {
+    try {
+      const after = process.env;
+      const added = [];
+      const removed = [];
+      const changed = [];
+      const IGNORE = new Set([
+        'TEST_ISOLATE_ENV_OUT',
+        // NODE_OPTIONS is rewritten by the parent's spawn; ignore it so
+        // the loader doesn't flag itself as a leak.
+        'NODE_OPTIONS',
+      ]);
+      for (const key of Object.keys(after)) {
+        if (IGNORE.has(key)) continue;
+        if (!(key in beforeSnapshot)) added.push(key);
+        else if (beforeSnapshot[key] !== after[key]) changed.push(key);
+      }
+      for (const key of Object.keys(beforeSnapshot)) {
+        if (IGNORE.has(key)) continue;
+        if (!(key in after)) removed.push(key);
+      }
+      if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+        return;
+      }
+      fs.writeFileSync(
+        pidPath,
+        JSON.stringify({ added, removed, changed }),
+        'utf8',
+      );
+    } catch {
+      // Best-effort — do not interfere with the host process exit.
+    }
+  });
+}

package/.agents/scripts/lib/test-isolate/list-files.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+
+/**
+ * Walk a directory and return repo-relative `*.test.js` paths (forward
+ * slashes). Skips `node_modules`, `.worktrees`, and dot-prefixed dirs.
+ *
+ * @param {string} root
+ * @param {typeof fs} [fsLike]
+ * @returns {string[]}
+ */
+export function walkTestFiles(root, fsLike = fs) {
+  const out = [];
+  walk(root, '');
+  return out.sort();
+
+  function walk(dir, prefix) {
+    if (!fsLike.existsSync(dir)) return;
+    for (const ent of fsLike.readdirSync(dir, { withFileTypes: true })) {
+      const name = ent.name;
+      if (
+        name === 'node_modules' ||
+        name === '.worktrees' ||
+        name.startsWith('.')
+      ) {
+        continue;
+      }
+      const abs = path.join(dir, name);
+      const rel = prefix ? `${prefix}/${name}` : name;
+      if (ent.isDirectory()) {
+        walk(abs, rel);
+      } else if (name.endsWith('.test.js')) {
+        out.push(rel.replace(/\\/g, '/'));
+      }
+    }
+  }
+}
+
+/**
+ * Resolve the user's pattern to a sorted list of repo-relative test file
+ * paths. Patterns may be:
+ *
+ * - a glob (`tests/**\/*.test.js`, `tests/lib/foo*.test.js`)
+ * - an explicit file path (absolute or repo-relative)
+ * - a directory (walked for `*.test.js` descendants)
+ * - omitted (defaults to `tests/**\/*.test.js`)
+ *
+ * @param {object} opts
+ * @param {string} [opts.pattern]
+ * @param {string} opts.repoRoot
+ * @param {string[]} [opts.allFiles] Override the discovered file list for tests.
+ * @param {typeof fs} [opts.fsLike]
+ * @returns {string[]}
+ */
+export function resolveTestFiles({ pattern, repoRoot, allFiles, fsLike = fs }) {
+  const discoverAll = () => allFiles ?? walkTestFiles(repoRoot, fsLike);
+
+  if (!pattern || pattern === 'tests/**/*.test.js') {
+    return discoverAll().filter((f) => f.startsWith('tests/'));
+  }
+
+  // Absolute path → relativize.
+  let target = pattern.replace(/\\/g, '/');
+  if (path.isAbsolute(target)) {
+    target = path.relative(repoRoot, path.resolve(target)).replace(/\\/g, '/');
+  }
+
+  // Directory → walk it for *.test.js files.
+  const absTarget = path.resolve(repoRoot, target);
+  if (fsLike.existsSync(absTarget)) {
+    const stat = fsLike.statSync(absTarget);
+    if (stat.isDirectory()) {
+      return walkTestFiles(absTarget, fsLike)
+        .map((rel) =>
+          path
+            .relative(repoRoot, path.join(absTarget, rel))
+            .replace(/\\/g, '/'),
+        )
+        .filter((f) => f.endsWith('.test.js'));
+    }
+    if (stat.isFile() && target.endsWith('.test.js')) {
+      return [target];
+    }
+  }
+
+  // Glob → filter the universe.
+  const isMatch = picomatch(target, { dot: true });
+  return discoverAll().filter((f) => isMatch(f));
+}