mandrel 1.82.0 → 1.84.0

package/.agents/README.md

@@ -216,6 +216,47 @@ If your AI tool is not Claude Code, load
 [`instructions.md`](instructions.md) verbatim through that tool's own
 system-prompt mechanism (`.cursorrules`, Custom Instructions, etc.).
 
+### What to always-load vs read on-demand
+
+The always-loaded context is re-paid on every session **and every subagent
+spawn**, so the shipped set is kept deliberately lean. Load this core into your
+system prompt; read everything else only when the task engages it (the same
+read-when-relevant pattern skills use).
+
+**Always-load (the recommended core):**
+
+- [`instructions.md`](instructions.md) — the core agent protocol.
+- [`personas/engineer.md`](personas/engineer.md) — the default persona (swap in
+  another persona when the task calls for it).
+- [`rules/security-baseline.md`](rules/security-baseline.md) — inviolable
+  security MUSTs, relevant to every change.
+- [`rules/git-conventions.md`](rules/git-conventions.md) — every commit,
+  branch, and PR touches it.
+
+**Read on-demand (do the read before the matching work):**
+
+- [`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.
+- [`rules/orchestration-error-handling.md`](rules/orchestration-error-handling.md)
+  — before writing or modifying orchestration scripts under
+  `.agents/scripts/**`.
+- The remaining domain rules
+  ([`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.
+- Every `SKILL.md` under [`skills/`](skills/) — when the task hits its trigger.
+- [`docs/execution-reference.md`](docs/execution-reference.md) — log-level and
+  token-budget reference detail lifted out of `instructions.md`.
+
+Each on-demand rule opens with a one-line "this rule applies when…" scope
+header, so a quick skim of its first paragraph tells you whether it governs the
+task at hand. `instructions.md` § 1.F is the canonical in-prompt statement of
+this split.
+
 ---
 
 ## Interactive repo / project pickers

package/.agents/docs/SDLC.md

@@ -1172,8 +1172,10 @@ non-QA consumer) but enforced at run time: the resolver fails **loudly** with
 "this project has not bound the QA harness" when no `qa` block is present —
 there is no silent fallback. The contract's four required keys are
 `qa.featureRoot` (the `.feature` discovery root), `qa.fixturesManifest`
-(persona → seed-data binding), `qa.signInSeam` (the dev-only sign-in seam,
-either `{ urlTemplate }` or `{ skill }`), and `qa.personas` (the persona set,
+(persona → seed-data binding), `qa.environments` (the environment-keyed map —
+each entry `{ baseUrl, signInSeam, allowWrites? }`, selected per invocation by
+`resolveQaEnvironment`; the per-environment `signInSeam` is either
+`{ urlTemplate }` or `{ skill }`), and `qa.personas` (the persona set,
 authored as a name-only array under a url-template seam or as a per-persona
 credential/skill map under a skill seam); the two optional keys
 `qa.consoleAllowlist` and `qa.designTokens` default to `[]` and `null`.

package/.agents/docs/agentrc-reference.json

@@ -264,8 +264,16 @@
   "qa": {
     "featureRoot": "tests/features",
     "fixturesManifest": "tests/fixtures/personas.json",
-    "signInSeam": {
-      "skill": "stack/qa/sign-in"
+    "environments": {
+      "local": {
+        "baseUrl": "http://localhost:3000",
+        "signInSeam": { "urlTemplate": "/dev/sign-in-as/{persona}" }
+      },
+      "staging": {
+        "baseUrl": "https://staging.example.test",
+        "signInSeam": { "skill": "stack/qa/sign-in" },
+        "allowWrites": false
+      }
     },
     "personas": {
       "admin": { "credentialRef": "QA_ADMIN_CREDENTIAL" },

package/.agents/docs/execution-reference.md

@@ -0,0 +1,52 @@
+# Execution Reference (on-demand)
+
+Reference-only material extracted from
+[`.agents/instructions.md`](../instructions.md) so the always-loaded system
+prompt stays lean (Story #4332). Nothing here is a per-task MUST — it is
+detail an agent consults **only when the relevant lever is in play** (tuning
+log verbosity, reasoning about the token budget). The always-loaded protocol
+links here from the sections that used to inline this content.
+
+---
+
+## 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.
+
+This is a diagnostic knob: set it when you need quieter script embedding
+(`silent`) or a deeper trace (`verbose`). The friction-telemetry MUST it sits
+under — post friction to the relevant ticket via `diagnose-friction.js` — stays
+in [`instructions.md` § 1.H](../instructions.md).
+
+---
+
+## 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. Consult this section when reasoning about why a task prompt was elided
+or why `/deliver` refused a fan-out on budget grounds.
+
+### 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.

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,6 +270,23 @@ 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
@@ -289,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

package/.agents/rules/testing-standards.md

@@ -161,6 +161,20 @@ assertions into a single "kitchen sink" test — split them.
 - Coverage targets apply to production code. Test helpers, fixtures, and
   generated code are excluded per the project's coverage config.
 
+## Anti-Gaming (review-side complement)
+
+These standards define what a *correct* test looks like; they cannot, on
+their own, catch a change that reaches green by **weakening the check rather
+than fixing the code** — a relaxed assertion, a skipped or deleted test, a
+swallowed error, a stub return, a fake rename, or a warning silenced by
+comment deletion. That shortcut taxonomy is enumerated, and the reviewer-facing
+detection lens for it lives, in the **Anti-Gaming / Shortcut Detection** pillar
+(Pillar 4) of
+[`../workflows/helpers/code-review.md`](../workflows/helpers/code-review.md#pillar-4-anti-gaming--shortcut-detection).
+When you loosen a matcher, quarantine a test, or remove coverage, record the
+spec-sanctioned rationale in the commit body or Story comment so that pillar
+reads it as a deliberate decision rather than gaming.
+
 ## Property-Based Testing (a technique, not a tier)
 
 Property-based testing is a **technique** — generating a domain of inputs and

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

@@ -1512,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": [
@@ -1575,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": {
@@ -1598,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": {

package/.agents/scripts/epic-deliver-prepare.js

@@ -32,13 +32,16 @@
  *   node .agents/scripts/epic-deliver-prepare.js --epic <epicId>
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
-import { getRunners, resolveConfig } from './lib/config-resolver.js';
+import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
 import { currentBranch as gitCurrentBranch } from './lib/git-branch-lifecycle.js';
 import { getEpicBranch, gitSpawn } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { buildDocsDigest } from './lib/orchestration/docs-digest.js';
 import {
   resolveOperator,
   runPrepareGuards,
@@ -286,6 +289,40 @@ function evaluatePrepareConcurrencyGate({
   return gate;
 }
 
+/**
+ * Build the per-Epic docs digest and write it to
+ * `<tempRoot>/epic-<id>/docs-digest.md`, returning its repo-relative path.
+ * Story #4338 — the parent threads this path into every child prompt so
+ * delivery sub-agents read one compact outline instead of re-ingesting the
+ * full `project.docsContextFiles` set per Story.
+ *
+ * Keyed off the **un-defaulted** config (`config.raw`): when the operator has
+ * not configured `project.docsContextFiles`, this returns `null` (no file
+ * written) rather than digesting the resolver's built-in default set — the
+ * digest is an opt-in surface for projects that curate their docs context.
+ *
+ * @param {{ epicId: number, cwd?: string, config: object }} args
+ * @returns {Promise<string|null>} repo-relative digest path, or null when
+ *   `project.docsContextFiles` is empty/unset (or every file is missing).
+ */
+async function writeDocsDigest({ epicId, cwd, config }) {
+  const rawFiles = config?.raw?.project?.docsContextFiles;
+  const docsContextFiles = Array.isArray(rawFiles) ? rawFiles : [];
+  if (docsContextFiles.length === 0) return null;
+
+  const paths = getPaths(config);
+  const root = path.resolve(cwd ?? process.cwd());
+  const docsRoot = path.resolve(root, paths.docsRoot);
+  const digest = await buildDocsDigest({ docsContextFiles, docsRoot });
+  if (digest == null) return null;
+
+  const relPath = path.join(paths.tempRoot, `epic-${epicId}`, 'docs-digest.md');
+  const absPath = path.resolve(root, relPath);
+  await fs.promises.mkdir(path.dirname(absPath), { recursive: true });
+  await fs.promises.writeFile(absPath, digest, 'utf-8');
+  return relPath;
+}
+
 export async function runEpicDeliverPrepare({
   epicId,
   cwd,
@@ -374,6 +411,8 @@ export async function runEpicDeliverPrepare({
     });
   }
 
+  const docsDigestPath = await writeDocsDigest({ epicId, cwd, config });
+
   return {
     epicId,
     storyCount: openStories.length,
@@ -385,6 +424,7 @@ export async function runEpicDeliverPrepare({
       new Date().toISOString(),
     concurrencyHazardsBypassed: gate.bypassed,
     preflightCache: cacheStatus,
+    docsDigestPath,
   };
 }
 

package/.agents/scripts/lib/config/explain.js

@@ -232,7 +232,10 @@ const PREFIX_MEANINGS = Object.freeze([
     'planning.taskSizing',
     'Story-sizing threshold for the decompose validator.',
   ],
-  ['qa.signInSeam', 'QA harness sign-in seam configuration.'],
+  [
+    'qa.environments',
+    'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate).',
+  ],
   ['qa.personas', 'QA harness persona / credential mapping.'],
 ]);
 

package/.agents/scripts/lib/config-settings-schema.js

@@ -406,12 +406,36 @@ const QA_PERSONAS_SCHEMA = {
   ],
 };
 
+// `environments` is the environment-keyed contract (Epic #4326, Story #4327).
+// It replaces the retired top-level single `signInSeam` shape: each named
+// environment carries its own `baseUrl`, its own per-environment `signInSeam`
+// (reusing the same url-template/skill union), and an optional `allowWrites`
+// gate. Downstream, `resolveQaEnvironment` selects one environment per
+// invocation by name or by raw-URL origin match against `baseUrl`. The map
+// must carry at least one environment. This is a hard cutover — there is no
+// top-level `signInSeam` acceptance branch (see
+// `.agents/rules/git-conventions.md` § Contract Cutovers).
+const QA_ENVIRONMENTS_SCHEMA = {
+  type: 'object',
+  minProperties: 1,
+  additionalProperties: {
+    type: 'object',
+    properties: {
+      baseUrl: { ...SAFE_STRING, minLength: 1 },
+      signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
+      allowWrites: { type: 'boolean' },
+    },
+    required: ['baseUrl', 'signInSeam'],
+    additionalProperties: false,
+  },
+};
+
 export const QA_SCHEMA = {
   type: 'object',
   properties: {
     featureRoot: { ...SAFE_STRING, minLength: 1 },
     fixturesManifest: { ...SAFE_STRING, minLength: 1 },
-    signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
+    environments: QA_ENVIRONMENTS_SCHEMA,
     personas: QA_PERSONAS_SCHEMA,
     consoleAllowlist: {
       type: 'array',

package/.agents/scripts/lib/epic-body-sections.js

@@ -198,6 +198,94 @@ export function hasTechSpecContent(body) {
   return typeof body === 'string' && DELIVERY_SLICING_RE.test(body);
 }
 
+/**
+ * `##` headings dropped from the delivery-hydrated Epic body. These are
+ * ideation / authoring / close-machinery sections a story agent never acts
+ * on: keeping them out of the per-Story prompt trims token cost without
+ * losing any binding context (the Story carries its own inline
+ * acceptance[] / verify[]).
+ *
+ * @type {ReadonlySet<string>}
+ */
+const DELIVERY_DROP_HEADINGS = new Set([
+  'context',
+  'scope',
+  'acceptance criteria',
+]);
+
+/**
+ * Slice an Epic body down to the sections a delivery story agent acts on.
+ *
+ * KEEP: the Epic title / preamble before the first `##`, `## Goal`,
+ * `## Non-Goals`, `## User Stories`, the `techSpec` managed region, and —
+ * fail-open — any unknown / operator-authored `##` section not in the drop
+ * list. DROP: `## Context`, `## Scope`, `## Acceptance Criteria`, and the
+ * `acceptanceTable` managed region.
+ *
+ * The `techSpec` region is located by its markers (not by heading
+ * boundaries) so its inner `## Delivery Slicing` heading is preserved
+ * verbatim and never mistaken for a plain droppable section. Plain `##`
+ * sections outside the managed regions are sliced by heading boundaries.
+ *
+ * Fail-open is load-bearing: any heading not explicitly in the drop set is
+ * kept, so operator-authored content is never silently lost.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function sliceEpicBodyForDelivery(body) {
+  if (typeof body !== 'string' || body.length === 0) return '';
+
+  // 1. Drop the acceptance-table managed region outright (authoring/close
+  //    machinery, never delivery context).
+  let working = stripEpicSection(body, 'acceptanceTable');
+
+  // 2. Protect the techSpec managed region from heading-boundary slicing by
+  //    lifting it out behind an opaque placeholder, then restoring it after
+  //    the plain-section pass. Its inner `## Delivery Slicing` heading must
+  //    survive verbatim.
+  const techLoc = locate(working, 'techSpec');
+  let techRegion = null;
+  const PLACEHOLDER = 'MANDREL_TECH_SPEC_PLACEHOLDER';
+  if (techLoc) {
+    const { end } = descriptor('techSpec');
+    techRegion = working.slice(techLoc.startIdx, techLoc.endIdx + end.length);
+    working =
+      working.slice(0, techLoc.startIdx) +
+      PLACEHOLDER +
+      working.slice(techLoc.endIdx + end.length);
+  }
+
+  // 3. Slice plain `##` sections by heading boundaries, dropping only the
+  //    known ideation/authoring headings. The preamble before the first
+  //    `##` (Epic title / lede) is always kept.
+  const kept = [];
+  let dropping = false;
+  for (const line of working.split('\n')) {
+    const headingMatch = line.match(/^##\s+(.*?)\s*$/);
+    if (headingMatch) {
+      dropping = DELIVERY_DROP_HEADINGS.has(
+        headingMatch[1].trim().toLowerCase(),
+      );
+      if (dropping) continue;
+    }
+    if (dropping) continue;
+    kept.push(line);
+  }
+  working = kept.join('\n');
+
+  // 4. Restore the techSpec region in place.
+  if (techRegion !== null) {
+    working = working.replace(PLACEHOLDER, () => techRegion);
+  }
+
+  // 5. Normalise the blank-line runs left by the drops.
+  return working
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+/, '')
+    .trimEnd();
+}
+
 /**
  * Strip the retired machine-managed `## Planning Artifacts` checklist from
  * an Epic body (the section that linked the now-retired context tickets).

package/.agents/scripts/lib/findings/promote-finding.js

@@ -196,8 +196,8 @@ function clusterToFinding(cluster) {
 /**
  * Build the `routedTo` link the schema stamps onto a promoted ledger item.
  *
- * The `routedTo.url` field is `minLength: 1` in both `qa-finding.schema.json`
- * and `qa-ledger.schema.json`, and the search/create port contract requires a
+ * The `routedTo.url` field is `minLength: 1` in `qa-ledger.schema.json`,
+ * and the search/create port contract requires a
  * routed issue to carry its canonical URL. So rather than silently stamp an
  * empty string (which would persist a schema-invalid ledger item), this guards
  * the url and throws when it is absent or blank (Story #3816, AC #4).
@@ -213,7 +213,7 @@ function routedToLink(issue, kind) {
     throw new Error(
       `promoteFindings: routed issue #${issue?.number ?? '?'} is missing a url; ` +
         'the search/create port contract requires a non-empty url ' +
-        '(routedTo.url is minLength:1 in the qa-finding/qa-ledger schemas)',
+        '(routedTo.url is minLength:1 in the qa-ledger schema)',
     );
   }
   return {