@dombaras/agent-harness 0.1.1 → 0.1.5

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
@@ -66,18 +73,34 @@ hardcoding domain assumptions.
 - Personas also carry mechanical guardrails in frontmatter:
   - thinkers (`planner`, `product-manager`) → `permission: { edit: deny, bash: deny }`
   - `qa-architect`, `handoff` → `permission: { bash: deny }`
+  - code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
+    `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
+    `diagnostics-expert`) → `permission.edit` allows everything EXCEPT
+    `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (governance
+    and harness files are read-only), plus `bash: allow`
   - deterministic personas → `temperature: 0.1`
   - all personas → a `steps:` cap (cost ceiling)
   - `planner`, `handoff` → `hidden: true`
 - `.agents/skills/*/SKILL.md` carries a `model:` label only (informational).
 - `npx @dombaras/agent-harness list` prints the persona → model mapping.
 - `npm run test:dispatch` mechanically verifies model pins against
-  `scripts/qa/models.allowlist.txt`.
+  `scripts/qa/models.allowlist.txt` and that `model-routing.md` does not name a
+  stale model no longer pinned anywhere (doc↔config drift).
 
 ## QA gates
 
-- `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity.
+- `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`.
 
@@ -93,6 +116,13 @@ 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.
 - **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 || "";
@@ -158,6 +278,22 @@ async function deploy(target, opts) {
   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);
@@ -225,7 +361,39 @@ async function deploy(target, opts) {
     fs.writeFileSync(path.join(target, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
   }
 
-  return { projectName, projectDomain, actions, dryRun: !!dryRun };
+  // 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 —
+  // still report it clearly instead of printing a zero-delta "Updated".
+  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;
+
+  // Auto-commit only this run's changed harness-owned files (update only).
+  let commitResult = null;
+  if (isUpdate && !dryRun) {
+    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) {
@@ -251,10 +419,11 @@ function printSummary(result, isUpdate) {
 
 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 +432,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 +467,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 +483,29 @@ 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);
+  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 +514,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.1",
+  "version": "0.1.5",
   "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.
 
@@ -38,7 +38,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration.
 - **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
 - **Locations Map**: Read `.agents/memory/locations.md` first — it is the canonical index of sessions, logs, docs, and data. Never re-hunt for a path.
-- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch independent subagents in parallel.
+- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
   - **Persona map**:
     | Work area | Persona |
     |---|---|
@@ -55,8 +55,21 @@ 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`.
+  - **Parallel = disjoint** — run personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize, with the shared-contract owner dispatched first.
+  - **Orchestrator acceptance gate** — after a persona reports done, re-run the gate yourself (`tsc --noEmit`, `npm run lint:hooks`, `npm run test:quick`) and grep the metric before integrating or committing. A subagent's `Evidence` is a claim, not proof.
+  - **No suppression shortcuts** — never accept (or produce) file-level `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore` to hit a metric. Suppressions are line-level only and each carries a reason — a file-level disable is a rules violation, not a fix.
 - **Synchronous Terminal Commands**: Prefer sync one-shot commands (build/test/lint) that return inline, over background servers/watchers.
 - **No Output Bloat**: Never paste large files/diffs into chat; apply edits with the edit tool, never print a code block of a change.
 - **Right-Size the QA Tier**: Never run the full regression suite for a CSS/copy tweak.
@@ -66,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` |
@@ -75,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
 
@@ -88,7 +102,8 @@ Every completed task passes this gate, in order:
    - [ ] RTL traced if layout touched; logical properties used.
    - [ ] Cross-screen audit if a new UX pattern was introduced.
    - [ ] No modified file over ~500 lines without extracting components.
-1. **QA tier** — `qa-architect` picks the tier (and authors progression tests); `qa-runner` executes and makes it pass (§6).
+   - [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
+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`.
@@ -99,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

@@ -27,6 +27,11 @@ frontmatter:
 - **Thinkers** (`planner`, `product-manager`) have `permission: { edit: deny, bash: deny }`.
 - **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
 - **`handoff`** has `permission: { bash: deny }`.
+- **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
+  `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
+  `diagnostics-expert`) allow `edit` everywhere except governance/harness paths
+  — `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` are denied —
+  so out-of-scope edits are blocked mechanically, not just by prose.
 - **Deterministic personas** (`planner`, `qa-architect`, `qa-runner`, `handoff`,
   `diagnostics-expert`) pin `temperature: 0.1`.
 - **`steps:`** caps iterations per persona (cost ceiling).
@@ -50,13 +55,18 @@ Every subagent must return a single final message with, in order:
 ## Gates
 
 - `npm run test:dispatch` — `scripts/qa/check-dispatch-config.js` verifies model
-  pins, persona↔skill parity, and the output-contract marker.
+  pins, persona↔skill parity, the output-contract marker, and that this doc does
+  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

@@ -4,8 +4,12 @@ Always in effect. Full detail lives in `.agents/AGENTS.md`; read it before non-t
 
 ## Step Zero — subagent dispatch gate (non-negotiable)
 
-Before reading or editing any file for a task, dispatch the relevant personas via the `task` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`). Dispatch independent subagents in parallel; serialize only on dependencies. Keep only coordination/mechanical work (reads, git, commits) on the main model.
+Before reading or editing any file for a task, dispatch the relevant personas via the `task` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`). Keep only coordination/mechanical work (reads, git, commits) on the main model.
 
+- **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`.
@@ -17,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/frontend-engineer/SKILL.md

@@ -57,6 +57,7 @@ Whenever you are writing frontend code or dealing with build errors, you MUST st
 - **500-Line Rule**: No single `.tsx` screen file should exceed ~500 lines. If it does, extract logically distinct sections (modals, list items, action handlers, sub-views) into separate component files in a co-located directory (e.g., `mobile/components/transactions/`). "Extract" means MOVE code into typed modules — never minify/compress JSX onto single lines to dodge the count, never swap real types for `any`, and never add `.d.ts` overrides or inline `require()` to silence tsc.
 - **Before adding code to a file that already exceeds 500 lines**: STOP. Refactor first, then add. Never grow a monolith.
 - **One component = one responsibility**: A screen file should orchestrate layout and state. Rendering logic for individual cards, list items, modals, or drawers should be in dedicated components.
+- **No suppression shortcuts**: never silence lint/type errors with file-level `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore` to hit a metric. Suppressions are line-level only, and each must carry a reason.
 
 ## Frontend Quality Exit Checklist
 Before declaring any UI work done, verify:

package/templates/.agents/skills/mobile-engineer/SKILL.md

@@ -38,3 +38,7 @@ You own the native React Native layer and its gotchas — not shared web UI (tha
   config, handoff, other screens) to satisfy a metric.
 - **Verify before done**: run `tsc --noEmit`, `npm run lint:hooks`, `npm run test:quick`
   yourself and report the observed output — never claim success you did not run.
+- **No suppression shortcuts**: never silence the gate with a file-level
+  `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore`. Suppressions are
+  line-level only and each carries a reason — a file-level disable to hit a
+  metric is a rules violation, not a fix.