@dombaras/agent-harness 0.1.10 → 0.1.12

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`.
 
@@ -44,6 +45,7 @@ npx @dombaras/agent-harness init --target . --dry-run
 | `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` gates + QA-script wiring check | harness (overwrite) |
 | `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history, flow-map, qa-plan) | **project** (create-if-missing) |
 | `.harness.json` | deployed version + project profile + per-file checksums | harness |
+| `.gitignore` | harness-managed section (`.harness-backup/`) merged in, project entries preserved | harness (merged) |
 
 ### `opencode.json` is merged, not clobbered
 
@@ -108,6 +110,10 @@ warns but does not block; the guarantee only applies to registered flows.
   `deepseek/deepseek-v4-pro` (default, direct API key), `zen`/`opencode` →
   `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 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
 
@@ -144,11 +150,13 @@ 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
+- **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
@@ -166,6 +174,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

@@ -217,6 +217,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 +367,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 +461,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,
@@ -527,13 +563,14 @@ 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 +822,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.10",
+  "version": "0.1.12",
   "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"

package/templates/.agents/AGENTS.md

@@ -103,9 +103,11 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 
 ## 7. Definition of Done & Continuous Backup
 
-Every completed task passes this gate, in order:
+Every completed task closes with this gate. **QA gates dev work only:** steps 0-2
+run when the session touched code paths — a backlog-only (or docs-only) change skips
+them. Steps 3-5 are the unconditional session close; they are NOT gated by QA.
 
-0. **Feature Completeness Gate**:
+0. **Feature Completeness Gate** (code changes 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.
@@ -113,10 +115,11 @@ Every completed task passes this gate, in order:
    - [ ] Cross-screen audit if a new UX pattern was introduced.
    - [ ] No modified file over ~500 lines without extracting components.
    - [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
-1. **QA tier** — `qa-architect` inspects the diff, picks the tier BY COVERAGE (not path-label), records the coverage map in `.agents/memory/qa-plan.md`, and authors progression tests for any GAP; if `qa-architect` is not dispatched the orchestrator plans in its place. `qa-runner` executes and makes it pass (§6). A change is not verified until `npm run test:qa-plan` passes: every changed code path covered or waivered, **and** every touched flow (`.agents/memory/flow-map.md`) has every sibling surface and declared variant addressed in the plan's `## Parallel-surface & variant audit`, **AND** the executed tier exercised the modified path.
-2. **Security check** — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
-3. **Commit** — concise `feat:` / `fix:` / `refactor:` message.
-4. **Push** — `git push origin main`.
+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.
+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.
+5. **Push** (always) — `git push origin main`.
 - **Mechanical floor**: a pre-push hook should run `npm run test:quick` (project-provided; the harness does not install git hooks).
 - **Lean permissions**: grant only the narrowest `git`/`gh` action needed; escalate only after a command has actually failed.
 - Git may not be on PATH in the default shell — use the full path (`.agents/memory/locations.md`).

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

@@ -23,12 +23,12 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 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.
+7. **Commit** with `feat:`/`fix:`/`refactor:` then push to main — including any `BACKLOG.md` delta.
 
 ## Definition of Done
 
-Right-sized QA tier → security lens (if the change touches data/auth/input/secrets) → commit → push.
+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.
 
 ## Session checklist
 
-Start: read `.agents/memory/locations.md` + `.agents/memory/model-routing.md` + `BACKLOG.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: move shipped `BACKLOG.md` rows to `Archive`, record the dispatch log, and update the handoff memory.

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

@@ -48,3 +48,4 @@ Date: <YYYY-MM-DD>
 - Update this at session end even if the user doesn't ask, per the DoD in `.agents/AGENTS.md` §8.
 - Keep it under ~40 lines. Code is the source of truth; the handoff is a pointer, not a spec.
 - Keeping `.agents/memory/locations.md` current is part of this skill. Read it first, update it last.
+- **You only touch handoff memory.** The board write-back — moving shipped `BACKLOG.md` rows to `Archive (shipped · done)` and committing them — is the orchestrator's DoD §7 step, not yours. If it hasn't been done, call it out in your output; never edit `BACKLOG.md` or run git yourself.

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

@@ -0,0 +1,21 @@
+---
+description: Show the local BACKLOG.md as a clean task list (title, short description, priority). Read-only — no git.
+---
+
+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.
+
+Render the `Open` rows (and the `Active / next` picks if present) as a table with
+exactly these columns:
+
+| Priority | Title | Short description |
+|----------|-------|-------------------|
+| P1       | F-001 | block something   |
+
+- **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.
+
+One row per open task. Never invent — show a `?` cell exactly as `?`.

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

@@ -16,9 +16,12 @@
  *   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.
+ *   7. `BACKLOG.md` is git-tracked (committed), not untracked — the board syncs
+ *      across sessions only through git. Skipped outside a git repo.
  */
 const fs = require("fs");
 const path = require("path");
+const { execFileSync } = require("child_process");
 
 const root = path.resolve(__dirname, "..", "..");
 
@@ -41,6 +44,40 @@ if (!fs.existsSync(canonical)) {
 }
 check(true, "canonical BACKLOG.md present at repo root");
 
+// ---- 7. BACKLOG.md must be git-tracked (committed), not untracked ----------
+// The board syncs across sessions only through git; an untracked BACKLOG.md
+// never reaches the shared board. Skipped outside a git repo.
+function insideGitRepo() {
+  try {
+    const r = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: root,
+      stdio: "pipe",
+    });
+    return (r.toString() || "").trim() === "true";
+  } catch (_) {
+    return false;
+  }
+}
+function gitTracked(rel) {
+  try {
+    const r = execFileSync("git", ["ls-files", "--error-unmatch", rel], {
+      cwd: root,
+      stdio: "pipe",
+    });
+    return (r.toString() || "").trim().length > 0;
+  } catch (_) {
+    return false;
+  }
+}
+if (insideGitRepo()) {
+  check(
+    gitTracked("BACKLOG.md"),
+    "BACKLOG.md is git-tracked (run `git add BACKLOG.md` then commit — an untracked board never syncs)"
+  );
+} else {
+  check(true, "not a git repo \u2014 skipping BACKLOG.md tracking check");
+}
+
 const src = fs.readFileSync(canonical, "utf8");
 const lines = src.split(/\r?\n/);