@dombaras/agent-harness 0.1.11 → 0.1.14

package/README.md

@@ -11,8 +11,9 @@ and QA gates — then deploys them into any project.
 
 ## Why
 
-- The agent harness is tooling, not application code. It should not be committed
-  into every app repo.
+- The agent harness is tooling, not application code. Its source lives in the
+  npm package — you deploy it with `init`/`update` rather than hand-copying it
+  into every repo.
 - One canonical, versioned source of truth for personas/rules/QA tiers, deployed
   on demand and updatable via `npx @dombaras/agent-harness update`.
 
@@ -42,8 +43,10 @@ npx @dombaras/agent-harness init --target . --dry-run
 | `.agents/features/INDEX.md` | pointer to `BACKLOG.md` (per-feature doc tree root) | **project** (create-if-missing) |
 | `opencode.json` | main/small model routing + `instructions` | harness (**merged**, see below) |
 | `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) |
+| `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history, flow-map, product-principles) | **project** (create-if-missing) |
+| `.agents/qa-plans/*` | project data (one QA plan file per change — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
 | `.harness.json` | deployed version + project profile + per-file checksums | harness |
+| `.gitignore` | harness-managed section (`.harness-backup/`) merged in, project entries preserved | harness (merged) |
 
 ### `opencode.json` is merged, not clobbered
 
@@ -67,12 +70,24 @@ single write-path for all open work: what's known, priority, evidence). When a f
 is picked up, the `features` persona authors the per-feature doc chain
 (`.agents/features/<slug>/`), each layer routed to its author persona — `intent.md`
 (product-manager) → `scope.md` (system-architect, HIGH-risk only) → `plan.md` (planner)
-→ `tests.md` (qa-architect, points to `qa-plan.md`). Ceremony is right-sized to blast
+→ `tests.md` (qa-architect, points to the feature's QA plan). Ceremony is right-sized to blast
 radius: trivial → none, low → single `intent.md`, high (auth/DB/public API/flow-siblings)
 → full chain. Docs live beside the code, are written-back before continuing when
 implementation invalidates them, and are archived on ship. `.agents/features/INDEX.md`
 is a pointer to `BACKLOG.md`. See `.agents/skills/features/SKILL.md`.
 
+**Product-first planning (`.agents/memory/product-principles.md`)** — the project-owned
+product concepts (actors, product concepts, UX heuristics, design language, key journeys,
+value-maximization rules) that LEAD planning. The `planner` reads it (plus a feature's
+`intent.md`) before emitting a dispatch plan and sequences work value-first — smallest
+slice that delivers the core outcome first — rather than by tech dependency. `intent.md`
+must define Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first
+sequence + Product concepts applied; `npm run test:product` fails a feature that reaches
+planning/implementation without them (a plan with no intent, or an intent that never
+names a user/need/outcome). Fill `product-principles.md` in at `init`; evolve it as the
+product does — see `.agents/skills/planner/SKILL.md` and
+`.agents/skills/features/SKILL.md`.
+
 **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,
@@ -109,10 +124,9 @@ warns but does not block; the guarantee only applies to registered flows.
   `opencode/deepseek-v4-pro` (gateway), `pickle` → `opencode/big-pickle`, or any
   explicit `provider/model`. Restart opencode after switching (config reads once).
 - **`/board` command** — every deploy ships an opencode command
-  (`.opencode/command/board.md`) that refreshes the canonical `BACKLOG.md` board:
-  `git pull --ff-only` (safe, never forces), then renders Open (by priority),
-  Frozen, the last few shipped rows, and the newest `.agents/memory/handoff.md`
-  delta. Read-only — it never edits the board.
+  (`.opencode/command/board.md`) that reads the local `BACKLOG.md` and renders a
+  clean task list (Priority · Title · Short description). Read-only, no git — the
+  local file is the source of truth.
 
 ## QA gates
 
@@ -122,9 +136,15 @@ warns but does not block; the guarantee only applies to registered flows.
   source of truth; status/priority enums, frozen-reopen conditions, non-empty
   priority/evidence, no duplicate IDs, and `INDEX.md`/`todo.md` must be pointers (not
   live lists).
+- `npm run test:product` — **product/UX-first gate**: every feature doc in
+  `.agents/features/<slug>/` must define its user before planning/implementation.
+  `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md`
+  a Value-first sequence + Product concepts applied; a `plan.md` with no `intent.md`
+  fails (never plan around an undefined user need). Backward-compatible — no feature
+  docs, gate passes.
 - `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
+  a QA plan (one per-change file under `.agents/qa-plans/`) 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
@@ -148,12 +168,14 @@ npx @dombaras/agent-harness update --target /path/to/project
 
 - Overwrites harness-owned files, preserves `.agents/memory/*` and `BACKLOG.md`.
 - Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
-  `test:qa-plan`, `test:backlog`) into the target's `package.json` (merged, add-only).
-- **Auto-commits** only the harness files it changed (`chore(harness): @dombaras/agent-harness
+  `test:qa-plan`, `test:backlog`, `test:product`) into the target's `package.json` (merged, add-only).
+- **Auto-commits** 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.
+  - `init` auto-commits + pushes by default too: it commits everything it scaffolds
+    (including `.agents/memory/*`, `.agents/features/*`, and `BACKLOG.md`) so a fresh
+    project starts fully tracked and no harness file is left untracked.
   - Harness-owned paths are **force-added**, so a project that gitignores deployment
     artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the
     harness commit instead of a raw `git add` failure that silently skips it — force-added
@@ -171,6 +193,10 @@ npx @dombaras/agent-harness update --target /path/to/project
   last deploy (tracked by checksum in `.harness.json`), it is backed up to
   `.harness-backup/<timestamp>/` before overwrite.
 - `opencode.json` is merged (project keys preserved).
+- **Managed `.gitignore`**: the harness merges a marked section (`.harness-backup/`, its
+  local rollback artifacts) into the project's `.gitignore`, preserving every project entry.
+  New harness files are tracked (committed), not ignored — so they don't need a gitignore
+  change. If the harness ever adds a new local-only artifact, `update` re-merges the entry.
 - `--dry-run` previews the plan without writing.
 
 ### Backlog migration (`migrate-backlog`)

package/bin/agent-harness.js

@@ -92,14 +92,16 @@ function relKey(rel) {
   return rel.split(path.sep).join("/");
 }
 
-/* `.agents/memory/*` (session memory) and `.agents/features/*` (feature doc
- * tree) are project data — scaffolded create-if-missing, never overwritten,
- * and never tracked in the manifest, exactly like the memory files. */
+/* `.agents/memory/*` (session memory), `.agents/features/*` (feature doc tree)
+ * and `.agents/qa-plans/*` (one QA plan file per change) are project data —
+ * scaffolded create-if-missing, never overwritten, and never tracked in the
+ * manifest. qa-plans is sharded per change so concurrent sessions never collide
+ * on a single shared file. */
 function isProjectScaffold(rel) {
   const parts = rel.split(path.sep);
   return (
     parts.includes(".agents") &&
-    (parts.includes("memory") || parts.includes("features"))
+    (parts.includes("memory") || parts.includes("features") || parts.includes("qa-plans"))
   );
 }
 /* The canonical `BACKLOG.md` at the repo root is also project data (a live task
@@ -199,6 +201,7 @@ const HARNESS_SCRIPTS = {
   "test:governance": "node scripts/qa/governance.js",
   "test:qa-plan": "node scripts/qa/check-qa-plan.js",
   "test:backlog": "node scripts/qa/check-backlog.js",
+  "test:product": "node scripts/qa/check-product.js",
 };
 
 // Merge harness gate scripts into the project's existing package.json, preserving
@@ -217,6 +220,25 @@ function mergePackageJson(target) {
   return { text: JSON.stringify(merged, null, 2) + "\n", hadPkg };
 }
 
+// Harness-managed .gitignore entries. These are LOCAL-ONLY artifacts (never
+// committed): everything else the harness deploys is tracked by git. Entries
+// live in a marked section so `update` can re-merge them (and pick up new
+// entries) without touching the project's own ignores.
+const GITIGNORE_MARKER = "# agent-harness (managed below)";
+const HARNESS_IGNORE_ENTRIES = [".harness-backup/"];
+
+function mergeGitignore(target) {
+  const p = path.join(target, ".gitignore");
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  const lines = existing.split(/\r?\n/);
+  const idx = lines.findIndex((l) => l === GITIGNORE_MARKER);
+  const kept = idx === -1 ? lines : lines.slice(0, idx);
+  while (kept.length && kept[kept.length - 1].trim() === "") kept.pop();
+  const managed = [GITIGNORE_MARKER, ...HARNESS_IGNORE_ENTRIES, ""];
+  const out = kept.length ? [...kept, "", ...managed] : [...managed];
+  return out.join("\n");
+}
+
 // ---------------------------------------------------------------- git helpers
 
 function runGit(target, args) {
@@ -348,6 +370,23 @@ async function deploy(target, opts) {
     }
   }
 
+  // Merge harness-managed gitignore entries (add-only, marked section).
+  {
+    const text = mergeGitignore(target);
+    const key = ".gitignore";
+    const targetAbs = path.join(target, ".gitignore");
+    const had = fs.existsSync(targetAbs);
+    const current = had ? fs.readFileSync(targetAbs, "utf8") : null;
+    if (!had) 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);
@@ -425,15 +464,15 @@ async function deploy(target, opts) {
     fs.writeFileSync(path.join(target, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
   }
 
-  // Auto-commit only this run's changed harness-owned files (update only).
+  // Auto-commit the files this run created/changed so nothing the harness
+  // deploys is left untracked. Runs for both `init` and `update`. Excludes only
+  // rollback artifacts; freshly-scaffolded project-data files (memory/features/
+  // BACKLOG) are committed so they start tracked, while pre-existing project
+  // data is never touched (a "preserve" never enters `changedRelsAll`).
   let commitResult = null;
-  if (isUpdate && !dryRun && !nothingToUpdate) {
-    const changedRels = changedRelsAll.filter(
-      (r) =>
-        !r.startsWith(".agents/memory/") &&
-        !r.startsWith(".agents/features/") &&
-        !r.startsWith(".harness-backup/")
-    );
+  const shouldCommit = !dryRun && (!isUpdate || !nothingToUpdate);
+  if (shouldCommit) {
+    const changedRels = changedRelsAll.filter((r) => !r.startsWith(".harness-backup/"));
     changedRels.push(CONFIG_FILE); // .harness.json reflects the new deployed version
     commitResult = commitHarnessChanges(target, changedRels, {
       commit,
@@ -514,26 +553,29 @@ function printUnpublishedWarning() {
 function printNextSteps() {
   console.log("  Next steps:");
   console.log("   1. Fill in `.agents/memory/domain-map.md`, `.agents/memory/stack-versions.md`,");
+  console.log("      `.agents/memory/product-principles.md` (actors, product concepts, UX");
+  console.log("      heuristics — the planner reads this to lead planning product-first),");
   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`,");
-    console.log("      `test:backlog`) were auto-wired into package.json \"scripts\".");
-    console.log("   3. Capture found items as one light row in the canonical `BACKLOG.md` (repo root);");
-    console.log("      dispatch the `features` persona to author the per-feature doc chain when one is picked up.");
-    console.log("   4. Restart your agent CLI (config is read once at startup).\n");
+  console.log("   2. Harness gate scripts (`test:dispatch`, `test:governance`, `test:qa-plan`,");
+  console.log("      `test:backlog`, `test:product`) were auto-wired into package.json \"scripts\".");
+  console.log("   3. Capture found items as one light row in the canonical `BACKLOG.md` (repo root);");
+  console.log("      dispatch the `features` persona to author the per-feature doc chain when one is picked up.");
+  console.log("   4. Restart your agent CLI (config is read once at startup).\n");
 }
 
 function printUsage() {
   console.log(
     `agent-harness v${PKG.version}\n\n` +
       `Usage:\n` +
-      `  agent-harness init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run]\n` +
+      `  agent-harness init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run] [--no-commit] [--no-push]\n` +
       `  agent-harness update [--target <dir>] [--dry-run] [--no-commit] [--no-push]\n` +
       `  agent-harness migrate-backlog [--target <dir>]\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` +
+      `  init and update auto-commit only the harness files they create/change\n` +
+      `  (chore(harness): ...) and push to origin by default. Use --no-commit to\n` +
+      `  skip commit+push, or --no-push to commit but not push. Your unrelated\n` +
+      `  uncommitted work is never staged.\n` +
       `\n` +
       `  migrate-backlog consolidates any live \`.agents/features/INDEX.md\` F-rows and\n` +
       `  \`.agents/memory/todo.md\` into the canonical BACKLOG.md, then rewrites those\n` +
@@ -785,10 +827,11 @@ async function init(target, flags) {
     yes: !!flags["--yes"],
     dryRun: !!flags["--dry-run"],
     isUpdate: false,
-    commit: false,
-    push: false,
+    commit: !flags["--no-commit"],
+    push: !flags["--no-commit"] && !flags["--no-push"],
   });
   printSummary(result, false);
+  printCommitResult(result);
   if (!result.dryRun) printNextSteps();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "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-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.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 && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/check-product.js"
   },
   "keywords": [
     "opencode",

package/templates/.agents/AGENTS.md

@@ -42,7 +42,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
   - **Persona map**:
     | Work area | Persona |
     |---|---|
-    | Task decomposition → dispatch plan | `planner` |
+    | Task decomposition → value-led dispatch plan (product-first) | `planner` |
     | Web app (React/Next.js/Tailwind/shadcn) | `frontend-engineer` |
     | Mobile native (Expo/React Native) | `mobile-engineer` |
     | Design system / tokens / shared components | `ui-designer` |
@@ -64,16 +64,25 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     low → single `intent.md`, high (auth/DB/API/flow-siblings) → full chain. Write
     back first (update the doc before continuing when implementation invalidates it),
     archive on ship. Feature docs are durable and complementary to the per-session
-    `qa-plan.md`/`handoff.md`; the `tests` doc points to `qa-plan.md`, never duplicates it.
+    `.agents/qa-plans/<feature-id>.md`/`handoff.md`; the `tests` doc points to the
+    feature's QA plan, never duplicates it.
+  - **Product intent is never optional (no silent skip)**: planning is
+    product-first. `intent.md` must define Actor(s) → Need → Outcome → Acceptance
+    criteria, and `plan.md` a Value-first sequence + Product concepts applied, read
+    against `.agents/memory/product-principles.md`. `npm run test:product` fails any
+    feature doc missing these, or a `plan.md` with no `intent.md` — mirroring the
+    "QA planning is never optional" ladder: `product-manager`/`planner` →
+    orchestrator fallback → (never a silent skip).
   - **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.
+    a per-change file under `.agents/qa-plans/` (one file per change, named by
+    `BACKLOG.md` ID or slug — never edit another change's plan file). 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`.
@@ -90,7 +99,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - 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.
 - **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`):
+- **Tiers** (commands are **project-provided** — the target project must define them; the harness ships only its own gates: `test:dispatch`, `test:governance`, `test:qa-plan`, `test:backlog`, `test:product`):
   | Tier | Scope | Command |
   |---|---|---|
   | 1 | UI/CSS/mobile/copy | `npm run test:quick` |
@@ -108,6 +117,7 @@ run when the session touched code paths — a backlog-only (or docs-only) change
 them. Steps 3-5 are the unconditional session close; they are NOT gated by QA.
 
 0. **Feature Completeness Gate** (code changes only):
+   - [ ] Product-first: `intent.md` (actor/need/outcome/acceptance) + value-led `plan.md` present — `npm run test:product` green (feature work only).
    - [ ] 5 UI states handled on every affected screen (list them).
    - [ ] No `catch` blocks that only `console.warn` without user-facing feedback.
    - [ ] Haptic/feedback consistency for every user-initiated action.
@@ -115,7 +125,7 @@ them. Steps 3-5 are the unconditional session close; they are NOT gated by QA.
    - [ ] 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** (code changes only) — `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.
+1. **QA tier** (code changes only) — `qa-architect` inspects the diff, picks the tier BY COVERAGE (not path-label), records the coverage map in a per-change plan under `.agents/qa-plans/` (one file per change — never edit another change's plan), 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** (code changes only) — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
 3. **Backlog write-back** (always) — move every task this session shipped from `Open` to `Archive (shipped · done)` in `BACKLOG.md` (with date/commit), then stage it explicitly: `git add BACKLOG.md` (it starts untracked — `git commit -am` / `git commit` without `add` will NOT pick it up). The board syncs across sessions only through git, so this delta is committed with the code, never left uncommitted.
 4. **Commit** (always) — concise `feat:` / `fix:` / `refactor:` message, including the `BACKLOG.md` delta.

package/templates/.agents/memory/product-principles.md

@@ -0,0 +1,37 @@
+# Product principles — {{PROJECT_NAME}}
+
+Project-owned product concepts that **lead** planning. The planner reads this
+before emitting a dispatch plan; `product-manager` and `ui-designer` keep it
+current. Fill it in during `npx @dombaras/agent-harness init`; evolve it as the
+product does. Skills reference this instead of hardcoding product/UX assumptions.
+
+## Actors
+<!-- who uses the product, their goals, and emotional states -->
+_TODO: list each actor (role), their primary goal, and what frustrates/delights them._
+
+## Product concepts
+<!-- the durable product ideas every feature must honor (e.g. community trust, one-tap primary actions) -->
+_TODO: name the 2-5 concepts that define this product._
+
+## UX heuristics
+<!-- the standing UX rules every screen/flow follows -->
+- **The 5 UI states** — ideal / empty (with CTA) / loading (skeleton) / error (retry) / partial.
+- **Progressive disclosure** — high-frequency actions primary (one tap); fold secondary tiers behind menus/sheets.
+- **Empty = default** — a new user's empty state is a primary design target, never an edge case.
+- **Mobile ergonomics** — thumb-reachability, bottom sheets over modals, swipe actions.
+- **RTL** — logical properties (`ps-*`/`pe-*`), direction-aware layout.
+- **No dead-ends** — every state has a way forward (CTA, retry, dismissal).
+
+## Design language
+<!-- tokens & patterns (from ui-designer): color/typography/spacing, shared components -->
+_TODO: reference the shared component / token system._
+
+## Key journeys
+<!-- the user-facing flows that matter most, with their happy + unhappy paths -->
+_TODO: list the core journeys and their critical states._
+
+## Value maximization rules
+<!-- how planning sequences work to maximize user value first -->
+- Ship the smallest slice that delivers the core outcome first.
+- Order steps by user value, not by tech-dependency convenience.
+- Prune anything that does not advance the user outcome.

package/templates/.agents/qa-plans/README.md

@@ -0,0 +1,49 @@
+# QA plans — one file per change
+
+Project-owned (like all `.agents/memory/*`). This directory holds the
+coverage-driven QA plan, **sharded**: one file per shipped change instead of a
+single shared `qa-plan.md`. Each concurrent session owns its own file, so two
+sessions (e.g. `F-003` and `F-035`) never rewrite each other's entries — the
+failure mode where one session's "keep-last-on-top" edit moves another's entry
+around (and risks dropping it on commit).
+
+`npm run test:qa-plan` reads EVERY `.md` file under this directory (plus the
+legacy `.agents/memory/qa-plan.md` if it exists) and unions their coverage maps,
+waivers, and flow audits against the live diff — so a changed code path is
+covered if ANY plan file names it.
+
+## Naming & ownership
+
+- One file per change. Name it after the `BACKLOG.md` feature ID (`F-003.md`),
+  or a short hyphenated slug of the change (`return-no-condition.md`) when there
+  is no feature row.
+- **Own your file; never edit another change's file.** That single rule removes
+  the collision. If a later change revisits the same feature, append a new
+  `##`-block to that feature's file (or open a new dated file) — never reorder
+  or delete another entry.
+- Same four sections the old `qa-plan.md` carried (authored by `qa-architect`,
+  or by the main orchestrator as the mandatory fallback): `## Change intent`,
+  `## Parallel-surface & variant audit`, `## Coverage map`, `## Waivers`.
+
+## Example (`F-003.md`)
+
+    # QA plan — F-003 (return flow: no condition selector)
+
+    ## Change intent
+    - change: return flow no longer offers a condition selector — every return POSTs without a condition payload
+
+    ## Parallel-surface & variant audit
+    - 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
+    - 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
+    # waived: src/some-screen.tsx reason: copy-only string swap, no runtime path changed
+
+Lines starting with `#` are ignored by the gate.

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

@@ -9,9 +9,10 @@ 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.
+- **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in a per-change file under `.agents/qa-plans/`) 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`.
 - **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root); on pickup dispatch `features` to author the per-feature doc chain (`.agents/skills/features/SKILL.md`). Right-size ceremony to risk.
+- **Product intent is never optional.** A feature never reaches planning/implementation without defining its user. `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first sequence + Product concepts applied — `npm run test:product` fails otherwise. Planning reads `.agents/memory/product-principles.md` and is value-led, not tech-led.
 - 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,14 +21,15 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 1. **Zero speculation** — base every fix/decision on observed logs, telemetry, or DB state; instrument first if evidence is missing.
 2. **No hardcoded mocks/fallback data** — prefer dynamic queries and database-backed settings.
 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 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 — including any `BACKLOG.md` delta.
+4. **Product-first planning** — define the actor/need/outcome/acceptance before code; sequence work value-first against `.agents/memory/product-principles.md`.
+5. **Verify stack versions** before writing framework code (`.agents/memory/stack-versions.md`).
+6. **Token discipline** — search before read, targeted reads, batch reads, don't re-read unchanged files, right-size QA.
+7. **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").
+8. **Commit** with `feat:`/`fix:`/`refactor:` then push to main — including any `BACKLOG.md` delta.
 
 ## Definition of Done
 
-QA tier + security lens gate **code changes only** (a backlog-only change skips them). Every session closes with **move shipped `BACKLOG.md` rows to `Archive` → commit → push** — the backlog write-back is never QA-gated.
+QA tier + security lens gate **code changes only** (a backlog-only change skips them). Every session closes with **move shipped `BACKLOG.md` rows to `Archive` → commit → push** — the backlog write-back is never QA-gated. Feature work is additionally gated by `test:product` (product intent + value-led plan).
 
 ## Session checklist
 

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

@@ -14,8 +14,9 @@ pull the implementation work onto yourself (that is dispatched to the code
 personas).
 
 The doc tree is **complementary** to the session memory (`.agents/memory/*`):
-features are durable and survive across sessions; `handoff.md`/`qa-plan.md` track
-per-session execution. Link between them, never duplicate.
+features are durable and survive across sessions; `handoff.md` and the per-change
+`.agents/qa-plans/<feature-id>.md` track per-session execution. Link between them,
+never duplicate.
 
 ## Two layers — do not cross them
 
@@ -35,9 +36,9 @@ BACKLOG.md                # canonical task list (Open / Frozen / Archive / Not t
 .agents/features/
   INDEX.md                # pointer to BACKLOG.md
   <slug>/
-    intent.md             # what & why, boundaries, acceptance criteria (1 pager)
+    intent.md             # what & why: actors, need, outcome, acceptance criteria (1 pager)
     scope.md              # optional — only on HIGH-risk features
-    plan.md               # implementation decomposition (HOW)
+    plan.md               # how, value-led: value-first sequence + product concepts applied
     tests.md              # intent-level acceptance + pointer to qa-plan.md
   archive/                # completed feature dirs moved here
 ```
@@ -79,10 +80,10 @@ to the correct persona** via the `task` tool (Step Zero dispatch — see
 
 | Doc | Frames | Author persona (dispatch) |
 |---|---|---|
-| `intent.md` | WHAT & WHY: outcomes, boundaries/out-of-scope, acceptance criteria, open questions | `product-manager` |
+| `intent.md` | WHAT & WHY, product-first: Actor(s) → Need → Outcome → Acceptance criteria (+ boundaries, open questions) | `product-manager` |
 | `scope.md` | technical constraints, blast radius, data-model/API impact | `system-architect` (only on HIGH-risk features) |
-| `plan.md` | HOW: ordered steps, owned files, per-step verification, commit boundaries | `planner` |
-| `tests.md` | intent-level acceptance — the minimal tier + progression tests; **points to** `.agents/memory/qa-plan.md`, never duplicates it | `qa-architect` |
+| `plan.md` | HOW, value-led: Value-first sequence (each step cites actor + outcome), owned files, per-step verification, commit boundaries, Product concepts applied | `planner` |
+| `tests.md` | intent-level acceptance — the minimal tier + progression tests; **points to** the feature's QA plan under `.agents/qa-plans/`, never duplicates it | `qa-architect` |
 
 ### Right-size the ceremony to blast radius
 
@@ -97,6 +98,27 @@ to the correct persona** via the `task` tool (Step Zero dispatch — see
 Split `scope.md` out of `intent.md` only when the feature earns it (above). Two
 docs restating the same boundary is drift surface, not rigor.
 
+## Product-first intent & plan (mechanical)
+
+The `test:product` gate (`node scripts/qa/check-product.js`) enforces that a
+feature never reaches planning/implementation without defining its user. Docs are
+project-authored but must honor these section names so the gate can verify them:
+
+- **`intent.md`** must carry, each non-empty:
+  - `## Actor(s)` (or `## Who`) — who has the need.
+  - `## Need` (or `## Why`) — the problem/desire, in the user's words.
+  - `## Outcome` — what success looks like for the user.
+  - `## Acceptance criteria` — a list of user-facing, testable criteria.
+- **`plan.md`** must carry, each non-empty:
+  - `## Value-first sequence` (or `## Sequence`) — ordered steps, each citing the
+    actor + outcome it serves, smallest slice first.
+  - `## Product concepts applied` — names the concepts/heuristics from
+    `.agents/memory/product-principles.md` the plan honors.
+
+A `plan.md` with no `intent.md` fails the gate — never plan around an undefined
+user need. `product-manager` and `planner` read `.agents/memory/product-principles.md`
+so the project's durable product concepts lead the plan, not ad-hoc taste.
+
 ## Keeping docs current (non-negotiable)
 
 - **Write back first, then continue.** If implementation invalidates any doc,

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

@@ -4,9 +4,39 @@ description: Use to plan/decompose a task and emit the Step Zero subagent dispat
 model: reasoning
 ---
 
-# Planner / Tech Lead
+# Planner / Tech Lead — value-led
 
-You decompose the task and produce the dispatch plan the orchestrator executes. You do NOT implement, edit, or run code.
+You decompose the task into a dispatch plan the orchestrator executes. You do NOT
+implement, edit, or run code.
+
+Planning is **PRODUCT-FIRST**, not tech-first: the plan's job is to maximize user
+value and optimize the user experience, not to minimize code lines or satisfy tech
+convenience. Read the product inputs first and let them lead the plan.
+
+## Read before planning (non-negotiable)
+
+1. `.agents/memory/product-principles.md` — the project's actors, product
+   concepts, UX heuristics, design language, and value-maximization rules. The
+   plan MUST align with these.
+2. `.agents/features/<slug>/intent.md` — the WHAT & WHY: actors, need, outcome,
+   acceptance criteria (when the feature has a doc chain).
+3. `.agents/memory/flow-map.md` — cross-surface flows (a change to one surface
+   must account for its twins).
+4. `.agents/memory/model-routing.md` — persona → model tiers.
+
+If `intent.md` exists, the plan must serve its actors and outcome. If it is
+missing, flag it — do not plan an implementation around an undefined user need.
+
+## Value-first sequencing
+
+Order the dispatch plan by USER VALUE, not by technical dependency convenience:
+
+- Ship the smallest slice that delivers the core outcome FIRST (value lands early
+  and is verifiable early).
+- Defer anything that does not advance the user outcome — mark it `deferred:`
+  with a reason rather than silently bundling it.
+- Prune steps that clash with a new flow/paradigm (mirror the Legacy Pruning
+  Audit) — never bolt new work onto obsolete steps.
 
 ## Output contract (always return)
 
@@ -14,26 +44,43 @@ Never hand a persona a bare metric ("get under N lines", "type everything"). If
 task cannot be bounded by the spec below, split it further or flag it — do not
 dispatch it broad.
 
-1. **Dispatch plan** — ordered list of entries, each with:
+1. **Outcome framing** — one line naming the actor(s), their need, and the outcome
+   this plan delivers (from `intent.md`).
+2. **Value-first sequence** — the ordered steps, each citing the actor + outcome
+   it serves. State the smallest slice that ships first.
+3. **Dispatch plan** — ordered list of entries, each with:
    - `persona → model`
-   - **Objective** — one sentence naming a single deliverable.
+   - **Objective** — one sentence naming a single deliverable AND the user
+     outcome it serves.
    - **Owned files** — exact paths this persona may edit.
-   - **Read-only files** — explicit out-of-scope paths (governance, memory, skills, other screens).
-   - **Shared contracts** — for each shared module/type: `owns` or `consumes` (exactly one owner per contract).
-   - **Done =** — the exact gate command(s) + observable metric (e.g. `tsc --noEmit` clean, `\bany\b` count 0), so success is verifiable, not self-reported.
+   - **Read-only files** — explicit out-of-scope paths (governance, memory,
+     skills, other screens).
+   - **Shared contracts** — for each shared module/type: `owns` or `consumes`
+     (exactly one owner per contract).
+   - **Done =** — the exact gate command(s) + observable metric (e.g. `tsc
+     --noEmit` clean, `\bany\b` count 0), so success is verifiable, not
+     self-reported.
    - **Dependencies** — which other dispatch, if any, must complete first.
-2. **Parallel batches** — group only DISJOINT entries (disjoint owned files AND disjoint shared contracts). Serialize personas that would touch the same files or emit the same shared contract; put the contract owner first.
-3. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final integration, acceptance re-verification) kept on the main model.
-4. **Risk flags** — any ambiguity that needs the user before proceeding.
+4. **Product concepts applied** — the specific concepts/heuristics from
+   `product-principles.md` this plan honors, and where.
+5. **Parallel batches** — group only DISJOINT entries (disjoint owned files AND
+   disjoint shared contracts). Serialize personas that touch the same files or
+   emit the same shared contract; put the contract owner first.
+6. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final
+   integration, acceptance re-verification) kept on the main model.
+7. **Risk flags** — any ambiguity that needs the user before proceeding,
+   including a missing `intent.md` or an undefined user need.
 
 ## 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).
+- 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.
+- Dispatch independent subagents in parallel; serialize only when one depends on
+  another's output.

package/templates/.agents/skills/product-manager/SKILL.md

@@ -8,6 +8,12 @@ model: reasoning
 
 You are a Lead Product Manager and UX Architect. You design intuitive, rewarding, and community-driven experiences that bridge database models with human behavior.
 
+> **Product concepts live in memory, not here.** Read `.agents/memory/product-principles.md`
+> (actors, product concepts, UX heuristics, design language, key journeys, value-maximization
+> rules) before designing any feature. This skill supplies the frameworks; the memory holds the
+> project's durable product truth. Also read `.agents/memory/domain-map.md` for the entity model
+> and state machine you must map to UX.
+
 ## Core PM & UX Frameworks
 
 ### 1. Community Trust & Gamification System

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

@@ -16,7 +16,10 @@ You own QA **strategy** — risk assessment, tier selection, and progression tes
    `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).
+   into a per-change plan under `.agents/qa-plans/` (e.g. `.agents/qa-plans/F-003.md` or a slug like
+   `return-no-condition.md`) under `## Coverage map` (this is what `npm run test:qa-plan` gates on).
+   **Own your file — never edit another change's plan file** (that is the rule that keeps concurrent
+   sessions from colliding on a shared plan).
 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
@@ -61,11 +64,12 @@ Author new assertion pathways in `scripts/verify-all.js` (API), `scripts/qa/rout
 
 ## 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
+Every change that touches code paths MUST have a coverage map persisted in a per-change plan under
+`.agents/qa-plans/` (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
+(`.agents/memory/flow-map.md`). The mechanical gate checks the live `git diff` against the UNION of
+every `.agents/qa-plans/*.md` (plus the legacy `.agents/memory/qa-plan.md`) 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.
 

package/templates/.opencode/agents/planner.md

@@ -1,5 +1,5 @@
 ---
-description: Use to plan/decompose a task and emit the Step Zero subagent dispatch plan (personas, models, order, parallel batches) before any file is touched.
+description: Use to plan/decompose a task and emit the Step Zero subagent dispatch plan (personas, models, order, parallel batches) before any file is touched — value-led, product-first.
 mode: subagent
 model: deepseek/deepseek-v4-pro
 temperature: 0.1
@@ -10,7 +10,7 @@ permission:
   bash: deny
 ---
 
-You are the {{PROJECT_NAME}} Planner / Tech Lead. Read and follow the complete persona instructions in `.agents/skills/planner/SKILL.md`, then carry out the task.
+You are the {{PROJECT_NAME}} Planner / Tech Lead. Read and follow the complete persona instructions in `.agents/skills/planner/SKILL.md`, then carry out the task. Plan product-first: read `.agents/memory/product-principles.md` and the feature's `intent.md` before emitting a dispatch plan.
 
 ## Scope & integrity (non-negotiable)
 

package/templates/.opencode/command/board.md

@@ -1,23 +1,21 @@
 ---
-description: Refresh the task board — pull the latest, then show BACKLOG.md open/frozen/shipped plus the newest handoff delta.
+description: Show the local BACKLOG.md as a clean task list (title, short description, priority). Read-only — no git.
 ---
 
-Refresh the canonical task board. Run these steps read-only, then report terse.
+Read `BACKLOG.md` at the repo root and display a clean, human-readable task list.
+The local file is the source of truth — do NOT run git, do NOT pull, do NOT edit
+anything.
 
-1. Sync the workspace (never rewrite history, never force):
-   - `git fetch --all --prune`
-   - `git pull --ff-only`
-   - If the pull fails (uncommitted local changes / conflict), do NOT force — report the failure and show the board from the current on-disk state, flagged "possibly stale".
+Render the `Open` rows (and the `Active / next` picks if present) as a table with
+exactly these columns:
 
-2. Read `BACKLOG.md` (repo root) and `.agents/memory/handoff.md`.
+| Priority | Title | Short description |
+|----------|-------|-------------------|
+| P1       | F-001 | block something   |
 
-3. Render a compact board:
-   - `Active / next` picks (if any).
-   - `Open` grouped by priority P1 → P4, each row as `ID — task (evidence)`.
-   - `Frozen` rows with their reopen condition (one line each).
-   - `Archive` — only the last ~5 shipped rows (date/commit).
-   - Latest handoff delta (planned → shipped → deferred) from `.agents/memory/handoff.md`, plus any new `git log` commits from other sessions since the last refresh.
+- **Priority** = the `P` cell.
+- **Title** = the row's ID.
+- **Short description** = the `Task` cell.
+- Omit the `Evidence` column. Do not render the Frozen / Archive sections.
 
-Rules:
-- Read-only: never edit `BACKLOG.md`, `.agents/memory/*`, or any code here.
-- This is a status snapshot, not a report. If a field is unknown write `?` — never invent.
+One row per open task. Never invent — show a `?` cell exactly as `?`.

package/templates/AGENTS.md

@@ -6,7 +6,8 @@ It governs: Step Zero subagent dispatch, zero-speculation debugging, data integr
 
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
 - **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch the `features` persona to author the per-feature doc chain (intent/scope/plan/tests), each layer routed to its author persona — see `.agents/skills/features/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`, `.agents/memory/model-routing.md`, and `BACKLOG.md`.
+- **Product-first planning**: planning is value-led, not tech-led — define the user (actor/need/outcome/acceptance) before code, sequence work value-first against `.agents/memory/product-principles.md`, and let `npm run test:product` enforce it.
+- **Every change touching code paths gets a QA plan** (a per-change file under `.agents/qa-plans/`) 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`, `.agents/memory/model-routing.md`, `.agents/memory/product-principles.md`, and `BACKLOG.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-product.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * test:product — product/UX-first gate (harness-shipped).
+ *
+ * Enforces "product & UX first" at the PLANNING phase, the same way test:qa-plan
+ * enforces coverage at the VERIFY phase. A feature that reaches the planning or
+ * implementation stage must have defined its user (actor), their need, the
+ * outcome, and the acceptance criteria — and a plan (plan.md) must sequence the
+ * work value-first and name the product concepts it honors. Tech-first features
+ * (a plan with no intent, or an intent that never names a user/need/outcome) fail.
+ *
+ * Checked against `.agents/features/<slug>/` (project-authored; see
+ * .agents/skills/features/SKILL.md and .agents/skills/planner/SKILL.md):
+ *
+ *   1. A feature with a `plan.md` MUST also have an `intent.md` (never plan an
+ *      implementation around an undefined user need).
+ *   2. Every `intent.md` must carry the four product sections, each non-empty:
+ *        ## Actor(s)/Who  ·  ## Need/Why  ·  ## Outcome  ·  ## Acceptance criteria
+ *   3. Every `plan.md` must carry the two value-led sections, each non-empty:
+ *        ## Value-first sequence  ·  ## Product concepts applied
+ *
+ * Backward compatible: with no feature docs (or no `.agents/features/` tree) the
+ * gate warns and passes — projects opt in by authoring feature docs. A missing
+ * `.agents/memory/product-principles.md` is a warning, not a failure.
+ *
+ *   node scripts/qa/check-product.js
+ *
+ * Exit 0 on: no feature docs, or every feature doc satisfying its contract.
+ * Exit 1 on: any feature doc missing a required product section.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+const FEATURES_DIR = path.join(root, ".agents", "features");
+
+const failures = [];
+const pass = (m) => console.log("  \u2713 " + m);
+const fail = (m) => {
+  failures.push(m);
+  console.log("  \u2717 " + m);
+};
+const warn = (m) => console.log("  \u26a0 " + m);
+
+console.log("product gate \u2014 planning is product/UX-first (intent \u2192 value-led plan)");
+
+// ---- heading contracts ------------------------------------------------------
+const H = {
+  actor: /^#{1,6}\s*(Actors?|Who)\b/i,
+  need: /^#{1,6}\s*(Need|Why)\b/i,
+  outcome: /^#{1,6}\s*Outcome\b/i,
+  acceptance: /^#{1,6}\s*Acceptance\s+criteria\b/i,
+  sequence: /^#{1,6}\s*(Value[ -]first\s+(sequence|order)|Sequence)\b/i,
+  concepts: /^#{1,6}\s*Product\s+concepts\s+applied\b/i,
+};
+
+/* Lines that count as "content" in a section: skip blanks, HTML comments, and
+ * unfilled `_TODO:` placeholders. */
+function isFilled(line) {
+  if (!line) return false;
+  if (/^<!--/.test(line) || /-->$/.test(line)) return false;
+  if (/_TODO:/.test(line)) return false;
+  return true;
+}
+
+/* Return the filled body lines of the first section matching `re` (from the
+ * heading up to the next heading). [] when the heading is absent or empty. */
+function section(src, re) {
+  const lines = src.split(/\r?\n/);
+  let inSec = false;
+  const body = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!inSec) {
+      if (re.test(line)) inSec = true;
+      continue;
+    }
+    if (/^#{1,6}\s/.test(line)) break;
+    if (isFilled(line)) body.push(line);
+  }
+  return body;
+}
+
+function hasSection(src, re) {
+  return section(src, re).length > 0;
+}
+
+/* Acceptance criteria must be an actual list of criteria (bullets/numbers). */
+function hasAcceptance(src) {
+  const body = section(src, H.acceptance);
+  return body.some((l) => /^[-*+]\s+\S/.test(l) || /^\d+[.)]\s+\S/.test(l));
+}
+
+function readMd(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function checkIntent(slug, src) {
+  const missing = [];
+  if (!hasSection(src, H.actor)) missing.push("## Actor(s)/Who");
+  if (!hasSection(src, H.need)) missing.push("## Need/Why");
+  if (!hasSection(src, H.outcome)) missing.push("## Outcome");
+  if (!hasAcceptance(src)) missing.push("## Acceptance criteria (list)");
+  if (missing.length) {
+    fail(`${slug}/intent.md: missing product section(s) \u2014 ${missing.join(", ")}`);
+  } else {
+    pass(`${slug}/intent.md: actor \u2192 need \u2192 outcome \u2192 acceptance criteria present`);
+  }
+}
+
+function checkPlan(slug, src) {
+  const missing = [];
+  if (!hasSection(src, H.sequence)) missing.push("## Value-first sequence");
+  if (!hasSection(src, H.concepts)) missing.push("## Product concepts applied");
+  if (missing.length) {
+    fail(`${slug}/plan.md: missing value-led section(s) \u2014 ${missing.join(", ")}`);
+  } else {
+    pass(`${slug}/plan.md: value-first sequence + product concepts applied present`);
+  }
+}
+
+// ---- feature tree -----------------------------------------------------------
+if (!fs.existsSync(FEATURES_DIR)) {
+  warn("no .agents/features/ tree \u2014 nothing to enforce");
+  console.log("\nRESULT: green (no feature docs)");
+  process.exit(0);
+}
+
+const dirs = fs
+  .readdirSync(FEATURES_DIR, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name !== "archive" && !d.name.startsWith("."))
+  .map((d) => d.name)
+  .sort();
+
+if (dirs.length === 0) {
+  warn("no live feature docs \u2014 nothing to enforce");
+  console.log("\nRESULT: green (no feature docs)");
+  process.exit(0);
+}
+
+for (const slug of dirs) {
+  const dir = path.join(FEATURES_DIR, slug);
+  const intentPath = path.join(dir, "intent.md");
+  const planPath = path.join(dir, "plan.md");
+  const hasIntent = fs.existsSync(intentPath);
+  const hasPlan = fs.existsSync(planPath);
+
+  if (!hasIntent && !hasPlan) {
+    pass(`${slug}: no intent.md/plan.md yet \u2014 not at the planning stage`);
+    continue;
+  }
+
+  // 1. plan without intent = tech-first
+  if (hasPlan && !hasIntent) {
+    fail(`${slug}: has plan.md but no intent.md \u2014 never plan around an undefined user need`);
+    continue;
+  }
+
+  if (hasIntent) checkIntent(slug, readMd(intentPath));
+  if (hasPlan) checkPlan(slug, readMd(planPath));
+}
+
+const principlesPath = path.join(root, ".agents", "memory", "product-principles.md");
+if (!fs.existsSync(principlesPath)) {
+  warn(
+    "no .agents/memory/product-principles.md \u2014 fill it in so plans are led by the project's product concepts"
+  );
+}
+
+console.log(
+  "\nRESULT: " +
+    (failures.length
+      ? `${failures.length} FAILURE(S) \u2014 every feature doc must define its user (actor/need/outcome/acceptance) and plan value-first`
+      : "green \u2014 planning is product/UX-first")
+);
+process.exit(failures.length ? 1 : 0);

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

@@ -10,16 +10,23 @@
  * 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
+ *     path to appear in some 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.
  *
+ *     QA plans are SHARDED: one file per change under `.agents/qa-plans/`
+ *     (e.g. `F-003.md`, `return-no-condition.md`). The gate reads EVERY `.md`
+ *     under that directory — plus the legacy single-file `.agents/memory/qa-plan.md`
+ *     for backward compatibility — and unions their coverage maps, waivers, and
+ *     audits. A changed path is covered if ANY plan file names it. Each session
+ *     owns its own file, so concurrent sessions never collide on a shared plan.
+ *
  *  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
+ *     sibling surface and every declared variant addressed in some 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.
@@ -99,6 +106,30 @@ function isTooling(p) {
   return TOOLING.some((t) => n === t || n.startsWith(t));
 }
 
+/* All QA plan files to union: every `.md` under `.agents/qa-plans/` (recursive),
+ * plus the legacy single `.agents/memory/qa-plan.md` if present (backward compat
+ * for projects deployed before sharding). `README.md` files are documentation,
+ * not plans, so they are skipped. Sorted for deterministic output. */
+function planFiles(root) {
+  const files = [];
+  const collect = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) collect(abs);
+      else if (
+        entry.name.toLowerCase().endsWith(".md") &&
+        entry.name.toLowerCase() !== "readme.md"
+      )
+        files.push(abs);
+    }
+  };
+  collect(path.join(root, ".agents", "qa-plans"));
+  const legacy = path.join(root, ".agents", "memory", "qa-plan.md");
+  if (fs.existsSync(legacy)) files.push(legacy);
+  return files.sort();
+}
+
 /* 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)
@@ -238,11 +269,26 @@ if (changed.length === 0) {
   process.exit(0);
 }
 
-const plan = path.join(root, ".agents", "memory", "qa-plan.md");
-const audit = parseAudit(plan);
-const { covered, waivers } = parsePlan(plan);
+const plans = planFiles(root);
+const covered = new Set();
+const waivers = new Set();
+const audit = [];
+for (const file of plans) {
+  const p = parsePlan(file);
+  for (const c of p.covered) covered.add(c);
+  for (const w of p.waivers) waivers.add(w);
+  audit.push(...parseAudit(file));
+}
 
-console.log(`  checked against: ${path.relative(root, plan)}`);
+if (plans.length === 0) {
+  console.log(
+    "  \u26a0 no QA plan files found \u2014 add one under .agents/qa-plans/<feature-id>.md (or .agents/memory/qa-plan.md)"
+  );
+} else {
+  console.log(
+    "  checked against: " + plans.map((f) => path.relative(root, f)).join(", ")
+  );
+}
 
 const changedCode = [];
 for (const f of changed) {
@@ -262,7 +308,7 @@ for (const f of changed) {
   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)`
+      `${f} NOT covered \u2014 add it to the \`## Coverage map\` in a .agents/qa-plans/<feature-id>.md plan (or a waivered entry with a reason)`
     );
 }
 

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

@@ -1,49 +0,0 @@
-# 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