mandrel 1.80.0 → 1.82.0

package/.agents/README.md

@@ -361,8 +361,8 @@ rule:
 > GitHub I/O, label transitions, JSON validators, NDJSON readers,
 > diff-vs-baseline gates, template renderers.
 >
-> **Prompt + judgment → make it a Skill.** Examples: composing a PRD
-> from an Epic body, classifying friction signals from a failed shell
+> **Prompt + judgment → make it a Skill.** Examples: composing a Tech
+> Spec from an Epic body, classifying friction signals from a failed shell
 > command, decomposing a Tech Spec into a ticket hierarchy.
 
 The rule is two-sided on purpose. "Has an LLM step adjacent" is *not*
@@ -377,9 +377,9 @@ judgment (Skill) or of a parseable transform (script).
 **split**: the deterministic halves stay as a script, the judgment middle
 moves to a Skill.
 
-- **`--emit-context`** (script half) — fetches the PRD and Tech Spec
-  bodies, scrapes project docs, emits a JSON envelope. Parseable in,
-  parseable out. Stays a script.
+- **`--emit-context`** (script half) — fetches the Epic body (which
+  carries the folded Tech Spec sections), scrapes project docs, emits a
+  JSON envelope. Parseable in, parseable out. Stays a script.
 - **Authoring middle** (Skill half) — given the envelope, author the
   ticket hierarchy JSON. Pure prompt + judgment. Migrates to a Skill
   under `.agents/skills/core/` so it ships with declarative

package/.agents/docs/SDLC.md

@@ -19,9 +19,11 @@ ADR 20260512-coupling-stance in [`../docs/decisions.md`](../../docs/decisions.md
 From zero to shipped:
 
 1. **Plan the work.** Run `/plan` in your agentic IDE. The framework
-   generates a PRD, a Tech Spec, and an Acceptance Spec, decomposes the
-   work into the flat Story backlog under the Epic, and
-   transitions the Epic to `agent::ready`.
+   authors a Tech Spec and an Acceptance Table and folds both into the
+   Epic body as managed sections (the Epic is the single planning
+   document — the PRD and context-ticket artifact classes were
+   retired), decomposes the work into the flat Story backlog under the
+   Epic, and transitions the Epic to `agent::ready`.
 
    The entry point you use selects where the run begins:
    - With **no arguments** (or `--idea "<seed>"`), the workflow enters at
@@ -50,19 +52,22 @@ From zero to shipped:
    4. **Phase 4 — open the Epic Issue** *(ideation entry only)* — opens
       the GitHub Issue with **only** the `type::epic` label; the captured
       id flows into the rest of the pipeline.
-   5. **Phase 5 — re-plan detection** — checks whether the Epic already
-      carries planning artifacts and, if so, prompts before overwriting
-      the PRD / Tech Spec / Acceptance Spec in place and recreating the
-      child Story tickets.
+   5. **Phase 5 — re-plan detection** — checks whether the Epic body
+      already carries the folded Tech Spec sections (keyed on the
+      `## Delivery Slicing` managed section — Story #4324) and, if so,
+      prompts before overwriting the Tech Spec / Acceptance Table
+      sections in place and recreating the child Story tickets. Legacy
+      context tickets on historical Epics are ignored (never fetched).
    6. **Phase 6 — Epic clarity gate** — scores the Epic body against the
       five canonical sections. A `clear` verdict requires ≥ 4 of 5
       sections present **and** the Acceptance Criteria section present (AC
       is required, not optional). A `clear` verdict proceeds silently;
       `needs-refinement` drops into a one-shot refinement loop with a HITL
       diff before persisting the sharpened body.
-   7. **Phase 7 — PRD, Tech Spec & Acceptance Spec** — the
-      `epic-plan-spec-author` skill authors all three planning artifacts
-      as linked context tickets, flips the Epic to `agent::review-spec`,
+   7. **Phase 7 — Tech Spec & Acceptance Spec** — the
+      `epic-plan-spec-author` skill authors both planning artifacts;
+      the persist half folds them into the Epic body's managed
+      sections, flips the Epic to `agent::review-spec`,
       and routes high-risk Epics to a HITL review stop (low-risk Epics
       auto-proceed).
    8. **Phase 8 — work-breakdown decomposition** — the
@@ -240,7 +245,7 @@ graph LR
 
     subgraph Phase2 ["Phase 2: Planning"]
         direction TB
-        C["🤖 PRD + Tech Spec authoring"]:::agentic
+        C["🤖 Tech Spec authoring"]:::agentic
         D["🤖 Ticket Decomposer"]:::agentic
         C --> D
         D -.-> D_Art["📄 GitHub Issue Hierarchy"]:::artifact
@@ -346,7 +351,7 @@ mode:
    the canonical Epic-from-idea template; the operator confirms before
    the GitHub Issue is opened.
 5. **Open the Epic.** The Issue is opened with **only** the `type::epic`
-   label — no `state::*` label is applied at creation. PRD authoring in
+   label — no `state::*` label is applied at creation. Spec authoring in
    Phase 1b advances it to `agent::review-spec`.
 
 #### Scope triage
@@ -354,7 +359,7 @@ mode:
 `/plan` Phase 1.5 runs the
 [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) rubric over the
 sharpened one-pager so a story-sized scope is not pushed through the full Epic
-ceremony (PRD + Tech Spec + Acceptance Spec + Story backlog +
+ceremony (Tech Spec + Acceptance Spec + Story backlog +
 `epic/<id>` integration branch) only to land as a degenerate one-Story
 output. The rubric anchors its sizing judgment **by reference** to
 the existing sizing SSOT (`DELIVERABLE_GRANULARITY_GUIDANCE` /
@@ -376,7 +381,7 @@ The same rubric also guards the **existing-Epic entry** (1b) as the
 hand-opened directly as a `type::epic` issue (the Phase 6 Epic Clarity Gate
 scores section *presence*, not scope *size*, so a clear-but-thin Epic would
 otherwise sail through). The advisory fires **only** when Phase 5 found no
-linked PRD / Tech Spec **and** the Epic has no open Story children, so
+folded Tech Spec sections **and** the Epic has no open Story children, so
 it never re-triages an Epic that is being re-planned. An `epic` verdict
 proceeds silently; a `story` / `borderline` verdict STOPs with the same
 three-way choice (convert to a standalone Story / proceed as Epic anyway /
@@ -420,7 +425,7 @@ Epic id.
 
 The framework reads the Epic and autonomously builds the entire work breakdown.
 
-> **Epic Clarity Gate (`/plan` `planning.clarity-gate` state).** Before PRD / Tech Spec /
+> **Epic Clarity Gate (`/plan` `planning.clarity-gate` state).** Before Tech Spec /
 > Acceptance Spec authoring kicks off, `/plan` scores the Epic body
 > against the five canonical sections from
 > [`templates/epic-from-idea.md`](../templates/epic-from-idea.md) (Context,
@@ -441,27 +446,32 @@ The framework reads the Epic and autonomously builds the entire work breakdown.
 
 1. **Epic Planner** (`epic-plan-spec.js`):
    - Synthesizes the Epic body with project documentation.
-   - Generates a **PRD** (`context::prd`), **Tech Spec**
-     (`context::tech-spec`), and **Acceptance Spec**
-     (`context::acceptance-spec`) as linked GitHub Issues.
-
-> [!TIP] **PRD authoring — acceptance criteria phrasing.** Write acceptance
+   - Folds the authored **Tech Spec** (opening with `## Delivery
+     Slicing`) and the **Acceptance Table** (the AC-ID table) into
+     marker-delimited managed sections of the Epic body. The Epic body
+     carries its `## User Stories` section inline — the PRD artifact
+     class was retired (Story #4314), and the `context::tech-spec` /
+     `context::acceptance-spec` ticket classes were retired the same way
+     (Story #4324): a `/plan` Epic run creates exactly **one** GitHub
+     issue.
+
+> [!TIP] **Acceptance criteria phrasing.** Write the Epic's acceptance
 > criteria in Gherkin-compatible `Given / When / Then` form so the QA
 > acceptance suite can lift them directly into executable `.feature` files. See
 > [`rules/gherkin-standards.md`](../rules/gherkin-standards.md) for the canonical
 > clause grammar, tag taxonomy, and forbidden patterns.
 
-### Acceptance Spec — the third planning context ticket
+### Acceptance Table — the second folded planning section
 
-Every Epic carries **three** planning context tickets, not two:
+Every planned Epic body carries **two** managed planning sections
+(Story #4324 — no separate context tickets):
 
-| Label                       | Artifact         | Authored by                                         | Drives                                                   |
-| --------------------------- | ---------------- | --------------------------------------------------- | -------------------------------------------------------- |
-| `context::prd`              | PRD              | `epic-plan-spec-author` skill (PRD persona)         | What we're shipping and why.                             |
-| `context::tech-spec`        | Tech Spec        | `epic-plan-spec-author` skill (Architect persona)   | How we're shipping it.                                   |
-| `context::acceptance-spec`  | Acceptance Spec  | `epic-plan-spec-author` skill (Acceptance Engineer) | The AC ID table that gates close-time reconciliation.    |
+| Section                | Artifact         | Authored by                                         | Drives                                                |
+| ---------------------- | ---------------- | --------------------------------------------------- | ----------------------------------------------------- |
+| `## Delivery Slicing`… | Tech Spec        | `epic-plan-spec-author` skill (Architect persona)   | How we're shipping it.                                |
+| `## Acceptance Table`  | Acceptance Table | `epic-plan-spec-author` skill (Acceptance Engineer) | The AC ID table that gates close-time reconciliation. |
 
-The Acceptance Spec body is a single Markdown table —
+The Acceptance Table section is a single Markdown table —
 `| AC ID | Outcome | Feature File | Scenario | Disposition |` — with
 stable `AC-<n>` IDs assigned in document order. IDs are reused across
 re-plans when an Outcome is materially unchanged so scenario tags
@@ -472,16 +482,20 @@ BDD runner + pending-tag (e.g. `playwright-bdd supports @skip`) for the
 features-first Story to consume.
 
 The spec is persisted by
-`epic-plan-spec.js --epic [Epic_ID] --prd ... --techspec ... --acceptance-spec ...`
-— the persist half writes all three artifacts in one atomic step and
-fails loudly if any is missing or empty.
+`epic-plan-spec.js --epic [Epic_ID] --tech-spec ... --acceptance-table ...`
+— the persist half folds both artifacts into the Epic body's managed
+sections in one atomic, section-scoped write (everything outside the
+managed regions is byte-preserved) and fails loudly if any input is
+missing or empty. At delivery time, hydration strips the
+`## Acceptance Table` section from story prompts — it is
+authoring/close-time machinery, not delivery context.
 
 #### Adaptive planning risk routing
 
 `/plan`'s `planning.spec-authoring` state derives a deterministic
 **`planningRisk`** envelope from a **planner-authored risk verdict**
-(`risk-verdict.json`, the fourth planning artifact the
-`epic-plan-spec-author` Skill writes from the PRD / Tech Spec it just
+(`risk-verdict.json`, the third planning artifact the
+`epic-plan-spec-author` Skill writes from the Epic body / Tech Spec it just
 authored). The persist half of `epic-plan-spec.js` validates the verdict
 against `risk-verdict.schema.json` — a malformed verdict fails closed —
 then derives the envelope via `deriveRiskEnvelope`
@@ -500,8 +514,8 @@ downstream decisions:
   Epics (visible behavior, public API, security, billing, data
   migration, destructive mutation, critical workflow) trigger a HITL
   stop after `planning.spec-authoring` so the operator can read the
-  PRD / Tech Spec / Acceptance Spec on GitHub before decomposition
-  starts. Low-risk Epics (docs-only, internal refactor, pure test
+  Epic body's Tech Spec / Acceptance Table sections on GitHub before
+  decomposition starts. Low-risk Epics (docs-only, internal refactor, pure test
   harness, cleanup) print the auto-proceed message from
   `reviewRouting.operatorMessage` and chain directly into the
   `planning.decompose` state. The operator can force the review
@@ -528,7 +542,8 @@ on the Epic ticket records the waiver. There are two routes to the label:
   (see § Adaptive planning risk routing) and,
   when `acceptanceDisposition === 'not-applicable'`, the persist half
   of `epic-plan-spec.js` applies `acceptance::n-a` on the Epic and skips
-  the Acceptance Spec artifact for that run. The disposition is also
+  the Acceptance Table section for that run (stripping a stale one on a
+  re-plan). The disposition is also
   recorded in the `epic-plan-state` checkpoint so the decision is
   auditable.
 
@@ -537,9 +552,11 @@ by both runtime gates:
 
 - The `/deliver` **start gate** (`delivery.snapshot` state) skips
   the acceptance-spec presence check when the label is set.
-- The finalize-time **acceptance-spec reconciler** returns
+- The finalize-time **acceptance reconciler** returns
   `status: 'waived'` without scanning `tests/features/**` and the
-  finalize step proceeds.
+  finalize step proceeds. (The waiver now waives the Epic body's
+  `## Acceptance Table` section — Story #4324 — with unchanged
+  meaning.)
 
 The waiver is binary — there is no partial opt-out. If an Epic later
 warrants spec coverage, remove the label and run `/plan`'s
@@ -550,9 +567,8 @@ warrants spec coverage, remove the label and run `/plan`'s
      (Epic → Story):
 
      ```text
-     Epic (type::epic)
-     ├── PRD (context::prd)
-     ├── Tech Spec (context::tech-spec)
+     Epic (type::epic)                ← body carries the folded Tech Spec
+     │                                  sections + ## Acceptance Table
      ├── Story (type::story)
      │   ├── acceptance[]            ← inline on Story body
      │   └── verify[]                ← inline on Story body
@@ -569,7 +585,7 @@ warrants spec coverage, remove the label and run `/plan`'s
 Story. The wave-loop fan-out in `/deliver` and the
 Story-branch → Epic-branch merge model are unchanged; the Feature and
 Task layers are gone, and thematic grouping lives as prose in the Epic
-body / Tech Spec.
+body (which also carries the folded Tech Spec sections).
 
 When decomposition completes the Epic flips to `agent::ready` and the
 dispatch manifest is posted as a structured comment on the Epic. That
@@ -585,9 +601,9 @@ contract is enforced at the planner boundary so `/deliver` can
 treat `agent::ready` as a load-bearing precondition rather than a
 hopeful signal.
 
-- **Planning artifacts linked or waived.** The Epic body lists a
-  linked `context::prd` and `context::tech-spec` ticket, and either a
-  linked `context::acceptance-spec` ticket **or** the
+- **Planning sections present or waived.** The Epic body carries the
+  folded Tech Spec sections (`## Delivery Slicing` onward), and either
+  the `## Acceptance Table` managed section **or** the
   `acceptance::n-a` waiver label. Missing-without-waiver fails the
   handoff.
 - **Decomposition persisted.** The structural reconciler has applied
@@ -641,19 +657,14 @@ side-effects rather than inline calls at phase boundaries; the
 "merge-lockout" lint rule keeps `gh pr merge` confined to the
 `AutomergeArmer` listener.
 
-> **Acceptance-spec start gate.** Before a single wave fans out,
+> **Acceptance start gate.** Before a single wave fans out,
 > `/deliver`'s `delivery.snapshot` state
 > ([`lib/orchestration/epic-runner/phases/snapshot.js`](../scripts/lib/orchestration/epic-runner/phases/snapshot.js))
 > asserts that the Epic either (a) carries the `acceptance::n-a`
-> waiver label, or (b) has a linked `context::acceptance-spec`
-> ticket. The ticket's GitHub state (open / closed) is not checked
-> — presence is sufficient, matching the PRD and Tech Spec contract.
-> The reviewer's OK during `/plan`'s `planning.spec-authoring`
-> state is the approval
-> signal, not a manual ticket-close action; the three planning
-> context tickets are closed automatically by the
-> `Finalizer` listener subscribed to `epic.close.end` once the
-> Epic PR opens. Neither
+> waiver label, or (b) carries the `## Acceptance Table` managed
+> section in its body (Story #4324). Presence is sufficient — the
+> reviewer's OK during `/plan`'s `planning.spec-authoring` state is
+> the approval signal. Neither
 > condition met → the snapshot throws a clear error naming the
 > missing precondition and `runAsCli` maps it to `process.exit(1)`.
 > This refuses to launch Epics that skipped acceptance-spec
@@ -748,7 +759,9 @@ standalone Stories), the Context Hydrator assembles a self-contained prompt:
 
 1. `agent-protocol.md` (universal rules).
 2. Persona and skill directives (from Task labels).
-3. Hierarchy context (Story → Epic → PRD → Tech Spec).
+3. Hierarchy context (Story → Epic — the Epic body carries the folded
+   Tech Spec sections; the `## Acceptance Table` section is stripped
+   from delivery prompts).
 4. **Story branch context.** Automatic checkouts to the Story branch. Under
    worktree isolation, each Story runs in its own `.worktrees/story-<id>/` so
    branch swaps, staging, and reflog activity are isolated per-story. See
@@ -902,15 +915,19 @@ watch / auto-merge / cleanup tail that drives the PR to merge:
    listener chain owns every close-time side effect end to end
    (Story #2894 — bus-owned finalize). The chain runs three
    responsibilities in order:
-   1. **Acceptance-spec reconciliation.** Invokes
+   1. **Acceptance reconciliation.** Invokes
       `acceptance-spec-reconciler.js` to diff the AC IDs declared in
-      the linked `context::acceptance-spec` body against `@ac-*` /
-      `@pending` tags in `tests/features/**`. A non-OK reconciliation
-      throws (per `.agents/rules/orchestration-error-handling.md`),
-      aborting finalize **before** the planning artifacts are closed —
-      so the PRD / Tech Spec / Acceptance Spec stay open until the AC
-      coverage gap is fixed. Skipped (`status: 'waived'`) when the Epic
-      carries `acceptance::n-a`.
+      the Epic body's `## Acceptance Table` managed section
+      (Story #4324) against `@epic-<id>-ac-*` / `@pending` tags in
+      `tests/features/**`. A non-OK reconciliation throws (per
+      `.agents/rules/orchestration-error-handling.md`), aborting
+      finalize **before** the PR opens — the Epic blocks until the AC
+      coverage gap is fixed. On a clean run the reconciler records
+      each row's verification outcome (`satisfied | pending |
+      missing`) into the table's Disposition column — a
+      section-scoped write that touches only the managed region.
+      Skipped (`status: 'waived'`) when the Epic carries
+      `acceptance::n-a`.
    2. **PR open (bus-owned, Story #2894).** On
       `acceptance.reconcile.ok`, the `Finalizer` listener invokes
       `openOrLocatePr({ epicId, headBranch: 'epic/<id>', baseBranch:
@@ -925,19 +942,15 @@ watch / auto-merge / cleanup tail that drives the PR to merge:
       (enforced by the merge-lockout rule in
       `.agents/scripts/check-lifecycle-lint.js`); the
       `delivery.finalize` state never shells the merge command.
-   3. **Planning-artifact close + hand-off (bus-owned, Story #2894).**
-      The `Finalizer` chains `closePlanningTickets({ epicId,
-      provider })` to close the three planning context tickets
-      (`context::prd`, `context::tech-spec`,
-      `context::acceptance-spec`) so the Epic's `Closes #<id>`
-      auto-close path is not blocked by open sub-issues, then
+   3. **Hand-off (bus-owned, Story #2894).** The `Finalizer` runs
       `postHandoffComment({ epicId, prNumber, prUrl, provider })` to
       upsert the canonical `epic-handoff` structured comment naming
-      the PR. Both helpers are idempotent — re-running finalize
-      after a crash counts already-closed tickets under
-      `alreadyClosed` and edits the existing handoff comment in
-      place rather than appending a duplicate. The Epic stays at
-      `agent::executing` until the PR merges.
+      the PR. (Story #4324 retired the `closePlanningTickets` sweep
+      with the context-ticket classes — there are no planning tickets
+      to close.) The helper is idempotent — re-running finalize after
+      a crash edits the existing handoff comment in place rather than
+      appending a duplicate. The Epic stays at `agent::executing`
+      until the PR merges.
 6. **Watch-and-iterate (Phase 8).** `/deliver` watches the open PR's
    required checks until they turn green. Transient failures trigger an
    automated re-run loop; durable failures surface for human remediation
@@ -982,7 +995,7 @@ required checks fail.
    `code-review` comment, and the retro before merging by hand, or
    (b) checks fail and need remediation on the Epic branch. There is
    no separate close command — the close-out side effects (PR open,
-   planning-ticket close, handoff comment) are owned by `/deliver`'s
+   handoff comment) are owned by `/deliver`'s
    `delivery.finalize` state (the lifecycle Finalizer listener), whose
    replay is idempotent.
 
@@ -1068,7 +1081,7 @@ action.
    integration target.
 2. **Completion.** Each Story flips to `agent::done` at its own closure
    (`story-close.js`); the wave loop tracks Epic-level progress as
-   Stories complete. There is no upward auto-cascade — Epics, PRDs, and
+   Stories complete. There is no upward auto-cascade — Epics and
    Tech Specs are never flipped by Story closure; the Epic only flips to
    `agent::done` when the operator merges the PR to `main`.
 
@@ -1205,7 +1218,7 @@ on so re-runs short-circuit when state has not changed.
 | Close-validation          | `/deliver` `delivery.close-validation` state    | lint + test + maintainability + CRAP + coverage ratchets via `evidence-gate.js`           | blocking  | `evidence-gate` cache entry keyed by `git rev-parse HEAD`                 |
 | Pre-push                  | Local `.husky/pre-push` hook on every push           | Diff-scoped quality preview + coverage/CRAP ratchet                                       | blocking  | Working-tree SHA + staged-diff hash (per push)                            |
 | Acceptance reconciliation | `/deliver` `delivery.finalize` state            | `acceptance-spec-reconciler.js` diffs AC IDs against `@ac-*` / `@pending` feature tags    | blocking  | `acceptance-reconcile` structured comment on Epic, keyed by spec-body SHA |
-| Spec freshness            | `/plan` `planning.spec-authoring` state         | Re-derives PRD / Tech Spec / Acceptance Spec staleness against Epic body checksum         | advisory  | `epic-plan-state` checkpoint entry per spec artifact body SHA             |
+| Spec freshness            | `/plan` `planning.spec-authoring` state         | Re-derives Tech Spec / Acceptance Spec staleness against Epic body checksum               | advisory  | `epic-plan-state` checkpoint entry per spec artifact body SHA             |
 
 ### Review & feedback loop
 
@@ -1411,9 +1424,9 @@ For Stories already in flight, use one of the three options above.
 | Command                                          | Purpose                                                                                                                                                                      |
 | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `npx mandrel init`                               | Cold-start command — install `mandrel` (if absent), `mandrel sync`, bootstrap.js (provisions repo + Projects V2 board, labels, branch protection), then onboarding tail (stack detection, docs scaffolding, doctor gate, `/plan` handoff). |
-| `/plan`                                     | Ideation entry — sharpen idea, search duplicates, open Epic, then PRD + Tech Spec + decomposition.                                                                            |
+| `/plan`                                     | Ideation entry — sharpen idea, search duplicates, open Epic, then Tech Spec + decomposition.                                                                                 |
 | `/plan --idea "<seed>"`                     | Same ideation entry with pre-supplied seed.                                                                                                                                   |
-| `/plan <epicId>`                            | Existing-Epic mode — PRD + Tech Spec + decomposition for an Epic Issue already opened.                                                                                       |
+| `/plan <epicId>`                            | Existing-Epic mode — Tech Spec + decomposition for an Epic Issue already opened.                                                                                             |
 | `/deliver <epicId>`                                      | Drive an Epic end-to-end. Wave loop → close-validation → code-review → retro → opens PR to `main` with auto-merge armed.                                                       |
 | `/deliver <storyId> [<storyId>...]`                     | Deliver one or more standalone Stories (no `Epic: #N` reference). Builds a dependency-aware wave plan and fans out one worker per Story per wave.                              |
 | `/plan`                                                 | Plan a one-off Story outside an Epic backlog.                                                                                                                                  |

package/.agents/docs/configuration.md

@@ -110,6 +110,8 @@ top-level keys are validation errors.
 | `taskSizing.hardFiles` | No | `integer` | — | File-count hard ceiling: a Story exceeding it is rejected unless it declares `wide` with a reason (default 30). |
 | `taskSizing.maxAcceptance` | No | `integer` | — | Hard ceiling on acceptance[] item count (default 14). |
 | `taskSizing.softAcceptanceCount` | No | `integer` | — | Soft-warn threshold on acceptance[] item count (default 10). |
+| `taskSizing.mergeCandidateMaxFiles` | No | `integer` | — | Under-size threshold (Story #4312): a Story with at most this many declared changes[] files, at most mergeCandidateMaxAcceptance acceptance items, and at least one depends_on edge to a sibling trips the advisory `merge-candidate` soft finding (default 3). |
+| `taskSizing.mergeCandidateMaxAcceptance` | No | `integer` | — | Under-size threshold (Story #4312): the acceptance[] item ceiling of the `merge-candidate` soft finding heuristic (default 4). |
 | `failOnSharedEditors` | No | `boolean` | — | — |
 | `requireExplicitCrossStoryDeps` | No | `boolean` | — | — |
 | `failOnRegistryConflicts` | No | `boolean` | — | — |
@@ -448,7 +450,8 @@ suppress a channel entirely, set its array to `[]`.
 ### `planning.context`
 
 Caps the size of `--emit-context` JSON payloads emitted during `/plan`
-so a runaway PRD / Tech Spec can't blow the planning agent's context budget.
+so a runaway Epic body (with its folded Tech Spec sections) can't blow the
+planning agent's context budget.
 
 | Field         | Required | Default  | Purpose                                                                                       |
 | ------------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
@@ -627,6 +630,12 @@ No tier-specific knobs beyond the common shape.
 | --------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
 | `bundles` | No       | `[]`    | Array of `{ name, path, limit }` entries (e.g. `{ "name": "app", "path": "dist/app.js", "limit": "100kB" }`). |
 
+Unlike `crap` / `maintainability`, this gate has no `refreshTag` config
+field — there is no scorer to regenerate the baseline from source, so the
+one-shot refresh/acknowledge mechanism is an env var, not a config knob.
+See [`.agents/docs/quality-gates.md` § Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)
+for `BUNDLE_SIZE_REFRESH=1` usage.
+
 #### `delivery.quality.formatAutofix`
 
 | Field       | Required | Default | Purpose                                                                                                                  |
@@ -791,6 +800,7 @@ the lint ratchet, and the CRAP/MI gates.
 | `baselines/lint.json`             | `lint-baseline.js`                   | `node .agents/scripts/lint-baseline.js capture`                       |
 | `baselines/crap.json`             | `update-crap-baseline.js`            | `npm run crap:update`                                                   |
 | `baselines/maintainability.json`  | `update-maintainability-baseline.js` | `npm run maintainability:update`                                        |
+| `baselines/bundle-size.json`      | consumer's own build/measure step    | Commit the build's measured sizes; for an intentional growth, run the check with `BUNDLE_SIZE_REFRESH=1` (see [Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
 
 These files are the contract. They are read by every gate (Story close, push
 hook, CI) and are regenerated only via tagged `baseline-refresh:` commits

package/.agents/docs/quality-gates.md

@@ -452,6 +452,67 @@ watch loop — an unjustified baseline ratchet is no longer caught by CI.
 
 ---
 
+## Bundle-size ratchet — one-shot refresh/acknowledge (Story #151)
+
+> Baseline envelope, axes, and component model: see the
+> [Baseline reference](#baseline-reference) section below.
+
+`check-baselines --gate bundle-size` is a **strict** ratchet: it diffs the
+branch's committed `baselines/bundle-size.json` (head) against the base
+ref's copy (`origin/main` by default) using the gate's configured
+`tolerance`, and separately checks the head aggregate against `floors`.
+Unlike `coverage` / `crap` / `maintainability`, bundle-size has **no
+scorer of its own** — the measured `rawKb` / `gzippedKb` numbers come from
+whatever build step the consumer already runs, not a source-tree rescan —
+so there is no `refreshBaseline({ kind: 'bundle-size', ... })` path to
+regenerate a "corrected" baseline the way `npm run crap:update` does.
+
+This makes an **intentional** bundle-size growth (a framework major bump,
+a new dependency, an SSR runtime swap) impossible to land cleanly with the
+usual levers: permanently raising `tolerance` in `.agentrc.json` disables
+the ratchet for every *future* PR too, not just the one that legitimately
+grew.
+
+### `BUNDLE_SIZE_REFRESH=1`
+
+Set the environment variable for the one CI/local run that needs to land
+the growth:
+
+```bash
+BUNDLE_SIZE_REFRESH=1 npm run bundle-size:check
+# or, calling the dispatcher directly:
+BUNDLE_SIZE_REFRESH=1 node .agents/scripts/check-baselines.js --gate bundle-size
+```
+
+When set (`1` or `true`, case-insensitive), every `bundle-size`
+head-vs-base regression is demoted to `unchanged` **for that invocation
+only** — the gate compares head-vs-head in effect, so it passes even
+though the committed baseline grew. **Floors still apply**: an
+acknowledged PR can still fail if the head aggregate breaches the
+configured `floors` budget, so a genuinely runaway regression isn't
+silently waved through under the guise of "intentional".
+
+Commit the regenerated `baselines/bundle-size.json` (reflecting the real,
+larger sizes) in the same PR so the new numbers become the base for the
+*next* PR's diff.
+
+### The ratchet returns to full strength automatically
+
+`BUNDLE_SIZE_REFRESH` is read fresh on every invocation and is **never
+persisted** — no config write, no committed tag, no lingering state. The
+very next `check-baselines --gate bundle-size` run (i.e. the next PR),
+without the env var set, re-enforces the ratchet at full strength against
+the now-larger committed baseline. There is nothing to remember to reset.
+
+This mirrors the `CRAP_TOLERANCE` env-override precedent (see
+[CRAP gate — Consumer onboarding](#crap-gate--consumer-onboarding) above),
+but as a true one-shot acknowledgment rather than a run-scoped tolerance
+override: `CRAP_TOLERANCE` changes the *threshold*, `BUNDLE_SIZE_REFRESH`
+demotes the *outcome* of an already-flagged regression, which is the
+correct shape for a gate with no rescoring path of its own.
+
+---
+
 ## HITL blocker escalation
 
 `risk::high` is informational/planning metadata only. Runtime execution

package/.agents/docs/workflows.md

@@ -57,7 +57,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/git-merge-pr` | Analyze, validate, resolve conflicts, and merge a given pull request by number. |
 | `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
-| `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
+| `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (sectioned Epic body: Tech Spec + Acceptance Table, then decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/instructions.md

@@ -263,16 +263,18 @@ stops.
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when
      absent or unrelated to the task — they are not part of the universal
      mandatory set.
-   - **Epic Context**: Additionally, read the context tickets (PRD, Tech
-     Spec) linked in the current Epic's body and the task-specific
-     instructions.
+   - **Epic Context**: Additionally, read the current Epic's body — the
+     single planning document (ideation sections plus the folded Tech
+     Spec sections; Story #4324 retired the separate context tickets) —
+     and the task-specific instructions.
    - **Optimization**: For large projects, prioritize targeted retrieval
      (semantic code search or focused text search) to isolate specific
      schemas or decisions before reading broad files.
 2. **Plan First:** For non-trivial tasks (3+ steps or architectural
-   decisions), enter **Plan Mode**. Update the Tech Spec issue or create a
-   new Technical Specification document in the `docs/` root (if not already
-   handled by a ticket) before touching code.
+   decisions), enter **Plan Mode**. Update the Epic body's Tech Spec
+   sections (via `/plan`) or create a new Technical Specification document
+   in the `docs/` root (if not already handled by a ticket) before
+   touching code.
 3. **Artifacts over Chat:** Create log files for test results, build
    outputs, or debug sessions rather than pasting large code blocks in
    chat.
@@ -350,7 +352,7 @@ Mandrel uses a **2-tier ticket hierarchy** (Epic → Story).
 Acceptance criteria and verification steps live inline on the Story
 body (`acceptance[]` / `verify[]`); there is no Feature tier and no
 `type::task` ticket layer. Thematic grouping lives as prose in the
-Epic body / Tech Spec.
+Epic body (which also carries the folded Tech Spec sections).
 
 - The decomposer emits only `type::epic` and `type::story` issues;
   Stories attach directly to the Epic.

package/.agents/personas/architect.md

@@ -14,8 +14,10 @@ _specifications_ that the Engineer personas will implement.
 
 Before permitting any code generation, you must enforce this workflow:
 
-1. **Interrogate Context:** Read the Epic's linked PRD (`context::prd`) and
-   Tech Spec (`context::tech-spec`) GitHub Issues, plus every file listed in
+1. **Interrogate Context:** Read the Epic body — including its `## User
+   Stories` section and the folded Tech Spec sections (`## Delivery
+   Slicing` onward; Story #4324 retired the separate Tech Spec ticket) —
+   plus every file listed in
    `project.docsContextFiles` (typically `architecture.md` and
    `data-dictionary.md`). Ask clarifying questions about scale, budget, or
    edge cases.
@@ -76,10 +78,11 @@ Before permitting any code generation, you must enforce this workflow:
 - **Context:** A brief summary of what files will be touched.
 - **Pseudo-code:** High-level logic flow.
 
-### Level 2: Complex Feature (Output to the Epic's Tech Spec GitHub Issue)
+### Level 2: Complex Feature (Output to the Epic body's Tech Spec sections)
 
-Open or update the GitHub Issue labelled `context::tech-spec` and linked to
-the parent Epic. The body must contain:
+Update the parent Epic body's managed Tech Spec sections (the
+`## Delivery Slicing`-led region — via `/plan` Phase 7, which owns the
+section-scoped write). The content must contain:
 
 1. **Goal:** One sentence summary.
 2. **Proposed Changes:** List of files to create/modify.

package/.agents/personas/engineer-mobile.md

@@ -8,12 +8,13 @@ specifications within the `@repo/mobile` workspace. You value **native feel**,
 **offline resilience**, and **cross-platform consistency**.
 
 **Golden Rule:** Never guess. If a requirement is missing from the Architect's
-plan or the PRD's Acceptance Criteria, stop and ask. Do not invent business
+plan or the Epic's Acceptance Criteria, stop and ask. Do not invent business
 logic or UX decisions.
 
 ## 2. Interaction Protocol
 
-1. **Read Context:** Before writing a single line, read the relevant tech spec
+1. **Read Context:** Before writing a single line, read the parent Epic
+   body's Tech Spec sections
    and the project's architectural guidelines. Understand the screen/navigation
    hierarchy.
 2. **Workspace Scope:** You operate exclusively within `@repo/mobile`. All

package/.agents/personas/engineer-web.md

@@ -8,12 +8,13 @@ Architect's design specifications within the `@repo/web` workspace. You value
 **component reusability**, **semantic HTML**, and **progressive enhancement**.
 
 **Golden Rule:** Never guess. If a requirement is missing from the Architect's
-plan or the PRD's Acceptance Criteria, stop and ask. Do not invent business
+plan or the Epic's Acceptance Criteria, stop and ask. Do not invent business
 logic or UX decisions.
 
 ## 2. Interaction Protocol
 
-1. **Read Context:** Before writing a single line, read the relevant tech spec
+1. **Read Context:** Before writing a single line, read the parent Epic
+   body's Tech Spec sections
    and the project's architectural guidelines. Understand the page/component
    hierarchy.
 2. **Workspace Scope:** You operate exclusively within `@repo/web`. All commands

package/.agents/personas/engineer.md

@@ -16,11 +16,12 @@ plan, stop and ask. Do not invent business logic.
 
 ## 2. Interaction Protocol
 
-1. **Read Context:** Before writing a single line, read the parent Epic's
-   linked Tech Spec GitHub Issue (`context::tech-spec`) and PRD
-   (`context::prd`), plus every file listed in
-   `project.docsContextFiles` (typically `architecture.md` and the
-   project's architectural guidelines).
+1. **Read Context:** Before writing a single line, read the parent Epic
+   body — the single planning document, including its `## User Stories`
+   section and the folded Tech Spec sections (`## Delivery Slicing`
+   onward; Story #4324 retired the separate Tech Spec ticket) — plus
+   every file listed in `project.docsContextFiles` (typically
+   `architecture.md` and the project's architectural guidelines).
 2. **Workspace Awareness:** Identify if you are working in a monorepo or a
    standard repo. Ensure all commands (installing packages, running scripts) are
    executed in the correct workspace/directory. Check `package.json` or the