mandrel 1.65.0 → 1.67.0

package/.agents/skills/core/epic-plan-premortem/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: epic-plan-premortem
+description: >-
+  Run a fresh-context, code-reading pre-mortem critic over the draft Story
+  ticket array an Epic's decompose phase produced. Use during Phase 8 of
+  `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write
+  `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
+  validates and persists it. Reads the PRD / Tech Spec AND the actual cited
+  code surfaces, then emits predicted-rework findings before any GitHub write.
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+---
+
+# epic-plan-premortem
+
+## Policy Capsule
+
+- Run only after a draft `temp/epic-<Epic_ID>/tickets.json` exists (authored by `epic-plan-decompose-author`, and consolidated by `epic-plan-consolidate` if that pass ran); fail loudly if the draft array is missing. Read the PRD / Tech Spec from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
+- **You MUST read the actual cited code surfaces.** For every Story, open the files named in its `changes[]` / `references[]` (resolve each path against the repo root; use `Read` / `Grep`) and read enough of each to judge whether the Story's `acceptance[]` is verifiable against the real code and whether its `changes[]` assumptions hold. This is the load-bearing difference between this critic and the structural file-assumption gate: that gate proves a path **exists** (or does not); this critic reads what the file actually **contains**. A pre-mortem that did not open the cited files has not run.
+- Emit exactly one artifact: a human-readable `temp/epic-<Epic_ID>/premortem-report.md` — the predicted-rework findings the operator reviews at the Phase 8 HITL diff. It MUST exist before returning.
+- **This critic never writes to GitHub and never persists `tickets.json`.** It is read-and-report only: it does NOT mutate the draft array, does NOT create issues, and does NOT flip any label. Re-authoring on its findings is the author skill's job (the workflow re-runs `epic-plan-decompose-author` on the report before the persist call).
+- **You are not scope-preserving.** Unlike `epic-plan-consolidate` (merge-and-rewire only), this critic MAY recommend splitting an under-specified Story, tightening or rewording an acceptance criterion, or flagging an over-specified Story — because it only *recommends* in a report; it never applies the change itself. The conservation invariant belongs to consolidation; this pass is deliberately a separate, additive-recommendation lens.
+- Hunt for the three predicted-rework finding classes the structural gates cannot catch: **(1) unverifiable acceptance criteria** (an AC no `verify[]` command or readable code state can prove); **(2) over- or under-specified Stories** (a Story whose `acceptance[]` is far broader or narrower than its `changes[]` footprint and the cited code support); **(3) semantically-wrong assumptions** (the cited file exists but does not contain the seam / export / shape the Story assumes — the file-assumption gate passes, the work would still rework).
+- Log only file/route/Story identifiers and short rationale in the report — never paste full source bodies, persona data, or secret material (per `rules/security-baseline.md` data-leakage MUSTs).
+
+## Role
+
+Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic**.
+This Skill is deliberately *separate* from `epic-plan-decompose-author` (the
+generator) and from `epic-plan-consolidate` (the scope-preserving merge critic):
+a same-pass self-critique is the weak mode this is built to escape. The
+generator maps PRD capabilities to Stories against the spec text; this critic
+opens the **actual cited code** and asks "if I tried to deliver this exact
+backlog, where would it rework?" — before any GitHub write makes the rework
+expensive.
+
+## When to use
+
+`/plan` Phase 8, as the **8.5 — Planning Pre-Mortem Critic** sub-step:
+after `epic-plan-decompose-author` writes (and, when present,
+`epic-plan-consolidate` consolidates) `temp/epic-<Epic_ID>/tickets.json`, after
+the reachability completeness critic (8.4), and **before**
+`epic-plan-decompose.js --tickets …` validates and persists. The pass operates
+on the temp artifact and emits a report so the operator sees predicted rework in
+the Phase 8 HITL diff before the GitHub write; the author re-runs on the
+findings and the deterministic validator runs *after*, so nothing this critic
+surfaces reaches GitHub unreviewed.
+
+## Inputs
+
+The workflow passes the Epic ID as the Skill argument. The Skill itself reads:
+
+- `temp/epic-<Epic_ID>/tickets.json` — the **draft** (or consolidated) Story
+  array. This is the pre-mortem subject.
+- `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope emitted
+  by `epic-plan-decompose.js --emit-context`. Read `prd.body` / `prd` and
+  `techSpec.body` / `techSpec` from it.
+- **The repository working tree** — the actual files each Story's `changes[]` /
+  `references[]` name. Resolve each path against the repo root and read it.
+
+## Outputs
+
+- `temp/epic-<Epic_ID>/premortem-report.md` — a human-readable findings report.
+  Each finding names its Story, the cited surface it read, the finding class
+  (unverifiable-AC / over-or-under-specified / wrong-assumption), a one-line
+  rationale grounded in what the file actually contains, and a recommended
+  re-authoring action. End with a one-line verdict
+  (`findings: N` / `findings: 0 — no predicted rework`).
+
+This file MUST exist before the Skill returns. The Skill writes **no** other
+artifact and mutates **no** GitHub state.
+
+## Procedure
+
+### Step 1 — Load the draft and the spec
+
+Read `temp/epic-<Epic_ID>/tickets.json` (the Story array) and
+`temp/epic-<Epic_ID>/decomposer-context.json` (for the PRD / Tech Spec). If the
+draft array is missing, fail loudly and instruct the caller to run the
+`epic-plan-decompose-author` Skill first.
+
+### Step 2 — Read the cited code surfaces
+
+For each Story, collect the paths in its `changes[]` and `references[]`. For
+each path that exists in the working tree, `Read` it (or `Grep` for the specific
+export / seam the Story assumes when the file is large). Build, per Story, a
+short note of what the cited code actually contains versus what the Story's
+`acceptance[]` / `changes[]` assume.
+
+### Step 3 — Hunt the three finding classes
+
+Across the backlog, surface predicted rework:
+
+- **Unverifiable AC** — an acceptance item nothing in `verify[]` (or readable
+  code state) can prove. Recommend a concrete verify command or a reworded,
+  checkable AC.
+- **Over- / under-specified Story** — `acceptance[]` materially broader or
+  narrower than the `changes[]` footprint and the cited code support. Recommend
+  a split (under-specified one Story doing the work of several) or a tightening.
+- **Semantically-wrong assumption** — the cited file exists (so the
+  file-assumption gate passes) but does not contain the seam, export, function,
+  or data shape the Story assumes. Recommend the corrected target or an explicit
+  "create the seam first" Story.
+
+Record each finding with its Story, cited surface, class, rationale, and
+recommended action.
+
+### Step 4 — Write the report
+
+Write all findings to `temp/epic-<Epic_ID>/premortem-report.md` with the verdict
+line. Paste identifiers and short rationale only — never full source bodies.
+
+### Step 5 — Hand back to `/plan`
+
+Return control. The workflow shows the operator the pre-mortem report at the
+Phase 8 HITL diff; on operator approval it re-runs
+`epic-plan-decompose-author` on the findings **before** the persist call
+(`node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
+temp/epic-<Epic_ID>/tickets.json`). This Skill itself persists nothing.
+
+## Constraints
+
+- Do **not** call the GitHub API from this Skill. It reads temp artifacts plus
+  the working tree and writes one temp report; persistence belongs to the
+  script, re-authoring belongs to `epic-plan-decompose-author`.
+- Do **not** write outside `temp/epic-<Epic_ID>/`, and do **not** mutate
+  `temp/epic-<Epic_ID>/tickets.json` — this critic is report-only.
+- Do **not** log full source bodies, persona data, or secrets into the report
+  (per `rules/security-baseline.md`). Identifiers and short rationale only.
+- If `temp/epic-<Epic_ID>/tickets.json` is missing, fail loudly and instruct the
+  caller to run the `epic-plan-decompose-author` Skill first.
+- The validator
+  ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
+  remains the authoritative post-re-author gate. This critic surfaces
+  *semantic* rework the structural validator cannot — it does not replace it.

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -72,6 +72,21 @@ reads:
     `codebaseSnapshot.files`, surface that as a `<!-- DRIFT -->` callout
     in the Tech Spec body naming the cited path, so the freshness gate
     (Story #2635) has prose context for the operator to read.
+    - `codebaseSnapshot.grounding` (Story #4139) — operator-visible
+      grounding signals derived before you author:
+      - `grounding.truncation` — non-null when the snapshot dropped files
+        (the skinny-tier cap kept only the first ~250 of N matched files).
+        Carries `{ dropped, matched, shown, tier, remedies[] }`. When it is
+        present, the file tree you see is **partial** — do not assume a
+        module is absent just because it is missing from
+        `codebaseSnapshot.files`; raise the partiality in a `<!-- DRIFT -->`
+        callout and prefer the `medium` tier (or a narrowed `include`) for
+        a grounded spec.
+      - `grounding.citedButAbsent[]` — paths the Epic body already cites
+        that are **not** in the snapshot and are not phrased as net-new.
+        Treat each as a likely drift signal: confirm the path exists (it may
+        have been dropped by truncation) or mark it net-new explicitly in
+        the spec so the post-author freshness gate does not flag it.
   - `systemPrompts.prd`, `systemPrompts.techSpec`, and
     `systemPrompts.acceptanceSpec` — left in the envelope as a backstop;
     this Skill's own body below carries the authoritative versions and is

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-11T19:47:29.752Z",
+  "generatedAt": "2026-06-15T13:34:12.163Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -138,10 +138,20 @@
       "category": "core",
       "path": ".agents/skills/core/epic-plan-decompose-author/SKILL.md",
       "description": "Author the Story ticket JSON for an Epic from the decomposer authoring context emitted by `epic-plan-decompose.js --emit-context`. Use during Phase 8 of `/plan` when the host LLM needs to write the ticket array before `epic-plan-decompose.js` validates and persists it.",
-      "policyCapsuleBullets": 12,
+      "policyCapsuleBullets": 14,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
+    {
+      "name": "epic-plan-premortem",
+      "tier": "core",
+      "category": "core",
+      "path": ".agents/skills/core/epic-plan-premortem/SKILL.md",
+      "description": "Run a fresh-context, code-reading pre-mortem critic over the draft Story ticket array an Epic's decompose phase produced. Use during Phase 8 of `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js` validates and persists it. Reads the PRD / Tech Spec AND the actual cited code surfaces, then emits predicted-rework findings before any GitHub write.",
+      "policyCapsuleBullets": 7,
+      "allowedTools": ["Read", "Write", "Bash", "Grep"],
+      "vendor": null
+    },
     {
       "name": "epic-plan-spec-author",
       "tier": "core",

package/.agents/workflows/audit-navigability.md

@@ -0,0 +1,129 @@
+---
+description: >-
+  Audit the whole route tree against the consumer's nav-registry SSOT —
+  every route has a persona nav door and no nav href is dead. A
+  deliberately-global lens (Epic #4131, F2/F3) exempt from the
+  cross-epic-leak guard and routed onto route-adding change sets.
+---
+
+# Navigability Audit
+
+## Role
+
+Information-Architecture Reviewer & Frontend Navigation Auditor
+
+## Context & Objective
+
+Evaluate the application's **navigability**: the property that every route a
+persona is entitled to reach has a real navigation door (a menu item, link, or
+button rendered in that persona's authenticated shell), and that every nav door
+points at a route that actually exists. The two failure modes this lens names
+are symmetric:
+
+- **Orphaned route** — a route is registered in the route tree but no
+  nav-registry entry surfaces it for any persona. The feature ships but is
+  unreachable through the product; only a hardcoded deep-link reaches it.
+- **Dead nav href** — a nav-registry entry points at a route (or path) that
+  does not exist in the route tree. The door is rendered but leads nowhere.
+
+This is **mechanism, not content**: the lens reads the consumer's
+configured route tree and nav-registry SSOT (see _Configuration_) and is a
+**silent no-op when neither is configured**. Mandrel ships the slot and the
+wiring; it never ships a specific consumer's route data or nav registry.
+
+## Whole-route-tree scope (global lens — leak-guard-exempt)
+
+Unlike the change-set-scoped lenses, this lens **always evaluates the whole
+route tree + the whole nav registry**, even when the change that triggered it
+touched only one route file. Reachability is a global property: adding one
+route can orphan it, but removing or renaming a route elsewhere can also break
+a nav href that the change set never touched.
+
+Because of this, the navigability lens is registered in the **global-lens
+allowlist** (`GLOBAL_LENS_ALLOWLIST` in
+[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js)) and is
+**exempt from the cross-epic-leak guard** (`#3362`) that narrows every other
+lens's evidence to the Epic's `changedFiles`. The exemption is scoped to this
+lens only — the guard is **not** weakened for any other lens, and the
+exemption never lets a foreign Epic's change set leak into a scoped lens.
+
+```text
+{{changedFiles}}
+```
+
+- For this lens, **ignore** the `{{changedFiles}}` block above even when it is
+  populated: navigability is evaluated codebase-wide regardless. The block is
+  rendered only for envelope-shape parity with the scoped lenses.
+
+## Configuration
+
+Read the consumer's navigability config (resolved from `.agentrc.json`):
+
+- `delivery.quality.navigability.routeGlobs` — globs identifying the
+  route-adding files / route tree (e.g. `pages/**`, `app/**/route.ts`). Drives
+  both the route-tree enumeration here and the route-added routing in
+  [`epic-audit-prepare.js`](../scripts/epic-audit-prepare.js).
+- `delivery.quality.navigability.navRegistry` — path(s) to the consumer's
+  nav-registry SSOT this lens reads.
+
+If **neither** `routeGlobs` nor `navRegistry` is present, emit a one-line
+"navigability not configured — skipped" note and exit without findings. Do
+**not** invent a route tree or guess a nav registry.
+
+## Step 1: Enumerate the route tree
+
+Enumerate every route from the files matched by `routeGlobs`. Record each
+route's path and the persona(s) entitled to reach it (from route metadata,
+guards, or the consumer's documented persona model). Log route **identifiers
+only** — never the full route body or any persona PII.
+
+## Step 2: Enumerate the nav registry
+
+Read every nav door from the `navRegistry` SSOT. Record each door's target
+path and the persona shell it renders in.
+
+## Step 3: Cross-check (the two invariants)
+
+1. **Every route has a persona nav door.** For each enumerated route, assert at
+   least one nav-registry entry surfaces it for an entitled persona. A route
+   with no door for any of its personas is an **orphaned route**.
+2. **No nav href is dead.** For each nav door, assert its target resolves to a
+   real route in the route tree. A door whose target is absent is a **dead nav
+   href**.
+
+## Step 4: Output Requirements
+
+Generate and save a structured Markdown audit report to
+`{{auditOutputDir}}/audit-navigability-results.md`, using the template below.
+
+```markdown
+# Navigability Audit report
+
+## Executive Summary
+
+[Reachability health (Score 1-10): count of orphaned routes and dead hrefs.]
+
+## Detailed Findings
+
+[For every orphaned route or dead nav href, use the following strict
+structure:]
+
+### [Short Title of the Issue]
+
+- **Dimension:** [Orphaned Route | Dead Nav Href]
+- **Impact:** [High | Medium | Low]
+- **Route / Door:** [the route path or nav-door identifier — identifier only]
+- **Persona(s):** [the persona(s) affected]
+- **Current State:** [why the route is unreachable or the href is dead]
+- **Recommendation & Rationale:** [the nav-registry change that restores
+  reachability — add a door for the orphaned route, or fix/remove the dead
+  href]
+- **Agent Prompt:**
+  `[A copy-pasteable, specific prompt to execute the nav-registry fix.]`
+```
+
+## Constraint
+
+This is a **read-only** audit. Provide the critique and the nav-registry fixes,
+but do not modify the route tree or the nav registry. Log route and door
+identifiers only — never full route bodies, source contents, or persona data.

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

@@ -31,6 +31,7 @@ back to the operator-merges-button path.
   → Phase 4 — epic-audit           (helpers/epic-audit.md — change-set audits via selectAudits)
   → Phase 5 — code-review          (helpers/code-review.md with scope: epic)
   → Phase 6 — retro                (.agents/scripts/lib/orchestration/retro-runner.js)
+  → Phase 6.5 — integration gate   (whole-product navigability + journey suite; @pending ≠ green for surface-adding Epics — blocks finalize)
   → Phase 7 — finalize             (lifecycle-emit → epic.close.end → open PR to main)
   → Phase 8 — watch-and-iterate    (poll `gh pr checks`; fix locally until green)
   → Phase 8.5 — auto-merge gate    (lifecycle-emit → epic.automerge.start)
@@ -52,7 +53,7 @@ spawned.
 ## Arguments
 
 ```text
-/deliver <epicId> [--skip-epic-audit] [--skip-code-review] [--skip-retro] [--full-retro]
+/deliver <epicId> [--skip-epic-audit] [--skip-code-review] [--skip-retro] [--full-retro] [--skip-integration-gate]
 ```
 
 - `epicId` — must carry `type::epic`. Otherwise STOP and tell the operator
@@ -63,6 +64,12 @@ spawned.
 - `--skip-retro` — skip Phase 6 (use sparingly).
 - `--full-retro` — force the six-section retro regardless of manifest
   cleanliness. `--skip-retro` wins over `--full-retro`.
+- `--skip-integration-gate` — skip Phase 6.5 (log the override). The
+  explicit operator override for the post-wave integration gate, consistent
+  with `--skip-epic-audit`. Use only when the deliberately-global checks are
+  known to be irrelevant for this Epic (e.g., a docs-only Epic that adds no
+  surface). Skipping the gate is recorded as a manual intervention and
+  disqualifies auto-merge, exactly like the other `--skip-*` overrides.
 
 Every other runtime modifier is sourced from the Epic's labels or from
 `delivery.deliverRunner` in `.agentrc.json`.
@@ -556,6 +563,109 @@ and never fails the phase.
 
 ---
 
+## Phase 6.5 — Post-wave integration gate (Epic #4131, F1/F4)
+
+This phase runs **after** the Phase 2 wave loop reports `epic-complete` and
+**before** the Phase 7 finalize emit opens the PR to `main`. Where every gate
+before it (`selectAudits`, the cross-epic-leak guard `#3362`, diff-against-base,
+the file-assumption gate) is **change-set-scoped** — it narrows its evidence to
+the Epic's `changedFiles` — this is the one **deliberately-global** gate: its
+evidence spans the **whole product**, not just the change set. The disease it
+catches is the surface that each Story shipped correctly in isolation yet that
+the assembled product cannot reach: a route nobody can navigate to, or a
+persona journey that the integrated waves silently broke. A change-set lens
+never sees that, because no single Story's diff contains the orphan.
+
+Skip when `--skip-integration-gate` (log the override; record a manual
+intervention per [§ Recording manual interventions](#recording-manual-interventions)).
+The gate is otherwise **always evaluated**, but it is a **silent no-op when
+unconfigured** (see *No-op when unconfigured* below) so consumers who ship no
+nav config and no journey suite are unaffected.
+
+### 6.5a — Whole-product navigability (reuses the Phase 4 lens)
+
+Run the `navigability` lens
+([`audit-navigability.md`](../audit-navigability.md), the deliberately-global
+lens delivered in this Epic's wave 0) in **whole-route mode** against the
+integrated `epic/<epicId>` tip. Unlike its Phase 4 change-set-routed invocation,
+here it is driven explicitly over the consumer's **entire** route tree + nav
+registry — it is on the global-lens allowlist (`GLOBAL_LENS_ALLOWLIST` in
+[`lib/audit-suite/selector.js`](../../scripts/lib/audit-suite/selector.js)) and
+exempt from the cross-epic-leak guard `#3362`, so a route orphaned anywhere in
+the product is in scope even when no Story in this Epic touched it.
+
+The lens reads the consumer's navigability config (resolved from `.agentrc.json`):
+
+- `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the lens
+  enumerates.
+- `delivery.quality.navigability.navRegistry` — the nav-registry SSOT the lens
+  cross-checks every route against.
+
+A whole-product finding is a **hard failure**: an **orphaned route** (a route
+with no nav door for any entitled persona) or a **dead nav href** (a nav door
+pointing at a route that no longer exists). On a hard failure the gate **blocks
+finalize** and names the orphaned surface (route identifier / nav-door
+identifier only — never the route body or persona PII, per
+`security-baseline.md`). Do **not** proceed to Phase 7.
+
+### 6.5b — Consumer journey suite
+
+Run the consumer's per-persona journey suite — the integrated, cross-Epic
+persona-journey verification — over the `epic/<epicId>` tip:
+
+- `delivery.quality.navigability.journeySuite` — path/command for the journey
+  suite. Absent ⇒ this sub-step is skipped (no-op).
+
+A failing journey (a persona cannot complete an end-to-end journey through the
+assembled product) is a **hard failure**: block finalize and name the broken
+journey. This is the runtime complement to 6.5a's static reachability check —
+6.5a proves a door exists; the journey suite proves the door, and everything
+behind it, actually works when the waves are integrated.
+
+### 6.5c — `@pending` ≠ green for surface-adding Epics (F4)
+
+The Phase 7 finalize chain runs the acceptance-spec reconciler
+([`acceptance-spec-reconciler.js`](../../scripts/acceptance-spec-reconciler.js)),
+which classifies every AC ID into `satisfied` (covered by a non-pending
+scenario), `pending` (covered **only** by scenarios tagged `@pending`), or
+`missing`. For a **surface-adding Epic** — one whose risk verdict carries a
+surface-adding signal (a route-adding change set, the `navigability` lens routed
+in Phase 4, or a configured `routeGlobs` match) — this phase tightens that
+contract: an AC whose coverage is **only `@pending`** is treated as
+**unsatisfied**, not green. A surface-adding Epic whose acceptance coverage is
+**only `@pending`** therefore **fails the close gate** instead of passing —
+shipping a new surface behind a deferred-forever `@pending` scenario is exactly
+the late-gate gap this Epic exists to close.
+
+This is **purely additive** and **scoped to surface-adding Epics**:
+refactor-only and docs-only Epics (no surface-adding signal) are **unaffected** —
+their `@pending` handling is exactly as before, and the existing
+`satisfied` / `missing` reconciliation is **not** de-scoped for any Epic.
+
+### No-op when unconfigured
+
+With **no** navigability config (`routeGlobs` / `navRegistry`) and **no**
+`journeySuite` present in `.agentrc.json`, this entire phase degrades to a
+**silent no-op**: 6.5a and 6.5b skip (nothing to enumerate or run) and 6.5c's
+surface-adding signal cannot fire without route globs, so the `@pending`
+tightening never engages. The gate adds **zero** behaviour to an unconfigured
+consumer — it neither blocks finalize nor changes the existing change-set-scoped
+gates. The override flag `--skip-integration-gate` is the explicit operator
+escape hatch (consistent with `--skip-epic-audit`) for a configured consumer who
+wants to bypass the gate for a specific run.
+
+### Fail safe and loud
+
+Per the Tech Spec's security note, this gate sits on the **critical path** to
+finalize. It MUST fail **safe and loud**: a hard failure **blocks** finalize and
+**names the cause** (the orphaned route, dead href, broken journey, or
+`@pending`-only AC), never silently passes. A genuinely unconfigured consumer is
+the **only** silent path, and that path **passes** (it is a no-op, not a block).
+On a hard failure, post a friction structured comment naming the surface, flip
+the Epic to `agent::blocked`, and park for the operator — do **not** open the PR.
+
+---
+
 ## Phase 7 — Finalize (open PR to main)
 
 ### 7.0 — Sync Epic branch from `main` (Story #2580)
@@ -859,6 +969,11 @@ the `epic-run-progress` structured comment.
   outcome.
 - **Always** auto-invoke the epic-audit, code-review, and retro helpers
   (Phases 4–6) when their artefacts aren't already present.
+- **Always** run the Phase 6.5 integration gate after the wave loop
+  reports `epic-complete` and before Phase 7 finalize (unless
+  `--skip-integration-gate`); **never** open the PR while the gate
+  reports a hard failure (orphaned surface, dead nav href, broken
+  journey, or a surface-adding Epic with only `@pending` AC coverage).
 - **Always** drive Phase 8 to green CI before returning control — the
   host LLM owns the loop until the PR is mergeable or the Epic is
   parked at `agent::blocked`.

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

@@ -743,7 +743,7 @@ node .agents/scripts/epic-plan-spec-validate.js \
    `depends_on`** — and it MUST NOT add scope or invent tickets; it
    consolidates fragmented slices by merging them into a cohesive Story,
    never by splitting one. It runs **before** the deterministic
-   validator (step 4), so the validator re-checks its output and the critic
+   validator (step 7), so the validator re-checks its output and the critic
    cannot emit an invalid plan.
 
    **Show the operator the consolidation report (the before/after diff +
@@ -752,7 +752,62 @@ node .agents/scripts/epic-plan-spec-validate.js \
    rejection, persist the draft instead. This is a sub-step of Phase 8 — it
    does **not** renumber the top-level lifecycle phases (9–12).
 
-4. **Persist to GitHub**: Run the decompose CLI's persist half. It
+4. **Phase 8.4 — Reachability Completeness Critic (HITL diff gate, F6)**:
+   After consolidation (8.3) and **before** the persist call below, run the
+   completeness critic. This is a **distinct pass** from
+   [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
+   and **must NOT relax** that skill's scope-preserving conservation invariant:
+   the consolidate critic is merge-and-rewire-only (it MUST NOT add scope or
+   invent tickets), whereas this critic is permitted exactly one **additive**
+   operation — appending a **single reachability Story** when, and only when, an
+   Epic introduces a user-facing surface (a new route/page) that **no Story
+   gives a navigation owner** (no nav-registry entry, no menu/link door from an
+   authenticated home). The two passes are deliberately separate so the
+   conservation invariant stays intact: consolidation never adds, and this
+   critic's only addition is the reachability Story.
+
+   - **Detection.** Scan the consolidated `tickets.json` for Stories that add a
+     route-shaped surface (paths under the consumer-configured
+     `planning.navigation.routeGlobs`, mirroring the
+     `epic-plan-healthcheck.js --paranoid` reachability check, F7). For each
+     such surface, confirm some Story's `acceptance[]` / `changes[]` references
+     the consumer's nav-registry SSOT (`planning.navigation.navRegistry`). A
+     surface with **no** nav owner is an orphan.
+   - **Action.** When at least one orphan surface exists, append **one**
+     reachability Story whose `acceptance[]` requires the orphaned surface to be
+     reachable by navigation from the relevant persona's authenticated home
+     (never by deep-link), and wire its `depends_on` to the surface-adding
+     Story. Append **at most one** reachability Story per decompose run — batch
+     every orphan under it — so the critic never fans out a parallel backlog.
+   - **No-op when unconfigured.** With no `planning.navigation` config present,
+     the critic degrades to a silent no-op (it cannot identify route-shaped
+     surfaces or a nav registry), exactly like the F7 healthcheck flag.
+   - **HITL.** The added Story is surfaced in the **same Phase 8 HITL diff** as
+     consolidation, **before** any GitHub write — never auto-persisted. On
+     operator rejection, drop the added Story and persist without it. The
+     deterministic validator (step 7) re-checks the critic's output, so an
+     invalid addition cannot reach GitHub.
+
+5. **Phase 8.5 — Planning Pre-Mortem Critic (code-reading, F9)**: After the
+   reachability critic (8.4) and **before** the persist call below, activate the
+   [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
+   skill with `[Epic_ID]` as input. This is a **fresh-context critic** sibling
+   to `epic-plan-consolidate`: it reads the drafted `tickets.json`, the PRD /
+   Tech Spec, **and the actual cited code surfaces** (the files each Story's
+   `changes[]` / `references[]` name), then emits predicted-rework findings —
+   unverifiable acceptance criteria, over- or under-specified Stories, and
+   semantically-wrong assumptions the structural file-assumption gate (step 7)
+   cannot catch — to `temp/epic-[Epic_ID]/premortem-report.md`.
+
+   Unlike the consolidate critic it is **not** scope-preserving-only: it may
+   recommend splitting an under-specified Story or tightening an AC. But it
+   **never writes to GitHub** and never persists `tickets.json` — it only emits
+   the report. Its findings are shown in the **same Phase 8 HITL diff**, and on
+   operator approval the author re-runs (Step 2) on the findings **before** the
+   persist call. The critic runs **before** the deterministic validator (step
+   7), so the persist below is the single GitHub write for the whole phase.
+
+6. **Persist to GitHub**: Run the decompose CLI's persist half. It
    validates the ticket array (`validateAndNormalizeTickets`), creates
    the Story issues, flips the Epic to `agent::ready`, and
    writes the `epic-plan-state` checkpoint.
@@ -767,7 +822,7 @@ node .agents/scripts/epic-plan-spec-validate.js \
      --tickets temp/epic-[Epic_ID]/tickets.json --force
    ```
 
-5. **Cross-Validation**:
+7. **Cross-Validation**:
    - Hierarchy completeness, dependency-DAG acyclicity, and `risk::high`
      labelling are deterministic invariants enforced by
      `validateAndNormalizeTickets` in
@@ -808,11 +863,11 @@ node .agents/scripts/epic-plan-spec-validate.js \
        --force
      ```
 
-6. **Audit**:
+8. **Audit**:
    - Check the Epic's comment thread to ensure the backlog summary was posted.
    - Verify that at least one `type::story` issue was created.
 
-7. **Cleanup**: The wrapper script (`epic-plan-decompose.js`) deletes the
+9. **Cleanup**: The wrapper script (`epic-plan-decompose.js`) deletes the
    Phase 8 temp files automatically on success — no operator action required.
    The cleanup contract lives in
    [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js).