mandrel 1.94.0 → 2.1.0

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

@@ -1,8 +1,9 @@
 import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
   AUTHORING_ALTITUDE_GUIDANCE,
-  DEFAULT_TASK_SIZING,
+  DEFAULT_MODEL_CAPACITY,
   DELIVERABLE_GRANULARITY_GUIDANCE,
+  resolveCapacityCeilings,
 } from '../orchestration/ticket-validator-sizing.js';
 
 /**
@@ -18,27 +19,16 @@ import {
  * asks the planner to carry acceptance/verify as top-level ticket arrays.
  *
  * **Single source of the prompt body (Story #4162).** This module is the sole
- * carrier of the full decomposer system-prompt body. The
- * `epic-plan-decompose-author` SKILL no longer embeds a second verbatim copy —
- * it references this rendered prompt (delivered to the host LLM in the
- * `systemPrompt` field of the authoring context envelope built by
- * `epic-plan-decompose/phases/context.js`) instead, so the two surfaces cannot
- * drift. A guard test (`tests/ticket-decomposer.test.js`) fails if the SKILL
- * re-grows a full copy of the prompt preamble.
- *
- * **Token-budget sizing input (Story #4162).** `maxTokenBudget` is the real
- * one-pass delivery envelope (the task-prompt hydration cap surfaced into the
- * authoring envelope by `context.js`, Story #3875). It is threaded into the
- * rendered prompt as a sizing input so the planner sizes Stories against the
- * envelope a single agent can actually deliver in one pass, rather than leading
- * with the file-count proxy alone.
+ * carrier of the full decomposer system-prompt body, delivered to the host
+ * LLM in the `systemPrompts.decompose` field of the `/plan` context envelope
+ * (via `lib/orchestration/planning/decomposer-context.js`), so no second
+ * verbatim copy can drift.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
-  maxTokenBudget = LIMITS_DEFAULTS.maxTokenBudget,
   epicId = null,
 } = {}) {
-  return render2TierPrompt({ maxTickets, maxTokenBudget, epicId });
+  return render2TierPrompt({ maxTickets, epicId });
 }
 
 /**
@@ -47,12 +37,16 @@ export function renderDecomposerSystemPrompt({
  * 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.
  */
-function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
-  // 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, softAcceptanceCount } = DEFAULT_TASK_SIZING;
+function render2TierPrompt({ maxTickets, epicId = null }) {
+  // 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
-  // soft envelope-floor heuristic are sourced from the single
+  // 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).
@@ -78,17 +72,20 @@ function render2TierPrompt({ maxTickets, maxTokenBudget, epicId = null }) {
     ? `@epic-${epicId}-ac-1`
     : '@epic-<id>-ac-N';
   return `You are an expert Senior Project Manager and Orchestrator.
-Your job is to take an Epic (including its inline User Stories) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
+Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
 
-### HIERARCHY RULES:
-1. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
-   - Every Story attaches directly to the Epic — there is NO Feature tier and NO Task layer in this hierarchy.
-   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
-   - Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
+### HIERARCHY RULES (v2 default-single):
+1. **Emit exactly one Story by default.** Split into N>1 only when pieces have near-zero overlap or sit across an architectural seam. Coupled work stays one Story — put intra-session checkpoints in \`## Slicing\` and fold the Tech Spec into \`## Spec\`.
+2. **Stories**: Specific user-facing or architectural capabilities (e.g., "Implement JWT Token Exchange").
+   - There is NO Epic parent ticket, NO Feature tier, and NO Task layer.
+   - **Story-Level Execution**: Each Story is executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
+   - Thematic grouping is prose in the Story's folded \`## Spec\` / \`## Slicing\`, never sibling tickets for coupled work.
 
 ### LABEL CONVENTIONS:
-- Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
-- Every ticket must have a \`persona::[engineer|architect|qa-engineer|security-engineer|etc]\` label indicating WHO should execute it.
+- \`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).
+- \`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.
@@ -102,7 +99,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
     "body": <string — see STORY BODY SCHEMA below>,
     "acceptance": ["<testable, observable criterion>", ...],
     "verify": ["<exact command or test path> (<tier>)", ...],
-    "labels": ["type::story", "persona::..."],
+    "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)
   }
 ]
@@ -112,12 +109,20 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
 \`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. 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 (not nested inside \`body\`). The validator reads \`story.acceptance\` and \`story.verify\` directly — nesting them inside the body makes them invisible to the validator and the decompose is rejected.
+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.
+
+If you do write those sections into the \`body\` string anyway, they must mirror the top-level arrays **item for item** — persist fails closed on a disagreement rather than guessing which list is authoritative. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
 
 The serialized \`body\` string renders these markdown sections (in order):
 
     ## Goal
-    <one sentence — why this Story exists within the Epic>
+    <one sentence — why this Story exists>
+
+    ## Slicing
+    <optional ordered intra-session checkpoints — not a second Spec or AC table>
+
+    ## Spec
+    <optional lean technical approach — do NOT restate Goal / Acceptance / Verify>
 
     ## Changes
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
@@ -141,7 +146,9 @@ The serialized \`body\` string renders these markdown sections (in order):
 
 #### STORY BODY RULES:
 
-- **goal** (in body string): One sentence stating WHY this story exists within the Epic.
+- **goal** (in body string): One sentence stating WHY this Story exists.
+- **spec** (optional, in body string as \`## Spec\`): Lean technical approach only. 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.
@@ -157,37 +164,35 @@ ${newFileContract}
 
 ${advisoryCaveat}
 
-#### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
+#### STORY SIZING — COHESION FIRST (session capacity 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.
-
-**Size against the real one-pass delivery envelope.** Each Story is delivered and self-verified by a single agent in one pass, whose context is capped by the delivery token budget \`maxTokenBudget = ${maxTokenBudget}\` tokens (the task-prompt hydration cap). Use that envelope — not the file count alone — as the leading sizing input: a Story is correctly sized when one agent can hold its full change, acceptance, and verification in a single pass within \`maxTokenBudget\`. The numeric file thresholds below are a coarse backstop on top of this envelope, not the primary signal.
+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."
 
 ${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.
 - ${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 that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.
+- **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.
 
-**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:
+**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:
 
-- 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.
-- Acceptance mass is **advisory only**: more than **${softAcceptanceCount} acceptance items** (\`softAcceptanceCount\`) emits an advisory warning. There is NO hard acceptance ceiling — a long binding contract is a signal to re-check cohesion, never a reason to fragment one coherent capability into dependent slices.
+- 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 (hydration, branch, PR, review, CI).
+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) envelope pressure** — merged into its neighbor it would exceed the one-pass delivery envelope (\`maxTokenBudget\`).
+   - **(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.
 
@@ -201,7 +206,7 @@ A Story whose footprint is legitimately broad declares \`wide\` carrying a one-l
 "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.
+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.
 

package/.agents/scripts/lib/templates/spec-author-prompts.js

@@ -1,23 +1,14 @@
 /**
- * spec-author-prompts.js — single source of the Tech Spec and Acceptance
- * Spec authoring system prompts (Epic #4474, M3 PR2).
+ * spec-author-prompts.js — Story-scoped Spec / Acceptance authoring prompts.
  *
- * **Single source of the prompt bodies.** These two prompts were lifted
- * VERBATIM from the "(authoritative)" fenced blocks in
- * `.agents/skills/core/epic-plan-spec-author/SKILL.md` (§ "Tech Spec system
- * prompt" and § "Acceptance Spec system prompt") as the M3 side of the
- * M3/M8 boundary handshake: the `plan-context.js` envelope renders them
- * into `systemPrompts.spec` / `systemPrompts.acceptance` so the envelope
- * is authoritative from day one, and M8 (#4479) then deletes the
- * skill-side copies. This mirrors the Story #4162 pattern established by
- * `decomposer-prompts.js` for the decompose prompt: one rendered carrier,
- * no second verbatim copy to drift.
+ * v2 keeps a single executable document per Story. These prompts used to
+ * author a separate Epic Tech Spec + Acceptance Spec that were folded into
+ * the Epic body and then restated on Stories — a duplication source. They
+ * now author only Story `## Spec` approach prose and remind authors that
+ * acceptance lives once on the Story (`acceptance[]` / `## Acceptance`).
  */
 
 /**
- * The Tech Spec authoring system prompt (verbatim from the
- * `epic-plan-spec-author` SKILL's authoritative block).
- *
  * @returns {string}
  */
 export function renderTechSpecSystemPrompt() {
@@ -25,9 +16,6 @@ export function renderTechSpecSystemPrompt() {
 }
 
 /**
- * The Acceptance Spec authoring system prompt (verbatim from the
- * `epic-plan-spec-author` SKILL's authoritative block).
- *
  * @returns {string}
  */
 export function renderAcceptanceSpecSystemPrompt() {
@@ -35,40 +23,54 @@ export function renderAcceptanceSpecSystemPrompt() {
 }
 
 const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
-Your job is to convert an Epic into a Technical Specification for implementation.
+Your job is to author the Story's \`## Spec\` approach section — the technical
+how for one cohesive, executable Story. There is no separate Epic Tech Spec
+document and no spill-to-docs path.
 
-The Tech Spec should outline:
-1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
-2. Architecture & Design
-3. Data Models (if any)
-4. API Changes (if any)
-5. Core Components
-6. Security & Privacy Considerations
+The Spec should outline only what an implementing agent needs beyond Goal /
+Changes / Acceptance:
+1. Architecture & Design (approach, seams, reuse)
+2. Data Models (if any)
+3. API Changes (if any)
+4. Core Components
+5. Security & Privacy Considerations
 
 CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Open the document with the \`## Delivery Slicing\` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
-- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional \`## Technical Overview\` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
+- Respond ONLY with valid Markdown suitable to paste into a Story \`## Spec\`.
+- Do not use top-level <h1> (# ) tags. Prefer \`##\` / \`###\` under Spec.
+- Do NOT restate the Story's Goal, Acceptance, Verify, Changes, or Non-Goals —
+  those sections already live on the same Story body. Restatement is
+  duplication and a drift risk. If a brief orientation helps, keep a
+  \`## Technical Overview\` to 2–3 sentences naming the technical approach only.
+- Do NOT author a Delivery Slicing / fan-out table. If the work needs multiple
+  independent Stories, say so in one short note and stop — oversized Specs
+  mean the Story should be split, not documented elsewhere.
 - Format architectural decisions clearly with bullet points.
-- Author the \`## Delivery Slicing\` section as a markdown table with columns \`Slice | What ships | Independent?\`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.`;
+- Keep the Spec lean enough to stay inline on the Story (persist rejects
+  over-budget Specs; they are never written under docs/).`;
 
 const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
-Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+Your job is to help author the Story's binding acceptance contract — not a
+separate Acceptance Spec document.
 
-The Acceptance Spec should outline:
-1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
-2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
-3. Disposition — tag each row with one of: new | updated | unchanged
+v2 rule: acceptance lives **once**, on the Story:
+- Machine contract: top-level \`acceptance[]\` (and \`verify[]\`) on the ticket JSON
+- Human document: the same items rendered under \`## Acceptance\` / \`## Verify\`
+  on the Story body (persist syncs top-level into the body)
 
-The Epic body's \`## Acceptance Criteria\` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
+Do **not** author an Epic Acceptance Table, PRD restatement, or a second
+criteria list inside \`## Spec\`.
 
 CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
-- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
-- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
-- Each Outcome MUST be a **terse restatement keyed to a specific Epic \`## Acceptance Criteria\` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
-- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
-- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
-- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.
-- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy \`baseline-refresh\` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (\`ticket-validator.js\` → \`validateAcceptanceSubjectPrefix\`) will reject the decompose with \`code: 'forbidden-subject-prefix'\`. Use a Conventional-Commits subject (e.g. \`chore(baselines): refresh ...\`) and a body trailer (e.g. \`baseline-refresh: true\` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.`;
+- Respond ONLY with guidance or a draft \`acceptance[]\` / \`verify[]\` list for
+  one Story — never a parallel "Acceptance Spec" markdown artifact.
+- Every acceptance item MUST be observable from outside the agent (command
+  exits 0, file exists, selector resolves, fixture count matches). Reject
+  vague "matches the spec" / "looks good" items.
+- Every verify entry MUST name a tier in parentheses: unit | contract | e2e |
+  validate (or \`manual:<reason>\` when genuinely unverifiable in isolation).
+- Do NOT re-elaborate Goal or Spec prose inside acceptance items — bind the
+  outcome, not the approach.
+- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a
+  non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|
+  refactor|perf|docs|style|test|build|ci|revert).`;

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

@@ -17,12 +17,25 @@
  *     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.)
+ *   - Every `GIT_*` variable is dropped. When the suite runs inside a git
+ *     hook (husky pre-push via the coverage-capture path), the parent git
+ *     invocation exports `GIT_DIR` — from a linked worktree, the absolute
+ *     `<main>/.git/worktrees/<name>` path. A test fixture's `git init`
+ *     under that env re-initializes the shared gitdir and writes
+ *     `core.bare=true` into the MAIN checkout's `.git/config`, breaking
+ *     every worktree at once (#4580). Production git call sites are
+ *     covered by `cleanGitEnv` in `git-utils.js`; this is the same scrub
+ *     for test child processes, which may spawn git directly. Tests that
+ *     need a `GIT_*` variable set it explicitly on their own spawn.
  *
  * @param {NodeJS.ProcessEnv} baseEnv
  * @returns {NodeJS.ProcessEnv}
  */
 export function buildWebhookSafeTestEnv(baseEnv = process.env) {
-  const env = { ...baseEnv, NODE_ENV: baseEnv.NODE_ENV ?? 'test' };
+  const env = Object.fromEntries(
+    Object.entries(baseEnv).filter(([k]) => !k.startsWith('GIT_')),
+  );
+  env.NODE_ENV = baseEnv.NODE_ENV ?? 'test';
   if (env.MANDREL_ALLOW_TEST_WEBHOOKS !== '1') {
     delete env.NOTIFICATION_WEBHOOK_URL;
   }

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

@@ -12,13 +12,10 @@ import picomatch from 'picomatch';
  */
 export const INTEGRATION_INCLUDE = [
   'tests/**/*.integration.test.js',
-  'tests/epic-execute/epic-execute-record-wave.test.js',
   'tests/hook-chain-reflog-invariant.test.js',
-  'tests/push-epic-retry.test.js',
   'tests/contract/check-baselines-regression.test.js',
   'tests/contract/check-baselines-kernel-mismatch.test.js',
   'tests/integration-prime-after-sweep.test.js',
-  'tests/concurrency-wiring.test.js',
   'tests/scripts/git-cleanup.test.js',
   'tests/lib/checks/runner-integration.test.js',
   'tests/single-story-close-sync.test.js',

package/.agents/scripts/lib/{epic-body-sections.js → ticket-body-sections.js}

@@ -1,19 +1,19 @@
 /**
- * epic-body-sections.js — marker-delimited managed sections of the Epic body.
+ * ticket-body-sections.js — marker-delimited managed sections of a
+ * planning ticket body.
  *
  * Story #4324 retired the `context::tech-spec` / `context::acceptance-spec`
- * ticket classes: the Epic body is now the single planning document. The
- * Tech Spec (opening with `## Delivery Slicing`, per #4316) and the
- * Acceptance Spec's AC-ID table (`## Acceptance Table`, Outcomes keyed to
- * Epic AC bullets per #4315) land as **managed sections** of the Epic body,
- * delimited by invisible HTML comment markers so each writer can update
- * *only its own region* without rewriting the rest of the body.
+ * ticket classes: the planning ticket body is the single planning document.
+ * The Tech Spec (opening with `## Delivery Slicing`, per #4316) and the
+ * Acceptance Spec's AC-ID table (`## Acceptance Table`) land as **managed
+ * sections**, delimited by invisible HTML comment markers so each writer
+ * can update *only its own region* without rewriting the rest of the body.
  *
  * Section-scoped writes are the load-bearing contract (extending the
  * single-writer discipline #4303 established for the body trailer):
  *
- *   - The Phase 7 spec persist path (`epic-plan-spec/phases/plan-epic.js`)
- *     upserts the `techSpec` and `acceptanceTable` regions.
+ *   - The `/plan` persist path upserts the `techSpec` and `acceptanceTable`
+ *     regions.
  *   - The close-time acceptance reconciler
  *     (`acceptance-spec-reconciler.js`) reads and rewrites the
  *     `acceptanceTable` region only (verification dispositions).
@@ -32,7 +32,7 @@
  *
  * @type {Readonly<Record<'techSpec'|'acceptanceTable', { start: string, end: string, label: string }>>}
  */
-export const EPIC_BODY_SECTIONS = Object.freeze({
+export const TICKET_BODY_SECTIONS = Object.freeze({
   techSpec: Object.freeze({
     start: '<!-- mandrel:tech-spec:start -->',
     end: '<!-- mandrel:tech-spec:end -->',
@@ -47,7 +47,7 @@ export const EPIC_BODY_SECTIONS = Object.freeze({
 
 /**
  * Canonical heading the acceptance-table region opens with. Distinct from
- * the Epic's ideation `## Acceptance Criteria` bullets (which remain the
+ * the ticket's ideation `## Acceptance Criteria` bullets (which remain the
  * SSOT for *what* the table verifies — the table anchors to those bullets).
  */
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
@@ -56,7 +56,7 @@ export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
  * Regex matching the Tech Spec's required opening heading (same variants
  * `spec-section-validator.js` accepts). Exported so it is the single
  * source of truth for this pattern — `spec-section-validator.js`,
- * `epic-plan-clarity.js`, and `consolidation-precondition.js` all import
+ * `consolidation-precondition.js` all import
  * it rather than each carrying their own copy.
  */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
@@ -66,10 +66,10 @@ export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
  * @returns {{ start: string, end: string, label: string }}
  */
 function descriptor(kind) {
-  const d = EPIC_BODY_SECTIONS[kind];
+  const d = TICKET_BODY_SECTIONS[kind];
   if (!d) {
     throw new TypeError(
-      `epic-body-sections: unknown section kind "${kind}" (expected ${Object.keys(EPIC_BODY_SECTIONS).join(' | ')})`,
+      `ticket-body-sections: unknown section kind "${kind}" (expected ${Object.keys(TICKET_BODY_SECTIONS).join(' | ')})`,
     );
   }
   return d;
@@ -103,24 +103,10 @@ function locate(body, kind) {
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {boolean}
  */
-export function hasEpicSection(body, kind) {
+export function hasTicketSection(body, kind) {
   return locate(body, kind) !== null;
 }
 
-/**
- * Extract a managed region's content (between the markers, trimmed).
- * Returns `null` when the region is absent.
- *
- * @param {string} body
- * @param {'techSpec'|'acceptanceTable'} kind
- * @returns {string|null}
- */
-export function extractEpicSection(body, kind) {
-  const loc = locate(body, kind);
-  if (!loc) return null;
-  return body.slice(loc.contentStart, loc.contentEnd).trim();
-}
-
 /**
  * Insert or replace a managed region, preserving every byte outside it.
  *
@@ -136,7 +122,7 @@ export function extractEpicSection(body, kind) {
  * @param {string} content Section content (headings included).
  * @returns {string}
  */
-export function upsertEpicSection(body, kind, content) {
+export function upsertTicketSection(body, kind, content) {
   const { start, end } = descriptor(kind);
   const safeBody = typeof body === 'string' ? body : '';
   const trimmedContent = typeof content === 'string' ? content.trim() : '';
@@ -179,7 +165,7 @@ export function upsertEpicSection(body, kind, content) {
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {string}
  */
-export function stripEpicSection(body, kind) {
+export function stripTicketSection(body, kind) {
   const { end } = descriptor(kind);
   const loc = locate(body, kind);
   if (!loc) return typeof body === 'string' ? body : '';
@@ -189,7 +175,7 @@ export function stripEpicSection(body, kind) {
 }
 
 /**
- * Re-plan / decompose detection: true when the Epic body carries folded
+ * Re-plan / decompose detection: true when the ticket body carries folded
  * Tech Spec content — the managed region, or (defence in depth for a
  * hand-authored body) a bare `## Delivery Slicing` heading.
  *
@@ -197,7 +183,7 @@ export function stripEpicSection(body, kind) {
  * @returns {boolean}
  */
 export function hasTechSpecContent(body) {
-  if (hasEpicSection(body, 'techSpec')) return true;
+  if (hasTicketSection(body, 'techSpec')) return true;
   return typeof body === 'string' && DELIVERY_SLICING_RE.test(body);
 }
 
@@ -217,9 +203,9 @@ const DELIVERY_DROP_HEADINGS = new Set([
 ]);
 
 /**
- * Slice an Epic body down to the sections a delivery story agent acts on.
+ * Slice a planning ticket body down to the sections a delivery story agent acts on.
  *
- * KEEP: the Epic title / preamble before the first `##`, `## Goal`,
+ * KEEP: the ticket title / preamble before the first `##`, `## Goal`,
  * `## Non-Goals`, `## User Stories`, the `techSpec` managed region, and —
  * fail-open — any unknown / operator-authored `##` section not in the drop
  * list. DROP: `## Context`, `## Scope`, `## Acceptance Criteria`, and the
@@ -236,12 +222,12 @@ const DELIVERY_DROP_HEADINGS = new Set([
  * @param {string} body
  * @returns {string}
  */
-export function sliceEpicBodyForDelivery(body) {
+export function sliceTicketBodyForDelivery(body) {
   if (typeof body !== 'string' || body.length === 0) return '';
 
   // 1. Drop the acceptance-table managed region outright (authoring/close
   //    machinery, never delivery context).
-  let working = stripEpicSection(body, 'acceptanceTable');
+  let working = stripTicketSection(body, 'acceptanceTable');
 
   // 2. Protect the techSpec managed region from heading-boundary slicing by
   //    lifting it out behind an opaque placeholder, then restoring it after
@@ -261,7 +247,7 @@ export function sliceEpicBodyForDelivery(body) {
 
   // 3. Slice plain `##` sections by heading boundaries, dropping only the
   //    known ideation/authoring headings. The preamble before the first
-  //    `##` (Epic title / lede) is always kept.
+  //    `##` (ticket title / lede) is always kept.
   const kept = [];
   let dropping = false;
   for (const line of working.split('\n')) {
@@ -291,7 +277,7 @@ export function sliceEpicBodyForDelivery(body) {
 
 /**
  * Strip the retired machine-managed `## Planning Artifacts` checklist from
- * an Epic body (the section that linked the now-retired context tickets).
+ * a planning ticket body (the section that linked the now-retired context tickets).
  * The slice ends at the next `## ` heading, a managed-region marker, or
  * EOF. Historical bodies without the section pass through untouched.
  *