@dombaras/agent-harness 0.1.1 → 0.1.5

package/templates/.agents/skills/planner/SKILL.md

@@ -10,14 +10,30 @@ You decompose the task and produce the dispatch plan the orchestrator executes.
 
 ## Output contract (always return)
 
-1. **Dispatch plan** — ordered list of `persona → model → exact prompt scope → dependencies`.
-2. **Parallel batches** — group independent dispatches to run concurrently (one message, multiple `task` calls).
-3. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final integration) kept on the main model.
+Never hand a persona a bare metric ("get under N lines", "type everything"). If a
+task cannot be bounded by the spec below, split it further or flag it — do not
+dispatch it broad.
+
+1. **Dispatch plan** — ordered list of entries, each with:
+   - `persona → model`
+   - **Objective** — one sentence naming a single deliverable.
+   - **Owned files** — exact paths this persona may edit.
+   - **Read-only files** — explicit out-of-scope paths (governance, memory, skills, other screens).
+   - **Shared contracts** — for each shared module/type: `owns` or `consumes` (exactly one owner per contract).
+   - **Done =** — the exact gate command(s) + observable metric (e.g. `tsc --noEmit` clean, `\bany\b` count 0), so success is verifiable, not self-reported.
+   - **Dependencies** — which other dispatch, if any, must complete first.
+2. **Parallel batches** — group only DISJOINT entries (disjoint owned files AND disjoint shared contracts). Serialize personas that would touch the same files or emit the same shared contract; put the contract owner first.
+3. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final integration, acceptance re-verification) kept on the main model.
 4. **Risk flags** — any ambiguity that needs the user before proceeding.
 
 ## Rules
 
 - Read `.agents/memory/model-routing.md` for the persona → model tiers.
+- Read `.agents/memory/flow-map.md`. If the task's behavior maps to a flow whose `surfaces:` cross
+  codebases/layers (e.g. web + `mobile/` + an API route), the dispatch plan MUST include the sibling
+  surface's persona (e.g. `mobile-engineer`) — or explicitly mark the sibling out-of-scope so
+  `qa-architect` records it as `audited: deferred` in the QA plan's flow-closure audit. A change to
+  one surface that never mentions the twin is a plan defect, not scope.
 - Never dispatch a persona for work the main model should just do (reads, commits, integration).
 - Prefer the most specific persona; if none clearly fits, ask the user rather than guess.
 - Dispatch independent subagents in parallel; serialize only when one depends on another's output.

package/templates/.agents/skills/qa-architect/SKILL.md

@@ -11,9 +11,28 @@ You own QA **strategy** — risk assessment, tier selection, and progression tes
 ## Output contract (always return)
 
 1. **Risk assessment** — blast radius (files/subsystems touched) + risk level `LOW | MEDIUM | HIGH`.
-2. **Selected tier + command(s)** — from the matrix below.
-3. **Progression plan** — any NEW tests to author (and where) before the run, or a statement that no new tests are needed.
-4. **Handoff to qa-runner** — exact commands + pass criteria.
+2. **Selected tier + command(s)** — from the matrix below, chosen by **coverage, not path-label** (see Diff coverage map).
+3. **Diff coverage map (MANDATORY)** — enumerate every changed path, one entry per line, as a
+   `Changed path -> executing test/assertion` table. A tier command matches a change only when its
+   backing suite ACTUALLY exercises that path/state. Any change with no runtime assertion is a **GAP**
+   — you must author a progression test for it (Progression vs regression below). Persist the same map
+   into `.agents/memory/qa-plan.md` under `## Coverage map` (this is what `npm run test:qa-plan` gates on).
+3b. **Flow closure audit (MANDATORY — "fix one, fix all")** — read `.agents/memory/flow-map.md`. For
+   every flow whose `surfaces:` intersect this diff, address in the plan's
+   `## Parallel-surface & variant audit` EVERY sibling surface (the same behavior living in another
+   codebase/layer — web vs `mobile/`, API route, another page) and EVERY declared `variant`. Each
+   entry is `- <surface> -> <assertion>` or `- <surface> audited: <reason>`; each variant is
+   `- flow: <name> variant: <label> -> <assertion>` or `... audited: <reason>`. A sibling that is
+   legitimately out of scope is NOT left unnamed — it is `audited: deferred — logged in handoff.md`.
+   `test:qa-plan` fails on any sibling surface or declared variant the plan does not name.
+   If `flow-map.md` has no flows, note it and proceed (the gate warns, does not block; register the
+   flow in flow-map.md when you touch its behavior).
+4. **Progression plan** — any NEW tests to author (and where) before the run, or a statement that no new tests are needed. For every **GAP** you MUST author a progression test that renders/executes the real path (real route/API — never a shell mock) and drives it click-through from the user's perspective.
+5. **Handoff to qa-runner** — exact commands + pass criteria.
+
+> The rule the whole plan rests on: a tier label never proves coverage. `test:quick` at label "Tier 1
+> components" does NOT cover a component unless its script actually exercises it. If the project's
+> backing script for a tier doesn't reach a changed path, that's a **coverage gap**, not a passing run.
 
 ## Dynamic Test Selection Matrix
 
@@ -29,7 +48,7 @@ You own QA **strategy** — risk assessment, tier selection, and progression tes
 Diff-aware planning helper: `npm run qa:plan [-- --json] [-- --base main]`.
 
 > The tier commands above are **project-provided** — the harness ships only
-> `test:dispatch` and `test:governance`. If a referenced script is missing,
+> `test:dispatch`, `test:governance`, and `test:qa-plan`. If a referenced script is missing,
 > route that finding to the orchestrator (`scripts/qa/check-qa-scripts.js`
 > verifies wiring mechanically).
 
@@ -40,6 +59,19 @@ Diff-aware planning helper: `npm run qa:plan [-- --json] [-- --base main]`.
 
 Author new assertion pathways in `scripts/verify-all.js` (API), `scripts/qa/routes.js` (routes), or `scripts/qa/tests/*.test.ts` (mobile/smoke), then hand the run to `qa-runner`. Once passing, the test graduates permanently into the regression baseline.
 
+## Coverage gate (`npm run test:qa-plan`)
+
+Every change that touches code paths MUST have a coverage map persisted in
+`.agents/memory/qa-plan.md` (or a scoped `waived:` entry per path) before the run can be declared
+verified — AND a flow-closure audit of every touched flow's sibling surfaces and declared variants
+(`.agents/memory/flow-map.md`). The mechanical gate checks the live `git diff` against both and
+fails on any uncovered code path or unaddressed sibling/variant. If you are not dispatched for a
+change, the main orchestrator performs your role and writes the same plan itself — a change with
+code-path edits and no QA plan is a rules violation.
+
 ## Iron law
 
-Never declare a change verified from static typing alone — every tier must execute a real runtime path. If the suite does not exercise the modified path, author a progression test first.
+Never declare a change verified from static typing alone — every tier must execute a real runtime path
+that exercises the MODIFIED code. A suite that touches unrelated code proves nothing about this change.
+If the suite does not exercise the modified path, author a progression test first and cover the GAP in
+the coverage map.

package/templates/.agents/skills/qa-runner/SKILL.md

@@ -17,6 +17,7 @@ You **execute**. A `qa-architect` (or the orchestrator) tells you which tier to
 ## Responsibilities
 
 - Run the tier you are given: `npm run test:quick` / `test:routes` / `test:api` / `test:verify` / `test:security`.
+- Run the diff-coverage gate: `npm run test:qa-plan` and report uncovered paths verbatim.
 - Data/catalog E2E journey (100 records): `npx ts-node scripts/test-catalog.ts`.
 - Catalog test-data cleanup when asked (via the catalog reset endpoint/scripts).
 

package/templates/.opencode/agents/data-engineer.md

@@ -3,6 +3,15 @@ description: Use for catalog/data ingestion and entity resolution — external-s
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Data Engineer. Read and follow the complete persona instructions in `.agents/skills/data-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/devops-engineer.md

@@ -3,6 +3,15 @@ description: Use for deployment, CI/CD, cron/scheduling, env & secrets managemen
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} DevOps Engineer. Read and follow the complete persona instructions in `.agents/skills/devops-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/diagnostics-expert.md

@@ -4,6 +4,15 @@ mode: subagent
 model: opencode/deepseek-v4-pro
 temperature: 0.1
 steps: 30
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Diagnostics Expert. Read and follow the complete persona instructions in `.agents/skills/diagnostics-expert/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/frontend-engineer.md

@@ -3,6 +3,15 @@ description: Use when writing or fixing web React / Next.js / Tailwind / shadcn
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Frontend Engineer. Read and follow the complete persona instructions in `.agents/skills/frontend-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/mobile-engineer.md

@@ -3,6 +3,15 @@ description: Use when writing or fixing Expo / React Native native code — nati
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Mobile Engineer. Read and follow the complete persona instructions in `.agents/skills/mobile-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/qa-architect.md

@@ -12,7 +12,8 @@ You are the {{PROJECT_NAME}} QA Architect. Read and follow the complete persona
 
 ## Scope & integrity (non-negotiable)
 
-- Edit ONLY files your role owns (progression-test authoring). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, other personas' files, and unrelated code are READ-ONLY absent an explicit orchestrator grant.
+- Edit ONLY files your role owns (progression-test authoring + `.agents/memory/qa-plan.md`). `opencode.json`, other `.agents/memory/*`, `.agents/rules/*`, other personas' files, and unrelated code are READ-ONLY absent an explicit orchestrator grant.
 - You design and author tests only — route execution to `qa-runner`. Never fabricate dispatch-log or handoff entries that did not actually occur.
+- Persist your plan's `## Coverage map` into `.agents/memory/qa-plan.md` — `npm run test:qa-plan` gates every changed code path against it. A change with code-path edits and no coverage map is not verifiable.
 
 Return your final message in this exact order: **Result** (what shipped / decided) -> **Evidence** (files changed, commands run, observed output) -> **Deferred & risks** (follow-ups the orchestrator must handle). Keep it under ~15 lines.

package/templates/.opencode/agents/security-engineer.md

@@ -3,6 +3,15 @@ description: Use when a change touches auth, secrets, input validation, external
 mode: subagent
 model: opencode/deepseek-v4-pro
 steps: 30
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Security Engineer. Read and follow the complete persona instructions in `.agents/skills/security-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/system-architect.md

@@ -3,6 +3,15 @@ description: Use when changing the Prisma schema, data model, multi-tenant bound
 mode: subagent
 model: opencode/deepseek-v4-pro
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} System Architect. Read and follow the complete persona instructions in `.agents/skills/system-architect/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/ui-designer.md

@@ -3,6 +3,15 @@ description: Use when designing the visual system — design tokens, theming, an
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} UI Designer. Read and follow the complete persona instructions in `.agents/skills/ui-designer/SKILL.md`, then carry out the task.

package/templates/AGENTS.md

@@ -5,6 +5,7 @@ The always-loaded rules summary lives in [`.agents/rules/00-operating.md`](.agen
 It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
 
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
+- **Every change touching code paths gets a QA plan** (`.agents/memory/qa-plan.md`) from `qa-architect` — if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - **At session start**, read `.agents/memory/locations.md` and `.agents/memory/model-routing.md`.
 
 > Deployed and maintained by `@dombaras/agent-harness` (`npx @dombaras/agent-harness init` / `update`). Do not hand-edit harness-owned files — regenerate them and commit the deltas.

package/templates/scripts/qa/check-dispatch-config.js

@@ -12,6 +12,8 @@
  *   3. Every agent body carries the output-contract marker (Result / Evidence /
  *      Deferred & risks) so subagents return a consistent report shape.
  *   4. `opencode.json` main `model` + `small_model` are also real provider IDs.
+ *   5. `.agents/memory/model-routing.md` does not name a concrete model that is
+ *      no longer pinned by any agent or opencode.json (doc↔config drift).
  *
  * Allowlist refresh (only when the provider adds/removes models):
  *   npx opencode models > scripts/qa/models.allowlist.txt
@@ -62,7 +64,12 @@ function frontmatterModel(file) {
   return modelLine.replace(/^model:\s*/i, "").trim();
 }
 
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // 1. every agent file exists, pins a real model, references a real skill
+const agentModels = new Set();
 const agentNames = fs
   .readdirSync(agentsDir)
   .filter((f) => f.endsWith(".md"))
@@ -72,6 +79,7 @@ for (const f of agentNames) {
   const name = f.replace(/\.md$/, "");
   const file = path.join(agentsDir, f);
   const model = frontmatterModel(file);
+  if (model) agentModels.add(model);
   const body = fs.readFileSync(file, "utf8");
   const skillMd = path.join(skillsDir, name, "SKILL.md");
   if (!model) fail(`agent ${f}: missing frontmatter model: (all agents must pin a model)`);
@@ -95,16 +103,40 @@ if (skillNames.join("|") === [...agentNames].map((f) => f.replace(/\.md$/, "")).
   pass(`persona parity: ${agentNames.length} agents == ${skillNames.length} skills`);
 
 // 3. opencode.json main + small model are real provider IDs
+const configModels = new Set();
 if (fs.existsSync(opencodeJson)) {
   const cfg = JSON.parse(fs.readFileSync(opencodeJson, "utf8"));
   for (const key of ["model", "small_model"]) {
     const v = cfg[key];
+    if (v) configModels.add(v);
     if (!v) warn(`opencode.json: no \`${key}\` set`);
     else if (allowlist.has(v)) pass(`opencode.json ${key} \`${v}\` is a real provider model`);
     else fail(`opencode.json ${key} \`${v}\` NOT in provider allowlist`);
   }
 } else warn("opencode.json not found (skip)");
 
+// 4. model-routing.md ↔ model: pin consistency (doc↔config drift)
+const usedModels = new Set([...agentModels, ...configModels]);
+const modelRoutingFile = path.join(root, ".agents", "memory", "model-routing.md");
+if (fs.existsSync(modelRoutingFile)) {
+  const doc = fs.readFileSync(modelRoutingFile, "utf8");
+  const modelPattern = [...allowlist].map(escapeRe).join("|");
+  const mentioned = new Set();
+  const re = new RegExp(modelPattern, "g");
+  let m;
+  while ((m = re.exec(doc)) !== null) mentioned.add(m[0]);
+  if (mentioned.size === 0) {
+    pass("model-routing.md names no concrete model IDs (tier policy only) — nothing to cross-check");
+  } else {
+    for (const mid of mentioned) {
+      if (usedModels.has(mid)) pass(`model-routing.md \`${mid}\` matches an actual pin`);
+      else fail(`model-routing.md references \`${mid}\` but no agent/config pins it (doc↔config drift)`);
+    }
+  }
+} else {
+  warn("model-routing.md not found (skip doc↔config drift check)");
+}
+
 console.log(
   `\nRESULT: ${agentNames.length} agents checked \u2014 ` +
     (failures.length ? `${failures.length} FAILURE(S)` : "0 failures") +

package/templates/scripts/qa/check-qa-plan.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * test:qa-plan — diff-coverage gate (harness-shipped).
+ *
+ * The anti-verification-from-unrelated-suites gate. A tier label never proves
+ * coverage; this gate forces a change's QA plan to actually cover the code it
+ * modified — otherwise "verified" is meaningless.
+ *
+ * Two stages:
+ *
+ *  1. Coverage map — inspects the live git diff and requires every changed CODE
+ *     path to appear in the QA plan's `## Coverage map` (persisted by
+ *     qa-architect, or by the main orchestrator as the qa-architect fallback)
+ *     BEFORE a change may be declared verified. Trivial diffs (copy/docs/not
+ *     code) and waivered paths are exempt.
+ *
+ *  2. Flow closure — reads `.agents/memory/flow-map.md` (project-owned): a
+ *     registry of user-facing flows, each listing the SURFACES that implement the
+ *     same behavior (web / mobile / API — any codebase/layer) and its optional
+ *     VARIANTS. Any flow whose surfaces intersect this diff must have every
+ *     sibling surface and every declared variant addressed in the plan's
+ *     `## Parallel-surface & variant audit` (covered `->` or `audited:` with a
+ *     reason). This is the gate that makes "Fix One, Fix All" mechanical: a
+ *     web-only diff can no longer silently leave the mobile twin on old behavior.
+ *     If flow-map.md is absent or lists no flows, the stage warns but never fails
+ *     (backward compatible — projects opt into flow closure by filling it in).
+ *
+ *   node scripts/qa/check-qa-plan.js                 # diff vs HEAD
+ *   node scripts/qa/check-qa-plan.js --base main     # diff vs a ref
+ *   node scripts/qa/check-qa-plan.js --strict        # non-code changes too
+ *
+ * Exit 0 on: no code-path changes, full coverage, valid waivers, full flow closure.
+ * Exit 1 on: a changed code path with no covering assertion/waiver, or a flow
+ *            sibling surface / declared variant the QA plan does not address.
+ */
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const root = path.resolve(__dirname, "..", "..");
+
+const argv = process.argv.slice(2);
+const base = (argv.find((a) => a.startsWith("--base=")) || "").split("=")[1] || "HEAD";
+const strict = argv.includes("--strict");
+
+// Paths that are tooling/harness, not application code under test. A change
+// that only touches these needs no runtime QA plan (they are guarded by
+// test:dispatch / test:governance themselves).
+const TOOLING = [
+  "opencode.json",
+  ".harness.json",
+  ".opencode/",
+  ".agents/",
+  "scripts/qa/",
+  ".github/",
+  "package.json",
+];
+// Non-code files never need a runtime path (copy/docs/styling/data-flat).
+const NON_CODE = /\.(md|mdx|png|jpg|jpeg|gif|svg|webp|ico|json|lock|txt|env|yml|yaml|toml|csv)$/i;
+
+const CODE = /\.(ts|tsx|js|jsx|css|scss|sass|prisma|sql)$/i;
+
+function norm(p) {
+  return p.replace(/\\/g, "/");
+}
+
+function gitChangedFiles() {
+  let files = [];
+  try {
+    const out = execFileSync("git", ["diff", "--name-only", base, "--"], {
+      cwd: root,
+      encoding: "utf8",
+    });
+    files = out.split(/\r?\n/).filter(Boolean);
+  } catch (e) {
+    // 128 = not a git repo / bad ref / no base history (e.g. empty repo).
+    if (e.status === 128) return null;
+    throw e;
+  }
+  // include untracked files so brand-new sources can't silently skip the gate
+  try {
+    const untracked = execFileSync(
+      "git",
+      ["ls-files", "--others", "--exclude-standard", "--", root],
+      { cwd: root, encoding: "utf8" }
+    )
+      .split(/\r?\n/)
+      .filter(Boolean);
+    files = [...new Set([...files, ...untracked])];
+  } catch (_) {
+    /* ls-files is best-effort */
+  }
+  return files.map(norm);
+}
+
+function isTooling(p) {
+  const n = norm(p);
+  return TOOLING.some((t) => n === t || n.startsWith(t));
+}
+
+/* Parse the QA plan file into { covered:Set, waivers:Set } of normalized paths.
+ * Coverage map format (one entry per changed path, under `## Coverage map`):
+ *   - components/return/ReturnConfirmDrawer.tsx -> test:quick::progression (click-through)
+ * Waivers live anywhere and carry a reason on the same line:
+ *   waived: components/nav.tsx reason: pure-copy change, no runtime path
+ */
+function parsePlan(file) {
+  const out = { covered: new Set(), waivers: new Set() };
+  if (!fs.existsSync(file)) return out;
+  const src = fs.readFileSync(file, "utf8");
+  const lines = src.split(/\r?\n/);
+
+  // Coverage map section only
+  let inMap = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^#{1,6}\s*Coverage map\s*$/i.test(line)) {
+      inMap = true;
+      continue;
+    }
+    if (/^[#;/]/.test(line)) continue;
+    if (inMap && /^#{1,6}\s/.test(line)) inMap = false;
+    if (!inMap) continue;
+
+    const m = line.match(/^[-*]\s*["']?([^\s"'>]+)/);
+    if (m) out.covered.add(norm(m[1]));
+  }
+
+  // Waivers (anywhere) — path then reason
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!/\bwaived:\s*\S/i.test(line)) continue;
+    const p = (line.match(/\bwaived:\s*["']?([^\s"',]+)/i) || [])[1];
+    if (p && /\breason:\s*\S/i.test(line)) out.waivers.add(norm(p));
+  }
+  return out;
+}
+
+function isCovered(pathi, covered, waivers) {
+  if (covered.has(pathi) || waivers.has(pathi)) return true;
+  // directory-prefix coverage (a plan may cover a whole folder)
+  for (const c of covered) if (pathi.startsWith(c.replace(/\/?$/, "/"))) return true;
+  for (const w of waivers) if (pathi.startsWith(w.replace(/\/?$/, "/"))) return true;
+  return false;
+}
+
+/* Parse `.agents/memory/flow-map.md` into [{ name, surfaces:[], variants:[] }].
+ * Format (one flow per `## flow:` header):
+ *   ## flow: return
+ *   behavior: "Mark as Returned" — optional condition payload (condition selector)
+ *   surfaces: components/LendingActionDrawers.tsx, mobile/features/return/ReturnStatusSheet.tsx, app/api/transactions/[id]/return/route.ts
+ *   variants: condition-selector-present, condition-selector-absent
+ */
+function parseFlowMap(file) {
+  const flows = [];
+  if (!fs.existsSync(file)) return flows;
+  let cur = null;
+  for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    const h = line.match(/^#{1,6}\s*flow:\s*(.+)$/i);
+    if (h) {
+      cur = { name: h[1].trim(), surfaces: [], variants: [] };
+      flows.push(cur);
+      continue;
+    }
+    if (/^[#;]/.test(line)) continue;
+    if (!cur) continue;
+    const s = line.match(/^surfaces?:\s*(.+)$/i);
+    if (s) cur.surfaces = s[1].split(",").map((x) => norm(x.trim())).filter(Boolean);
+    const v = line.match(/^variants?:\s*(.+)$/i);
+    if (v) cur.variants = v[1].split(",").map((x) => x.trim()).filter(Boolean);
+  }
+  return flows.filter((f) => f.name && f.surfaces.length > 0);
+}
+
+/* Parse the plan's `## Parallel-surface & variant audit` entries.
+ * Entry forms:
+ *   - <surface> -> <assertion>
+ *   - <surface> audited: <reason>
+ *   - flow: <name> variant: <label> -> <assertion>
+ *   - flow: <name> variant: <label> audited: <reason>
+ */
+function parseAudit(file) {
+  const entries = [];
+  if (!fs.existsSync(file)) return entries;
+  let inAudit = false;
+  for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^#{1,6}\s*Parallel[ -]surface.{0,40}(?:&\s*|and\s+).{0,40}audit\s*$/i.test(line)) {
+      inAudit = true;
+      continue;
+    }
+    if (/^[#;]/.test(line)) continue;
+    if (inAudit && /^#{1,6}\s/.test(line)) inAudit = false;
+    if (!inAudit) continue;
+
+    const vm = line.match(/^[-*]\s*flow:\s*["']?([^\s"']+)\s+variant:\s*["']?([^\s"']+)\s+(audited:.+|->\s*.+)$/i);
+    if (vm) {
+      entries.push({ flow: vm[1], variant: vm[2], surface: null, disposition: vm[3].trim() });
+      continue;
+    }
+    const pm = line.match(/^[-*]\s*["']?([^\s"'>]+)\s+(audited:.+|->\s*.+)$/);
+    if (pm) entries.push({ surface: norm(pm[1]), disposition: pm[2].trim() });
+  }
+  return entries;
+}
+
+/* True when path a and path b are the same file/dir or one nests under the other
+ * as a directory prefix — lenient matching for surfaces vs coverage/audit paths. */
+function matches(a, b) {
+  const A = norm(a).replace(/\/$/, "");
+  const B = norm(b).replace(/\/$/, "");
+  return A === B || A.startsWith(B + "/") || B.startsWith(A + "/");
+}
+
+const failures = [];
+const pass = (m) => console.log("  \u2713 " + m);
+const fail = (m) => {
+  failures.push(m);
+  console.log("  \u2717 " + m);
+};
+
+console.log("diff-coverage gate \u2014 QA plan covers every changed code path");
+
+const changed = gitChangedFiles();
+if (changed == null) {
+  console.log("  \u26a0 not a git repo or no base history \u2014 coverage gate skipped");
+  console.log("\nRESULT: skipped (0 failures)");
+  process.exit(0);
+}
+if (changed.length === 0) {
+  console.log("  \u2713 no diff vs " + base + " \u2014 nothing to cover");
+  console.log("\nRESULT: green");
+  process.exit(0);
+}
+
+const plan = path.join(root, ".agents", "memory", "qa-plan.md");
+const audit = parseAudit(plan);
+const { covered, waivers } = parsePlan(plan);
+
+console.log(`  checked against: ${path.relative(root, plan)}`);
+
+const changedCode = [];
+for (const f of changed) {
+  if (isTooling(f)) {
+    pass(`${f} (harness/tooling \u2014 self-guarded)`);
+    continue;
+  }
+  if (NON_CODE.test(f) && !strict) {
+    pass(`${f} (non-code \u2014 no runtime path required)`);
+    continue;
+  }
+  if (!CODE.test(f)) {
+    pass(`${f} (not a code path)`);
+    continue;
+  }
+  changedCode.push(f);
+  if (isCovered(f, covered, waivers)) pass(`${f} covered by QA plan`);
+  else
+    fail(
+      `${f} NOT covered \u2014 add it to the \`## Coverage map\` in qa-plan.md (or a waivered entry with a reason)`
+    );
+}
+
+// ------------------------------------------------------------ flow closure
+const flowMap = parseFlowMap(path.join(root, ".agents", "memory", "flow-map.md"));
+const hitFlows = new Set();
+for (const f of flowMap) {
+  if (changedCode.some((c) => f.surfaces.some((s) => matches(c, s)))) hitFlows.add(f);
+}
+
+if (!flowMap.length) {
+  console.log(
+    "  \u26a0 flow-map.md has no flows \u2014 sibling/variant closure NOT enforced (add flows to secure \"Fix One, Fix All\")"
+  );
+} else if (hitFlows.size) {
+  console.log("flow-closure gate \u2014 every sibling surface & variant of a touched flow is addressed");
+  for (const f of flowMap) {
+    if (!hitFlows.has(f)) {
+      pass(`flow "${f.name}" not touched \u2014 no sibling requirement`);
+      continue;
+    }
+    // Sibling surfaces: every declared surface must be addressed by the diff
+    // (as a changed path) or by a named audit entry, or audited with a reason.
+    for (const s of f.surfaces) {
+      if (changedCode.some((c) => matches(c, s))) {
+        continue; // the changed path itself is required in the Coverage map above
+      }
+      const addressed = audit.some((e) => e.surface && matches(e.surface, s));
+      if (addressed) pass(`flow "${f.name}": sibling \`${s}\` addressed in audit`);
+      else
+        fail(
+          `flow "${f.name}": sibling surface \`${s}\` not addressed \u2014 add it to \`## Parallel-surface & variant audit\` as \`-> <assertion>\` or \`audited: <reason>\``
+        );
+    }
+    // Declared variants: each must be named with a disposition for this flow.
+    for (const v of f.variants) {
+      const addressed = audit.some((e) => e.flow && e.variant && e.flow === f.name && e.variant === v);
+      if (addressed) pass(`flow "${f.name}": variant \`${v}\` addressed`);
+      else
+        fail(
+          `flow "${f.name}": declared variant \`${v}\` not addressed \u2014 add \`flow: ${f.name} variant: ${v} -> <assertion>\` or \`... audited: <reason>\` to \`## Parallel-surface & variant audit\``
+        );
+    }
+  }
+}
+
+if (!changedCode.length) {
+  console.log("  \u2713 no application code paths changed");
+}
+console.log(
+  "\nRESULT: " +
+    (failures.length
+      ? `${failures.length} FAILURE(S) \u2014 every changed code path needs a covering assertion or a waivered reason; every touched flow's sibling surfaces & variants must be addressed in the audit`
+      : "green \u2014 all changed code paths have a covering QA plan and all touched flows are closed")
+);
+process.exit(failures.length ? 1 : 0);

package/templates/scripts/qa/check-qa-scripts.js

@@ -22,6 +22,7 @@ const strict = process.argv.includes("--strict");
 const EXPECTED = {
   "test:dispatch": "harness — persona model-pin preflight (shipped)",
   "test:governance": "harness — session-governance gate (shipped)",
+  "test:qa-plan": "harness — diff-coverage + flow-closure gate (changed code paths covered; touched flows' sibling surfaces/variants audited)",
   "test:quick": "Tier 1 — types + translations + mobile smoke",
   "test:routes": "Tier 2 — route/page render",
   "test:api": "Tier 3 — API/ORM edge cases",