mandrel 2.40.0 → 2.41.0

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: qa-harness
 description:
-  Conventions for the agent-driven QA harness that drives Gherkin scenarios
-  through a real browser. Use when executing `/qa-run` or instrumenting
-  a live surface — covers navigation-first execution, per-surface console and
-  network capture, design-token visual checks, and the framework-generic
-  heuristic cards for turning signal into findings. The harness procedure lives
-  in `.agents/workflows/qa-run.md`; this skill is the conventions
-  reference it leans on.
+  Conventions for agent-driven QA driving — the one driving-conventions
+  reference behind both `/qa-run` (the known-scenario sweep through a real
+  browser) and `/qa-explore` (agent-led exploratory driving). Use when
+  instrumenting a live surface — covers navigation-first execution,
+  per-surface console and network capture, design-token visual checks, the
+  `F#` finding shape, per-environment resolution, and static driving as the
+  documented interim. The run procedures live in `.agents/workflows/qa-run.md`
+  and `.agents/workflows/qa-explore.md`; this skill is the conventions
+  reference they lean on.
 ---
 
 # Skill: qa-harness
@@ -15,47 +17,110 @@ description:
 ## Policy Capsule
 
 - Driving rules (navigation-first, semantic `Then`, mandatory redaction, sequential-only) live in one prose home — [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md); apply them, do not restate them.
+- Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
+- Resolve the target **environment** before driving (via `resolveQaEnvironment`); each environment keys its own `baseUrl`, `signInSeam`, and `allowWrites`, and its name is recorded on the ledger.
+- Sign in only through the resolved `signInSeam` (`kind: 'url'` dev impersonation or `kind: 'skill'` with a stored `credentialRef`). **Never** type real credentials inline and never fabricate a session.
+- Hold the read-only capture invariant absolutely: no source edits, no product mutations — the only write is appending to the `temp/qa/<sessionId>` ledger.
+- Scrub captured console, network, and headers of tokens, session cookies, and PII before any finding reaches disk or GitHub; findings are posted to GitHub at approval time.
 - Capture console and network per surface; turn each non-allowlisted console error and each failed/error-status request into one structured `F#` finding.
 - Filter console through `qa.consoleAllowlist` via `filterConsoleMessages`; treat the allowlist as a benign-noise filter, never as a security control to silence genuine errors.
 - Spot-check surfaces against `qa.designTokens` when set; flag gross token violations (off-palette colors, off-scale spacing/typography) as findings.
-- Scrub captured console and network of tokens, session cookies, and PII before rendering any finding — findings are posted to GitHub at approval time.
-- Record findings as `QaLedgerItem`s and route them through the shared classify/route/promote core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md)); the harness never files tickets autonomously.
-- Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
-
-Guidance for executing the agent-driven QA harness through a real browser (the
-chrome-devtools MCP surface). The harness **procedure** — argument parsing,
-step ordering, contract resolution sequence — is the SSOT in
-[`.agents/workflows/qa-run.md`](../../../../workflows/qa-run.md);
-this skill shows **how** to apply the instrumentation and inspection
-conventions that procedure depends on. The assertion-tier rules it enforces
-live in [`testing-standards.md`](../../../../rules/testing-standards.md)
+- Choose **static driving** only at Plan time and only where no seam resolves — the documented interim, never a silent fallback — and record the partial coverage.
+- Record findings as `QaLedgerItem`s and route them through the shared classify/route/promote core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md)); the harness never files tickets autonomously, and every phase transition is HITL-gated.
+
+Guidance for driving a live surface through a real browser (the chrome-devtools
+MCP surface). Two workflows lean on this one skill: the **known-scenario
+sweep** ([`qa-run.md`](../../../../workflows/qa-run.md)) walks a resolved
+Gherkin scenario set, and **exploratory driving**
+([`qa-explore.md`](../../../../workflows/qa-explore.md)) walks a named surface
+the agent has no script for. Each **procedure** — argument parsing, phase
+gates, contract resolution sequence — is the SSOT in its own workflow; this
+skill shows **how** to apply the driving and instrumentation conventions both
+depend on. Assertion-tier rules live in
+[`testing-standards.md`](../../../../rules/testing-standards.md)
 (§ Assertion Placement); scenario prose conventions live in
 [`gherkin-authoring`](../gherkin-authoring/SKILL.md); browser-locator
-discipline is shared with [`playwright`](../playwright/SKILL.md). Read this
-skill before instrumenting a live surface; read the workflow for the run order.
+discipline is shared with [`playwright`](../playwright/SKILL.md); browser
+instrumentation lives in
+[`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
+Read this skill before instrumenting a live surface; read the workflow for the
+run order.
 
 ## 1. Driving Rules Live in One Prose Home
 
-The driving rules the harness depends on — **navigation-first / never URL-jump**,
-**semantic `Then` assertion** against the accessibility snapshot, the Gherkin →
-browser-action mapping, the per-`When` write guard, mandatory evidence
-redaction, and the **sequential-only** browser rule — are stated once in
-[`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md), the
-single-scenario driver `/qa-run` delegates to. Apply them from there; this skill
-does not restate them. In short: reach every surface the way a real user would
-(start at a root, click affordances, never deep-link a `Given`), assert `Then`
-semantically (roles, accessible names, visible text — never DOM/CSS/XPath
-selectors, HTTP status, response bodies, or DB rows), and record each scenario's
-result (pass / fail / blocked), the surface it ended on, and a one-line symptom
-for any failure. Assertion-tier rules are in
+The driving rules both modes depend on — **navigation-first / never
+URL-jump**, **semantic `Then`** assertion against the accessibility snapshot,
+the Gherkin → browser-action mapping, the per-`When` write guard, mandatory
+evidence redaction, and the **sequential-only** browser rule — are stated once
+in [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
+Apply them from there; this skill does not restate them. In short: reach every
+surface the way a real user would (start at a root, click affordances, never
+deep-link a starting state), assert semantically (roles, accessible names,
+visible text — never DOM/CSS/XPath selectors, HTTP status, response bodies, or
+DB rows), and treat broken navigation — a missing affordance, a nav 404, a
+guard redirect loop — as a **finding, not a workaround**. Assertion-tier rules
+are in
 [`testing-standards.md` § Assertion Placement](../../../../rules/testing-standards.md#assertion-placement).
 
-## 2. Per-Surface Console & Network Capture
+## 2. The Read-Only Capture Invariant
+
+Capture is **strictly read-only** in both modes. This invariant is inviolable
+per [`security-baseline.md`](../../../../rules/security-baseline.md) — it is
+not a soft preference.
+
+- **No source edits.** The agent does not modify application code, config, or
+  tests while driving. Driving observes; it never repairs.
+- **No product mutations.** No creating, updating, or deleting product data, no
+  destructive form submissions, no irreversible actions "to see what happens".
+  When a surface's only path forward is a mutating action, record the boundary
+  as the finding and stop — do not cross it.
+- **The only write is the ledger.** The single permitted side effect is
+  appending finding lines under `temp/qa/<sessionId>`.
+- **Scrub before persisting.** Strip tokens, session cookies, `Authorization`
+  headers, and PII from captured console and network evidence via the shared
+  redaction path **before** any finding reaches disk or GitHub. Captured
+  evidence is untrusted until scrubbed.
+- **HITL gates every write outward.** Phase transitions and GitHub writes
+  (ticket creation, promotion) happen only behind an operator confirmation
+  gate; the agent never files or promotes findings autonomously.
+
+## 3. Contract, Environment & Sign-In
 
-Instrument each surface the moment you land on it, before moving on. Capture is
-**per surface** so evidence is attributable to a concrete user-reachable state.
+- **Resolve the `qa` contract first.** Before any browser work, resolve the
+  contract via `resolveQaContract(config)`. When the block is absent,
+  malformed, or missing a required field, the resolver **throws** — relay its
+  verbatim message and STOP. There is no auto-detection fallback.
+- **Resolve the environment.** `resolveQaEnvironment` keys each deployment
+  target to `{ name, baseUrl, signInSeam, allowWrites }`. Where the operator's
+  input does not pin an unambiguous target and the contract declares more than
+  one environment, prompt (or accept `defaultEnvironment`) — never silently
+  pick one. Record the resolved name on the ledger.
+- **Sign in through the seam, never inline.** The two seam kinds:
+  - **`kind: 'url'` (dev impersonation).** Substitute the persona **name** into
+    the seam's URL template and navigate there. The persona name is the sole
+    input; no per-persona auth material is read.
+  - **`kind: 'skill'` (procedural / credential).** Invoke the named consumer
+    sign-in skill, which reads a per-persona **`credentialRef`** — an indirect
+    handle to a stored credential, never an inline secret. Read that skill's
+    `SKILL.md` and follow it.
+
+  The agent MUST NOT type real usernames, passwords, or tokens, and MUST NOT
+  fabricate or forge a session. This is a hard security boundary, not a
+  convenience to work around. Confirm authenticated state with a
+  `take_snapshot` before driving.
+- **No headless fallback.** The chrome-devtools MCP surface is a host-provided
+  runtime dependency. If it is unavailable, degrade with a clear error and stop
+  — never fall back to the retired headless BDD runner.
 
-### 2.1 Console
+## 4. Mode — Known-Scenario Sweep (`/qa-run`)
+
+The sweep drives a resolved scenario set and instruments each surface the
+moment it lands on it, before moving on. Capture is **per surface** so evidence
+is attributable to a concrete user-reachable state. Record each scenario's
+result (pass / fail / blocked), the surface it ended on, and a one-line symptom
+for any failure.
+
+### 4.1 Console
 
 1. Capture with `list_console_messages` on the current surface.
 2. Filter through the contract's `consoleAllowlist` using
@@ -75,13 +140,13 @@ Allowlist matching is case-sensitive substring matching, so patterns stay
 readable in `.agentrc.json` without regex escaping; a blank pattern is ignored
 rather than matching everything.
 
-### 2.2 Network
+### 4.2 Network
 
 Capture with `list_network_requests` on the surface. Failed requests and
 error-status responses (4xx / 5xx) become findings alongside the
 console-derived set, sharing the same `F#` numbering across the surface.
 
-### 2.3 Design-token visual check
+### 4.3 Design-token visual check
 
 When the contract's `designTokens` pointer is set (it defaults to `null`),
 spot-check the rendered surface against the token source. Flag **gross** token
@@ -98,10 +163,10 @@ A gross violation is one a designer would call a regression on sight; subtle
 sub-pixel differences are not harness findings. When `designTokens` is `null`,
 skip this check entirely — do not invent a token source.
 
-## 3. Findings — the `F#` Shape
+### 4.4 The `F#` finding shape
 
-Every captured problem is normalized into the structured `F#` finding shape so
-the sweep can record it onto the shared ledger (each `F#` finding becomes one
+Every captured problem is normalized into the structured `F#` shape so the
+sweep can record it onto the shared ledger (each `F#` finding becomes one
 `QaLedgerItem` — see [`qa-core.md`](../../../../workflows/helpers/qa-core.md))
 and the schema validates:
 
@@ -111,7 +176,7 @@ and the schema validates:
   "classification": "console-error", // console-error | network-error | visual-token | ...
   "surface": "/invoices",           // the user-reachable surface, not a deep link
   "symptom": "...",                 // one-line user-visible / captured symptom
-  "likelyRootCause": null,          // heuristic card output (§4); null until enriched
+  "likelyRootCause": null,          // null unless the cause is evidenced, not guessed
   "disposition": "follow-up",       // blocker | follow-up
   "acceptance": null,               // AC this folds into, when known
   "evidence": {
@@ -124,77 +189,71 @@ and the schema validates:
 - **Determinism is load-bearing.** Re-running the same selector over the same
   captured console with the same allowlist yields the same findings in the same
   order. Do not reorder or renumber findings between sweeps.
-- **Scrub before rendering.** Before any finding's `evidence` is rendered or
-  drafted, strip tokens, session cookies, Authorization headers, and PII from
-  the captured console and network per
-  [`security-baseline.md`](../../../../rules/security-baseline.md). Findings are
-  posted to GitHub at approval time — captured evidence is untrusted until
-  scrubbed.
-
-## 4. Framework-Generic Heuristic Cards
-
-The harness ships **framework-generic** root-cause heuristics — they reason
-about symptoms, not about any one frontend framework. Use a card to populate
-`likelyRootCause` and to set `disposition`. The cards are guidance, not a
-classifier: when a symptom matches none cleanly, leave `likelyRootCause: null`
-and let the operator triage from the symptom.
-
-| Symptom pattern | Likely root cause | Default disposition |
-| --- | --- | --- |
-| `404` / `Not Found` on a navigation or asset request | Dead route, broken link, or missing build artifact | follow-up (blocker if it breaks the scenario path) |
-| `401` / `403` reaching a surface the persona should see | Missing or over-tight authorization check; guard misconfig | blocker |
-| `500` / `502` / `503` on a user action | Server-side fault behind the action | blocker |
-| Uncaught `TypeError` / `ReferenceError` in console | Null/undefined dereference or missing binding in client code | blocker when it breaks the surface, else follow-up |
-| `Failed to fetch` / `NetworkError` / CORS-rejected request | Misconfigured CORS allowlist, wrong origin, or a downed dependency | follow-up |
-| Hydration / mismatch warning escalated to error | Server/client render divergence | follow-up |
-| Off-palette color, off-scale spacing/typography | Design-token drift — hard-coded value bypassing the token | follow-up |
-| Repeated identical console error across many surfaces | A shared component or global bootstrap fault | record once; the shared route/dedup core collapses duplicates at triage |
-
-Heuristics for working the cards:
-
-- **Record once, let dedup collapse.** When the same error fires on many
-  surfaces, record it once rather than filing N copies; the shared
-  classify/route/dedup core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md))
-  collapses duplicates at triage against the fingerprint footer.
 - **Blocker vs. follow-up.** A finding is a **blocker** when it breaks the
   scenario's user-visible outcome or exposes an authorization gap. Everything
-  else (noise that does not break the journey, cosmetic token drift) is a
+  else — noise that does not break the journey, cosmetic token drift — is a
   **follow-up**.
 - **Symptom over diagnosis.** When unsure of the root cause, record the precise
   symptom and leave `likelyRootCause: null`. A wrong guess is worse than an
   honest "unknown" the operator can triage.
-
-## 5. Record onto the Ledger & Triage (Never File Autonomously)
-
-Record each `F#` finding as a `QaLedgerItem` on the shared session ledger under
+- **Record once, let dedup collapse.** When the same error fires on many
+  surfaces, record it once rather than filing N copies; the shared
+  classify/route/dedup core collapses duplicates at triage against the
+  fingerprint footer.
+
+## 5. Mode — Exploratory Driving (`/qa-explore`)
+
+Exploratory driving walks a named surface with no scenario script, capturing
+what it observes. It is the agent-led half of exploratory QA; its human-led
+sibling is `/qa-assist` (the human drives, the agent scribes). Everything in
+§§ 1–3 applies unchanged; the deltas are the method choice and the per-surface
+boundary.
+
+- **Pick the driving method explicitly at Plan time** — drive (default) vs.
+  static — and record it in the ledger. Do not switch methods mid-surface
+  without a new Plan note.
+- **Drive is the default.** When the resolved environment carries a
+  `signInSeam`, authenticated surfaces — including deployed hosts — are
+  **driven** through that seam, not statically deferred.
+- **Static driving is the documented interim**, chosen **only where no seam
+  resolves** for the target environment. It walks the surface from source,
+  route definitions, and rendered markup rather than a running browser:
+  - **Never a silent fallback.** Static is a deliberate Plan-phase decision
+    recorded with its reason ("environment: preview, method: static, reason: no
+    seam resolves"), not something the agent slips into when the browser MCP
+    hiccups.
+  - **Interim, not equivalent.** Static driving cannot exercise real
+    authorization, routing guards, or runtime console/network signal. Treat its
+    coverage as partial and say so in the ledger; a static pass does not close
+    the same coverage a driven pass would.
+  - **Same read-only invariant** (§ 2) applies identically.
+  - **Promote to driving when a seam lands.** Re-run the surface driven rather
+    than leaving it permanently static.
+- **A surface that could not be driven is itself a signal.** Where the
+  environment resolves no seam, drive the unauthenticated surface or fall back
+  to static and record the gap — never a silent skip.
+- **Observe, do not fabricate.** Never script the runtime to manufacture an
+  outcome the exploration is meant to discover.
+
+## 6. Record onto the Ledger & Triage (Never File Autonomously)
+
+Record each finding as a `QaLedgerItem` on the shared session ledger under
 `temp/qa/`, then route the ledger through the shared classify → route →
 disposition → promote core — both stated once in
 [`qa-core.md`](../../../../workflows/helpers/qa-core.md). The harness **MUST
-NOT** create tickets autonomously: findings are promoted through `/mandrel-plan` only
-after the operator confirms each disposition at the HITL write gate. That gate
-is the safety boundary against spurious filing.
-
-## 6. Sign-In & Contract Discipline
-
-- **Resolve the `qa` contract first.** Before any browser work, resolve the
-  contract via `resolveQaContract(config)`. When the block is absent,
-  malformed, or missing a required field, the resolver **throws** — relay its
-  verbatim message and STOP. There is no auto-detection fallback.
-- **Dev seam only.** Sign in once per persona via the contract's `signInSeam`
-  (`kind: 'url'` dev seam or `kind: 'skill'`). **Never** enter real
-  credentials. Confirm authenticated state with a `take_snapshot` before
-  driving any scenario.
-- **No headless fallback.** The chrome-devtools MCP surface is a host-provided
-  runtime dependency. If it is unavailable, degrade with a clear error and stop
-  — never fall back to the retired headless BDD runner.
+NOT** create tickets autonomously: findings are promoted through
+`/mandrel-plan` only after the operator confirms each disposition at the HITL
+write gate. That gate is the safety boundary against spurious filing.
 
 ## 7. Cross-References
 
-- Run procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
+- Sweep procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
+- Exploration procedure (SSOT): [`qa-explore.md`](../../../../workflows/qa-explore.md).
 - Driving rules (one prose home): [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
 - Shared QA core (contract/session/redaction/ledger/triage/HITL): [`qa-core.md`](../../../../workflows/helpers/qa-core.md).
 - Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
 - Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
 - Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).
 - Browser-locator discipline: [`playwright`](../playwright/SKILL.md).
-- Evidence scrubbing: [`security-baseline.md`](../../../../rules/security-baseline.md).
+- Browser instrumentation: [`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
+- Evidence scrubbing / read-only boundary: [`security-baseline.md`](../../../../rules/security-baseline.md).

package/.agents/workflows/git-cleanup.md

@@ -17,8 +17,9 @@ Reach for it when the automated hygiene left an unusual state behind.
 > **When to run**: after a session that landed several PRs, or before starting a
 > new Story, to put the local checkout into a known tidy state.
 >
-> **Persona**: `devops-engineer` · **Skills**:
-> `core/git-workflow-and-versioning`
+> **Persona**: `devops-engineer` — git guidance comes from the always-on
+> [`rules/git-conventions.md`](../rules/git-conventions.md), which needs no
+> skill citation.
 
 The enumeration + reap logic lives in
 [`git-cleanup.js`](../scripts/git-cleanup.js) — it computes the candidate list,

package/.agents/workflows/git-deliver.md

@@ -19,8 +19,9 @@ explicitly; the interactive choice prompt fires **only** when the detected
 state is genuinely ambiguous, so the common path stays non-interactive and
 scriptable.
 
-> **Persona**: `devops-engineer` · **Skills**:
-> `core/git-workflow-and-versioning`
+> **Persona**: `devops-engineer` — git guidance comes from the always-on
+> [`rules/git-conventions.md`](../rules/git-conventions.md), which needs no
+> skill citation.
 
 ---
 

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

@@ -234,7 +234,7 @@ Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
 `title`, `body` (`goal`, optional `spec`, `changes[{path, assumption}]` —
 `creates|refactors-existing|deletes`, `non_goals`, `reason_to_exist`),
 top-level `acceptance[]`, `verify[]` (`… (unit|contract|e2e|validate)`), and
-`depends_on[]` (N>1 only).
+`depends_on[]` (a sibling slug, or `#<id>` for an existing open Story).
 
 Nothing in that shape inventories the repo for the author. `changes[]` arrives
 pre-resolved against the working tree, and Phase 8's
@@ -414,7 +414,53 @@ That is the whole point of running it first: a dry run that comes back clean
 has already paid for every deterministic refusal, so the real persist has
 nothing left to discover except network failure.
 
-## The container Epic (Gate #3, N>2)
+## The container Epic (Gate #3)
+
+Gate #3 has two branches, in this order: **adopt** an Epic that already exists,
+else **create** a new one.
+
+### Adopting an open Epic (any N)
+
+`epicCandidates[]` in the plan-context envelope lists **every open `type::epic`
+issue**, each `{ id, title, url, score, childIds }`, ranked by token overlap
+between the seed and the Epic's title, `## Goal` and its children's titles. The
+list is deliberately **complete rather than thresholded**: a low score is
+evidence for the operator to weigh, and hiding a candidate is exactly how a
+plan opens its second container for one body of work.
+
+This branch fires at **any N, N=1 included** — "add this to the Epic we started
+last week" is the single-Story case, and refusing it below three Stories would
+leave the common follow-up plan with nowhere to file itself. The three-Story
+threshold governs **creation** only, where it still holds: at two Stories a
+pair of ids is as easy to carry as one container id.
+
+On a yes, pass `--epic <id>`. Persist then:
+
+1. resolves the id **before the first create** (dry run included) — it must be
+   **open** and carry `type::epic`, or the run hard-errors having written
+   nothing;
+2. after the Stories exist, appends one `- [ ] #N` row per new Story to the
+   Epic's checklist via `appendEpicChildIds`, which is idempotent and preserves
+   existing rows' **checked state**, their order, and the fingerprint marker;
+3. mirrors a native sub-issue edge per child.
+
+The refusal posture is the **opposite** of creation's, deliberately. Creation
+degrades (an unensurable label just skips the container) because the operator
+never named one. Adoption cannot: the operator named a specific id, so silently
+not adopting it would leave them believing their Stories were filed somewhere
+they were not. Hence a hard error, raised while nothing has been written and
+the fix is free. Once the Stories are live the posture flips back — a failed
+checklist write or sub-issue edge only warns.
+
+**Only open Epics are adoptable.** A closed Epic is a finished body of work;
+joining one would reopen a container the epilogue deliberately closed and
+re-scope a completed plan. Open a new container, or reopen the old one by hand.
+
+`--epic` and `--epic-title`/`--epic-goal` are **mutually exclusive** — a run
+either joins a container or opens one — and supplying both is a usage error
+raised before any I/O.
+
+### Creating a new container (N>2)
 
 Above two Stories, `/mandrel-plan` offers to group them under one `type::epic`
 container. Confirmed, persist opens it **after** the Stories — its body embeds
@@ -442,6 +488,40 @@ existing Epic carrying the same fingerprint, which is keyed on the title **and
 the exact child set**, so a run grouping different Stories never adopts the
 wrong container.
 
+## Cross-plan `depends_on` (`#<id>`)
+
+A `depends_on[]` entry is read **lexically**: `some-slug` is a sibling inside
+this plan, `#<id>` an **external** blocker already live on the tracker. The
+second form is what lets a plan authored today wait on a Story an earlier plan
+opened and never had to name.
+
+`dependencyCandidates[]` in the envelope is the advisory prompt for it: open
+`type::story` issues whose declared `changes[]` footprint intersects the seed's
+`complexitySignals.predictedPaths`, each carrying the `overlappingPaths[]` that
+matched. Overlap is computed on **declared footprints** and not on prose, using
+the same `storyFootprint` the wave runner uses to withhold colliding Stories at
+dispatch — so the planner sees the collision the runtime would later enforce,
+one layer earlier and while it is still cheap to order around. A seed naming no
+paths short-circuits to `[]` with no provider call at all.
+
+It stays advisory: two Stories can touch a shared barrel file with no real
+ordering between them, and only the operator knows.
+
+External refs are **excluded from sibling ordering and cycle detection** —
+a Story already open is not scheduled by this run, so it has no position in the
+topological sort and cannot close a cycle back into a Story that does not exist
+yet. They are validated **before any create** (dry run included): each must
+resolve to an **open `type::story`**, and a closed issue, a container Epic, a
+missing id or a non-Story hard-errors with every bad ref named in one pass. The
+strictness is the point — a blocker that can never be satisfied reads to the
+delivery engine as a permanent wedge rather than as an error worth reporting.
+
+Persist renders the entry unchanged as a `blocked by #<id>` footer line and
+mirrors the native `blocked_by` edge, which is the same pair of surfaces a
+sibling edge produces. `/mandrel-deliver` therefore gates on it with no engine
+change: `resolve-stories.js` has always resolved foreign blockers from live
+state.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.