mandrel 1.82.0 → 1.83.0

package/.agents/workflows/helpers/epic-deliver-story.md

@@ -133,11 +133,15 @@ in-process (retrying the install command when
 `dependenciesInstalled === 'false'`, default `npm ci`) and rendered the
 initial snapshot (`phase: "init"`). There is no separate command to run.
 
-The Step 0 result envelope carries a `prepare.renderedBody` field — the
-markdown body for the initial Story-phase table. **Relay it verbatim to
-chat** so operators see the initial progress block before the first commit
-lands. Do the same after every transition in Step 1 / Step 3 (the body is
-the Story-level rollup the parent `/deliver` aggregator reads).
+Step 0's init run already upserted the initial `story-run-progress`
+snapshot (`phase: "init"`) as a structured comment on the Story — that
+comment, refreshed by `story-phase.js` at each transition, is the
+authoritative Story-level rollup the parent `/deliver` aggregator reads.
+You do **not** relay `prepare.renderedBody` verbatim to chat. Instead,
+relay **one line per phase transition** (e.g. `Story #<id>: init →
+implementing`), and do the same after every transition in Step 1 / Step 3.
+The snapshot CLI carries the full body; the chat line is a terse progress
+delta, not a body dump.
 
 ---
 
@@ -162,6 +166,20 @@ Run a single Story-implementation phase against the inline `acceptance[]`
    `context.verify`). Treat the acceptance items as the contract and
    the verify items as the canonical at-keyboard checks.
 
+   **Docs context — read the digest, not the full set.** Do **not**
+   re-read every file in `project.docsContextFiles`. The parent prompt
+   passes a `docsDigestPath` (the per-Epic docs digest at
+   `temp/epic-<epicId>/docs-digest.md`, written by
+   `epic-deliver-prepare.js`). Read that digest — a compact per-file
+   outline (path, size, heading outline with line numbers, first
+   paragraph under each `##`) — to decide which docs bear on this Story,
+   then **pull the full file on demand** (jump to the section at the line
+   number the digest names) only when relevant. When `docsDigestPath` is
+   null (the project configured no `docsContextFiles`), there is no
+   digest and no per-Story docs mandate — read a full doc only if the
+   Story's own context points you at one. See
+   [`.agents/instructions.md` § 3](../../instructions.md).
+
 3. Implement the work as one or more commits on `story-<storyId>`.
    Author commits directly with the project's editor / `git commit`,
    following
@@ -240,10 +258,14 @@ partially-implemented Story picks up from whatever commits are already
 on `story-<storyId>`; the agent inspects `git log` to decide what work
 remains.
 
-After each `story-phase.js` call, **relay the envelope's
-`renderedBody` to chat** as the Story's progress update. Skip chat
-relay only when running in a non-interactive sub-agent context where
-the parent will aggregate.
+After each `story-phase.js` call, relay **one line naming the phase
+transition** (e.g. `Story #<id>: implementing → closing`) as the Story's
+progress update — not the envelope's `renderedBody` verbatim. The
+`story-phase.js` CLI has already upserted the full body into the
+`story-run-progress` snapshot; that comment is the authoritative rollup
+the parent `/deliver` aggregator reads. Skip chat relay entirely when
+running in a non-interactive sub-agent context where the parent will
+aggregate.
 
 > Rebase pauses on conflicts → follow
 > [`_merge-conflict-template.md`](_merge-conflict-template.md).
@@ -338,8 +360,10 @@ regardless of the reap status.
 `story-phase.js` (typically the `phase: 'done'` snapshot at close,
 or the `phase: 'blocked'` snapshot on a blocker). The parent
 `/deliver` may inline a digest of this in its wave-level Notable
-section. When run interactively (no parent), omit it — the chat already
-has the latest body relayed during Step 1 / Step 3.
+section. When run interactively (no parent), omit it — the authoritative
+body lives in the `story-run-progress` snapshot the phase CLI upserted,
+and the chat already carries the per-transition progress lines from
+Step 1 / Step 3.
 
 ---
 

package/.agents/workflows/helpers/plan-epic-reference.md

@@ -0,0 +1,136 @@
+---
+description: >-
+  Reference companion to plan-epic.md — the recovery procedures, --resume
+  mechanics, troubleshooting, and background rationale blocks moved out of the
+  runtime core so every /plan run ingests only the phase flow. Read on demand
+  from the trigger-point pointers in plan-epic.md.
+caller: plan-epic.md
+---
+
+# helpers/plan-epic-reference — Epic-planning reference & recovery
+
+> **Not a slash command.** This file lives in `helpers/` and is a
+> path-included reference module (not projected into the plugin command
+> tree). [`plan-epic.md`](plan-epic.md) is the runtime core — the phase
+> flow, commands, and gate contracts. This file holds the secondary
+> material a run needs only when it hits an edge (a recovery path, a
+> troubleshooting symptom) or wants the design rationale behind a phase.
+> Each section below is reached from a one-line pointer at its trigger
+> point in the core.
+
+## Phase 7 — background rationale
+
+The Phase 7 (Tech Spec & Acceptance Spec) core carries only the commands and
+the gate contract. The design rationale for the phase's guards and managed
+sections lives here.
+
+### Epic-lease preflight (workflow guard)
+
+Before any Phase 7 mutation, `epic-plan-spec.js` acquires the Epic-lease via
+the assignee-as-lease primitive (`lib/orchestration/ticket-lease.js`, wired
+through `lib/orchestration/epic-plan-lease-guard.js`). The lease rides the
+Epic's single assignee: the operator (`github.operatorHandle` in
+`.agentrc.json`) claims the Epic for the duration of the plan. The guard
+**fails closed**: `/plan` emits no `story.heartbeat` during its run
+(heartbeats are a delivery-time signal), so there is no live-heartbeat source
+to judge a concurrent plan's liveness from. Any **foreign assignee** is
+therefore treated as a live claim — the persist half **exits non-zero and
+names the current owner**, so two `/plan` runs cannot drive the same Epic
+concurrently. Pass **`--steal`** to forcibly transfer a foreign claim once you
+have confirmed the other run is dead. An **unassigned** Epic, or one **already
+held by this operator**, is taken (or re-affirmed) silently. The lease is
+**released after Phase 8** (decompose) completes.
+
+### Idempotent managed sections
+
+The persist half is section-scoped and keyed on the Epic body: a re-run that
+finds the requested sections already present
+(`<!-- mandrel:tech-spec:start/end -->` /
+`<!-- mandrel:acceptance-table:start/end -->`) short-circuits as
+`already-planned` instead of duplicating content. Pass `--force` to overwrite
+the managed sections in place (same Epic issue, refreshed section bodies).
+
+### One planning document
+
+A `/plan` Epic run creates exactly **one** issue — the Epic. The planning
+artifacts land as marker-delimited managed sections of the Epic body: the Tech
+Spec (opening with `## Delivery Slicing`) inside
+`<!-- mandrel:tech-spec:start/end -->`, and the Acceptance Spec's AC-ID table
+(headed `## Acceptance Table`) inside
+`<!-- mandrel:acceptance-table:start/end -->`. The PRD artifact class was
+retired (Story #4314) — its one novel section, **User Stories**, lives inline
+in the Epic body as a `## User Stories` section — and Story #4324 retired the
+`context::tech-spec` / `context::acceptance-spec` ticket classes the same way.
+The `## Acceptance Table` section captures the stable-ID acceptance criteria
+table (`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that
+drives close-time reconciliation during `/deliver` Phase 6. Operators may opt
+out for refactor-only or docs-only Epics by applying the `acceptance::n-a`
+label to the Epic ticket — when present, the `epic-plan-spec-author` skill
+skips the Acceptance Table output and the runtime gates (start gate, finalize
+reconciler) honour the waiver — the section need not be authored when the
+waiver is set. See [SDLC § Acceptance Table — the second folded planning
+section](../../docs/SDLC.md#acceptance-table--the-second-folded-planning-section)
+for the full lifecycle.
+
+### Parallel-safe file naming (per-Epic tree)
+
+Multiple Epics may be planned or decomposed concurrently. Every temp file
+written in the workflow lives under the per-Epic tree
+(`temp/epic-[Epic_ID]/<artifact>`) — e.g.
+`temp/epic-[Epic_ID]/planner-context.json`,
+`temp/epic-[Epic_ID]/techspec.md`,
+`temp/epic-[Epic_ID]/decomposer-context.json`,
+`temp/epic-[Epic_ID]/tickets.json`. The directory namespace is the isolation
+boundary; basenames inside it are stable. Do **not** reuse bare flat names
+like `temp/techspec.md` or the legacy `temp/<artifact>-epic-<id>.<ext>` shape
+— both have been retired.
+
+**Durability.** The per-Epic tree is durable across runs: only the wrapper
+scripts perform intra-phase cleanup of files they wrote in the same invocation
+(see [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js)).
+Nothing else garbage-collects the tree, so cross-Epic artifacts — retros, perf
+reports, signals, manifests — accumulate until an operator explicitly removes
+them.
+
+## Phase 8 — `--resume` recovery (secondary rate limit)
+
+The Phase 8 (Work Breakdown Decomposition) core carries the normal-path and
+`--force` persist commands. The `--resume` recovery path — reached when a
+large decomposition aborts mid-persist — lives here.
+
+**Secondary rate limit on large Epics.** For backlogs over ~60 tickets,
+GitHub's secondary rate limit (HTTP 403, body contains "secondary rate limit")
+can trip mid-decomposition after ~80 issue creations. The http-client retries
+automatically with a 30–120s backoff and the decomposer drops `concurrencyCap`
+to 1 for the rest of the run on the first observation. If the run still aborts
+(network drop, exhausted retries, etc.), resume from the partial backlog with:
+
+```bash
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
+  --tickets temp/epic-[Epic_ID]/tickets.json --resume
+```
+
+`--resume` is idempotent: the reconciler recovers the slug→issue map from
+`temp/epic-[Epic_ID]/[Epic_ID].state.json`, and when that file is missing or
+incomplete it **reseeds the map from live GitHub state** by matching each spec
+slug against the open children of the Epic by title. Slugs that resolve to an
+existing open child diff as Updates/no-ops; only the genuinely-missing children
+are created — the existing tree is never duplicated. To force-throttle from the
+first call on a known-large Epic, set `(framework constant: decomposer
+concurrency): 1` in `.agentrc.json`.
+
+## Troubleshooting
+
+- If `epic-plan-spec.js --emit-context` fails, confirm the Epic exists and
+  has a body with enough initial context.
+- If `epic-plan-decompose.js` rejects the tickets file, re-read the
+  validator's error message — the most common causes are a ticket whose
+  `type` is not `story`, a Story missing its inline `acceptance[]` /
+  `verify[]` contract, or a dependency cycle in the Story `depends_on`
+  graph.
+- If decomposition persisted the tickets but the Epic is not on `agent::ready`,
+  you likely called `runDecomposePhase` from `epic-plan-decompose.js`
+  directly without completing the persist flow — only the CLI surface
+  (`node epic-plan-decompose.js --tickets ...`) drives the full
+  reconciler pipeline and flips the lifecycle label. Apply `agent::ready`
+  by hand and re-run via the CLI next time.

package/.agents/workflows/helpers/plan-epic.md

@@ -92,54 +92,25 @@ Phase 5 (Re-Plan Detection).
 
 ## Phase 1.5: Scope Triage (ideation path only)
 
-This phase runs **only** on the ideation path, immediately after Phase 1
-produces the sharpened one-pager. It is **skipped entirely** when an Epic ID
-argument was supplied (the existing-Epic path jumps straight to Phase 5), and
-it is **skipped** when `/plan` was entered via a scope-triage handoff from
-[`/plan`](plan-story.md) — a handoff is a triage decision already made,
-and re-triaging it would re-litigate a settled call (the no-re-triage rule the
-skill states once).
-
-1. **Activate the scope-triage skill**: Read
-   [`<agentRoot>/skills/core/scope-triage/SKILL.md`](../../skills/core/scope-triage/SKILL.md)
-   via the `Read` tool (resolve `<agentRoot>` from `project.paths.agentRoot` —
-   default `.agents`) and apply its rubric to the Phase 1 one-pager. The skill
-   anchors its sizing judgment **by reference** to
-   `DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING` in
-   [`ticket-validator-sizing.js`](../../scripts/lib/orchestration/ticket-validator-sizing.js)
-   and emits one verdict: `epic` | `story` | `borderline`. The verdict is
-   host-LLM judgment — there is **no `--flag`**, no scorer, no schema, and no
-   label transition.
-
-2. **Fold the verdict into the existing Phase 1 HITL stop** — do **not** add a
-   second stop:
-   - **`epic` verdict** → no extra prompt. The Phase 1 confirmation proceeds
-     as a plain one-pager confirm and the run continues to Phase 2.
-   - **`story` or `borderline` verdict** → the Phase 1 confirmation prompt
-     presents a **three-way operator choice**:
-     - **Recommended: single Story** (with the triage rationale) — persist the
-       one-pager to a notes file and hand off to
-       `/plan --from-notes <path>`, identifying the invocation as a
-       scope-triage handoff so `/plan` skips its own gate. Then **exit
-       `/plan`**.
-     - **Plan as Epic anyway** — ignore the recommendation and continue to
-       Phase 2 with the one-pager.
-     - **Abort** — stop planning entirely.
-
-   **Never auto-route.** The verdict is advisory; the operator always decides.
-   Being wrong in the `epic` direction is cheap (Phase 8.3 consolidation and
-   the sizing validator catch an over-planned Story later); the gate exists to
-   avoid the ceremony tax of pushing a story-sized scope through the full Epic
-   pipeline.
-
-   > **`--yes` (headless) exception.** "Never auto-route" is the interactive
-   > contract. Under `--yes` the operator has *pre-authorized* the
-   > recommendation: the three-way choice resolves to its **Recommended**
-   > branch deterministically — `single Story` hands off to
-   > `/plan --from-notes <path>` (carrying `--yes` so the receiving story
-   > path also auto-proceeds), and an `epic` verdict simply continues to
-   > Phase 2. No operator wait. This is the only sanctioned auto-route, and it
-   > exists solely to make `/plan` driveable headlessly.
+This phase runs the shared scope-triage gate over the Phase 1 one-pager. The
+gate mechanics — verdict meanings, the three-way operator choice, the `--yes`
+resolution, and the no-re-triage rule — live in the single-homed fragment
+[`scope-triage-gate.md`](scope-triage-gate.md); read it and follow it. This
+phase supplies only its path-specific firing conditions:
+
+- **When it runs**: only on the ideation path, immediately after Phase 1
+  produces the sharpened one-pager. The rubric is applied to the **Phase 1
+  one-pager**, and the verdict folds into the **existing Phase 1 HITL stop**
+  (do **not** add a second stop).
+- **When it is skipped**: entirely, when an Epic ID argument was supplied (the
+  existing-Epic path jumps straight to Phase 5); and when `/plan` was entered
+  via a scope-triage handoff from [`/plan`](plan-story.md) (the no-re-triage
+  rule in the fragment).
+- **Recommended branch on a `story` / `borderline` verdict**: persist the
+  one-pager to a notes file and hand off to `/plan --from-notes <path>`,
+  identifying the invocation as a scope-triage handoff so `/plan` skips its
+  own gate, then **exit `/plan`**. The alternative branches are **plan as Epic
+  anyway** (continue to Phase 2) and **abort**.
 
 ## Phase 2: Cross-Epic Duplicate Search
 
@@ -278,36 +249,21 @@ triage on the one-pager before the Epic existed.
 
 ### Triage
 
-1. **Activate the scope-triage skill**: Read
-   [`<agentRoot>/skills/core/scope-triage/SKILL.md`](../../skills/core/scope-triage/SKILL.md)
-   via the `Read` tool (resolve `<agentRoot>` from `project.paths.agentRoot` —
-   default `.agents`) and apply its rubric to the **Epic body**. The skill is
-   artifact-agnostic — it reads the same against an Epic body as against a
-   one-pager or a Story draft — and anchors its sizing judgment **by
-   reference** to `DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING`
-   in
-   [`ticket-validator-sizing.js`](../../scripts/lib/orchestration/ticket-validator-sizing.js).
-   It emits one verdict: `epic` | `story` | `borderline`. The verdict is
-   host-LLM judgment — there is **no `--flag`**, no scorer, no schema, and no
-   label transition behind this gate. Do **not** restate the skill's rubric or
-   its sizing thresholds here.
-
-2. **`epic` verdict** → proceed silently. No extra prompt, no HITL stop. The
-   run continues straight to Phase 6. Being wrong in the `epic` direction is
-   cheap (Phase 8.3 consolidation and the sizing validator catch an
-   over-planned Story later), so an `epic` verdict never costs the operator a
-   stop.
-
-3. **`story` or `borderline` verdict** → **STOP** and present a **three-way
-   operator choice**. Never auto-route; the verdict is advisory and the
-   operator always decides.
-
-   - **Recommended: convert to a standalone Story** (with the triage
-     rationale) — run the conversion path below.
-   - **Proceed as Epic anyway** — ignore the recommendation and continue to
-     Phase 6 with the Epic unchanged.
-   - **Abort** — stop planning entirely. The Epic is left exactly as it was;
-     no labels move and nothing is closed.
+Run the shared scope-triage gate over the **Epic body** — the gate mechanics
+(verdict meanings, the three-way operator choice, the `--yes` resolution, and
+the no-re-triage rule) live in [`scope-triage-gate.md`](scope-triage-gate.md);
+read it and follow it. The scope-triage skill is artifact-agnostic, so it
+reads the same against an Epic body as against a one-pager or a Story draft.
+The path-specific bindings for this advisory:
+
+- **`epic` verdict** → proceed silently to Phase 6. No extra prompt, no HITL
+  stop.
+- **`story` / `borderline` verdict** → **STOP** and present the three-way
+  choice, whose **Recommended** branch here is **convert to a standalone
+  Story** via the conversion path below. The alternative branches are
+  **proceed as Epic anyway** (continue to Phase 6 with the Epic unchanged) and
+  **abort** (the Epic is left exactly as it was; no labels move and nothing is
+  closed).
 
 ### Conversion path (close-and-recreate)
 
@@ -453,78 +409,15 @@ for the scoring logic.
 
 ## Phase 7: Epic Planning (Tech Spec & Acceptance Spec)
 
-> **Epic-lease preflight (workflow guard).** Before any Phase 7 mutation,
-> `epic-plan-spec.js` acquires the Epic-lease via the assignee-as-lease
-> primitive (`lib/orchestration/ticket-lease.js`, wired through
-> `lib/orchestration/epic-plan-lease-guard.js`). The lease rides the Epic's
-> single assignee: the operator (`github.operatorHandle` in `.agentrc.json`)
-> claims the Epic for the duration of the plan. The guard **fails closed**:
-> `/plan` emits no `story.heartbeat` during its run (heartbeats are a
-> delivery-time signal), so there is no live-heartbeat source to judge a
-> concurrent plan's liveness from. Any **foreign assignee** is therefore
-> treated as a live claim — the persist half **exits non-zero and names the
-> current owner**, so two `/plan` runs cannot drive the same Epic
-> concurrently. Pass **`--steal`** to forcibly transfer a foreign claim once
-> you have confirmed the other run is dead. An **unassigned** Epic, or one
-> **already held by this operator**, is taken (or re-affirmed) silently. The
-> lease is **released after Phase 8** (decompose) completes; see the Phase 8
-> note.
-
-<!-- separator: adjacent blockquotes -->
-
-> **Idempotent managed sections.** The persist half is section-scoped and
-> keyed on the Epic body: a re-run that finds the requested sections already
-> present (`<!-- mandrel:tech-spec:start/end -->` /
-> `<!-- mandrel:acceptance-table:start/end -->`) short-circuits as
-> `already-planned` instead of duplicating content. Pass `--force` to
-> overwrite the managed sections in place (same Epic issue, refreshed
-> section bodies).
-
-<!-- separator: adjacent blockquotes -->
-
-> **One planning document.** A `/plan` Epic run creates exactly **one**
-> issue — the Epic. The planning artifacts land as marker-delimited
-> managed sections of the Epic body: the Tech Spec (opening with
-> `## Delivery Slicing`) inside `<!-- mandrel:tech-spec:start/end -->`,
-> and the Acceptance Spec's AC-ID table (headed `## Acceptance Table`)
-> inside `<!-- mandrel:acceptance-table:start/end -->`. The PRD artifact
-> class was retired (Story #4314) — its one novel section, **User
-> Stories**, lives inline in the Epic body as a `## User Stories`
-> section — and Story #4324 retired the `context::tech-spec` /
-> `context::acceptance-spec` ticket classes the same way. The
-> `## Acceptance Table` section captures the stable-ID acceptance
-> criteria table (`| AC ID | Outcome | Feature File | Scenario |
-> Disposition |`) that drives close-time reconciliation during
-> `/deliver` Phase 6. Operators may opt out for refactor-only or
-> docs-only Epics by applying the `acceptance::n-a` label to the Epic
-> ticket — when present, the `epic-plan-spec-author` skill skips the
-> Acceptance Table output and the runtime gates (start gate, finalize
-> reconciler) honour the waiver — the section need not be authored when
-> the waiver is set. See [SDLC § Acceptance Table — the second folded
-> planning section](../../docs/SDLC.md#acceptance-table--the-second-folded-planning-section)
-> for the full lifecycle.
-
-<!-- separator: adjacent blockquotes -->
-
-> **Parallel-safe file naming (per-Epic tree).** Multiple Epics may be
-> planned or decomposed concurrently. Every temp file written in this
-> workflow lives under the per-Epic tree
-> (`temp/epic-[Epic_ID]/<artifact>`) — e.g.
-> `temp/epic-[Epic_ID]/planner-context.json`,
-> `temp/epic-[Epic_ID]/techspec.md`,
-> `temp/epic-[Epic_ID]/decomposer-context.json`,
-> `temp/epic-[Epic_ID]/tickets.json`. The directory namespace is the
-> isolation boundary; basenames inside it are stable. Do **not** reuse
-> bare flat names like `temp/techspec.md` or the legacy
-> `temp/<artifact>-epic-<id>.<ext>` shape — both have been retired.
->
-> **Durability.** The per-Epic tree is durable across runs: only the
-> wrapper scripts perform intra-phase cleanup of files they wrote in
-> the same invocation (see
-> [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js)).
-> Nothing else garbage-collects the tree, so cross-Epic artifacts —
-> retros, perf reports, signals, manifests — accumulate until an
-> operator explicitly removes them.
+> **Phase-7 guards & managed-section rationale (reference).** This phase runs
+> behind an **Epic-lease preflight** (`--steal` transfers a confirmed-dead
+> claim; the lease releases after Phase 8), writes **idempotent managed
+> sections** (`--force` overwrites them in place), lands **one planning
+> document** (Tech Spec + Acceptance Table folded into the Epic body;
+> `acceptance::n-a` waives the table), and namespaces every temp file under
+> the durable **per-Epic tree** (`temp/epic-[Epic_ID]/…`). The full rationale
+> for each guard is in
+> [`plan-epic-reference.md` § Phase 7 — background rationale](plan-epic-reference.md#phase-7--background-rationale).
 
 1. **Gather Authoring Context**: Run the spec-phase CLI in context-emission
    mode to fetch the Epic body, scraped project docs, and the recommended
@@ -883,6 +776,11 @@ node .agents/scripts/epic-plan-spec-validate.js \
      --tickets temp/epic-[Epic_ID]/tickets.json --force
    ```
 
+   > On a large Epic (~60+ tickets) the persist can trip GitHub's secondary
+   > rate limit mid-run. Resume from the partial backlog with `--resume` — the
+   > full recovery contract is in
+   > [`plan-epic-reference.md` § Phase 8 — `--resume` recovery (secondary rate limit)](plan-epic-reference.md#phase-8----resume-recovery-secondary-rate-limit).
+
 7. **Cross-Validation**:
    - Hierarchy completeness, dependency-DAG acyclicity, and `risk::high`
      labelling are deterministic invariants enforced by
@@ -1075,40 +973,12 @@ condition.
    node .agents/scripts/notify.js [Epic_ID] "Planning complete, review tickets. Backlog decomposition complete. Epic is ready for /deliver." --action
    ```
 
-## Troubleshooting
-
-- If `epic-plan-spec.js --emit-context` fails, confirm the Epic exists and
-  has a body with enough initial context.
-- If `epic-plan-decompose.js` rejects the tickets file, re-read the
-  validator's error message — the most common causes are a ticket whose
-  `type` is not `story`, a Story missing its inline `acceptance[]` /
-  `verify[]` contract, or a dependency cycle in the Story `depends_on`
-  graph.
-- If decomposition persisted the tickets but the Epic is not on `agent::ready`,
-  you likely called `runDecomposePhase` from `epic-plan-decompose.js`
-  directly without completing the persist flow — only the CLI surface
-  (`node epic-plan-decompose.js --tickets ...`) drives the full
-  reconciler pipeline and flips the lifecycle label. Apply `agent::ready`
-  by hand and re-run via the CLI next time.
-- **Secondary rate limit on large Epics**: For backlogs over ~60 tickets,
-  GitHub's secondary rate limit (HTTP 403, body contains "secondary rate
-  limit") can trip mid-decomposition after ~80 issue creations. The
-  http-client retries automatically with a 30–120s backoff and the
-  decomposer drops `concurrencyCap` to 1 for the rest of the run on the
-  first observation. If the run still aborts (network drop, exhausted
-  retries, etc.), resume from the partial backlog with:
-
-  ```bash
-  node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-    --tickets temp/epic-[Epic_ID]/tickets.json --resume
-  ```
+## Troubleshooting & recovery
+
+Troubleshooting symptoms (emit-context failures, tickets-file rejections, a
+decomposition that persisted but left the Epic off `agent::ready`) and the
+large-Epic **secondary-rate-limit `--resume`** recovery path live in the
+reference companion — they are consulted only when a run hits the edge:
 
-  `--resume` is idempotent: the reconciler recovers the slug→issue map
-  from `temp/epic-[Epic_ID]/[Epic_ID].state.json`, and when that file is
-  missing or incomplete it **reseeds the map from live GitHub state** by
-  matching each spec slug against the open children of the Epic by title.
-  Slugs that resolve to an existing open child diff as Updates/no-ops;
-  only the genuinely-missing children are created — the existing tree is
-  never duplicated. To force-throttle from the first call on a known-large
-  Epic, set `(framework constant: decomposer concurrency): 1` in
-  `.agentrc.json`.
+- [`plan-epic-reference.md` § Troubleshooting](plan-epic-reference.md#troubleshooting)
+- [`plan-epic-reference.md` § Phase 8 — `--resume` recovery (secondary rate limit)](plan-epic-reference.md#phase-8----resume-recovery-secondary-rate-limit)

package/.agents/workflows/helpers/plan-story.md

@@ -125,32 +125,31 @@ Write the draft to `temp/single-story-draft.md`.
 
 ### Scope-triage escalation gate (symmetric counterpart to `/plan` Phase 1.5)
 
-Once the draft body exists — and **only** then, because the seed alone is not
-an honest basis for a sizing judgment — run the
-[`core/scope-triage`](../../skills/core/scope-triage/SKILL.md) rubric over the
-**drafted Story body** to catch an Epic-sized scope before it is persisted as a
-standalone Story. This is the outbound mirror of `/plan` Phase 1.5's
-inbound downgrade gate: the two planning entry points route toward each other
-instead of each silently accepting wrong-sized work.
-
-**Skip the gate entirely when `/plan` was entered via a scope-triage
-handoff** — i.e. from `/plan` Phase 1.5 (the inbound route above) or the
-`/plan` Phase 5.5 existing-Epic conversion path. A handoff is a triage
-decision already made; re-running the rubric here would re-litigate a settled
-call and risk a ping-pong between the two workflows (the skill's no-re-triage
-rule).
-
-Otherwise, activate the skill **by reference** — read its `SKILL.md` via the
-`Read` tool and apply its rubric; do **not** restate its sizing thresholds or
-copy its verdict prose here. The skill anchors its sizing judgment to
-`DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING` in
-[`ticket-validator-sizing.js`](../../scripts/lib/orchestration/ticket-validator-sizing.js)
-and emits one verdict — `epic` | `story` | `borderline`. The verdict is
-host-LLM judgment: there is **no `--flag`**, no scorer, no schema, and no label
-transition behind it. (The `refine` heuristic in `story-plan.js` is unchanged —
-it is a deterministic seed-length proxy, not a scope-size judgment.) The verdict
-folds into the **existing** draft-confirmation HITL stop below — it does **not**
-add a second stop.
+This gate runs the shared scope-triage gate over the **drafted Story body** to
+catch an Epic-sized scope before it is persisted as a standalone Story — the
+outbound mirror of `/plan` Phase 1.5's inbound downgrade gate. The gate
+mechanics (verdict meanings, the three-way operator choice, the `--yes`
+resolution, and the no-re-triage rule) live in the single-homed fragment
+[`scope-triage-gate.md`](scope-triage-gate.md); read it and follow it. This
+phase supplies only its path-specific firing conditions:
+
+- **When it runs**: only **after the draft body exists** — the seed alone is
+  not an honest basis for a sizing judgment. The rubric is applied to the
+  **drafted Story body**, and the verdict folds into the **existing**
+  draft-confirmation HITL stop below (it does **not** add a second stop). (The
+  `refine` heuristic in `story-plan.js` is unchanged — it is a deterministic
+  seed-length proxy, not a scope-size judgment.)
+- **When it is skipped**: entirely, when `/plan` was entered via a scope-triage
+  handoff — from `/plan` Phase 1.5 (the inbound route above) or the `/plan`
+  Phase 5.5 existing-Epic conversion path (the no-re-triage rule in the
+  fragment).
+- **Recommended branch on an `epic` verdict**: escalate to `/plan --idea` —
+  persist the notes/draft to a notes file and hand off to `/plan --idea` (or
+  `--from-notes <path>`), identifying the invocation as a scope-triage handoff
+  so `/plan` skips its own Phase 1.5 gate, then **abandon the draft and exit
+  `/plan`** (no standalone Story is created). The alternative branches are
+  **persist as a standalone Story anyway** (proceed to Phase 3 with the draft
+  unchanged) and **abort**.
 
 ### HITL — operator confirms the draft (verdict folded in)
 
@@ -158,41 +157,12 @@ Display the draft to the operator and **STOP**. Do not call the persist phase
 until the operator explicitly confirms the draft. This mirrors the HITL gate
 `/plan` Phase 3 enforces before opening the Epic Issue. This is the
 story-path face of `/plan`'s **gate #1** (the ideation one-pager /
-scope-triage confirm). The scope-triage verdict folds into this same stop:
-
-> **`--yes` (headless) auto-proceed.** When `/plan` was invoked with `--yes`,
-> this gate does **not** STOP: the draft confirm resolves as **approved** and
-> the run proceeds to Phase 3 (persist). An `epic` verdict resolves to its
-> **Recommended** branch — escalate to `/plan --idea` (carrying `--yes`),
-> abandoning the draft — rather than prompting the three-way choice. Display
-> the draft and the verdict line for the record, then proceed without
-> waiting. See
-> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-
-- **`story` verdict (or gate skipped via handoff)** → no extra prompt. The
-  operator confirms the draft as usual and the run proceeds to Phase 3
-  (persist).
-- **`epic` verdict** (multiple independent capabilities, a plausible
-  sizing-ceiling breach, or a real dependency structure) → the confirmation
-  prompt presents a **three-way operator choice**:
-  - **Recommended: escalate to `/plan --idea`** (with the triage
-    rationale) — persist the notes/draft to a notes file and hand off to
-    `/plan --idea` (or `--from-notes <path>`), identifying the invocation
-    as a **scope-triage handoff** so `/plan` skips its own Phase 1.5 gate
-    (the skill's no-re-triage rule). Then **abandon the draft and exit
-    `/plan`** — no standalone Story is created.
-  - **Persist as a standalone Story anyway** — ignore the recommendation and
-    proceed to Phase 3 with the draft unchanged. Being wrong in the `epic`
-    direction is cheap to tolerate: if the operator persists an oversized Story,
-    the sizing validator and delivery reality push back later. The gate's value
-    is surfacing the recommendation while the scope is still free to change.
-  - **Abort** — stop planning entirely. No Issue is created.
-
-  **Never auto-route.** The verdict is advisory; the operator always decides,
-  and no `agent::*` / label transition happens on either side of the choice.
-  (**`--yes` exception:** headless mode pre-authorizes the **Recommended**
-  branch deterministically — see the `--yes` note above — the only sanctioned
-  auto-route, present solely to make `/plan` driveable without an operator.)
+scope-triage confirm). The scope-triage verdict folds into this same stop, per
+the branch bindings above; on a **`story` verdict (or gate skipped via
+handoff)** there is no extra prompt and the operator confirms the draft as
+usual. The `--yes` headless resolution of this stop is the fragment's — see
+[`scope-triage-gate.md` § `--yes` (headless) resolution](scope-triage-gate.md#--yes-headless-resolution)
+and [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
 
 ## Phase 3 — Persist (`gh issue create`)