@dombaras/agent-harness 0.1.2 → 0.1.6

package/README.md

@@ -39,8 +39,8 @@ npx @dombaras/agent-harness init --target . --dry-run
 | `.agents/rules/00-operating.md` | always-loaded rules summary (wired into `opencode.json` `instructions`) | harness (overwrite) |
 | `.agents/skills/*/SKILL.md` | persona instruction skills | harness (overwrite) |
 | `opencode.json` | main/small model routing + `instructions` | harness (**merged**, see below) |
-| `scripts/qa/*` | `test:dispatch` / `test:governance` gates + QA-script wiring check | harness (overwrite) |
-| `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history) | **project** (create-if-missing) |
+| `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` gates + QA-script wiring check | harness (overwrite) |
+| `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history, flow-map, qa-plan) | **project** (create-if-missing) |
 | `.harness.json` | deployed version + project profile + per-file checksums | harness |
 
 ### `opencode.json` is merged, not clobbered
@@ -59,6 +59,13 @@ tiers, trust tiers) live in `.agents/memory/domain-map.md`, which `init`
 scaffolds for you to fill in — the skills and rules reference memory instead of
 hardcoding domain assumptions.
 
+**Flow map (`.agents/memory/flow-map.md`)** — the project-owned registry powering the
+flow-closure half of `test:qa-plan`. Each user-facing flow lists the code surfaces that
+implement the same behavior across codebases/layers (e.g. web component, `mobile/` sheet,
+API route) plus its optional variants (e.g. `condition-selector-present` vs `-absent`). Fill
+it in so a change to one surface is forced to account for all the others. If empty, the gate
+warns but does not block; the guarantee only applies to registered flows.
+
 ## Model routing & enforcement
 
 - Concrete models are set in `.opencode/agents/<name>.md` (`model:` field) and
@@ -84,6 +91,16 @@ hardcoding domain assumptions.
 
 - `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity + model-routing↔pin drift check.
 - `npm run test:governance` — session wrap-up dispatch-log enforcement.
+- `npm run test:qa-plan` — **diff-coverage + flow-closure gate**:
+  every changed CODE path must have a covering assertion (or a waivered reason) in
+  `.agents/memory/qa-plan.md` before a change is verified — and every touched flow
+  (`.agents/memory/flow-map.md`) must have every sibling surface and declared optional
+  variant addressed in the plan's `## Parallel-surface & variant audit`. Kills the
+  "verified by a suite that never touched the change" failure mode: a tier label never
+  proves coverage. It also makes **"Fix One, Fix All" mechanical**: a change to one
+  surface (e.g. web) cannot ship while the same flow in another codebase (e.g. `mobile/`)
+  silently keeps old behavior — the plan must name each sibling as covered (`->`) or
+  out-of-scope (`audited: reason`, e.g. `deferred — logged in handoff.md`).
 - `node scripts/qa/check-qa-scripts.js` — warns (or `--strict` fails) when the
   DoD-referenced runtime QA tiers aren't wired into `package.json`.
 
@@ -99,6 +116,22 @@ npx @dombaras/agent-harness update --target /path/to/project
 ```
 
 - Overwrites harness-owned files, preserves `.agents/memory/*`.
+- Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
+  `test:qa-plan`) into the target's `package.json` (merged, add-only).
+- **Auto-commits** only the harness files it changed (`chore(harness): @dombaras/agent-harness
+  <old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
+  modified harness files. Your unrelated uncommitted work is never staged.
+  - `--no-commit` to skip commit+push, `--no-push` to commit but not push.
+  - `init` never commits.
+- **`[Nothing-to-Update]` confirmation**: if the target is already at this CLI's version and no
+  harness-owned file changed, `update` says so explicitly, writes nothing, and makes no commit —
+  a no-op is never mistaken for a sync and never churns `.harness.json`.
+- **Downgrade guard**: `update` refuses to run on a target whose deployed harness is NEWER than
+  this CLI (e.g. deployed from a local checkout that was never published) and tells you to publish
+  that version first.
+- **Published-version check**: if this CLI's version is not the latest `dist-tags.latest` on npm,
+  `update` warns you — catches the "bumped the version and updated a project from a local
+  checkout, but never published" gap before it silently forks the projects.
 - **Non-destructive**: if a harness-owned file was modified locally since the
   last deploy (tracked by checksum in `.harness.json`), it is backed up to
   `.harness-backup/<timestamp>/` before overwrite.

package/bin/agent-harness.js

@@ -27,6 +27,7 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const readline = require("readline");
+const { spawnSync } = require("child_process");
 
 const PKG = require("../package.json");
 const TEMPLATES_DIR = path.resolve(__dirname, "..", "templates");
@@ -35,6 +36,36 @@ const BACKUP_DIR = ".harness-backup";
 
 // ---------------------------------------------------------------- helpers
 
+/* Numeric semver compare (major.minor.patch; prerelease tags ignored).
+ * Returns <0 / 0 / >0 like a normal comparator. */
+function compareVersions(a, b) {
+  const pa = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0) ? 1 : -1;
+  }
+  return 0;
+}
+
+/* Best-effort: the latest `dist-tags.latest` for PKG.name on the configured
+ * registry. Returns null when the registry is unreachable / package unknown,
+ * so the check never blocks a deploy. */
+function publishedLatestVersion() {
+  const npmCli = process.env.npm_execpath
+    ? path.join(path.dirname(process.env.npm_execpath), "npm-cli.js")
+    : null;
+  const args = ["view", PKG.name, "version", "--json", "--fetch-timeout=5000", "--fetch-retries=0"];
+  const r = npmCli
+    ? spawnSync(process.execPath, [npmCli, ...args], { encoding: "utf8", timeout: 10000 })
+    : spawnSync("npm", args, { encoding: "utf8", timeout: 10000 });
+  if (r.status !== 0) return null;
+  try {
+    return JSON.parse(r.stdout.trim());
+  } catch (_) {
+    return r.stdout.trim() || null;
+  }
+}
+
 function listFiles(dir, base = dir) {
   const out = [];
   if (!fs.existsSync(dir)) return out;
@@ -135,6 +166,95 @@ function mergeOpencodeJson(target, variables) {
   return JSON.stringify(merged, null, 2) + "\n";
 }
 
+// Harness-shipped npm scripts auto-wired into the target project's package.json
+// scripts (merged, not clobbered). Every other script the project has is preserved.
+// These gates ship with the harness, so a deploy wires them up like opencode.json.
+const HARNESS_SCRIPTS = {
+  "test:dispatch": "node scripts/qa/check-dispatch-config.js",
+  "test:governance": "node scripts/qa/governance.js",
+  "test:qa-plan": "node scripts/qa/check-qa-plan.js",
+};
+
+// Merge harness gate scripts into the project's existing package.json, preserving
+// every other script. ADD-ONLY: an existing script is never overwritten, so a
+// project's deliberate customization of a gate survives re-deploys. Returns
+// { text, hadPkg }.
+function mergePackageJson(target) {
+  const p = path.join(target, "package.json");
+  const hadPkg = fs.existsSync(p);
+  const existing = hadPkg ? safeJson(fs.readFileSync(p, "utf8"), {}) : {};
+  const scripts = Object.assign({}, existing.scripts || {});
+  for (const [name, cmd] of Object.entries(HARNESS_SCRIPTS)) {
+    if (!(name in scripts)) scripts[name] = cmd;
+  }
+  const merged = { ...existing, scripts };
+  return { text: JSON.stringify(merged, null, 2) + "\n", hadPkg };
+}
+
+// ---------------------------------------------------------------- git helpers
+
+function runGit(target, args) {
+  const result = require("child_process").spawnSync("git", args, {
+    cwd: target,
+    encoding: "utf8",
+  });
+  return { ok: result.status === 0, status: result.status, out: (result.stdout || "").trim(), err: (result.stderr || "").trim() };
+}
+
+function isGitRepo(target) {
+  const r = runGit(target, ["rev-parse", "--is-inside-work-tree"]);
+  return r.ok;
+}
+
+// Auto-commit ONLY the harness-owned files an update just changed, so the target
+// project's next session never sees "unexplained" modified harness files. Scoped
+// to this run's changed harness files (never `git add -A`) so unrelated uncommitted
+// work is NEVER swept in. Memory/backup files are excluded (project data / rollback).
+// Returns { committed:boolean, staged:string[], skipped:string[], pushed:boolean|null }.
+function commitHarnessChanges(target, changedRels, opts) {
+  const out = { committed: false, staged: [], skipped: [], pushed: null };
+  if (!opts.commit) return out;
+  if (!isGitRepo(target)) {
+    out.skipped.push("not a git repo");
+    return out;
+  }
+  if (changedRels.length === 0) {
+    out.skipped.push("no harness files changed");
+    return out;
+  }
+  const addR = runGit(target, ["add", "--", ...changedRels]);
+  if (!addR.ok) {
+    out.skipped.push("git add failed: " + addR.err);
+    return out;
+  }
+  const diffCached = runGit(target, ["diff", "--cached", "--name-only"]);
+  const staged = (diffCached.out || "").split(/\r?\n/).filter(Boolean).map(relKey);
+  if (staged.length === 0) {
+    out.skipped.push("no harness changes staged");
+    return out;
+  }
+  out.staged = staged;
+  const prior = opts.priorVersion ? opts.priorVersion + " -> " : "";
+  const message = `chore(harness): @dombaras/agent-harness ${prior}${PKG.version}`;
+  const commitR = runGit(target, ["commit", "-m", message]);
+  if (!commitR.ok) {
+    out.skipped.push("commit failed: " + commitR.err);
+    return out;
+  }
+  out.committed = true;
+  if (opts.push) {
+    const hasRemote = runGit(target, ["remote"]).ok && runGit(target, ["remote"]).out;
+    if (hasRemote) {
+      const pushR = runGit(target, ["push", "origin", "HEAD"]);
+      out.pushed = pushR.ok;
+      if (!pushR.ok) out.skipped.push("push failed: " + pushR.err);
+    } else {
+      out.skipped.push("no git remote to push");
+    }
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------- deploy
 
 function backup(target, rel, content) {
@@ -145,7 +265,7 @@ function backup(target, rel, content) {
 }
 
 async function deploy(target, opts) {
-  const { name, domain, yes, dryRun, isUpdate } = opts || {};
+  const { name, domain, yes, dryRun, isUpdate, commit, push } = opts || {};
   const existing = readConfig(target);
   const projectName = name || existing.projectName || path.basename(target);
   let projectDomain = domain || existing.projectDomain || "";
@@ -154,10 +274,37 @@ async function deploy(target, opts) {
   }
   const VARIABLES = { PROJECT_NAME: projectName, PROJECT_DOMAIN: projectDomain };
 
+  // Refuse to downgrade: the target's deployed harness is newer than this CLI.
+  // This is how the "I updated from a local checkout that I never published"
+  // mistake surfaces instead of silently writing older templates over a newer
+  // deployment (and auto-committing that regression).
+  if (isUpdate && existing.version && compareVersions(existing.version, PKG.version) > 0) {
+    throw new Error(
+      `"${projectName}" has harness v${existing.version} — NEWER than this CLI (v${PKG.version}). ` +
+        `Not downgrading. Publish v${existing.version} (or this CLI) so \`update\` can re-sync from the registry.`
+    );
+  }
+
   const previousFiles = existing.files || {};
   const actions = [];
   const manifest = {};
 
+  // Auto-wire harness gate scripts into the target package.json (merged, add-only).
+  {
+    const { text, hadPkg } = mergePackageJson(target);
+    const key = "package.json";
+    const targetAbs = path.join(target, "package.json");
+    const current = hadPkg ? fs.readFileSync(targetAbs, "utf8") : null;
+    if (!hadPkg) actions.push({ rel: key, kind: "create" });
+    else if (current !== text) actions.push({ rel: key, kind: "merge" });
+    else actions.push({ rel: key, kind: "unchanged" });
+    manifest[key] = sha256(text);
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+      fs.writeFileSync(targetAbs, text, "utf8");
+    }
+  }
+
   for (const { abs, rel } of listFiles(TEMPLATES_DIR)) {
     const key = relKey(rel);
     const targetAbs = path.join(target, rel);
@@ -213,6 +360,16 @@ async function deploy(target, opts) {
     }
   }
 
+  // Nothing-to-update detection: an update that made no effective change to any
+  // harness-owned file and was already running this exact version is a no-op —
+  // report it clearly instead of printing a zero-delta "Updated", and leave the
+  // target byte-for-byte untouched (no .harness.json timestamp churn, no commit).
+  const changedRelsAll = actions
+    .filter((a) => ["create", "overwrite", "overwrite (backup)", "merge"].includes(a.kind))
+    .map((a) => a.rel);
+  const nothingToUpdate =
+    !!isUpdate && changedRelsAll.length === 0 && compareVersions(existing.version || "0", PKG.version) === 0;
+
   const config = {
     version: PKG.version,
     projectName,
@@ -221,11 +378,34 @@ async function deploy(target, opts) {
     updatedAt: new Date().toISOString(),
     files: manifest,
   };
-  if (!dryRun) {
+  if (!dryRun && !nothingToUpdate) {
     fs.writeFileSync(path.join(target, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
   }
 
-  return { projectName, projectDomain, actions, dryRun: !!dryRun };
+  // Auto-commit only this run's changed harness-owned files (update only).
+  let commitResult = null;
+  if (isUpdate && !dryRun && !nothingToUpdate) {
+    const changedRels = changedRelsAll.filter(
+      (r) => !r.startsWith(".agents/memory/") && !r.startsWith(".harness-backup/")
+    );
+    changedRels.push(CONFIG_FILE); // .harness.json reflects the new deployed version
+    commitResult = commitHarnessChanges(target, changedRels, {
+      commit,
+      push,
+      priorVersion: existing.version || null,
+    });
+  }
+
+  return {
+    projectName,
+    projectDomain,
+    actions,
+    dryRun: !!dryRun,
+    commitResult,
+    isUpdate: !!isUpdate,
+    nothingToUpdate,
+    priorVersion: existing.version || null,
+  };
 }
 
 function summarize(actions) {
@@ -236,10 +416,22 @@ function summarize(actions) {
 
 function printSummary(result, isUpdate) {
   const { projectName, actions, dryRun } = result;
+
+  if (isUpdate && result.nothingToUpdate) {
+    console.log(
+      `\n[Nothing-to-Update] agent-harness v${PKG.version}: "${projectName}" is already at ` +
+        `v${result.priorVersion || PKG.version} and no harness-owned file changed.`
+    );
+    return;
+  }
+
   const verb = isUpdate
     ? (dryRun ? "Would update" : "Updated")
     : (dryRun ? "Would initialize" : "Initialized");
   console.log(`\nagent-harness v${PKG.version} ${verb.toLowerCase()} "${projectName}"` + (dryRun ? " (dry run)" : ""));
+  if (isUpdate && result.priorVersion && result.priorVersion !== PKG.version) {
+    console.log(`  harness: v${result.priorVersion} -> v${PKG.version}`);
+  }
   for (const a of actions) console.log(`  [${a.kind}] ${a.rel}`);
   const counts = summarize(actions);
   console.log(
@@ -249,12 +441,29 @@ function printSummary(result, isUpdate) {
   );
 }
 
+/* Best-effort warning: when this CLI's version is not the latest published on
+ * the registry, flag it. This catches the "bumped + ran update from a local
+ * checkout, but never published" silent gap. */
+function printUnpublishedWarning() {
+  const published = publishedLatestVersion();
+  if (published == null || published === "" || published === PKG.version) return;
+  const cmp = compareVersions(PKG.version, published);
+  if (cmp <= 0) return;
+  console.log(
+    `\n  WARNING: this CLI is v${PKG.version}, but the latest version published on ` +
+      `npm is v${published}. If you ran this from a local checkout, the changes were ` +
+      `NOT published — Publish first, then \`update\` other projects, or they will ` +
+      `branch off an older harness.`
+  );
+}
+
 function printNextSteps() {
   console.log("  Next steps:");
-  console.log("   1. Fill in `.agents/memory/domain-map.md` and `.agents/memory/stack-versions.md`.");
-  console.log("   2. Add QA gate scripts to package.json:");
-  console.log('      "test:dispatch": "node scripts/qa/check-dispatch-config.js",');
-  console.log('      "test:governance": "node scripts/qa/governance.js"');
+  console.log("   1. Fill in `.agents/memory/domain-map.md`, `.agents/memory/stack-versions.md`,");
+  console.log("      and `.agents/memory/flow-map.md` (register cross-surface flows so");
+  console.log("      test:qa-plan enforces their sibling-surface/variant closure).");
+  console.log("   2. Harness gate scripts (`test:dispatch`, `test:governance`, `test:qa-plan`) were");
+  console.log('      auto-wired into package.json "scripts".');
   console.log("   3. Restart your agent CLI (config is read once at startup).\n");
 }
 
@@ -263,7 +472,12 @@ function printUsage() {
     `agent-harness v${PKG.version}\n\n` +
       `Usage:\n` +
       `  agent-harness init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run]\n` +
-      `  agent-harness update [--target <dir>] [--dry-run]\n` +
+      `  agent-harness update [--target <dir>] [--dry-run] [--no-commit] [--no-push]\n` +
+      `\n` +
+      `  update auto-commits only the harness files it changes (chore(harness): ...) and\n` +
+      `  pushes to origin by default. Use --no-commit to skip commit+push, or --no-push\n` +
+      `  to commit but not push. Your unrelated uncommitted work is never staged.\n` +
+      `\n` +
       `  agent-harness list\n` +
       `  agent-harness --version | -v\n` +
       `  agent-harness --help | -h\n`
@@ -293,6 +507,8 @@ async function init(target, flags) {
     yes: !!flags["--yes"],
     dryRun: !!flags["--dry-run"],
     isUpdate: false,
+    commit: false,
+    push: false,
   });
   printSummary(result, false);
   if (!result.dryRun) printNextSteps();
@@ -307,8 +523,30 @@ async function update(target, flags) {
     yes: true,
     dryRun: !!flags["--dry-run"],
     isUpdate: true,
+    commit: !flags["--no-commit"],
+    push: !flags["--no-commit"] && !flags["--no-push"],
   });
   printSummary(result, true);
+  printUnpublishedWarning();
+  printCommitResult(result);
+}
+
+function printCommitResult(result) {
+  const c = result.commitResult;
+  if (!c) return;
+  console.log("");
+  if (c.committed) {
+    console.log("  committed harness files: " + c.staged.join(", "));
+    console.log(
+      c.pushed === true
+        ? "  pushed to origin."
+        : c.pushed === null
+          ? "  push skipped (no --push / no remote)."
+          : "  WARNING: commit made but push FAILED."
+    );
+  } else {
+    console.log("  no harness auto-commit: " + (c.skipped.join("; ") || "no-op"));
+  }
 }
 
 function parseArgs(argv) {
@@ -317,6 +555,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--target" || a === "--name" || a === "--domain") flags[a] = argv[++i];
     else if (a === "--dry-run" || a === "--yes" || a === "-y") flags[a] = true;
+    else if (a === "--no-commit" || a === "--no-push") flags[a] = true;
   }
   return flags;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-scripts.js"
+    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js"
   },
   "keywords": [
     "opencode",

package/templates/.agents/AGENTS.md

@@ -20,7 +20,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - **Progressive Hydration & Cold-Start**: Never render empty states while waiting on async auth/sync. Hydrate from local cache so the UI renders immediately.
 - **The 5 Essential UI States**: Every screen/list component must handle Ideal, Empty (with CTA), Loading (skeleton), Error (retry), and Partial/single-item states.
 - **Error-Handling Contract (Mobile)**: Every `catch` block in a native screen must (1) fire an error haptic, (2) set a user-visible error state that renders inline — never `console.warn` alone, and (3) provide a retry or dismissal path. Follow the reference pattern in `.agents/skills/mobile-engineer/SKILL.md`.
-- **Cross-Screen Consistency ("Fix One, Fix All")**: When you implement a UX pattern in one screen, grep for analogous screens and apply it globally; if scope is too large, log a deferred item in the handoff with exact files/patterns. A local-only fix is a regression-in-waiting.
+- **Cross-Screen Consistency ("Fix One, Fix All")**: When you implement a UX pattern in one screen, grep for analogous screens and apply it globally; if scope is too large, log a deferred item in the handoff with exact files/patterns. A local-only fix is a regression-in-waiting. Mechanically enforced by `test:qa-plan` via `.agents/memory/flow-map.md`: a change that touches a registered flow must address EVERY sibling surface (other codebases like `mobile/`, other layers) and every declared optional variant in the QA-plan audit — covered `->`, or `audited:` with a reason (including `deferred — logged in handoff`). A sibling the plan does not name fails the gate.
 - **Bidirectional & RTL**: Use logical properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`) never physical ones (`pl-*`, `left-*`); use inverted horizontal lists / direction-aware layout in native RTL; pass dynamic `dir` to UI primitives.
 - **Legacy Pruning & Physical Walkthrough**: When introducing a new flow/paradigm, explicitly audit and PRUNE obsolete mechanisms that contradict it — never bolt new steps on top of removed ones. Trace every physical/interaction flow step-by-step from each actor's perspective to eliminate unnecessary friction.
 
@@ -55,6 +55,15 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Data ingestion / entity resolution | `data-engineer` |
     | Deployment / cron / secrets / build+release | `devops-engineer` |
     | Session wrap-up / handoff | `handoff` |
+  - **QA planning is never optional (no silent skip)**: every change that touches
+    code paths MUST get a QA plan before it is verified. The plan is authored by
+    `qa-architect` (thinker). If `qa-architect` is not dispatched — for ANY reason,
+    including dispatch failure or simply not invoking it — the **main orchestrator
+    performs the qa-architect role itself** and writes the same coverage plan into
+    `.agents/memory/qa-plan.md`. The QA plan/copy escalation ladder NEVER leaves a
+    code change unplanned: `qa-architect` -> orchestrator fallback -> (never a silent
+    skip). `npm run test:qa-plan` enforces that every changed code path has a covering
+    assertion or a waivered reason.
   - **Waivers** (the only way to skip a persona): a persona may be skipped only when (a) the change is fully covered by an automated gate on push or in the QA tiers, AND (b) the skip is pre-audited in `.agents/memory/` with a cited pointer. Log every waiver as `waived: <persona>` with `reason: <gate|pointer>`.
   - **Dispatch failure ladder** (never silent): retry once (resume the same `task_id`); if it still fails, do the work inline and log `degraded: <persona> model: <reason>`; never silently skip.
   - **Bound every dispatch (task spec)** — never hand a persona a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries: `Objective` (one deliverable) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
@@ -70,7 +79,8 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - Never run heavy regression suites blindly for small changes.
 - Split QA personas: `qa-architect` (thinks — inspects the diff, audits gaps, selects the minimal tier, authors progression tests) vs `qa-runner` (does — executes the chosen tier, reports pass/fail verbatim). The thinker never runs; the doer never designs.
 - **Static ≠ Runtime rule**: never declare UI/mobile/API changes verified from static typing alone — execute a real runtime path.
-- **Tiers** (commands are **project-provided** — the target project must define them; the harness ships only `test:dispatch` and `test:governance`):
+- **Coverage ≠ label rule**: a tier command verifies a change ONLY when its backing suite actually exercises the changed path. A suite that touches unrelated code proves nothing about this change. `npm run test:qa-plan` mechanically asserts every changed code path is covered by the QA plan (or waivered) before verification — and, via `flow-map.md`, that every touched flow's sibling surfaces and declared optional variants are addressed in the plan's audit (the "fix one, fix all" gate: a web-only diff must still say what the mobile twin does).
+- **Tiers** (commands are **project-provided** — the target project must define them; the harness ships only `test:dispatch`, `test:governance`, and `test:qa-plan`):
   | Tier | Scope | Command |
   |---|---|---|
   | 1 | UI/CSS/mobile/copy | `npm run test:quick` |
@@ -79,7 +89,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
   | 4 | Data ingestion | the project's data E2E script |
   | 5 | Major release / breaking refactor | `npm run test:verify` |
   | 6 | Security / deps | `npm run test:security` |
-- **Progression Workflow**: for new routes/endpoints/states, (1) author a dedicated assertion path, (2) run the targeted progression test, (3) graduate it into the permanent regression suite.
+- **Progression Workflow**: for new routes/endpoints/states, (1) author a dedicated assertion path, (2) run the targeted progression test, (3) graduate it into the permanent regression suite. A change is NOT verified if the executed tier's backing suite never exercised the modified path — author a progression test for that path first (this is the "GAP" rule).
 
 ## 7. Definition of Done & Continuous Backup
 
@@ -93,7 +103,7 @@ Every completed task passes this gate, in order:
    - [ ] Cross-screen audit if a new UX pattern was introduced.
    - [ ] No modified file over ~500 lines without extracting components.
    - [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
-1. **QA tier** — `qa-architect` picks the tier (and authors progression tests); `qa-runner` executes and makes it pass (§6).
+1. **QA tier** — `qa-architect` inspects the diff, picks the tier BY COVERAGE (not path-label), records the coverage map in `.agents/memory/qa-plan.md`, and authors progression tests for any GAP; if `qa-architect` is not dispatched the orchestrator plans in its place. `qa-runner` executes and makes it pass (§6). A change is not verified until `npm run test:qa-plan` passes: every changed code path covered or waivered, **and** every touched flow (`.agents/memory/flow-map.md`) has every sibling surface and declared variant addressed in the plan's `## Parallel-surface & variant audit`, **AND** the executed tier exercised the modified path.
 2. **Security check** — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
 3. **Commit** — concise `feat:` / `fix:` / `refactor:` message.
 4. **Push** — `git push origin main`.
@@ -104,6 +114,7 @@ Every completed task passes this gate, in order:
 ## 8. Session & Traceability Discipline
 
 - **One session = one coherent task**; keep a short checklist as the single source of truth.
+- **Harness-update awareness**: `npx @dombaras/agent-harness update` auto-commits the harness files it changes as `chore(harness): @dombaras/agent-harness <old> -> <new>`. If you see such a commit (or modified `.agents/**`, `scripts/qa/**`, `AGENTS.md`, `opencode.json` you didn't touch), do NOT treat it as unexplained — run `git log -1 --stat` / `git show` to see exactly which harness files changed and why, then read the rulebook. Never guess at the cause.
 - **Planned vs. Shipped**: at session end, record a "planned → shipped → deferred" delta so aspirational docs are never mistaken for reality. Always verify against live code and schema.
 - **Dispatch Log (mandatory)**: every wrap-up opens with `subagent → model → shipped/deferred`. An empty log is non-compliant.
 - **Persist Continuity**: use the `handoff` skill to update `.agents/memory/handoff.md`. Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.

package/templates/.agents/memory/flow-map.md

@@ -0,0 +1,23 @@
+# Flow map — every user-facing flow and where it lives
+
+Project-owned (like all `.agents/memory/*`). This is the registry that turns the
+"Fix One, Fix All" rule (`AGENTS.md` §3) into a **gate**:
+`npm run test:qa-plan` reads this file and, for every flow your diff touches,
+requires the QA plan to explicitly address EVERY sibling surface — the same
+behavior implemented anywhere else: another codebase (web vs `mobile/`), another
+layer (API route), another page — and every OPTIONAL variant (state a surface can
+be in, e.g. "condition selector present" vs "absent") before the change may be
+verified.
+
+The failure mode this kills: a change to one surface (e.g. web) ships while its
+twin in another codebase silently keeps the old behavior. The diff is web-only so
+per-file coverage looks green, but the flow is now inconsistent — the exact
+"web/mobile return flow" miss.
+
+Keep it current: every time a flow gains/removes a surface or variant, update its
+entry here in the same change.
+
+## flow: return
+behavior: "Mark as Returned" — return POST with an 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

package/templates/.agents/memory/model-routing.md

@@ -59,10 +59,14 @@ Every subagent must return a single final message with, in order:
   not name a concrete model no longer pinned anywhere (doc↔config drift).
 - `npm run test:governance` — `scripts/qa/governance.js` enforces the wrap-up
   dispatch log.
+- `npm run test:qa-plan` — `scripts/qa/check-qa-plan.js` enforces diff coverage:
+  every changed CODE path must have a covering assertion (or a waivered reason)
+  in `.agents/memory/qa-plan.md` before the change is verified.
 - `scripts/qa/check-qa-scripts.js` — verifies the DoD-referenced QA tier scripts
   (project-provided) are wired into `package.json`.
 
-Run `test:dispatch` after editing any agent/skill path.
+Run `test:dispatch` after editing any agent/skill path, and `test:qa-plan` on any
+change that touches code paths.
 
 ## Gotchas
 

package/templates/.agents/memory/qa-plan.md

@@ -0,0 +1,49 @@
+# QA plan — coverage-driven
+
+One entry per SHIPPED change. Authored by `qa-architect` (thinker), or by the
+main orchestrator as the mandatory fallback when qa-architect is not dispatched.
+Gated mechanically by `npm run test:qa-plan` — a changed code path that is neither
+covered nor waivered here fails, so the change cannot be declared verified.
+
+Keep the LAST change on top. Remove the illustrative examples below; never leave
+a real-looking path in Coverage map without the actual runtime assertion backing it.
+
+## Change intent
+
+One sentence naming the SEMANTIC behavior change (what the user experiences), not
+the file list. The flow-closure half of the gate judges sibling surfaces and
+optional variant states against this intent.
+
+- change: return flow no longer offers a condition selector — every return POSTs without a condition payload
+
+## Parallel-surface & variant audit
+
+For every flow in `.agents/memory/flow-map.md` whose `surfaces:` intersect this
+diff, address EVERY sibling surface and EVERY declared `variant` here — either
+`->` a covering assertion or `audited:` with a reason. `test:qa-plan` fails on any
+sibling surface or variant the plan does not NAME. A sibling that intentionally
+keeps old behavior must say so (`audited: deferred — logged in handoff`), never be
+silently omitted.
+
+- components/LendingActionDrawers.tsx -> test:quick::return (click-through: Mark as Returned, no condition selector)
+- mobile/features/return/ReturnStatusSheet.tsx audited: deferred — mobile still renders the selector; same simplification pending, logged in handoff.md
+- app/api/transactions/[id]/return/route.ts -> test:api::return (POST without condition payload succeeds)
+- flow: return variant: condition-selector-present audited: removed by this change — asserting absence only
+- flow: return variant: condition-selector-absent -> test:quick::return (no-selector click-through renders no condition UI)
+
+## Coverage map
+
+A `Changed path -> executing test/assertion` list. Every changed CODE path needs a
+runtime assertion that ACTUALLY exercises it (never trust a tier label — verify the
+backing suite reaches the path). Paths may be files or directories. Lines starting
+with `#` are ignored.
+
+# components/return/ReturnConfirmDrawer.tsx -> test:quick::progression (click-through: Mark as Returned -> confirm -> /api/transactions/[id]/return)
+# app/api/transactions/[id]/return/route.ts -> test:quick::progression (return POST succeeds with no condition payload)
+
+## Waivers
+
+Trivial diffs only (pure copy/docs, or a path whose behavior is already covered
+elsewhere). Every waiver MUST carry a `reason:` on the same line.
+
+# waived: src/some-screen.tsx reason: copy-only string swap, no runtime path changed

package/templates/.agents/rules/00-operating.md

@@ -9,6 +9,7 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 - **Bound every task before dispatching.** No persona gets a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries a task spec: `Objective` (one deliverable) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
 - **Parallel = disjoint.** Dispatch two personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize and put the shared-contract owner first.
 - **Accept, don't trust.** After a code persona reports done, the orchestrator re-runs the gate itself (`tsc --noEmit`, `lint:hooks`, `test:quick`) and greps the metric before integrating — a subagent's `Evidence` is a claim, not proof.
+- **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in `.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.
 - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
 - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
 - Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.
@@ -20,7 +21,7 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 3. **5 UI states** (ideal/empty/loading/error/partial), user-visible errors (never `console.warn`-only), and RTL-safe logical props.
 4. **Verify stack versions** before writing framework code (`.agents/memory/stack-versions.md`).
 5. **Token discipline** — search before read, targeted reads, batch reads, don't re-read unchanged files, right-size QA.
-6. **Static ≠ runtime** — never declare verified from `tsc` alone; execute a real runtime/API path.
+6. **Static ≠ runtime** — never declare verified from `tsc` alone; execute a real runtime/API path that exercises the MODIFIED code — a tier label never proves coverage. `test:qa-plan` gates every changed code path to a covering assertion or waiver, and every touched flow's sibling surfaces / variants to an audit entry (`.agents/memory/flow-map.md` — "fix one, fix all").
 7. **Commit** with `feat:`/`fix:`/`refactor:` then push to main.
 
 ## Definition of Done

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

@@ -29,6 +29,11 @@ dispatch it broad.
 ## 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/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/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-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",