mandrel 2.56.0 → 2.58.0

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

@@ -1,71 +1,61 @@
-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 tickets-mode rules** ({@link ticketsModePromptField}, Story
+ *     #5323) — what to re-derive rather than carry when the seed is an
+ *     existing ticket whose body is already in Story shape.
+ *
+ * The envelope carries the core as `systemPrompts.story`, the split rules as
+ * `systemPrompts.storySplitRules` and the tickets rules as
+ * `systemPrompts.storyTicketsRules`; a planner reads the second only when the
+ * default-single split policy clears, and the third only in tickets mode.
  */
-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 +74,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 +88,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 +98,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 +113,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 +134,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\`. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. 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 +149,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 +167,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 +193,92 @@ 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.`;
+}
+
+/**
+ * The rules that only apply when the seed is an existing ticket (Story
+ * #5323).
+ *
+ * A `--tickets` seed arrives already in Story shape — rendered `AC-<n>:`
+ * checkboxes, a `## Verify` list, a `## Changes` footprint — and an author
+ * reading it as a template carries that shape forward instead of re-deriving
+ * it. The observed failure (swarm-os #2707 / #2708, planned from #2542 under
+ * mandrel 2.57.0) was a Story whose acceptance list was the source's, handles
+ * and all, and whose verify entries carried a tier suffix retired two
+ * releases earlier. The source ticket is **evidence**, not a draft.
+ *
+ * @returns {string}
+ */
+function renderStoryTicketsRules() {
+  return `#### TICKETS-MODE DRAFT — the source ticket is evidence, not a template:
 
-### 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.`;
+You are planning from one or more existing tickets. Read them for **what the work is** — the problem, the constraints, the commands that verify it — and re-derive everything else. Specifically:
+
+1. **Re-derive \`acceptance[]\` from the goal.** Do not copy the source's \`## Acceptance\` list, and never carry its \`AC-<n>:\` handles — the body renderer numbers the checkboxes itself, so a copied handle renders doubled. A source ticket carrying fifteen criteria is telling you its acceptance was over-specified, not that yours must be: state the three to six outcomes a PR reviewer can confirm, and let the rest fall to \`verify[]\`.
+2. **A mechanical check is a \`verify[]\` command, not an acceptance item.** "Baselines refreshed", "lint exits 0", "the generated index is regenerated", "the quality gate passes" are commands the deliverer runs and the critic reads as evidence. Carrying them as acceptance items inflates the binding contract with work every close already gates.
+3. **Read the source's \`verify[]\` for the commands it names, not for its shape.** Take the test paths and scripts; drop any trailing tier suffix (\`(unit)\`, \`(contract)\`, \`(e2e)\`, \`(validate)\`) and any \`manual:<reason>\` escape — a verify entry is a bare command.
+4. **Re-derive the footprint against the tree as it is now.** The source ticket's \`## Changes\` predicted a repository that has since moved; probe the paths you cite and omit the generated artifacts it listed.
+5. **Do not carry the source's prose wholesale.** Its current-state narration and per-file walkthroughs are exactly what the SPEC PROSE CONTRACT above forbids. Restate the contract and the invariants; the deliverer reads the code for the rest.`;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * The mode-conditional slice of `systemPrompts`.
+ *
+ * `storyTicketsRules` only means anything when the seed is an existing
+ * ticket, and an envelope carrying it in every mode teaches the author to
+ * look for a source ticket a `--seed` run does not have. Returning a
+ * spreadable object rather than a nullable string keeps the decision here,
+ * beside the prompt it selects, instead of as a branch in the envelope
+ * builder.
+ *
+ * @param {string|undefined} mode The plan-context mode.
+ * @returns {{ storyTicketsRules?: string }}
+ */
+export function ticketsModePromptField(mode) {
+  return mode === 'tickets'
+    ? { storyTicketsRules: renderStoryTicketsRules() }
+    : {};
 }

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 ?? {}));
+  };
+}