@dombaras/agent-harness 0.1.11 → 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
 
@@ -109,10 +111,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
 
@@ -149,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
@@ -171,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.11",
+  "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/.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 `?`.