mandrel 1.81.0 → 1.83.0

package/.agents/instructions.md

@@ -87,10 +87,39 @@ local copy is ignored with a `shadowed` warning).
 
 ### F. Modular Global Rules
 
-Before writing code or documentation, verify if any domain-agnostic rules
-apply by checking the `.agents/rules/` directory (e.g.,
-`security-baseline.md`, `testing-standards.md`, `api-conventions.md`,
-`git-conventions.md`, `shell-conventions.md`).
+The `.agents/rules/` directory is split into an **always-on core** and an
+**on-demand set** — the same read-when-relevant pattern skills use (§ 1.B).
+The core loads into every session; the on-demand rules are read only when the
+task actually engages them, so a generic task (and every subagent it spawns)
+does not re-pay their bytes on every turn.
+
+- **Always-on core** (loaded alongside this file):
+  - [`rules/security-baseline.md`](rules/security-baseline.md) — inviolable
+    security MUSTs; applies to every piece of code generated.
+  - [`rules/git-conventions.md`](rules/git-conventions.md) — every commit,
+    branch, and PR touches it.
+
+- **On-demand** — read the file **before** doing the matching work; each opens
+  with a one-line "this rule applies when…" scope header, so skimming its first
+  paragraph confirms whether it governs the task at hand:
+  - [`rules/shell-conventions.md`](rules/shell-conventions.md) — before
+    chaining shell commands or writing cross-platform command strings.
+  - [`rules/testing-standards.md`](rules/testing-standards.md) — before
+    authoring or restructuring tests (the three-tier pyramid, assertion
+    placement, mocking/isolation MUSTs).
+  - [`rules/orchestration-error-handling.md`](rules/orchestration-error-handling.md)
+    — before writing or modifying orchestration scripts under
+    `.agents/scripts/**`.
+  - [`rules/api-conventions.md`](rules/api-conventions.md),
+    [`rules/gherkin-standards.md`](rules/gherkin-standards.md),
+    [`rules/changelog-style.md`](rules/changelog-style.md),
+    [`rules/test-seams.md`](rules/test-seams.md) — when the task is in that
+    domain (API surface, Gherkin scenarios, changelog prose, test seams).
+
+When in doubt, read the rule — the read is cheap relative to shipping a
+MUST-violating change. Precedence between a rule and any other governance
+document is unchanged (§ 1.K): loading a rule on demand does not lower its
+authority.
 
 ### G. Structured Configuration
 
@@ -123,14 +152,9 @@ GitHub Story (or Epic) ticket:
 
 #### Log Level Control
 
-The orchestrator logger (`lib/Logger.js`) emits progress/trace output based
-on the `AGENT_LOG_LEVEL` environment variable:
-
-- `silent`  — only `fatal` emits; useful for script embedding where the
-  caller owns presentation.
-- `info`    — default. Emits `info` / `warn` / `error` / `fatal`.
-- `verbose` — adds `debug` trace output on top of the `info` set. `debug` is
-  accepted as a backward-compatible alias.
+The orchestrator logger honors `AGENT_LOG_LEVEL` (`silent` / `info` /
+`verbose`). The per-level emission table is reference detail — see
+[`docs/execution-reference.md` § Log-level control](docs/execution-reference.md#log-level-control).
 
 ### I. Anti-Thrashing Protocol
 
@@ -217,27 +241,14 @@ Two carve-outs refine the ordering:
 
 ## 2. FinOps & Token Budgeting (Economic Guardrails)
 
-Mandrel does **not** enforce live LLM spend from response metadata. The
-framework limits **hydrated prompt size** and optional **pre-dispatch
-estimates**; your host runtime (editor / CLI) owns session quota and hard
-stops.
-
-### A. Token budget (hydration + pre-dispatch estimates)
-
-- **`delivery.maxTokenBudget`** (`.agentrc.json`, resolved via
-  `lib/config/limits.js`): caps the task prompt built by
-  `hydrate-context` / `hydrateContext`. The pipeline uses a rough token
-  estimate (≈4 characters per token) and applies section-aware elision
-  (`elideEnvelope`) so oversized envelopes drop or summarize
-  lower-priority sections before you receive the prompt.
-- **`delivery.preflight.*`** (optional): before `/deliver` fan-out,
-  `epic-deliver-preflight.js` compares **estimated** story count, waves,
-  install time, GitHub API volume, and Claude quota tokens against
-  configured ceilings (`maxClaudeQuotaTokens`, etc.). A breach surfaces
-  via `agent::blocked`; there is no per-tool-call metering.
-- **Host runtime**: session billing, quota exhaustion, and operator
-  overrides are enforced by your provider (e.g. Claude Code), not by
-  Mandrel scripts.
+Mandrel does **not** enforce live LLM spend from response metadata. It caps
+**hydrated prompt size** (`delivery.maxTokenBudget`, section-aware elision) and
+runs optional **pre-dispatch estimates** (`delivery.preflight.*`); your host
+runtime owns session quota and hard stops. The config keys, the ≈4-char/token
+estimate, and the elision behaviour are reference detail — see
+[`docs/execution-reference.md` § FinOps & token budgeting](docs/execution-reference.md#finops--token-budgeting-economic-guardrails).
+Consult it when a task prompt was elided or `/deliver` refused a fan-out on
+budget grounds.
 
 ---
 
@@ -245,8 +256,9 @@ stops.
 
 1. **Context First:** Before proposing any solution, understand the
    repository's tech stack, historical context, and structure.
-   - **Mandatory Reading**: Before starting ANY task, you MUST read every
-     file listed in `project.docsContextFiles` in `.agentrc.json`.
+   - **Mandatory Reading (planning & interactive tasks)**: For planning
+     (`/plan`) and interactive tasks, before starting ANY work you MUST read
+     every file listed in `project.docsContextFiles` in `.agentrc.json`.
      This list is the project's authoritative reference set (architecture,
      data dictionary, decisions log, patterns, etc.) and replaces any
      hardcoded filename list. Resolve each entry against
@@ -258,21 +270,40 @@ stops.
      When it is an index, only the index is the mandatory-read; the
      per-ADR bodies under `decisions/` are link-followed on demand
      (index-only by default), not auto-loaded into every task's context.
+   - **Digest-first Reading (`/deliver` story sub-agents)**: A `/deliver`
+     Story delivery sub-agent (dispatched via `helpers/epic-deliver-story` or
+     `helpers/single-story-deliver`) does **not** re-read the full
+     `project.docsContextFiles` set per Story. Instead it reads the **per-Epic
+     docs digest** — a single compact outline (path, byte size, heading
+     outline with line numbers, and the first paragraph under each `##`) that
+     `epic-deliver-prepare.js` writes to
+     `temp/epic-<epicId>/docs-digest.md` and the parent threads into the
+     child prompt as `docsDigestPath`. Use the digest to decide which docs are
+     relevant to the Story at hand, then **pull the full file on demand**
+     (reading the section at the line number the digest names) when a section
+     bears on the change. When `docsDigestPath` is null (the project has no
+     `project.docsContextFiles` configured) there is no digest to read and no
+     per-Story docs mandate — read a full doc only if the Story's own context
+     points you at one. This is the hard cutover from the former
+     read-every-file-per-Story rule: delivery children no longer ingest the
+     whole docs set up front.
    - **Conditional Reads**: When the task touches UI copy, layout, or
      routing and the corresponding file is present in the project, also
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when
      absent or unrelated to the task — they are not part of the universal
      mandatory set.
-   - **Epic Context**: Additionally, read the context tickets (PRD, Tech
-     Spec) linked in the current Epic's body and the task-specific
-     instructions.
+   - **Epic Context**: Additionally, read the current Epic's body — the
+     single planning document (ideation sections plus the folded Tech
+     Spec sections; Story #4324 retired the separate context tickets) —
+     and the task-specific instructions.
    - **Optimization**: For large projects, prioritize targeted retrieval
      (semantic code search or focused text search) to isolate specific
      schemas or decisions before reading broad files.
 2. **Plan First:** For non-trivial tasks (3+ steps or architectural
-   decisions), enter **Plan Mode**. Update the Tech Spec issue or create a
-   new Technical Specification document in the `docs/` root (if not already
-   handled by a ticket) before touching code.
+   decisions), enter **Plan Mode**. Update the Epic body's Tech Spec
+   sections (via `/plan`) or create a new Technical Specification document
+   in the `docs/` root (if not already handled by a ticket) before
+   touching code.
 3. **Artifacts over Chat:** Create log files for test results, build
    outputs, or debug sessions rather than pasting large code blocks in
    chat.
@@ -287,9 +318,18 @@ stops.
 
 - **Re-Plan on Failure:** If a strategy fails, **STOP** and re-plan
   immediately. Do not repeat a broken approach.
-- **Subagent Strategy:** Use subagents liberally for research, exploration,
-  or parallel analysis to keep the main context window focused. One
-  objective per subagent.
+- **Subagent Strategy:** Spawning a subagent is not free — each spawn
+  re-pays the full always-loaded context, so treat it as a cost decision,
+  not a reflex. Prefer an **inline search** (grep, a targeted read) for
+  small or localized lookups where you already know roughly where to look;
+  reach for a subagent **only when the work is large enough to justify
+  replicating context** — a broad multi-file investigation, a parallel
+  exploration front, or an isolated task that would otherwise crowd the main
+  context window. One objective per subagent. When the host exposes a
+  cheaper or faster capability, prefer it for **mechanical or read-only**
+  spawns (search, doc regeneration, lint, log triage) and keep
+  **implementation and design** work on the default capability; name no
+  specific model — let the host and operator own the concrete mapping.
 - **Anti-Laziness:** NEVER use placeholder comments like
   `// ... existing code ...`, `/* rest of file */`, or
   `// implementation here`. You MUST output the ENTIRE file or the ENTIRE
@@ -350,7 +390,7 @@ Mandrel uses a **2-tier ticket hierarchy** (Epic → Story).
 Acceptance criteria and verification steps live inline on the Story
 body (`acceptance[]` / `verify[]`); there is no Feature tier and no
 `type::task` ticket layer. Thematic grouping lives as prose in the
-Epic body / Tech Spec.
+Epic body (which also carries the folded Tech Spec sections).
 
 - The decomposer emits only `type::epic` and `type::story` issues;
   Stories attach directly to the Epic.

package/.agents/personas/architect.md

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

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

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

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

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

package/.agents/personas/engineer.md

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

package/.agents/personas/product.md

@@ -16,7 +16,7 @@ Scope ruthlessly to deliver the MVP.
 
 ## 2. Interaction Protocol (The Discovery Phase)
 
-Before creating a PRD or Story, you must validate the request:
+Before shaping an Epic body or Story, you must validate the request:
 
 1. **The "Five Whys":** Interrogate the user to find the root need.
 2. **Define Success:** Ask "What does 'done' look like?" and "How will we
@@ -26,17 +26,22 @@ Before creating a PRD or Story, you must validate the request:
 
 ## 3. Core Responsibilities
 
-### A. Requirements Gathering (PRDs)
+### A. Requirements Gathering (Epic body)
 
-For any feature larger than a bug fix, open (or update) a GitHub Issue
-labelled `context::prd` and linked to the parent Epic. If the project lists
-`docs/style-guide.md` in `project.docsContextFiles`, ensure the PRD's
+For any feature larger than a bug fix, shape the requirements **directly on
+the parent Epic body** — there is no longer a separate `context::prd` ticket
+(the PRD artifact class was retired). The Epic body carries the `## Context`,
+`## Goal`, `## Non-Goals`, `## Scope`, `## User Stories`, and
+`## Acceptance Criteria` sections. If the project lists
+`docs/style-guide.md` in `project.docsContextFiles`, ensure the Epic's
 UI copy, metadata, and structural assumptions align with it.
 
-- **Problem Statement:** 1-2 sentences on the pain point.
-- **User Stories:** Standard format: "As a [Role], I want [Action] so that
-  [Benefit]."
-- **Acceptance Criteria (AC):** A bulleted checklist of pass/fail conditions.
+- **Problem Statement:** 1-2 sentences on the pain point (the `## Context`
+  section).
+- **User Stories:** Standard format in the `## User Stories` section:
+  "As a [Role], I want [Action] so that [Benefit]."
+- **Acceptance Criteria (AC):** A bulleted checklist of pass/fail conditions
+  in the `## Acceptance Criteria` section.
   _This is the contract with Engineering._ Ensure ACs are testable by the QA
   Automation Engineer.
 
@@ -62,11 +67,12 @@ Output to Chat:
 > **Story:** As a site visitor, I want... **Acceptance Criteria:** [ ] Condition
 > 1, [ ] Condition 2...
 
-### Level 2: The PRD (For epics)
+### Level 2: The Epic body (For epics)
 
-Open (or update) the Epic's linked `context::prd` GitHub Issue with a body
-detailing problem statement, target audience, MoSCoW priorities, and strict
-Acceptance Criteria. Structured comments on the Issue capture iteration.
+Open (or update) the Epic GitHub Issue with a body detailing the problem
+statement, target audience, MoSCoW-prioritised scope, `## User Stories`, and
+strict `## Acceptance Criteria`. Structured comments on the Issue capture
+iteration.
 
 ## 5. Scope Boundaries
 

package/.agents/personas/project-manager.md

@@ -17,10 +17,11 @@ SQL, or UI components — stop immediately.
 
 ## 2. Interaction Protocol
 
-1. **Gather Context:** Read the parent Epic's linked PRD (`context::prd`)
-   and Tech Spec (`context::tech-spec`) GitHub Issues, plus every file
-   listed in `project.docsContextFiles` (typically `architecture.md`
-   and the data dictionary).
+1. **Gather Context:** Read the parent Epic body — including its
+   `## User Stories` section and the folded Tech Spec sections
+   (`## Delivery Slicing` onward; Story #4324 retired the separate Tech
+   Spec ticket) — plus every file listed in `project.docsContextFiles`
+   (typically `architecture.md` and the data dictionary).
 2. **Decompose:** Break the Epic into **Stories** that carry their own
    inline acceptance criteria and verification steps. Aim for roughly
    five acceptance bullets per Story as a soft atomicity heuristic; if
@@ -31,7 +32,7 @@ SQL, or UI components — stop immediately.
    domain, and tag the issue with the matching `persona::` label.
 4. **Format:** Generate the Story backlog using the
    `/plan` workflow.
-5. **Validate:** Ensure every Acceptance Criterion from the PRD has a
+5. **Validate:** Ensure every Acceptance Criterion from the Epic has a
    corresponding Story-body acceptance bullet. Do not drop business
    logic.
 
@@ -71,13 +72,13 @@ SQL, or UI components — stop immediately.
   `/deliver`, which runs `lib/orchestration/retro-runner.js`
   in-process. Do not write custom retro instructions.
 - **Story Finalization:** Ensure every Story's body incorporates a step
-  to self-verify its own context (PRD/Tech Spec linkage, parent
-  Epic) before starting work.
+  to self-verify its own context (parent Epic linkage — the Epic body
+  carries the Tech Spec sections) before starting work.
 
 ### D. Quality Control
 
 - **Coverage Audit:** Before finalizing the Issue hierarchy, cross-reference
-  every Acceptance Criterion in the PRD against the generated
+  every Acceptance Criterion on the Epic against the generated
   Story-body acceptance bullets. Any missed AC is a planning failure.
 - **Format Compliance:** Use the exact Issue body templates, label taxonomy,
   and parent/blocked-by linkage rules required by `/plan` so the

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

@@ -8,14 +8,17 @@ repeatable test processes. You value **coverage**, **hermetic test
 environments**, and **deterministic results**.
 
 **Golden Rule:** Never invent tests from scratch without a specification. Every
-test case must trace back to an Acceptance Criterion in the PRD or a regression
-scenario from a known bug. If the spec is ambiguous, stop and ask.
+test case must trace back to an Acceptance Criterion on the Epic (or its
+`## Acceptance Table` section) or a regression scenario from a known bug.
+If the spec is ambiguous, stop and ask.
 
 ## 2. Interaction Protocol
 
-1. **Read Context:** Before writing any test, read the parent Epic's linked
-   PRD (`context::prd`) and Tech Spec (`context::tech-spec`) GitHub Issues
-   to extract all Acceptance Criteria.
+1. **Read Context:** Before writing any test, read the parent Epic body —
+   the single planning document. Its `## Acceptance Criteria` bullets, the
+   folded Tech Spec sections (`## Delivery Slicing` onward), and the
+   `## Acceptance Table` AC-ID table all live on the Epic body itself
+   (Story #4324 retired the separate context tickets).
 2. **Plan First:** Execute the `/audit-quality` workflow to evaluate test coverage,
    seed files, and the test plan document before executing any tests.
 3. **Execute:** Run tests using the standard test framework script (e.g. `npm test`). Do not invent
@@ -33,7 +36,8 @@ scenario from a known bug. If the spec is ambiguous, stop and ask.
   it to the project's configured test-plan path if one is listed in
   `project.docsContextFiles`.
 - **Coverage Mapping:** Explicitly map each test case to an Acceptance Criterion
-  from the PRD. Flag any AC that lacks a corresponding test.
+  from the Epic (or its `## Acceptance Table` section). Flag any AC that
+  lacks a corresponding test.
 - **Edge Cases:** Go beyond the happy path. Test boundary conditions, empty
   states, error responses, and unauthorized access scenarios.
 

package/.agents/personas/refactorer.md

@@ -23,8 +23,9 @@ red tests green by "refactoring".
 ## 2. Interaction Protocol
 
 1. **Read Context:** Before touching anything, confirm the suite is green
-   and the quality gates currently pass. Read the parent Epic's Tech Spec
-   (`context::tech-spec`) and PRD (`context::prd`) plus every file listed in
+   and the quality gates currently pass. Read the parent Epic body —
+   including its folded Tech Spec sections (Story #4324) — plus every file
+   listed in
    `project.docsContextFiles` so you know the conventions the code must keep
    matching.
 2. **Establish the baseline:** Capture the current CRAP and maintainability

package/.agents/personas/technical-writer.md

@@ -17,7 +17,8 @@ wasn't in the room when it was built.
 1. **Identify Audience:** Before writing, determine who will read this document
    (developers, end users, PMs, or future agents). Adjust tone and detail level
    accordingly.
-2. **Read Source Material:** Review the relevant code changes, PRDs, tech specs,
+2. **Read Source Material:** Review the relevant code changes, Epic planning
+   bodies (including their folded Tech Spec sections),
    and commit history to understand what actually shipped — not what was
    planned.
 3. **Write:** Produce or update documentation following the standards below.

package/.agents/personas/ux-designer.md

@@ -16,8 +16,8 @@ action is destructive.
 
 ## 2. Interaction Protocol
 
-1. **Contextualize the User:** Understand the PRD and the user story. Identify
-   the primary Call to Action (CTA).
+1. **Contextualize the User:** Understand the Epic body and its user stories.
+   Identify the primary Call to Action (CTA).
 2. **Flow Before UI:** Do not design specific UI components until the entire
    end-to-end user flow is mapped out and theoretically sound.
 3. **State Management:** Define every state of a page or component (Empty,

package/.agents/schemas/agentrc.schema.json

@@ -348,6 +348,16 @@
           "type": "integer",
           "minimum": 1,
           "description": "Soft-warn threshold on acceptance[] item count (default 10)."
+        },
+        "mergeCandidateMaxFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Under-size threshold (Story #4312): a Story with at most this many declared changes[] files, at most mergeCandidateMaxAcceptance acceptance items, and at least one depends_on edge to a sibling trips the advisory `merge-candidate` soft finding (default 3)."
+        },
+        "mergeCandidateMaxAcceptance": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Under-size threshold (Story #4312): the acceptance[] item ceiling of the `merge-candidate` soft finding heuristic (default 4)."
         }
       },
       "additionalProperties": false
@@ -1502,6 +1512,34 @@
         }
       ]
     },
+    "qaEnvironments": {
+      "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as `qaSignInSeam`), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["baseUrl", "signInSeam"],
+        "additionalProperties": false,
+        "properties": {
+          "baseUrl": {
+            "allOf": [
+              {
+                "$ref": "#/$defs/safeString"
+              },
+              {
+                "minLength": 1
+              }
+            ]
+          },
+          "signInSeam": {
+            "$ref": "#/$defs/qaSignInSeam"
+          },
+          "allowWrites": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
     "qaPersonas": {
       "description": "Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names \u2014 the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a `skill`/credential seam.",
       "oneOf": [
@@ -1565,7 +1603,7 @@
     },
     "qa": {
       "type": "object",
-      "description": "Agent-driven QA harness contract (Epic #3214). Optional top-level block. All filesystem-pointer fields (featureRoot, fixturesManifest, designTokens) carry safeString guards rejecting shell-injection metacharacters. signInSeam is a url-template/skill union; personas resolve to a stored credential reference or a sign-in skill, never an inline secret.",
+      "description": "Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326). Optional top-level block. All filesystem-pointer fields (featureRoot, fixturesManifest, designTokens) carry safeString guards rejecting shell-injection metacharacters. environments is a map of named deployment targets (each with a baseUrl, a per-environment url-template/skill sign-in seam, and an optional allowWrites gate); personas resolve to a stored credential reference or a sign-in skill, never an inline secret.",
       "additionalProperties": false,
       "properties": {
         "featureRoot": {
@@ -1588,8 +1626,8 @@
             }
           ]
         },
-        "signInSeam": {
-          "$ref": "#/$defs/qaSignInSeam"
+        "environments": {
+          "$ref": "#/$defs/qaEnvironments"
         },
         "personas": {
           "$ref": "#/$defs/qaPersonas"

package/.agents/schemas/qa-ledger.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://mandrel.dev/schemas/qa-ledger.schema.json",
   "title": "QaLedgerItem",
-  "description": "Structured exploratory-QA ledger item (`f3-qa-explore-core`, Feature #3710, Epic #3686). One object per observation captured while exploring a consumer surface — distinct from a `qa-finding` (the browser-sweep `F#` finding): a ledger item classifies a broader exploratory signal (product bug, environment-setup friction, tooling/DX gap, test-coverage gap, or enhancement idea), records the evidence and coverage context, names any missing test, and carries the operator disposition so Triage can parse a whole session. A ledger item has a two-phase lifecycle: the read-only **Capture** phase appends an item with the Capture-phase fields populated (`id`, `class`, `severity`, `evidence`, `coverage`, `missingTest`) but no resolved `disposition`; the **Triage** phase later assigns the `disposition`. The schema therefore validates BOTH the captured-but-untriaged shape (`disposition` absent, `null`, or a `pending`/`untriaged` sentinel — the rolling backlog `.agents/scripts/lib/qa/qa-session.js` reads back on resume) AND the fully-triaged shape (`disposition` resolved to `file`/`defer`/`dismiss`), while still rejecting genuinely malformed items. Evidence MUST already be scrubbed of secrets, session tokens, and PII per `.agents/rules/security-baseline.md` before it is rendered here.",
+  "description": "Structured exploratory-QA ledger item (`f3-qa-explore-core`, Feature #3710, Epic #3686). One object per observation captured while exploring a consumer surface, and — since Story #4330 unified `/qa-run` onto this ledger — one object per browser-sweep `F#` finding as well: a ledger item classifies an exploratory or sweep signal (product bug, environment-setup friction, tooling/DX gap, test-coverage gap, or enhancement idea), records the evidence and coverage context, names any missing test, and carries the operator disposition so Triage can parse a whole session. A ledger item has a two-phase lifecycle: the read-only **Capture** phase appends an item with the Capture-phase fields populated (`id`, `class`, `severity`, `evidence`, `coverage`, `missingTest`) but no resolved `disposition`; the **Triage** phase later assigns the `disposition`. The schema therefore validates BOTH the captured-but-untriaged shape (`disposition` absent, `null`, or a `pending`/`untriaged` sentinel — the rolling backlog `.agents/scripts/lib/qa/qa-session.js` reads back on resume) AND the fully-triaged shape (`disposition` resolved to `file`/`defer`/`dismiss`), while still rejecting genuinely malformed items. Evidence MUST already be scrubbed of secrets, session tokens, and PII per `.agents/rules/security-baseline.md` before it is rendered here.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -64,7 +64,7 @@
     },
     "routedTo": {
       "type": "object",
-      "description": "Optional finding-to-issue link recording where Triage routed this item. Populated only after the item is promoted to a follow-up ticket (`disposition: file`); omit while the item is still in Capture or was deferred/dismissed. The same link shape is mirrored on `qa-finding.schema.json`.",
+      "description": "Optional finding-to-issue link recording where Triage routed this item. Populated only after the item is promoted to a follow-up ticket (`disposition: file`); omit while the item is still in Capture or was deferred/dismissed.",
       "additionalProperties": false,
       "required": ["issue", "url", "kind"],
       "properties": {