mandrel 2.56.0 → 2.57.0

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

@@ -1,71 +1,57 @@
-import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
   AUTHORING_ALTITUDE_GUIDANCE,
-  DEFAULT_MODEL_CAPACITY,
   DELIVERABLE_GRANULARITY_GUIDANCE,
-  resolveCapacityCeilings,
 } from '../orchestration/ticket-validator-sizing.js';
 import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.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`.
- *
- * 2-tier is the only published hierarchy after Story #4041 removed the
- * Feature tier: the prompt emits Stories only (direct Epic children) and
- * asks the planner to carry acceptance/verify as top-level ticket arrays.
+ * The story-author system prompt (Story #5312 — rendered from the draft's
+ * Story count).
  *
  * **Single source of the prompt body (Story #4162).** This module is the sole
- * carrier of the full decomposer system-prompt body, delivered to the host
- * LLM in the `systemPrompts.decompose` field of the `/mandrel-plan` context envelope
- * (via `lib/orchestration/planning/decomposer-context.js`), so no second
+ * carrier of the story-author system prompt, delivered to the host LLM in the
+ * `systemPrompts.story` field of the `/mandrel-plan` context envelope (via
+ * `lib/orchestration/plan-context.js#buildSystemPrompts`), so no second
  * verbatim copy can drift.
+ *
+ * Two layers, composed by {@link renderStoryAuthorPrompt}:
+ *
+ *   - **The N=1 core** ({@link renderStoryAuthorCore}) — what every draft
+ *     needs: the body schema, the contract-level Spec rule, the deterministic
+ *     body-format lints, and acceptance defined as outcomes a PR reviewer can
+ *     confirm from the diff and the verify output. It carries no delivery
+ *     schedule, no per-file behavior paragraphs, no reviewability budget and
+ *     no verify-tier suffix — every one of those either scored a shape the
+ *     authoring model already judges or prescribed a proxy that became the
+ *     goal.
+ *   - **The N>1 rules** ({@link renderStorySplitRules}) — the schedule and
+ *     partition rules that only mean anything once a draft has siblings:
+ *     every Story must earn its slot in the wave schedule, and every
+ *     acceptance criterion belongs to exactly one Story.
+ *
+ * The envelope carries the core as `systemPrompts.story` and the split rules
+ * as `systemPrompts.storySplitRules`; a planner reads the second only when
+ * the default-single split policy clears.
  */
-export function renderDecomposerSystemPrompt({
-  maxTickets = LIMITS_DEFAULTS.maxTickets,
-} = {}) {
-  return render2TierPrompt({ maxTickets });
-}
 
 /**
- * 2-tier prompt (Story #4041). Decomposes to Stories only — no Feature and
- * 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. Thematic grouping lives as prose in the Epic body / Tech Spec.
+ * The N=1 core of the story-author prompt.
+ *
+ * @returns {string}
  */
-function render2TierPrompt({ maxTickets }) {
-  // v2 Stage 3: default-single — emit one Story unless the split policy clears.
-  // Capacity thresholds are sourced from the single DEFAULT_MODEL_CAPACITY
-  // constant (ticket-validator-sizing.js) so the prompt and the validator
-  // cannot drift.
-  const { softSessionTokens, hardSessionTokens } = resolveCapacityCeilings(
-    DEFAULT_MODEL_CAPACITY,
-  );
-  // Deliverable-granularity definition + single-consumer merge rule + the
-  // thin-dependent merge heuristic are sourced from the single
-  // DELIVERABLE_GRANULARITY_GUIDANCE constant (ticket-validator-sizing.js) so
-  // the prompt and the authoring SKILL cannot drift (Story #3777; the
-  // envelope-floor sentence added by Story #4313).
+export function renderStoryAuthorCore() {
   const {
     definition: granularityDefinition,
     singleConsumerRule,
     envelopeFloor,
   } = DELIVERABLE_GRANULARITY_GUIDANCE;
-  // The binding-vs-advisory authoring altitude + the New-File Contract are
-  // sourced from the single AUTHORING_ALTITUDE_GUIDANCE constant
-  // (ticket-validator-sizing.js) so the prompt and the authoring SKILL cannot
-  // drift (Story #4272).
   const {
     altitude: authoringAltitude,
     advisoryCaveat,
     newFileContract,
   } = AUTHORING_ALTITUDE_GUIDANCE;
   // The deterministic body-format lints (structured `## Changes` bullet shape,
-  // verify-tier suffixes, …) rendered example-first from their single source
+  // non-empty sections) rendered example-first from their single source
   // (`lib/story-body/body-format-lints.js`) so an authored draft is lint-clean
   // by construction rather than discovered as a persist dry-run failure and
   // re-authored at resident-context prices (Story #4684).
@@ -84,10 +70,9 @@ Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI
    - Thematic grouping is prose in the Story's folded \`## Spec\` / \`## Slicing\`, never sibling tickets for coupled work.
 
 ### LABEL CONVENTIONS:
-- \`type::story\` is applied automatically by persist — you do not need to emit it, and no other type label is allowed (the retired Feature and Task tiers have no labels under this hierarchy).
+- \`type::story\` is applied automatically by persist — you do not need to emit it, and no other type label is allowed.
 - \`labels[]\` is **optional**. Emit it only to request an *additional* label; persist sanitizes the list before applying it.
 - Do **not** emit \`agent::*\` labels — lifecycle state is runtime-owned, and persist applies \`agent::ready\` itself once every checkpoint is on the ticket.
-- Do **not** emit \`persona::*\` labels — the behavioral persona concept (and its label axis) was removed in v2.
 
 ### OUTPUT FORMAT:
 You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.
@@ -99,8 +84,8 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
     "type": "story",
     "title": "Short descriptive title",
     "body": <string — see STORY BODY SCHEMA below>,
-    "acceptance": ["<testable, observable criterion>", ...],
-    "verify": ["<exact command or test path> (<tier>)", ...],
+    "acceptance": ["<outcome a PR reviewer can confirm>", ...],
+    "verify": ["<exact command or test path>", ...],
     "labels": ["<extra-label>"] (optional — type::story is applied automatically; omit this field unless you need an additional label),
     "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
   }
@@ -109,7 +94,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -124,18 +109,18 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
     <optional ordered intra-session checkpoints — not a second Spec or AC table>
 
     ## Spec
-    <optional lean technical approach — do NOT restate Goal / Acceptance / Verify>
+    <optional technical approach at contract level — do NOT restate Goal / Acceptance / Verify>
 
     ## Changes
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
     - ...
 
     ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
-    - [ ] <testable, observable criterion>
+    - [ ] <outcome a PR reviewer can confirm>
     - ...
 
     ## Verify              <-- synthesized by persist from verify[]; do not author
-    - <exact command or test path> (<tier>)
+    - <exact command or test path>
     - ...
 
     ## Non-Goals
@@ -145,16 +130,12 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 #### STORY BODY RULES:
 
 - **goal** (in body string): One sentence stating WHY this Story exists.
-- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only, at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. If the Spec is large enough to feel like its own document, the Story is probably too big — split it. Persist keeps Specs inline and rejects over-budget Specs (never writes them under \`docs/\`).
-- **slicing** (optional): Ordered intra-session checkpoints for one Story. Not a fan-out table and not a duplicate of Acceptance.
-- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
-- **acceptance** (top-level array on the ticket object): 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** (top-level array on the ticket object): 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.
-- **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
-- **Observed-behavior claims open with \`Current state (verified <date>)\`.** Any Spec claim about how the codebase behaves today MUST open with that preamble (e.g. \`Current state (verified 2026-07-17): …\`) so a reader can tell a verified observation from an assumption, and can tell when the observation went stale.
-- **Intent-then-proxy acceptance shape.** When an acceptance item verifies through a proxy check (a grep, a file-exists probe, an exit-code test), state the intent clause before the proxy check — what outcome the check stands in for — so the proxy never becomes the goal (e.g. "the workflow names hygiene findings as re-author input: \`grep -n "textHygiene" …\` exits 0").
-- **Slicing checkpoints are one line each.** Each \`## Slicing\` checkpoint is a single line naming the checkpoint; implementation detail lives in \`## Spec\`, never duplicated into Slicing. A Slicing section outweighing its Spec is a defect the text-hygiene lint flags.
-- **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
+- **spec** (optional, in body string as \`## Spec\`): The technical approach at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. Write as much as the work needs and no more; persist keeps Specs inline at any length and never writes them under \`docs/\`.
+- **slicing** (optional): Ordered intra-session checkpoints for one Story, one line each. Not a fan-out table and not a duplicate of Acceptance.
+- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals. Persist probes every path against the base branch and repairs a plain-string bullet or a trailing parenthetical into the object form for you; a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning, and only a \`deletes\` naming an absent path is refused.
+- **acceptance** (top-level array on the ticket object): Each item is an **outcome a PR reviewer can confirm from the diff and the verify output** — what is true of the codebase once the Story lands, stated at the altitude of the capability (a command that now exits 0 against a named input, a behavior a named test now asserts, a config that now fails validation on a retired key, a document that now records a decision). Aim for **three to six** items: fewer than three usually means the outcome is under-specified; more than six usually means acceptance is re-listing the footprint or the mechanical checks that belong in \`verify[]\`. Push grep-shaped probes, file-exists checks and exit-code tests down into \`verify[]\`; never pin an internal helper name or a private file path into an acceptance item the advisory \`changes[]\` is free to reshape. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec".
+- **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. Stories with zero verify entries fail validation.
+- **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it, and the dry-run warns on every one it finds. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
 #### SPEC PROSE CONTRACT — state the contract, not the implementation:
@@ -164,13 +145,13 @@ The Story is executed by a frontier-model deliverer that reads the codebase itse
 - **Spec states the contract and invariants**: interfaces, status codes, security invariants, and load-bearing constraints — each with its why. That is the whole job of the Spec.
 - **Implementation choices belong to the deliverer** unless a choice is load-bearing; a load-bearing choice is stated as a constraint (with why it binds), never as a walkthrough of how to code it.
 - **No per-file behavior paragraphs.** The \`## Changes\` list already names the footprint; do not narrate what each file will do.
-- **No current-state narration.** Do not describe how the codebase works today as scene-setting; the deliverer reads the code. The only current-state prose allowed is a claim a decision depends on, opening with \`Current state (verified <date>)\` per the observed-behavior rule above.
+- **No current-state narration.** Do not describe how the codebase works today as scene-setting; the deliverer reads the code. State only the claims a decision depends on.
 - **Do not author a \`## References\` section.** Read-only context the deliverer needs is discoverable from the contract and the footprint.
 - **Acceptance criteria remain the binding contract** — the Spec constrains and explains; \`acceptance[]\` binds.
 
 #### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
 
-Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. \`verify-tier-suffix\` is the one rule persist repairs for you: when the tier is unambiguously inferable from the command, persist appends it and proceeds; when it is not, the entry is still rejected and you must choose the tier. \`changes-path-entry-shape\` emits the corrected form in the dry-run failure output but is never applied for you.
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. \`changes-path-entry-shape\` is the one rule persist repairs for you: a plain-string bullet whose path can be salvaged is rewritten into the object form by probing the base branch, and the repair is reported in the dry-run output.
 
 ${bodyFormatLintChecklist}
 
@@ -182,51 +163,17 @@ ${newFileContract}
 
 ${advisoryCaveat}
 
-#### STORY SIZING — COHESION FIRST (session capacity is only a backstop):
+#### STORY SIZING — COHESION, NOT COUNT:
 
 **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 rename from a hard parser+caller+config change — so lead with the change's reason, not its size. Frontier models one-shot capability-sized work in a single pass — do not fragment a coherent capability into dependent slices just to stay "small."
+The only sizing question is **cohesion**: *is this one coherent change with one reason to exist?* There is no ceiling on a Story's footprint, Spec length or acceptance count — a broad contract cutover is one Story when every changed site changes for the same reason. Frontier models one-shot capability-sized work in a single pass; do not fragment a coherent capability into dependent slices to stay "small", and do not pad a Story with adjacent work to look "complete".
 
 ${envelopeFloor}
 
-- **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. State that sentence explicitly in the Story's \`reason_to_exist\` meta field (see STORY BODY RULES) so the consolidate critic can check it.
+- **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 — 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 whose authored ticket mass is high for one reason). Declaring \`wide\` lifts the hard session-mass ceiling — see below.
-
-**Capacity backstop (validator-enforced).** Absolute authored-token ceilings from the single \`DEFAULT_MODEL_CAPACITY\` constant in \`ticket-validator-sizing.js\` — not operator-tunable. They catch Spec novels, not capability-sized Stories:
-
-- Soft advisory (**${softSessionTokens} tokens**): authored session mass above this emits a nudge to check cohesion or declare \`wide\`.
-- Hard ceiling (**${hardSessionTokens} tokens**): authored session mass above this is **rejected** unless the Story declares \`wide\` with a reason.
-- Session mass = **authored tokens only** (goal / reason / Spec / acceptance / verify / slicing / change-path text). File count and AC count do **not** inflate mass — a long binding contract or a broad file footprint is never by itself a reason to fragment one coherent capability into dependent slices.
-
-#### DELIVERY-SCHEDULE SIMULATION — the story count must earn itself:
-
-Before emitting, simulate the delivery schedule your plan implies, and judge the plan by its schedule — not by how tidy the taxonomy looks:
-
-1. **Build the wave schedule.** A Story runs only after every \`depends_on\` completes, and two Stories that name the same file in \`changes[]\` cannot run in the same wave (the scheduler serializes file-overlapping Stories even when no \`depends_on\` edge links them).
-2. **Compute the parallelism yield**: story count ÷ critical-path length in waves. A yield near 1.0 means the plan is a serial chain — N Stories that deliver no faster than one Story while paying N delivery sessions (branch, PR, review, CI).
-3. **Every Story must earn its slot** by at least one of:
-   - **(a) parallelism** — it actually runs concurrently with a sibling in the schedule you just built ("logically independent" does not count; *schedule*-independent does);
-   - **(b) risk isolation** — it isolates a consumer-facing behavior change or high-risk cutover into its own reviewable, revertable unit;
-   - **(c) cohesion break** — merged into its neighbor it would no longer be one coherent change with one reason to exist.
-4. **A dependent link with none of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains.
-5. **Hot-file rule.** When one file appears in the \`changes[]\` of more than a third of your Stories, the slicing axis cuts across a shared seam — merge the Stories that co-edit it, or re-slice along the seam so each Story owns its files.
-
-End each Story's \`reason_to_exist\` with its justification letter and one clause, e.g. "… (a: runs in wave 1 alongside <slug>)" or "(b: isolates the auto-merge default change)". A reason that names only a topic ("config work", "docs") with no justification is a merge signal.
-
-#### \`wide\` DECLARATION (optional — for legitimately broad changes):
-
-A Story whose footprint is legitimately broad declares \`wide\` carrying a one-line human-readable reason. Encode it in the \`<!-- meta: {"wide": {"reason": "..."}} -->\` comment that \`serialize()\` appends to the body string — it is NOT a top-level ticket field:
-
-\`\`\`json
-"wide": { "reason": "hard contract cutover: migrate every <X> call site in one PR" }
-\`\`\`
-
-Declaring \`wide\` with a non-empty reason **lifts the hard session-mass 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):
 
@@ -242,31 +189,47 @@ Every \`changes[]\` entry is a \`{ path, assumption }\` object — a prose bulle
 
 - 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 the plan seed"]\`. Silence on style sourcing is a smell.
 
-### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when your plan verifies against a scenario that does not exist yet):
-The plan-context envelope's \`bddScenarios\` field is the index of Gherkin scenarios that **already exist on \`main\`** — one row per scenario, carrying its \`.feature\` file path, line, scenario title and tags. It is the live signal for this rule: a \`.feature\` path + scenario your plan needs but that appears in no \`bddScenarios\` row does not exist yet. 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.
+CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
+IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
+**Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
+}
 
-When **one or more** \`.feature\` scenarios your plan verifies against are absent from \`bddScenarios\`, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
+/**
+ * The rules that only apply once a draft has more than one Story: the
+ * delivery-schedule simulation that makes each Story earn its slot, and the
+ * acceptance partition persist enforces at N>1.
+ *
+ * @returns {string}
+ */
+export function renderStorySplitRules() {
+  return `#### MULTI-STORY DRAFT — the story count must earn itself:
 
-- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
-- **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
-- **changes**: one entry per distinct absent \`.feature\` file, 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 the required tags 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.
+You are splitting past the default-single policy, so simulate the delivery schedule your plan implies and judge the plan by its schedule — not by how tidy the taxonomy looks:
 
-When every scenario your plan verifies against is already present in \`bddScenarios\`, do NOT emit a scaffold Story — there is nothing to create.
+1. **Build the wave schedule.** A Story runs only after every \`depends_on\` completes, and two Stories that name the same file in \`changes[]\` cannot run in the same wave (the scheduler serializes file-overlapping Stories even when no \`depends_on\` edge links them).
+2. **Every Story must earn its slot** by at least one of:
+   - **(a) parallelism** — it actually runs concurrently with a sibling in the schedule you just built ("logically independent" does not count; *schedule*-independent does);
+   - **(b) risk isolation** — it isolates a consumer-facing behavior change or high-risk cutover into its own reviewable, revertable unit;
+   - **(c) cohesion break** — merged into its neighbor it would no longer be one coherent change with one reason to exist.
+3. **A dependent link with none of those justifications merges into its consumer.** This generalizes the single-consumer merge rule from pairs to chains: N Stories that deliver no faster than one Story pay N delivery sessions (branch, PR, review, CI) for nothing.
+4. **When one file appears in the \`changes[]\` of most of your Stories, the slicing axis cuts across a shared seam** — merge the Stories that co-edit it, or re-slice along the seam so each Story owns its files.
 
-### 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 plan 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's top-level \`acceptance\` array 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.
+#### ACCEPTANCE PARTITION (persist-enforced at N>1):
 
-CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
-IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
+- Every acceptance criterion of the plan belongs to **exactly one** Story — no criterion is shared, and none is dropped. Persist refuses a draft whose criteria overlap or leave a plan-level criterion unclaimed.
+- Each Story carries its **own** \`## Spec\`; a shared \`techspec.md\` cannot be folded into N>1 Stories.
+- Express ordering with \`depends_on\` (a sibling slug, or \`#<id>\` for an open Story from an earlier plan). A Story whose \`verify[]\` runs against a file a sibling creates MUST \`depends_on\` that sibling, so the file exists when verification runs.`;
+}
 
-### 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\` note inside the FIRST Story's \`## Goal\` section 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.`;
+/**
+ * Render the story-author prompt for a draft of `storyCount` Stories: the
+ * N=1 core, plus the schedule and partition rules when the draft has
+ * siblings.
+ *
+ * @param {{ storyCount?: number }} [args]
+ * @returns {string}
+ */
+export function renderStoryAuthorPrompt({ storyCount = 1 } = {}) {
+  const core = renderStoryAuthorCore();
+  return storyCount > 1 ? `${core}\n\n${renderStorySplitRules()}` : core;
 }

package/.agents/scripts/lib/test-isolate/cli-options.js

@@ -0,0 +1,93 @@
+/**
+ * lib/test-isolate/cli-options.js — argv → options for the `test-isolate` CLI.
+ *
+ * Story #5316: this lived inside `.agents/scripts/test-isolate.js`, a file no
+ * test imports, so it scored the CRAP formula's untested maximum (210 at
+ * cyclomatic 14 and 0% coverage) and carried the tree's `test-isolate.js`
+ * cyclomatic breach row. It sits here beside `list-files.js`, `parse-tap.js`
+ * and `runner.js` for the same reason they do: the CLI shell is unreachable
+ * from a test, and everything reachable belongs under `lib/`.
+ *
+ * The long `else if` ladder it replaces was cyclomatic 14, above the repo's
+ * must-fix ceiling of 12. Dispatching through two flag tables is the same
+ * parse — same precedence, same tolerance for a value-taking flag that ends
+ * the argv — at roughly half the branch count.
+ */
+
+/**
+ * Flags that consume the following argv entry as a number, keyed by the
+ * option each one sets.
+ */
+const NUMERIC_FLAGS = {
+  '--workers': 'workers',
+  '--max-bisect-depth': 'maxBisectDepth',
+  '--max-bisect-targets': 'maxBisectTargets',
+  '--suite-concurrency': 'suiteConcurrency',
+};
+
+/** Flags that are their own value. */
+const BOOLEAN_FLAGS = {
+  '--json': 'json',
+  '--quiet': 'quiet',
+};
+
+/**
+ * Defaults every parse starts from. Deliberately module-private: nothing in
+ * production reads it, and exporting it so a test could assert against it
+ * would both make that test tautological and land a test-only export on the
+ * `dead-exports:production` ratchet.
+ */
+function defaultOptions() {
+  return {
+    pattern: undefined,
+    workers: undefined,
+    maxBisectDepth: 8,
+    maxBisectTargets: 5,
+    suiteConcurrency: 8,
+    json: false,
+    quiet: false,
+  };
+}
+
+/**
+ * Parse the `test-isolate` CLI's argv.
+ *
+ * Precedence, unchanged from the ladder this replaces:
+ *   - a known numeric flag consumes the next entry, but only when there IS a
+ *     next entry — a trailing `--workers` is ignored rather than setting NaN;
+ *   - a known boolean flag sets its option;
+ *   - the FIRST non-flag argument becomes the pattern, and later ones are
+ *     ignored;
+ *   - anything else is ignored, so an unknown `--flag` is never mistaken for
+ *     the pattern.
+ *
+ * @param {string[]} [argv]
+ * @returns {{
+ *   pattern: string|undefined,
+ *   workers: number|undefined,
+ *   maxBisectDepth: number,
+ *   maxBisectTargets: number,
+ *   suiteConcurrency: number,
+ *   json: boolean,
+ *   quiet: boolean,
+ * }}
+ */
+export function parseIsolateArgv(argv = []) {
+  const options = defaultOptions();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const numericKey = NUMERIC_FLAGS[arg];
+    if (numericKey && argv[i + 1]) {
+      options[numericKey] = Number(argv[i + 1]);
+      i += 1;
+      continue;
+    }
+    const booleanKey = BOOLEAN_FLAGS[arg];
+    if (booleanKey) {
+      options[booleanKey] = true;
+      continue;
+    }
+    if (!arg.startsWith('--') && !options.pattern) options.pattern = arg;
+  }
+  return options;
+}

package/.agents/scripts/lib/test-isolate/progress-log.js

@@ -0,0 +1,45 @@
+/**
+ * lib/test-isolate/progress-log.js — the `onProgress` sink for a
+ * `diagnoseIsolation` run.
+ *
+ * Story #5316: this was an anonymous arrow inlined into `runTestIsolate`'s
+ * argument list, which is exactly why it scored CRAP 72 (cyclomatic 8 at 0%
+ * coverage) under a name — `<anon runTestIsolate/(stage,payload)#0>` — that no
+ * test could address. As a named factory it is a plain table lookup.
+ */
+
+/** How many bisection suspects are named inline before eliding the rest. */
+const SUSPECT_PREVIEW = 3;
+
+/**
+ * Per-stage line formatters. A stage with no entry here is ignored, which is
+ * what the `else if` ladder this replaces did by falling off the end — so a
+ * new stage emitted by the runner stays silent rather than throwing.
+ */
+const STAGE_LINES = {
+  'isolated:start': (p) => `[test-isolate] isolated phase: ${p.count} file(s)`,
+  'isolated:done': () => '[test-isolate] isolated phase: done',
+  'suite:start': (p) => `[test-isolate] suite phase: ${p.count} file(s)`,
+  'suite:done': () => '[test-isolate] suite phase: done',
+  'bisect:start': (p) => `[test-isolate] bisecting flipper: ${p.target}`,
+  'bisect:done': (p) => {
+    const list = p.suspects.slice(0, SUSPECT_PREVIEW).join(', ');
+    const hidden = p.suspects.length - SUSPECT_PREVIEW;
+    const more = hidden > 0 ? ` (+${hidden} more)` : '';
+    return `[test-isolate]   suspects: ${list}${more}`;
+  },
+};
+
+/**
+ * Build the progress callback `diagnoseIsolation` calls as each phase starts
+ * and finishes.
+ *
+ * @param {(line: string) => void} onLog
+ * @returns {(stage: string, payload: object) => void}
+ */
+export function createProgressLogger(onLog) {
+  return (stage, payload) => {
+    const format = STAGE_LINES[stage];
+    if (format) onLog(format(payload ?? {}));
+  };
+}

package/.agents/scripts/lib/test-isolate/render-report.js

@@ -0,0 +1,97 @@
+/**
+ * lib/test-isolate/render-report.js — the human-readable `test-isolate` report.
+ *
+ * Story #5316: extracted verbatim from `.agents/scripts/test-isolate.js`,
+ * where no test could reach it (CRAP 72 at cyclomatic 8, 0% coverage). Pure
+ * string building — no I/O, no clock — so the whole surface is assertable.
+ *
+ * The three sections it renders are split into helpers so each is
+ * independently readable and none of them alone approaches the cyclomatic
+ * ceiling; `renderReport` is left as the composition.
+ */
+
+/**
+ * The flipper section: files that passed alone and failed in the suite, plus
+ * the bisection suspects for each.
+ *
+ * @param {string[]} lines Accumulator, appended in place.
+ * @param {import('./runner.js').IsolateReport} report
+ */
+function pushFlipperSection(lines, report) {
+  if (report.flippers.length === 0) {
+    lines.push('✓ No flippers detected — every file that passed alone');
+    lines.push('  also passed in the full suite run.');
+    return;
+  }
+  lines.push(`✗ ${report.flippers.length} flipper(s) detected:`);
+  for (const f of report.flippers) lines.push(`  - ${f}`);
+  lines.push('');
+  if (report.bisections.length === 0) return;
+  lines.push('Likely polluters (bisection suspects):');
+  for (const b of report.bisections) {
+    const tag = b.inconclusive ? ' [inconclusive]' : '';
+    lines.push(`  ${b.file}${tag}`);
+    for (const s of b.suspects) lines.push(`    ← ${s}`);
+  }
+}
+
+/**
+ * One env-mutating file's added/removed/changed summary. Empty parts are
+ * omitted, so a file that only added a var reads as `added=[...]` alone.
+ *
+ * @param {{added: string[], removed: string[], changed: string[]}} envDiff
+ * @returns {string}
+ */
+function formatEnvDiff(envDiff) {
+  const parts = [];
+  if (envDiff.added.length > 0)
+    parts.push(`added=[${envDiff.added.join(', ')}]`);
+  if (envDiff.removed.length > 0) {
+    parts.push(`removed=[${envDiff.removed.join(', ')}]`);
+  }
+  if (envDiff.changed.length > 0) {
+    parts.push(`changed=[${envDiff.changed.join(', ')}]`);
+  }
+  return parts.join(' ');
+}
+
+/**
+ * The env-leak section: files whose process exited with `process.env` still
+ * mutated, called out even when no failure cascade has manifested yet.
+ *
+ * @param {string[]} lines Accumulator, appended in place.
+ * @param {import('./runner.js').IsolateReport} report
+ */
+function pushEnvSection(lines, report) {
+  if (report.envMutators.length === 0) {
+    lines.push('✓ No env-var leaks detected across isolated runs.');
+    return;
+  }
+  lines.push(
+    `⚠ ${report.envMutators.length} file(s) left process.env mutated:`,
+  );
+  for (const m of report.envMutators) {
+    lines.push(`  ${m.file}`);
+    lines.push(`    ${formatEnvDiff(m.envDiff)}`);
+  }
+}
+
+/**
+ * Render the diagnostic report as text.
+ *
+ * @param {import('./runner.js').IsolateReport} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const lines = [];
+  lines.push('');
+  lines.push('=== test-isolate diagnostic report ===');
+  lines.push(`Files scanned:  ${report.files.length}`);
+  lines.push(`Wall duration:  ${(report.durationMs / 1000).toFixed(1)}s`);
+  lines.push('');
+  pushFlipperSection(lines, report);
+  lines.push('');
+  pushEnvSection(lines, report);
+  lines.push('');
+  return lines.join('\n');
+}