@dombaras/agent-harness 0.1.9 → 0.1.10

package/README.md

@@ -34,11 +34,12 @@ npx @dombaras/agent-harness init --target . --dry-run
 | Path | Content | Ownership |
 |---|---|---|
 | `AGENTS.md` | root dispatcher (points to the rulebook) | harness (overwrite) |
+| `BACKLOG.md` | canonical task list (Open / Frozen / Archive / Not tracking) | **project** (create-if-missing) |
 | `.opencode/agents/*.md` | 14 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
 | `.agents/AGENTS.md` | full canonical operating rulebook | harness (overwrite) |
 | `.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) |
-| `.agents/features/INDEX.md` | feature backlog + status board (durable feature doc tree root) | **project** (create-if-missing) |
+| `.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) |
@@ -61,15 +62,16 @@ scaffolds for you to fill in — the skills and rules reference memory instead o
 hardcoding domain assumptions.
 
 **Features (`.agents/features/`)** — the durable, feature-centric plan of record. A
-found item is captured as one light row in `.agents/features/INDEX.md` (backlog: what's
-known, priority, context, status). When a feature 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 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. See
-`.agents/skills/features/SKILL.md`.
+found item is captured as one light row in the canonical `BACKLOG.md` (repo root; the
+single write-path for all open work: what's known, priority, evidence). When a feature
+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
+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`.
 
 **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
@@ -111,6 +113,10 @@ warns but does not block; the guarantee only applies to registered flows.
 
 - `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:backlog` — canonical single-backlog gate: `BACKLOG.md` is the one
+  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: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
@@ -135,9 +141,9 @@ scripts are **project-provided** — the rulebook references them, and
 npx @dombaras/agent-harness update --target /path/to/project
 ```
 
-- Overwrites harness-owned files, preserves `.agents/memory/*`.
+- Overwrites harness-owned files, preserves `.agents/memory/*` and `BACKLOG.md`.
 - Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
-  `test:qa-plan`) into the target's `package.json` (merged, add-only).
+  `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
   <old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
   modified harness files. Your unrelated uncommitted work is never staged.
@@ -162,6 +168,18 @@ npx @dombaras/agent-harness update --target /path/to/project
 - `opencode.json` is merged (project keys preserved).
 - `--dry-run` previews the plan without writing.
 
+### Backlog migration (`migrate-backlog`)
+
+```bash
+npx @dombaras/agent-harness migrate-backlog --target /path/to/project
+```
+
+Consolidates any live `.agents/features/INDEX.md` F-rows and
+`.agents/memory/todo.md` list items into the canonical `BACKLOG.md`, then rewrites
+both as pointers. Idempotent — re-running never duplicates rows (it only merges into
+an empty board) — and never deletes a source before `BACKLOG.md` is written and
+verified. Logs a summary: `N open · M frozen · K archived`.
+
 ## Develop
 
 ```bash

package/bin/agent-harness.js

@@ -7,6 +7,7 @@
  * Commands:
  *   init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run]
  *   update [--target <dir>] [--dry-run]
+ *   migrate-backlog [--target <dir>]
  *   list
  *   --version | -v
  *   --help | -h
@@ -16,6 +17,8 @@
  *
  * Ownership model:
  *   - `.agents/memory/*` + `.agents/features/*` is project data -> create-if-missing (never overwrite).
+ *   - `BACKLOG.md` (repo root) is project data -> create-if-missing (never overwrite); it is the
+ *     canonical task list, and `update` must never clobber the project's live board.
  *   - `opencode.json` is MERGED: harness manages $schema/model/small_model/
  *     instructions; every other key the project adds is preserved.
  *   - all other harness-owned files are overwritten. If a harness-owned file was
@@ -99,6 +102,18 @@ function isProjectScaffold(rel) {
     (parts.includes("memory") || parts.includes("features"))
   );
 }
+/* The canonical `BACKLOG.md` at the repo root is also project data (a live task
+ * list the project owns): scaffolded create-if-missing, never overwritten so an
+ * `update` can never clobber the project's board, and never tracked in the
+ * manifest (its content is the project's, not the harness's). */
+function isBacklogFile(rel) {
+  return relKey(rel) === "BACKLOG.md";
+}
+/* Combined: any file that must be scaffolded create-if-missing rather than
+ * overwritten. */
+function isCreateIfMissing(rel) {
+  return isProjectScaffold(rel) || isBacklogFile(rel);
+}
 /* Back-compat alias (kept for any external caller referencing the old name). */
 function isMemoryFile(rel) {
   return isProjectScaffold(rel);
@@ -183,6 +198,7 @@ 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",
+  "test:backlog": "node scripts/qa/check-backlog.js",
 };
 
 // Merge harness gate scripts into the project's existing package.json, preserving
@@ -350,7 +366,7 @@ async function deploy(target, opts) {
       continue;
     }
 
-    if (isProjectScaffold(rel)) {
+    if (isCreateIfMissing(rel)) {
       if (fs.existsSync(targetAbs)) {
         actions.push({ rel: key, kind: "preserve" });
       } else {
@@ -500,11 +516,11 @@ function printNextSteps() {
   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. Capture found items as rows in `.agents/features/INDEX.md`; dispatch the `features`");
-  console.log("      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`) 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() {
@@ -513,11 +529,17 @@ function printUsage() {
       `Usage:\n` +
       `  agent-harness init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run]\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` +
       `\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` +
+      `  files as pointers. Idempotent: re-running never duplicates rows or deletes a\n` +
+      `  source before BACKLOG.md is written and verified.\n` +
+      `\n` +
       `  agent-harness list\n` +
       `  agent-harness --version | -v\n` +
       `  agent-harness --help | -h\n`
@@ -534,6 +556,222 @@ function printPersonas(templatesDir) {
   }
 }
 
+// ---------------------------------------------------------------- backlog migration
+
+/* Split a markdown table row on unescaped `|` (respects `\|` inside cells). */
+function splitCells(row) {
+  const cells = [];
+  let cur = "";
+  let esc = false;
+  for (const ch of row) {
+    if (esc) {
+      cur += ch;
+      esc = false;
+    } else if (ch === "\\") {
+      esc = true;
+      cur += ch;
+    } else if (ch === "|") {
+      cells.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+/* Parse markdown table data rows, skipping headers and separator/empty rows. */
+function parseTableRows(src) {
+  const rows = [];
+  for (const raw of String(src || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!/^\|.*\|$/.test(line)) continue;
+    const cells = splitCells(line.slice(1, -1));
+    if (cells.every((c) => /^[-:|\s]*$/.test(c))) continue; // separator
+    if (cells.every((c) => c.trim() === "")) continue; // empty row
+    if (
+      cells.some((c) =>
+        /^(ID|[Ii]d|P|Task|Item|Priority|Context|Status|Evidence|Why frozen|Closed|Why frozen \/ reopen when)$/.test(c)
+      )
+    )
+      continue; // header
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/* Parse markdown list items (bullets / checkboxes), preserving the text. */
+function parseListItems(src) {
+  const items = [];
+  for (const raw of String(src || "").split(/\r?\n/)) {
+    const m = raw.match(/^\s*[-*]\s+(?:\[[ x]\]\s*)?(.+)$/);
+    if (m && m[1].trim()) items.push(m[1].trim());
+  }
+  return items;
+}
+
+/* Map an old INDEX.md F-row (ID | Item | Priority | Context | Status) into the
+ * BACKLOG schema. Returns null for rows that carry no usable identity. */
+function mapIndexRow(cells) {
+  const id = (cells[0] || "").trim();
+  if (!id) return null;
+  const task = (cells[1] || "").trim() || id;
+  const rawPriority = (cells[2] || "").trim();
+  const context = (cells[3] || "").trim();
+  const status = (cells[4] || "").trim().toLowerCase();
+
+  // Reconcile the priority direction: old `P0` (blocking) == new `P1`.
+  let priority = rawPriority;
+  if (priority === "P0") priority = "P1";
+  if (!/^P[1-4]$/.test(priority)) priority = "?";
+
+  const evidence = context || "?";
+  const base = { id, task, priority, evidence };
+
+  if (/^(shipped|archived|done|closed)$/.test(status)) {
+    return { ...base, section: "archive", closed: status };
+  }
+  if (status === "frozen") {
+    return { ...base, section: "frozen", reopen: context || "frozen (migrated); reopen when evidence recurs" };
+  }
+  return { ...base, section: "open" };
+}
+
+/* Ensure the canonical BACKLOG.md exists (create-if-missing from the template),
+ * then — ONLY when it is still empty — consolidate a live INDEX.md F-rows list
+ * and a live todo.md list into it, and rewrite both as pointers. Idempotent:
+ * a re-run finds BACKLOG.md already populated and leaves it untouched. */
+function migrateBacklog(target) {
+  const backlogPath = path.join(target, "BACKLOG.md");
+  const indexPath = path.join(target, ".agents", "features", "INDEX.md");
+  const todoPath = path.join(target, ".agents", "memory", "todo.md");
+  const templatePath = path.join(TEMPLATES_DIR, "BACKLOG.md");
+
+  const summary = { open: 0, frozen: 0, archived: 0, sources: [], createdBacklog: false, rewritten: [] };
+
+  // 1. Scaffold BACKLOG.md if missing (never overwrite an existing board).
+  if (!fs.existsSync(backlogPath)) {
+    if (!fs.existsSync(templatePath)) {
+      throw new Error("templates/BACKLOG.md not found next to this CLI.");
+    }
+    fs.mkdirSync(path.dirname(backlogPath), { recursive: true });
+    fs.writeFileSync(backlogPath, fs.readFileSync(templatePath, "utf8"), "utf8");
+    summary.createdBacklog = true;
+  }
+
+  // 2. Only merge into an empty board — idempotency guard against duplicates.
+  const existing = fs.readFileSync(backlogPath, "utf8");
+  const alreadyHasRows = parseTableRows(existing).length > 0;
+  if (alreadyHasRows) {
+    summary.skipped = "BACKLOG.md already has rows — nothing merged";
+    return summary;
+  }
+
+  // 3. Read the two sources.
+  const open = [];
+  const frozen = [];
+  const archive = [];
+  const seenIds = new Set();
+
+  const push = (row) => {
+    if (!row || seenIds.has(row.id)) return;
+    seenIds.add(row.id);
+    if (row.section === "archive") archive.push(row);
+    else if (row.section === "frozen") frozen.push(row);
+    else open.push(row);
+  };
+
+  if (fs.existsSync(indexPath)) {
+    const indexSrc = fs.readFileSync(indexPath, "utf8");
+    const isPointer = /BACKLOG\.md/.test(indexSrc);
+    if (!isPointer) {
+      summary.sources.push(".agents/features/INDEX.md");
+      for (const row of parseTableRows(indexSrc)) push(mapIndexRow(row));
+    }
+  }
+
+  let tCounter = 0;
+  if (fs.existsSync(todoPath)) {
+    const todoSrc = fs.readFileSync(todoPath, "utf8");
+    const isPointer = /BACKLOG\.md/.test(todoSrc);
+    if (!isPointer) {
+      summary.sources.push(".agents/memory/todo.md");
+      for (const item of parseListItems(todoSrc)) {
+        tCounter += 1;
+        push({
+          id: `T-${String(tCounter).padStart(3, "0")}`,
+          task: item,
+          priority: "?",
+          evidence: ".agents/memory/todo.md",
+          section: "open",
+        });
+      }
+    }
+  }
+
+  // 4. Emit BACKLOG.md only if there was something to migrate.
+  const total = open.length + frozen.length + archive.length;
+  if (total === 0) {
+    summary.skipped = "no live rows found in INDEX.md / todo.md";
+    return summary;
+  }
+
+  const toRow = (r) => `| ${r.id} | ${r.priority} | ${r.task} | ${r.evidence} |`;
+  const frozenRow = (r) => `| ${r.id} | ${r.task} | ${r.reopen} |`;
+  const archiveRow = (r) => `| ${r.id} | ${r.task} | ${r.closed} |`;
+
+  const table = (headers, rows) =>
+    [`| ${headers.join(" | ")} |`, `|${headers.map(() => "---").join("|")}|`, ...rows].join("\n");
+
+  const openBlock =
+    open.length === 0
+      ? ""
+      : `## Open\n\nSorted by priority (P1 → P4).\n\n${table(["ID", "P", "Task", "Evidence"], open.map(toRow))}`;
+  const frozenBlock =
+    frozen.length === 0
+      ? ""
+      : `## Frozen\n\nParked, not deleted. Reopen only when the stated condition recurs.\n\n${table(
+          ["ID", "Task", "Why frozen / reopen when"],
+          frozen.map(frozenRow)
+        )}`;
+  const archiveBlock =
+    archive.length === 0
+      ? ""
+      : `## Archive (shipped · done)\n\n${table(["ID", "Task", "Closed"], archive.map(archiveRow))}`;
+
+  // Rebuild the board: keep the template's usage header, replace the body.
+  const header = existing.split(/^## Active \/ next/m)[0].trim();
+  const body = [header, "## Active / next\n", openBlock, frozenBlock, archiveBlock, "## Not tracking (leave-in-place, no action)\n"]
+    .filter((b) => b.length > 0)
+    .join("\n\n") + "\n";
+
+  fs.writeFileSync(backlogPath, body, "utf8");
+
+  // 5. Verify BACKLOG.md is written and non-empty BEFORE rewriting sources.
+  const verify = fs.readFileSync(backlogPath, "utf8");
+  if (parseTableRows(verify).length === 0) {
+    throw new Error("refusing to rewrite sources: BACKLOG.md was not written with rows");
+  }
+
+  // 6. Rewrite sources as pointers (never before the board is verified).
+  const pointerFor = (name) =>
+    `# ${name}\n\nThe backlog lives in \`BACKLOG.md\` (repo root). Per-feature docs still\nlive in \`.agents/features/<slug>/\`. This file is a pointer, not a list.\n`;
+  if (fs.existsSync(indexPath) && !/BACKLOG\.md/.test(fs.readFileSync(indexPath, "utf8"))) {
+    fs.writeFileSync(indexPath, pointerFor("Features"), "utf8");
+    summary.rewritten.push(".agents/features/INDEX.md");
+  }
+  if (fs.existsSync(todoPath) && !/BACKLOG\.md/.test(fs.readFileSync(todoPath, "utf8"))) {
+    fs.writeFileSync(todoPath, pointerFor("Todo"), "utf8");
+    summary.rewritten.push(".agents/memory/todo.md");
+  }
+
+  summary.open = open.length;
+  summary.frozen = frozen.length;
+  summary.archived = archive.length;
+  return summary;
+}
+
 // ---------------------------------------------------------------- commands
 
 async function init(target, flags) {
@@ -628,6 +866,24 @@ function main() {
         process.exit(1);
       });
       break;
+    case "migrate-backlog":
+      try {
+        const s = migrateBacklog(target);
+        if (s.skipped) {
+          console.log(`\n[migrate-backlog] ${s.skipped}`);
+        } else {
+          console.log(
+            `\n[migrate-backlog] consolidated ${s.open} open · ${s.frozen} frozen · ${s.archived} archived`
+          );
+          if (s.sources.length) console.log(`  read from: ${s.sources.join(", ")}`);
+          if (s.rewritten.length) console.log(`  rewritten as pointers: ${s.rewritten.join(", ")}`);
+          if (s.createdBacklog) console.log("  created BACKLOG.md from the template");
+        }
+      } catch (e) {
+        console.error(e);
+        process.exit(1);
+      }
+      break;
     case "list":
       printPersonas(TEMPLATES_DIR);
       break;
@@ -650,6 +906,11 @@ module.exports = {
   resolveVars,
   mergeOpencodeJson,
   deploy,
+  migrateBacklog,
+  splitCells,
+  parseTableRows,
+  parseListItems,
+  mapIndexRow,
   printPersonas,
   TEMPLATES_DIR,
   CONFIG_FILE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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"
+    "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"
   },
   "keywords": [
     "opencode",

package/templates/.agents/AGENTS.md

@@ -57,7 +57,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Session wrap-up / handoff | `handoff` |
     | Feature backlog + per-feature doc tree (intent/scope/plan/tests) | `features` |
   - **Feature docs, not ceremony**: capture a found item as one light row in
-    `.agents/features/INDEX.md` (backlog). When a feature is picked up, dispatch
+    the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch
     `features` to author the doc chain — `intent` (product-manager) → `scope`
     (system-architect, HIGH-risk only) → `plan` (planner) → `tests` (qa-architect) —
     each by its author persona. Match ceremony to blast radius: trivial → none,

package/templates/.agents/features/INDEX.md

@@ -1,22 +1,8 @@
-# Features — backlog & status board
+# Features — pointer
 
-Project-owned (like all `.agents/features/*`). This is the **collection box**, not a
-spec and not a status board. Every found item gets one terse row here; the per-feature
-doc chain (`.agents/features/<slug>/` intent · scope · plan · tests) is written only
-when the main agent focuses on the feature. Keep rows ultra-light — a note, not a promise.
+The backlog lives in **`BACKLOG.md`** (repo root) — the canonical task list. Per-feature
+spec docs (`.agents/features/<slug>/` intent · scope · plan · tests) still live here in
+this tree, owned by the `features` persona (`.agents/skills/features/SKILL.md`).
 
-Maintained by the `features` persona (`.agents/skills/features/SKILL.md`).
-
-## Backlog
-
-One row per found item. `Status`: `backlog → ready → in-progress → testing → shipped → archived`.
-
-| ID | Item (what's known so far) | Priority | Context | Status |
-|----|----------------------------|----------|---------|--------|
-| F-001 | _replace: short, only-what-is-known description; open questions with `?`_ | P3 | _pointer to evidence (file/log/ticket/words), not a re-derivation_ | backlog |
-
-<!-- Add rows as items surface. Never invent status or priority — leave blank/`?` if unknown. -->
-
-## Active / next
-
-- _when a feature is about to be worked, cite it here and route the docs to the author personas (see skill)._
+This file is a pointer, not a list. Capture a found item as one row in `BACKLOG.md`;
+when a feature is picked up, dispatch `features` to author the per-feature doc chain.

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

@@ -27,7 +27,7 @@ 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 }`.
-- **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `.agents/features/*` (backlog + per-feature docs), routes each doc layer to its author persona.
+- **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `BACKLOG.md` (repo root) + `.agents/features/*` (per-feature docs), routes each doc layer to its author persona.
 - **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

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

@@ -11,7 +11,7 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 - **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`.
-- **Features**: capture a found item as one light row in `.agents/features/INDEX.md`; on pickup dispatch `features` to author the per-feature doc chain (`.agents/skills/features/SKILL.md`). Right-size ceremony to risk.
+- **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.
 - 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`.
 
@@ -31,4 +31,4 @@ Right-sized QA tier → security lens (if the change touches data/auth/input/sec
 
 ## Session checklist
 
-Start: read `.agents/memory/locations.md` + `.agents/memory/model-routing.md`. End: record the dispatch log and update the handoff memory.
+Start: read `.agents/memory/locations.md` + `.agents/memory/model-routing.md` + `BACKLOG.md`. End: record the dispatch log and update the handoff memory.

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

@@ -1,16 +1,17 @@
 ---
 name: features
-description: Use when the user asks to capture a found item, register a feature, manage the feature backlog, or prepare a feature for implementation — owns the .agents/features/ doc tree (INDEX + per-feature intent/scope/plan/tests).
+description: Use when the user asks to capture a found item, register a feature, manage the feature backlog, or prepare a feature for implementation — owns the BACKLOG.md task list and the .agents/features/ doc tree (per-feature intent/scope/plan/tests).
 model: mechanical
 ---
 
 # Features — backlog & per-feature doc tree
 
-You are the Feature Registrar for {{PROJECT_NAME}}. You keep the
-`.agents/features/` tree as the durable, feature-centric plan of record — the
-backlog of found items plus, once a feature is picked up, the intent → scope →
-plan → tests docs that frame it. You coordinate the authors; you do NOT pull the
-implementation work onto yourself (that is dispatched to the code personas).
+You are the Feature Registrar for {{PROJECT_NAME}}. You keep the canonical
+`BACKLOG.md` (repo root) as the single task list of record — the backlog of found
+items — plus, once a feature is picked up, the `.agents/features/<slug>/` intent →
+scope → plan → tests docs that frame it. You coordinate the authors; you do NOT
+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
@@ -20,7 +21,7 @@ per-session execution. Link between them, never duplicate.
 
 | Layer | What it is | Weight |
 |---|---|---|
-| **Backlog** (`.agents/features/INDEX.md`) | collection box of found items — one short row per item (what's known, priority, context, status). NOT a spec, NOT a status board. | ultra-light — every item gets one |
+| **Backlog** (`BACKLOG.md`, repo root) | collection box of found items — one short row per item (what's known, priority, evidence, section). NOT a spec, NOT a status board. `.agents/features/INDEX.md` is a pointer to it. | ultra-light — every item gets one |
 | **Feature docs** (`.agents/features/<slug>/` intent · scope · plan · tests) | the contract, written ONLY when the main agent focuses on the feature. | right-sized to risk |
 
 A found item is **only** ever a backlog row until it is picked up. Do not
@@ -30,35 +31,49 @@ the heavy SDLC the harness is designed to avoid.
 ## Tree layout
 
 ```
+BACKLOG.md                # canonical task list (Open / Frozen / Archive / Not tracking)
 .agents/features/
-  INDEX.md                 # backlog + status board (one row per item)
+  INDEX.md                # pointer to BACKLOG.md
   <slug>/
-    intent.md              # what & why, boundaries, acceptance criteria (1 pager)
-    scope.md               # optional — only on HIGH-risk features
-    plan.md                # implementation decomposition (HOW)
-    tests.md               # intent-level acceptance + pointer to qa-plan.md
-  archive/                 # completed feature dirs moved here
+    intent.md             # what & why, boundaries, acceptance criteria (1 pager)
+    scope.md              # optional — only on HIGH-risk features
+    plan.md               # implementation decomposition (HOW)
+    tests.md              # intent-level acceptance + pointer to qa-plan.md
+  archive/                # completed feature dirs moved here
 ```
 
 Save docs beside the code they describe; keep them in the same commit as the
 code that implements them so a feature's intent and its delivery cannot drift.
 
-## Backlog — `.agents/features/INDEX.md`
+## Backlog — `BACKLOG.md`
 
 One row per found item. Add a row when the user brings up a new idea/need/bug
-that is not yet being worked. Fields (keep each terse):
+that is not yet being worked. One write-path only: capture → `BACKLOG.md`, update
+it in the same session the work happens. Sections (see the `BACKLOG.md` header):
+
+- **Active / next** (optional) — the next few picks, cited as `ID (P)`.
+- **Open** — `| ID | P | Task | Evidence |`, sorted by priority.
+- **Frozen** — parked, don't-do-but-don't-delete; MUST carry a *why* and a *reopen condition*.
+- **Archive (shipped · done)** — completed rows, never deleted.
+- **Not tracking** — leave-in-place features, one prose note.
+
+Fields (keep each terse):
 
 - **What's known so far** — only what is actually known; mark open questions with `?`.
-- **Priority** — `P0` (blocking) / `P1` (important) / `P2` (nice-to-have) / `P3` (backlog).
-- **Context** — a pointer to evidence (file, log, ticket, the user's words), never a re-derivation.
-- **Status** — `backlog → ready → in-progress → testing → shipped → archived`.
+- **Priority** — `P1` (blocking) / `P2` (important) / `P3` (nice-to-have) / `P4` (later).
+  Applies to open rows only.
+- **Evidence** — a pointer to evidence (file, log, ticket, the user's words), never a re-derivation.
+- **Status ladder** — `backlog → ready → in-progress → testing → shipped → archived`, plus `frozen`.
 
-Never invent status or priority. If a field is unknown, leave it blank or `?` and
-say so; the row is a note, not a promise.
+Never invent status or priority. If a field is unknown, write `?` — an explicit
+unknown, never a blank cell. `npm run test:backlog` fails on a blank priority or
+evidence, a duplicate ID, an illegal status/priority, a `frozen` row without a
+reopen condition, or a live `.agents/features/INDEX.md` / `.agents/memory/todo.md`
+that isn't a pointer.
 
 ## Feature lifecycle (when the main agent focuses on a feature)
 
-Pick the ready item from `INDEX.md`, then author the docs **by routing each layer
+Pick the ready item from `BACKLOG.md`, then author the docs **by routing each layer
 to the correct persona** via the `task` tool (Step Zero dispatch — see
 `.agents/rules/00-operating.md` §Step Zero):
 
@@ -72,7 +87,7 @@ to the correct persona** via the `task` tool (Step Zero dispatch — see
 ### Right-size the ceremony to blast radius
 
 - **Trivial** (copy/docs, CSS tweak, single-file bug, anything a human would fix
-  in <30 minutes): no feature docs. Optionally note it in `INDEX.md` and close it.
+  in <30 minutes): no feature docs. Optionally note it in `BACKLOG.md` and close it.
 - **Low risk** (touches few files, no auth/DB/API contract): ONE `intent.md`
   (what & why, boundaries, acceptance) is enough. Fold scope into it.
 - **High risk** (auth/security, DB schema/migration, public API, payments, a flow
@@ -87,17 +102,18 @@ docs restating the same boundary is drift surface, not rigor.
 - **Write back first, then continue.** If implementation invalidates any doc,
   update the doc BEFORE coding continues. A stale spec is worse than none.
 - **Archive when it ships.** Move `.agents/features/<slug>/` to `archive/` and
-  mark the `INDEX.md` row `shipped`/`archived`. Do not leave a pile of completed
-  designs cluttering the live tree.
+  move the `BACKLOG.md` row to `Archive (shipped · done)` (or mark it
+  `shipped`/`archived`). Do not leave a pile of completed designs cluttering the
+  live tree.
 - Each doc starts with a `status:` line (`proposed → scoped → planned → testing →
   shipped → archived`) so an agent knows validity without reading the whole file.
 - When implementation drifts from a doc, fix the implementation to match the
   doc; when the doc is genuinely wrong, update the doc explicitly (with a one-line
-  note in `INDEX.md`), then regenerate the derived layers — never let the code
-  and the doc mutely diverge.
+  note in the `BACKLOG.md` row's evidence), then regenerate the derived layers —
+  never let the code and the doc mutely diverge.
 
 ## Output contract (always return)
 
-1. **Backlog delta** — items added / status changes, in `.agents/features/INDEX.md`.
+1. **Backlog delta** — items added / status changes, in `BACKLOG.md`.
 2. **Docs authored** — which feature docs were created/updated, by which dispatched persona.
 3. **Deferred & risks** — features parked, open questions, and what the orchestrator must route next.

package/templates/.opencode/agents/features.md

@@ -1,5 +1,5 @@
 ---
-description: Use when the user asks to capture a found item, register/manage a feature, or prepare a feature for implementation — owns the .agents/features/ doc tree (INDEX backlog + per-feature intent/scope/plan/tests) and routes each layer to its author persona.
+description: Use when the user asks to capture a found item, register/manage a feature, or prepare a feature for implementation — owns the BACKLOG.md task list and the .agents/features/ doc tree (per-feature intent/scope/plan/tests) and routes each layer to its author persona.
 mode: subagent
 model: opencode/gpt-5-nano
 temperature: 0.1
@@ -13,8 +13,8 @@ You are the {{PROJECT_NAME}} Feature Registrar. Read and follow the complete per
 
 ## Scope & integrity (non-negotiable)
 
-- Edit ONLY `.agents/features/*` (the INDEX backlog and per-feature doc dirs, including `archive/`). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, `.agents/skills/*`, other personas' files, and all code are READ-ONLY absent an explicit orchestrator grant.
+- Edit ONLY `BACKLOG.md` (repo root) and `.agents/features/*` (the per-feature doc dirs, including `archive/`). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, `.agents/skills/*`, other personas' files, and all code are READ-ONLY absent an explicit orchestrator grant.
 - You coordinate authors; you do NOT implement. When a feature doc layer needs writing, dispatch the owning persona (`product-manager`, `system-architect`, `planner`, `qa-architect`) via the `task` tool and route its output into the doc tree. Never fabricate a doc, a status, or a backlog row that has no basis in what was actually said or done.
-- Keep the two layers separate: every found item is a light `INDEX.md` row until it is picked up; the full doc chain is written only when the main agent focuses on the feature. Right-size ceremony to risk (trivial → none, low → `intent.md` only, high → full chain).
+- Keep the two layers separate: every found item is a light `BACKLOG.md` row until it is picked up; the full doc chain is written only when the main agent focuses on the feature. Right-size ceremony to risk (trivial → none, low → `intent.md` only, high → full chain).
 
 Return your final message in this exact order: **Result** (backlog delta + docs authored) -> **Evidence** (files changed, personas dispatched, observed output) -> **Deferred & risks** (features parked, open questions, next routing). Keep it under ~15 lines.

package/templates/AGENTS.md

@@ -5,8 +5,8 @@ The always-loaded rules summary lives in [`.agents/rules/00-operating.md`](.agen
 It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
 
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
-- **Features**: capture a found item as one light row in `.agents/features/INDEX.md` (backlog). 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`.
+- **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` and `.agents/memory/model-routing.md`.
+- **At session start**, read `.agents/memory/locations.md`, `.agents/memory/model-routing.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/BACKLOG.md

@@ -0,0 +1,52 @@
+# BACKLOG — canonical task list
+
+Single source of truth for **all** open work: features, bugs, follow-ups, audits,
+roadmaps, ideas. Every other list (`.agents/features/INDEX.md`,
+`.agents/memory/todo.md`, historical docs) points here. One row per task — if it's
+not a row, it doesn't exist.
+
+**Status ladder:** `backlog → ready → in-progress → testing → shipped → archived`,
+plus `frozen` (parked — keep a *why* and a *reopen condition*, never delete).
+**Priority (`P`):** `P1` blocking · `P2` important · `P3` nice-to-have · `P4` later.
+Priority applies to open rows only. **Evidence** = a pointer (file/log/ticket/words),
+never a re-derivation. Leave `?` where unknown — don't invent.
+
+> Updated in the same session the work happens. Archive `shipped` rows; freeze
+> don't-delete. Historical design docs are aspirational — verify against live code.
+
+## Active / next
+
+- _the next few picks (optional): cite each as `ID (P)`._
+
+## Open
+
+Sorted by priority (P1 → P4).
+
+| ID | P | Task | Evidence |
+|----|---|------|----------|
+| | | | |
+
+_Rows: `| F-001 | P3 | short desc; open questions with \`?\` | pointer, never a re-derivation |`_
+
+## Frozen
+
+Parked, not deleted. Reopen only when the stated condition recurs.
+
+| ID | Task | Why frozen / reopen when |
+|----|------|--------------------------|
+| | | |
+
+_Rows: `| F-002 | short desc | why + reopen condition (required) |`_
+
+## Archive (shipped · done)
+
+| ID | Task | Closed |
+|----|------|--------|
+| | | |
+
+_Rows: `| F-003 | short desc | shipped/done + date/commit |`_
+
+## Not tracking (leave-in-place, no action)
+
+_One prose note listing built-and-stable items deliberately left in place (no
+investment, no removal). Omit the section if there is nothing to note._

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

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * test:backlog — canonical-single-backlog gate (repo guard).
+ *
+ * Mechanically enforces the harness's ONE-write-path rule: `BACKLOG.md` at the
+ * repo root is the single source of truth for open work, and every other list
+ * (`.agents/features/INDEX.md`, `.agents/memory/todo.md`) is a pointer (or
+ * absent), never a live list.
+ *
+ *   1. Only ONE canonical backlog file exists: the repo-root `BACKLOG.md`.
+ *   2. Priority values are from {P1..P4} and apply to open rows only.
+ *   3. Every `frozen` row has a non-empty "why / reopen" condition.
+ *   4. Every `open` row has non-empty priority and evidence cells. `?` is
+ *      allowed but must be explicit — a blank cell is a failure.
+ *   5. No duplicate IDs across the whole file.
+ *   6. `INDEX.md` / `todo.md`, if present, are pointers (content referencing
+ *      BACKLOG.md), not live row lists.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+
+const PRIORITY = new Set(["P1", "P2", "P3", "P4"]);
+
+const failures = [];
+const warnings = [];
+const check = (ok, msg) => {
+  console.log(`  ${ok ? "\u2713" : "\u2717"} ${msg}`);
+  if (!ok) failures.push(msg);
+};
+
+console.log("backlog gate \u2014 canonical single-file BACKLOG.md");
+
+// ---- 1. Only ONE canonical backlog file ------------------------------------
+const canonical = path.join(root, "BACKLOG.md");
+if (!fs.existsSync(canonical)) {
+  console.error("FATAL: missing BACKLOG.md at repo root (the canonical task list)");
+  process.exit(2);
+}
+check(true, "canonical BACKLOG.md present at repo root");
+
+const src = fs.readFileSync(canonical, "utf8");
+const lines = src.split(/\r?\n/);
+
+// ---- table parsing ----------------------------------------------------------
+// Split a markdown table row on unescaped `|` (respects `\|` inside cells).
+function splitCells(row) {
+  const cells = [];
+  let cur = "";
+  let esc = false;
+  for (const ch of row) {
+    if (esc) {
+      cur += ch;
+      esc = false;
+    } else if (ch === "\\") {
+      esc = true;
+      cur += ch;
+    } else if (ch === "|") {
+      cells.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+// Group table rows by the last `##`/`###` section heading that preceded them.
+function parseSectionRows(lines) {
+  const buckets = {};
+  let current = null;
+  let rowCount = 0;
+  for (const raw of lines) {
+    const heading = raw.match(/^#{2,3}\s+(.*)$/);
+    if (heading) {
+      current = heading[1].trim();
+      buckets[current] = buckets[current] || [];
+      continue;
+    }
+    if (!current) continue;
+    const row = raw.trim();
+    if (!/^\|.*\|$/.test(row)) continue;
+    const inner = row.slice(1, -1);
+    const cells = splitCells(inner);
+    // skip empty rows and separators like `|---|---|`
+    if (cells.every((c) => /^[-:|\s]*$/.test(c) && c.trim().length === 0)) continue;
+    if (cells.every((c) => /^[-:|\s]*$/.test(c))) continue;
+    const joined = cells.join("|").trim();
+    if (/^([-:|\s]*)$/.test(joined)) continue;
+    // skip header rows named ID/P/Task/...
+    if (cells.some((c) => /^(ID|[Ii]d|P|Task|Evidence|Why frozen \/ reopen when|Closed)$/.test(c))) continue;
+    buckets[current].push(cells);
+    rowCount++;
+  }
+  return { buckets, rowCount };
+}
+
+const { buckets, rowCount } = parseSectionRows(lines);
+
+// Column indexes per section (from the BACKLOG template schema).
+const COLS = {
+  open: { id: 0, priority: 1, evidence: 3 },
+  frozen: { id: 0, reopen: 2 },
+  "archive (shipped · done)": { id: 0 },
+};
+
+function bucketRows(key) {
+  // tolerate loose heading variants
+  return buckets[key] || [];
+}
+
+const openRows = bucketRows("Open");
+const frozenRows = bucketRows("Frozen");
+const archiveRows = bucketRows("Archive (shipped · done)") || bucketRows("Archive");
+
+// ---- 3. Frozen requires a reopen condition ---------------------------------
+for (const r of frozenRows) {
+  const reopen = (r[COLS.frozen.reopen] || "").trim();
+  check(
+    reopen.length > 0,
+    `frozen row ${r[COLS.frozen.id]}: must carry a "why frozen / reopen when" condition`
+  );
+}
+
+// ---- 2 + 4. Open rows: valid priority + non-empty evidence -----------------
+for (const r of openRows) {
+  const id = r[COLS.open.id] || "?";
+  const priority = (r[COLS.open.priority] || "").trim();
+  const evidence = (r[COLS.open.evidence] || "").trim();
+  if (priority.length === 0) {
+    check(false, `open row ${id}: priority must not be blank (use P1..P4, or \`?\` if unknown)`);
+  } else if (!PRIORITY.has(priority)) {
+    check(false, `open row ${id}: priority \`${priority}\` not in {P1,P2,P3,P4}`);
+  } else {
+    check(true, `open row ${id}: priority \`${priority}\` is valid`);
+  }
+  check(
+    evidence.length > 0,
+    `open row ${id}: evidence must not be blank (pointer, or \`?\` if unknown)`
+  );
+}
+
+// ---- 5. No duplicate IDs across the whole file -----------------------------
+const allRows = [...openRows.map((r, i) => ({ cells: r, tag: "Open" })),
+  ...frozenRows.map((r, i) => ({ cells: r, tag: "Frozen" })),
+  ...archiveRows.map((r, i) => ({ cells: r, tag: "Archive" }))];
+const totalRows = allRows.length;
+if (totalRows > 0) {
+  check(true, `parsed ${totalRows} row(s) across Open/Frozen/Archive`);
+  const seen = new Map();
+  for (const { cells, tag } of allRows) {
+    const id = (cells[0] || "").trim();
+    if (!id) {
+      check(false, `${tag}: a row has no ID — rows must carry an ID (F-001, ...)`);
+      continue;
+    }
+    if (seen.has(id)) check(false, `duplicate ID \`${id}\` (${seen.get(id)} and ${tag})`);
+    else seen.set(id, tag);
+  }
+} else {
+  check(true, "empty board (no Open/Frozen/Archive rows yet) — valid for a fresh project");
+}
+
+// ---- 6. INDEX.md / todo.md are pointers, not live lists --------------------
+for (const rel of [".agents/features/INDEX.md", ".agents/memory/todo.md"]) {
+  const p = path.join(root, rel);
+  if (!fs.existsSync(p)) {
+    check(true, `${rel} absent`);
+    continue;
+  }
+  const content = fs.readFileSync(p, "utf8");
+  const isPointer = /BACKLOG\.md/.test(content);
+  const hasList = /^\s*\|.+\|/m.test(content);
+  if (isPointer) {
+    check(true, `${rel} is a pointer to BACKLOG.md`);
+  } else if (hasList) {
+    check(false, `${rel} looks like a live list — point it at BACKLOG.md (or remove it)`);
+  } else {
+    check(true, `${rel} present and not a live list`);
+  }
+}
+
+console.log(
+  `\nRESULT: ${failures.length ? `${failures.length} FAILURE(S)` : "backlog green"}`
+);
+process.exit(failures.length ? 1 : 0);