mandrel 1.82.0 → 1.83.0

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -8,12 +8,69 @@
  */
 
 import { resolveBundleSizeEnvOverrides } from '../../../baselines/env-overrides.js';
-import { checkKernelVersion } from '../../../baselines/kernel.js';
+import {
+  checkKernelVersion,
+  getKindModule,
+} from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
 import { Logger } from '../../../Logger.js';
+import { isIgnoredByGlobs } from '../../../maintainability-utils.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
 
+/**
+ * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
+ * incident). The generation path already drops `ignoreGlobs`-matched files
+ * before they reach `rows` (both the canonical `buildDefaultMaintainabilityScorer`
+ * and the story-close `buildKindScorer`), so a freshly-generated baseline's
+ * `rollup["*"]` never includes an ignored file. But the floor check trusts the
+ * *stored* `rollup["*"]`: if a baseline is poisoned by some other route — a
+ * stale branch's older tooling, a hand-edit, a future generation bug — an
+ * ignored file's metric can still drag the global floor axis (e.g.
+ * maintainability `min`) below its floor and block every downstream close.
+ *
+ * This recomputes the global `*` aggregate over the baseline rows that are NOT
+ * matched by the gate's `ignoreGlobs`, using the kind's own canonical
+ * `rollup()` aggregator, so the floor axis reflects only the files the gate is
+ * meant to police. It is a **no-op for a correctly-generated baseline** (no
+ * ignored file is present in `rows`, so the filtered set is identical and the
+ * stored `rollup["*"]` is returned unchanged) and only affects the `*`
+ * component the incident poisons; named-component rollups are left as stored.
+ * The compare/regression stage is untouched — this only reshapes the floor
+ * input. All three `ignoreGlobs`-configured gates (maintainability, crap,
+ * duplication) are `path`-keyed, so the shared path matcher applies uniformly.
+ *
+ * Kept module-local (not exported): the poison-exclusion behaviour is covered
+ * end-to-end through `evaluateKind` by the `check-baselines.min-floor` suite,
+ * so there is no external consumer to justify widening the surface.
+ *
+ * @param {{ kind: string, baseline: { rollup?: object, rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
+ * @returns {object} the effective rollup to feed the floor check
+ */
+function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
+  const rollup = baseline?.rollup;
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return rollup;
+  const rows = baseline?.rows;
+  if (!Array.isArray(rows) || rows.length === 0) return rollup;
+  let mod;
+  try {
+    mod = getKindModule(kind);
+  } catch {
+    return rollup;
+  }
+  if (mod?.keyField !== 'path' || typeof mod.rollup !== 'function')
+    return rollup;
+  const kept = rows.filter((row) => {
+    const p = row?.path;
+    return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
+  });
+  // Nothing ignored is present → the stored rollup already excludes ignored
+  // files (the correct-baseline fast path); return it untouched.
+  if (kept.length === rows.length) return rollup;
+  const recomputed = mod.rollup(kept);
+  return { ...rollup, '*': recomputed?.['*'] ?? rollup?.['*'] };
+}
+
 function loadHeadBaseline(kind, cwd, configPath) {
   try {
     return { baseline: reader.load(kind, { cwd, configPath }) };
@@ -100,7 +157,13 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
-  const findings = applyFloors(kind, baseline.rollup, gateBlock.floors ?? {});
+  const floorRollup = rollupExcludingIgnored({
+    kind,
+    baseline,
+    ignoreGlobs: gateBlock.ignoreGlobs,
+    cwd,
+  });
+  const findings = applyFloors(kind, floorRollup, gateBlock.floors ?? {});
   const breaches = flattenBreaches(findings);
   const cmp = await evaluateCompare({ kind, gateBlock, scope, cwd });
   const rawCompare = runCompareStage(baseline, cmp);

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -27,7 +27,7 @@ import {
   PROJECT_ROOT,
   resolveConfig,
 } from '../config-resolver.js';
-import { stripEpicSection } from '../epic-body-sections.js';
+import { sliceEpicBodyForDelivery } from '../epic-body-sections.js';
 import { Logger } from '../Logger.js';
 import {
   buildEnvelope,
@@ -233,6 +233,71 @@ export function extractStorySections(body) {
   return { acceptance, verify };
 }
 
+/**
+ * Remove one `## <heading>` section (heading line through the last line
+ * before the next `## ` heading, or EOF) from a Story body. Byte-preserving
+ * outside the removed span. No-op when the heading is absent. Case- and
+ * whitespace-tolerant to match `extractSectionList`.
+ *
+ * @param {string} body
+ * @param {string} heading
+ * @returns {string}
+ */
+function stripSection(body, heading) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  const pattern = new RegExp(
+    `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+    'mi',
+  );
+  const startMatch = body.match(pattern);
+  if (!startMatch || startMatch.index == null) return body;
+  const start = startMatch.index;
+  const afterHeading = start + startMatch[0].length;
+  const rest = body.slice(afterHeading);
+  const nextHeading = rest.search(/^##\s+/m);
+  const end = nextHeading === -1 ? body.length : afterHeading + nextHeading;
+  const before = body.slice(0, start).replace(/\n+$/, '\n');
+  const after = body.slice(end).replace(/^\n+/, '');
+  return (before + after).replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+/**
+ * Strip the inline `## Acceptance Criteria` / `## Acceptance` and `## Verify`
+ * sections from a Story body. Used to build the `taskInstructions` section
+ * when the dedicated `acceptanceCriteria` / `verificationCommands` envelope
+ * sections already carry those lists — so the binding acceptance/verify
+ * content appears exactly once in the hydrated envelope rather than being
+ * duplicated between the dedicated sections and the full task body.
+ *
+ * Each heading group is stripped only when its own dedicated section was
+ * emitted (`acceptance` gates `## Acceptance Criteria` + `## Acceptance`;
+ * `verify` gates `## Verify`). This keeps the strip symmetric with what was
+ * reproduced elsewhere in the envelope: a `## Verify` section that carried no
+ * bullets (so no dedicated `verificationCommands` section fired) is left
+ * intact in `taskInstructions` rather than being silently dropped. Both flags
+ * default to `true` so a no-argument call preserves the original
+ * strip-everything behaviour.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: boolean, verify?: boolean }} [opts]
+ * @returns {string}
+ */
+export function stripStorySectionsForTaskInstructions(
+  body,
+  { acceptance = true, verify = true } = {},
+) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  let out = body;
+  if (acceptance) {
+    out = stripSection(out, 'Acceptance Criteria');
+    out = stripSection(out, 'Acceptance');
+  }
+  if (verify) {
+    out = stripSection(out, 'Verify');
+  }
+  return out;
+}
+
 /**
  * Detect whether the dispatched unit is a 2-tier Story (Story is the
  * leaf, carries inline acceptance/verify) vs. a 4-tier Task (Task is
@@ -371,16 +436,15 @@ async function buildHierarchySections(task, provider, epicId, agentSettings) {
       try {
         const t = await provider.getTicket(item.id);
         provenance.push(ticketSnapshot(t, retrievedAt));
-        // Hydration section-elision guardrail (Story #4324): the Epic
-        // body's ## Acceptance Table managed section is authoring/close
-        // machinery — never delivery context. Strip it before it reaches
-        // a story agent's prompt so per-story prompt size stays flat
-        // versus the pre-fold baseline (the old acceptance-spec ticket
-        // was never hydrated either).
+        // Hydration section-slicing guardrail (Story #4340): the Epic body
+        // is sliced down to only the sections a delivery story agent acts
+        // on — Goal / Non-Goals / User Stories / Tech Spec (plus any
+        // operator-authored section, fail-open). Ideation / authoring /
+        // close machinery (## Context, ## Scope, ## Acceptance Criteria,
+        // and the ## Acceptance Table managed region) is dropped so
+        // per-story prompt size stays flat versus the pre-fold baseline.
         const body =
-          item.key === 'Epic'
-            ? stripEpicSection(t.body ?? '', 'acceptanceTable')
-            : t.body;
+          item.key === 'Epic' ? sliceEpicBodyForDelivery(t.body ?? '') : t.body;
         return `### ${item.key}: ${t.title} (#${t.id})\n\n${body}\n`;
       } catch (err) {
         const detail = err?.message ? `: ${err.message}` : '';
@@ -485,9 +549,16 @@ function buildStaticSections(
     }
   }
 
+  // Track which dedicated section(s) were emitted so taskInstructions drops
+  // only the inline sections that were actually reproduced elsewhere in the
+  // envelope — keeping each binding acceptance/verify item present exactly
+  // once, without dropping a bulletless section that has no dedicated twin.
+  let acceptanceEmitted = false;
+  let verifyEmitted = false;
   if (isTwoTierStoryTask(task)) {
     const { acceptance, verify } = extractStorySections(task.body ?? '');
     if (acceptance.length > 0) {
+      acceptanceEmitted = true;
       sections.push({
         name: 'acceptanceCriteria',
         priority: DEFAULT_SECTION_PRIORITIES.acceptanceCriteria,
@@ -499,6 +570,7 @@ function buildStaticSections(
       });
     }
     if (verify.length > 0) {
+      verifyEmitted = true;
       sections.push({
         name: 'verificationCommands',
         priority: DEFAULT_SECTION_PRIORITIES.verificationCommands,
@@ -511,11 +583,24 @@ function buildStaticSections(
     }
   }
 
+  // When a dedicated acceptance/verify section carries that list, strip the
+  // matching inline heading(s) from the task body so they are not duplicated
+  // in taskInstructions. Each group is gated on its own section: an inline
+  // section with no dedicated twin (e.g. a bulletless `## Verify`) is left
+  // intact. When neither fired, taskInstructions is byte-identical to the
+  // full body.
+  const taskBody =
+    acceptanceEmitted || verifyEmitted
+      ? stripStorySectionsForTaskInstructions(task.body ?? '', {
+          acceptance: acceptanceEmitted,
+          verify: verifyEmitted,
+        })
+      : task.body;
   sections.push({
     name: 'taskInstructions',
     priority: DEFAULT_SECTION_PRIORITIES.taskInstructions,
     elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.taskInstructions,
-    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${task.body}`,
+    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${taskBody}`,
     source: { kind: 'ticket', ref: String(task.id) },
   });
 

package/.agents/scripts/lib/orchestration/doc-reader.js

@@ -4,6 +4,35 @@ import { getPaths } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
 import { applyBudget } from './planning-context-budget.js';
 
+/**
+ * Read an explicit list of doc files relative to `docsRoot`, returning one
+ * `{ name, path, content }` object per file that exists and reads cleanly.
+ * Missing or unreadable files are skipped silently (mirrors
+ * {@link readDocsFromRoot}'s per-file try/catch). Order is preserved from the
+ * input list. This is the shared read/normalize seam the per-Epic docs digest
+ * builds on (Story #4338) so there is a single home for the fs read path.
+ *
+ * @param {{ files: string[], docsRoot?: string }} args
+ * @returns {Promise<Array<{ name: string, path: string, content: string }>>}
+ */
+export async function readDocFiles({ files, docsRoot } = {}) {
+  const list = Array.isArray(files) ? files : [];
+  const root =
+    typeof docsRoot === 'string' && docsRoot.length > 0 ? docsRoot : '.';
+  const reads = list.map(async (name) => {
+    const full = path.join(root, name);
+    try {
+      const stat = await fs.promises.stat(full);
+      if (!stat.isFile()) return null;
+      const content = await fs.promises.readFile(full, 'utf-8');
+      return { name, path: name, content };
+    } catch (_e) {
+      return null;
+    }
+  });
+  return (await Promise.all(reads)).filter(Boolean);
+}
+
 async function readDocsFromRoot(docsRoot, settings) {
   const explicit =
     Array.isArray(settings.docsContextFiles) &&

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -0,0 +1,134 @@
+/**
+ * docs-digest.js — per-Epic docs digest builder (Story #4338).
+ *
+ * `/deliver` story sub-agents previously re-read every file in
+ * `project.docsContextFiles` on every Story, re-paying the full docs payload
+ * per child. This module produces a single **digest** — one compact markdown
+ * outline per configured doc — that the parent threads into every child prompt
+ * once. The digest gives each child enough shape (path, size, heading outline
+ * with line numbers, and the first paragraph under each `##` section) to decide
+ * which full files to pull on demand, instead of ingesting the whole set up
+ * front.
+ *
+ * The heavy lifting of reading + normalizing doc bodies is delegated to
+ * `doc-reader.js` (`readDocFiles`), keeping a single home for the fs read path.
+ */
+
+import { readDocFiles } from './doc-reader.js';
+
+/**
+ * Level-2 / level-3 markdown heading matcher. Mirrors the outline granularity
+ * the planning-context budget already uses so the two surfaces agree on what a
+ * "section" is.
+ */
+const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
+
+function byteLen(s) {
+  if (s == null) return 0;
+  return Buffer.byteLength(String(s), 'utf-8');
+}
+
+/**
+ * Extract the heading outline (level + text + 1-based line number) from a
+ * markdown body. Line numbers let a child jump straight to the section it
+ * needs when it pulls the full file.
+ *
+ * @param {string} content
+ * @returns {Array<{ level: number, text: string, line: number }>}
+ */
+function extractOutline(content) {
+  if (!content) return [];
+  const lines = String(content).split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = HEADING_RE.exec(lines[i]);
+    if (m) out.push({ level: m[1].length, text: m[2], line: i + 1 });
+  }
+  return out;
+}
+
+/**
+ * The first non-empty paragraph that follows a given heading line, up to the
+ * next heading or a blank-line paragraph break. Returns '' when the section
+ * has no prose (e.g. a heading immediately followed by a sub-heading).
+ *
+ * @param {string[]} lines full doc split into lines
+ * @param {number} headingLine 1-based line of the heading
+ * @returns {string}
+ */
+function firstParagraphAfter(lines, headingLine) {
+  const para = [];
+  for (let i = headingLine; i < lines.length; i++) {
+    const line = lines[i];
+    if (HEADING_RE.test(line)) break;
+    if (line.trim() === '') {
+      if (para.length > 0) break;
+      continue;
+    }
+    para.push(line.trim());
+  }
+  return para.join(' ').trim();
+}
+
+/**
+ * Render one doc's digest section: path + byte size, then a bulleted heading
+ * outline where each `##` bullet carries the first paragraph beneath it.
+ *
+ * @param {{ path: string, content: string }} doc
+ * @returns {string} markdown block
+ */
+function renderDocSection(doc) {
+  const content = typeof doc.content === 'string' ? doc.content : '';
+  const lines = content.split(/\r?\n/);
+  const outline = extractOutline(content);
+  const size = byteLen(content);
+
+  const parts = [`### \`${doc.path}\` (${size} bytes)`, ''];
+  if (outline.length === 0) {
+    parts.push('_No `##`/`###` headings._', '');
+    return parts.join('\n');
+  }
+
+  for (const h of outline) {
+    const indent = h.level === 3 ? '  ' : '';
+    parts.push(`${indent}- L${h.line} \`${'#'.repeat(h.level)}\` ${h.text}`);
+    if (h.level === 2) {
+      const para = firstParagraphAfter(lines, h.line);
+      if (para) parts.push(`${indent}  ${para}`);
+    }
+  }
+  parts.push('');
+  return parts.join('\n');
+}
+
+/**
+ * Build the per-Epic docs digest markdown from the configured docs context
+ * files. Missing files are skipped silently (the read seam returns only the
+ * files it could stat + read). Returns `null` when there is nothing to digest
+ * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
+ * `docsDigestPath` rather than writing an empty file.
+ *
+ * @param {{ docsContextFiles?: string[], docsRoot?: string }} args
+ * @returns {Promise<string|null>} the digest markdown, or null when there are
+ *   no files to digest.
+ */
+export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
+  const files = Array.isArray(docsContextFiles) ? docsContextFiles : [];
+  if (files.length === 0) return null;
+
+  const docs = await readDocFiles({ files, docsRoot });
+  if (docs.length === 0) return null;
+
+  const header = [
+    '# Docs digest',
+    '',
+    'Per-Epic outline of the project docs context set. Each entry lists the',
+    'file path, byte size, and its heading outline (with line numbers) plus',
+    'the first paragraph under each `##` section. Read the full file on demand',
+    'when a section looks relevant — do **not** ingest the whole set per Story.',
+    '',
+  ].join('\n');
+
+  const sections = docs.map(renderDocSection).join('\n');
+  return `${header}\n${sections}`.replace(/\n+$/, '\n');
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/refresh-commit.js

@@ -32,6 +32,7 @@ import { Logger as DefaultLogger } from '../../../../Logger.js';
 import {
   calculateAll as defaultCalculateAll,
   scanDirectory as defaultScanDirectory,
+  isIgnoredByGlobs as isIgnoredByGlobsMi,
 } from '../../../../maintainability-utils.js';
 
 /**
@@ -101,7 +102,20 @@ export function buildKindScorer({
           const underTarget = targetAbsDirs.some(
             (root) => abs === root || abs.startsWith(`${root}${path.sep}`),
           );
-          if (underTarget) sourceList.push(abs);
+          // Apply `ignoreGlobs` here too — the full-scope walk drops
+          // ignore-matched files via `scanDirectory`, so the diff-scope path
+          // must do the same or an ignored-but-changed file (e.g. one matched
+          // by `config-settings-schema*.js`) enters `rows` and drags the
+          // `rollup["*"].min` below the maintainability floor. This mirrors the
+          // canonical `buildDefaultMaintainabilityScorer` (refresh-service.js,
+          // Story #4293); the story-close auto-refresh routes through this
+          // scorer, not that one, so the fix has to live here too.
+          if (
+            underTarget &&
+            !isIgnoredByGlobsMi(abs, miIgnoreGlobs, effectiveCwd)
+          ) {
+            sourceList.push(abs);
+          }
         }
       }
       const scores = await calculateAll(sourceList);

package/.agents/scripts/lib/qa/console-allowlist.js

@@ -19,10 +19,11 @@
  *
  * The emitted finding aligns with the `F#` finding shape from Tech Spec #3285
  * (`{ id, classification, surface, symptom, likelyRootCause, disposition,
- * acceptance, evidence: { console[], network[] } }`). Finding-shape *schema*
- * validation (`qa-finding.schema.json`) is a sibling Story; this module only
- * produces the console-derived subset and leaves richer enrichment
- * (likely-root-cause heuristics, drafting) to later layers.
+ * acceptance, evidence: { console[], network[] } }`). This module produces the
+ * console-derived subset; `/qa-run` (Story #4330) maps each such finding onto a
+ * `QaLedgerItem` (`qa-ledger.schema.json`) before routing it through the shared
+ * classify/route/dedup/promote core, leaving richer enrichment
+ * (likely-root-cause heuristics, drafting) to those later layers.
  */
 
 /**

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -1,9 +1,11 @@
 /**
- * `qa` contract resolver — Epic #3214, Story #3294.
+ * `qa` contract resolver — Epic #3214, Story #3294; environment-keyed
+ * contract added by Epic #4326, Story #4327.
  *
  * The agent-driven QA harness (`/qa-run`) needs the
  * consumer's `.agentrc.json` `qa` block to know where the `.feature` root
- * lives, how to sign in, and which personas the seam accepts. The block is
+ * lives, which deployment targets (`environments`) exist and how to sign in
+ * to each, and which personas the seam accepts. The block is
  * *optional in the schema* (most repos never bind the harness, so config
  * validation must not break them — see Tech Spec #3285 § "qa contract
  * block"), which means presence is enforced at run time by this resolver
@@ -16,8 +18,14 @@
  *     exists.
  *   - Malformed block → throw an error naming the offending field so the
  *     operator can fix `.agentrc.json` without spelunking the schema.
- *   - Well-formed block → return the normalized contract object with the
- *     two optional fields (`consoleAllowlist`, `designTokens`) defaulted.
+ *   - Well-formed block → return the normalized contract object with
+ *     `environments` + `defaultEnvironment` and the two optional fields
+ *     (`consoleAllowlist`, `designTokens`) defaulted.
+ *
+ * `resolveQaEnvironment(contract, target)` selects one environment per
+ * harness invocation — by exact name or by raw-URL origin match against each
+ * environment's `baseUrl` — and throws loudly (naming the known environments)
+ * on an unknown name or unmatched URL.
  */
 
 import Ajv from 'ajv';
@@ -36,10 +44,19 @@ import { QA_SCHEMA } from '../config-settings-schema.js';
 export const QA_REQUIRED_FIELDS = Object.freeze([
   'featureRoot',
   'fixturesManifest',
-  'signInSeam',
+  'environments',
   'personas',
 ]);
 
+/**
+ * The environment name whose `allowWrites` defaults to `true` when the
+ * consumer omits the flag. Every other environment defaults to read-only
+ * (`allowWrites: false`) so an unguarded remote target cannot accept writes
+ * by accident — only the conventional `local` environment is write-enabled
+ * by default.
+ */
+const WRITE_ENABLED_DEFAULT_ENVIRONMENT = 'local';
+
 /** Defaults applied to the optional fields of a well-formed contract. */
 export const QA_CONTRACT_DEFAULTS = Object.freeze({
   consoleAllowlist: Object.freeze([]),
@@ -48,7 +65,7 @@ export const QA_CONTRACT_DEFAULTS = Object.freeze({
 
 const ABSENT_MESSAGE =
   'qa: this project has not bound the QA harness — add a `qa` block to ' +
-  '.agentrc.json (featureRoot, fixturesManifest, signInSeam, personas) ' +
+  '.agentrc.json (featureRoot, fixturesManifest, environments, personas) ' +
   'before invoking the QA harness. See .agents/docs/agentrc-reference.json for the ' +
   'full contract shape.';
 
@@ -127,7 +144,8 @@ function describeError(err) {
  * @returns {{
  *   featureRoot: string,
  *   fixturesManifest: string,
- *   signInSeam: object,
+ *   environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>,
+ *   defaultEnvironment: string,
  *   personas: Record<string, object>,
  *   personaNames: string[],
  *   consoleAllowlist: string[],
@@ -173,10 +191,28 @@ export function resolveQaContract(config) {
 
   const { personas, personaNames } = normalizePersonas(qa.personas);
 
+  // Clone each environment so callers cannot mutate the resolver's input.
+  const environments = {};
+  for (const [name, env] of Object.entries(qa.environments)) {
+    environments[name] = { ...env };
+  }
+
+  // The default environment is the conventional `local` target when present,
+  // otherwise the first-declared environment. `resolveQaEnvironment(contract)`
+  // (no target) resolves to this one.
+  const environmentNames = Object.keys(environments);
+  const defaultEnvironment = Object.hasOwn(
+    environments,
+    WRITE_ENABLED_DEFAULT_ENVIRONMENT,
+  )
+    ? WRITE_ENABLED_DEFAULT_ENVIRONMENT
+    : environmentNames[0];
+
   return {
     featureRoot: qa.featureRoot,
     fixturesManifest: qa.fixturesManifest,
-    signInSeam: qa.signInSeam,
+    environments,
+    defaultEnvironment,
     personas,
     personaNames,
     consoleAllowlist: Array.isArray(qa.consoleAllowlist)
@@ -188,3 +224,103 @@ export function resolveQaContract(config) {
         : qa.designTokens,
   };
 }
+
+/**
+ * Normalize a value to its URL origin (`protocol//host:port`), or `null` when
+ * it is not a parseable absolute URL. Used to match a raw-URL `target` against
+ * each environment's `baseUrl` by origin, so a target carrying a path,
+ * query-string, or trailing slash still resolves to the right environment.
+ *
+ * @param {string} value
+ * @returns {string | null}
+ */
+function toOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a single QA environment for one harness invocation.
+ *
+ * `target` selects which of the contract's `environments` to run against:
+ *   - **Omitted / falsy** → the contract's `defaultEnvironment`.
+ *   - **Exact environment name** → that environment.
+ *   - **Raw URL** → the environment whose `baseUrl` shares the same origin
+ *     (`protocol//host:port`), so a target with a path or query still matches.
+ *
+ * Resolution is name-first: a `target` that exactly names an environment wins
+ * even if it also happens to parse as a URL.
+ *
+ * `allowWrites` is resolved to an explicit boolean on the returned object: the
+ * environment's own value when set, otherwise `true` only for the conventional
+ * `local` environment and `false` for every other target — an unguarded remote
+ * environment is read-only unless the consumer opts in.
+ *
+ * Fails **loudly**: an unknown name or an unmatched URL throws an error that
+ * names the known environments so the operator can correct the invocation.
+ *
+ * @param {{ environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
+ *   A contract returned by `resolveQaContract`.
+ * @param {string} [target] Environment name or raw URL. Omit for the default.
+ * @returns {{ name: string, baseUrl: string, signInSeam: object, allowWrites: boolean }}
+ * @throws {Error} on an unknown name or unmatched URL.
+ */
+export function resolveQaEnvironment(contract, target) {
+  const environments = contract?.environments;
+  if (
+    environments == null ||
+    typeof environments !== 'object' ||
+    Object.keys(environments).length === 0
+  ) {
+    throw new Error(
+      'qa: cannot resolve an environment — the contract carries no ' +
+        '`environments`. Call resolveQaContract first.',
+    );
+  }
+
+  const known = Object.keys(environments);
+  const knownList = known.map((name) => `\`${name}\``).join(', ');
+
+  // No target → the default environment.
+  const name =
+    target == null || target === '' ? contract.defaultEnvironment : target;
+
+  // Exact-name match wins first (a name that also parses as a URL still
+  // resolves by name).
+  let resolvedName = Object.hasOwn(environments, name) ? name : null;
+
+  // Otherwise try to match the target as a raw URL against each baseUrl origin.
+  if (resolvedName === null) {
+    const targetOrigin = toOrigin(name);
+    if (targetOrigin !== null) {
+      resolvedName =
+        known.find(
+          (envName) => toOrigin(environments[envName].baseUrl) === targetOrigin,
+        ) ?? null;
+    }
+  }
+
+  if (resolvedName === null) {
+    throw new Error(
+      `qa: unknown environment \`${name}\` — the contract declares ${knownList}. ` +
+        'Pass an exact environment name or a URL whose origin matches one of ' +
+        'their baseUrl values.',
+    );
+  }
+
+  const env = environments[resolvedName];
+  const allowWrites =
+    typeof env.allowWrites === 'boolean'
+      ? env.allowWrites
+      : resolvedName === WRITE_ENABLED_DEFAULT_ENVIRONMENT;
+
+  return {
+    name: resolvedName,
+    baseUrl: env.baseUrl,
+    signInSeam: env.signInSeam,
+    allowWrites,
+  };
+}