opencode-agent-harness 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 — 2026-11-16
4
+
5
+ First public release under the `opencode-agent-harness` name.
6
+
7
+ - Renamed the package from `@dombaras/agent-harness` to `opencode-agent-harness`
8
+ (the CLI binary remains `agent-harness`).
9
+ - `init` no longer commits or pushes by default; pass `--commit` / `--push`.
10
+ `update` keeps its auto-commit behaviour.
11
+ - `init` refuses to overwrite a pre-existing `AGENTS.md` it did not create;
12
+ `--accept-harness` overwrites deliberately after backing the file up under
13
+ `.harness-backup/`. Pre-existing untracked harness files are backed up before
14
+ any overwrite.
15
+ - Added `repository`, `homepage`, `bugs`, `author`, and public-package keywords;
16
+ Node engine raised to `>=20`.
17
+ - Added a packed-tarball smoke test (`npm run test:pack`), a `prepublishOnly`
18
+ gate, and a tag-driven release workflow.
19
+ - Default model routing is unchanged (`opencode-go/*`).
20
+
21
+ ## 0.1.21 — 2026-09-04
22
+
23
+ Last release under the previous name, `@dombaras/agent-harness`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 opencode-agent-harness contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,591 @@
1
- # Temporary Holding Version
1
+ # opencode-agent-harness
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A reusable multi-agent harness for AI-assisted development. Ships a persona
4
+ fleet (planner, engine engineer, mobile, QA architect/runner, security,
5
+ architecture, product, data, devops, handoff, docs), operating rules, model routing,
6
+ and QA gates — then deploys them into any project.
7
+
8
+ > Extracted from a production project so the "agents / subagents / guardrails /
9
+ > personas" layer is **not** an inherent part of the app codebase. It lives in its
10
+ > own repo and is installed via `npx opencode-agent-harness init`.
11
+
12
+ > **OpenCode V2 (2.0.29+), V2-native.** The harness ships the V2 plugin API
13
+ > (`@opencode/plugin`; plugins default-export `{ id, setup }` and register tools
14
+ > via `ctx.tool.transform` and behavior via `ctx.tool`/`ctx.session`/`ctx.shell`/
15
+ > `ctx.permission`/`ctx.event` hooks) — V1 plugin implementations do **not** run in
16
+ > V2. Configuration is native V2 (`permissions`, `agents`, `mcp.servers`, no
17
+ > `small_model`), commands live in `.opencode/commands/`, and the always-loaded
18
+ > project instructions are `AGENTS.md` (V2 ignores the `instructions` config key).
19
+
20
+ ## Prerequisites
21
+
22
+ - **OpenCode V2** (`opencode --version` >= 2.0.29). The harness ships V2 plugins
23
+ and does not run on V1.
24
+ - **Node.js >= 20** and **git**.
25
+ - The default model routing targets the `opencode-go` provider. If you use a
26
+ different provider, edit the `model:` lines in `.opencode/agents/*.md` and
27
+ `opencode.json` after `init`; the routing policy is documented in
28
+ `.agents/memory/model-routing.md`.
29
+
30
+ `init` writes into the target directory and does **not** commit or push by
31
+ default. Preview first with `--dry-run`.
32
+
33
+ ## Why
34
+
35
+ - The agent harness is tooling, not application code. Its source lives in the
36
+ npm package — you deploy it with `init`/`update` rather than hand-copying it
37
+ into every repo.
38
+ - One canonical, versioned source of truth for personas/rules/QA tiers, deployed
39
+ on demand and updatable via `npx opencode-agent-harness update`.
40
+
41
+ ## Install & initialize
42
+
43
+ ```bash
44
+ # from anywhere (uses a target dir or defaults to cwd)
45
+ npx opencode-agent-harness init --target /path/to/project --name "MyApp" --domain "a widget catalog"
46
+
47
+ # non-interactive
48
+ npx opencode-agent-harness init --target . --yes
49
+
50
+ # preview what would change, without writing anything
51
+ npx opencode-agent-harness init --target . --dry-run
52
+ ```
53
+
54
+ `init` writes:
55
+
56
+ | Path | Content | Ownership |
57
+ |---|---|---|
58
+ | `AGENTS.md` | always-loaded project instructions (OpenCode V2 reads `AGENTS.md`; the V1 `instructions` key is ignored) | harness (overwrite) |
59
+ | `BACKLOG.md` | canonical task list (Open / In progress / Frozen / Archive / Not tracking) | **project** (create-if-missing) |
60
+ | `.opencode/agents/*.md` | 15 persona subagent defs (native V2 frontmatter: `model: provider/model#variant`, `permissions`, `steps`, `hidden`) | harness (overwrite) |
61
+ | `.agents/AGENTS.md` | full canonical operating rulebook (V2 auto-discovers it as you work under `.agents/`) | harness (overwrite) |
62
+ | `.agents/rules/00-operating.md` | expanded operating rules (referenced from `AGENTS.md`; V2 ignores the `instructions` config key) | harness (overwrite) |
63
+ | `.agents/skills/*/SKILL.md` | persona instruction skills (V2 also discovers `.agents/skills/` as skills) | harness (overwrite) |
64
+ | `.agents/features/INDEX.md` | pointer to `BACKLOG.md` (per-feature doc tree root) | **project** (create-if-missing) |
65
+ | `opencode.json` | main model + `agents` defaults (small-model on `title`, opportunistic `explore`) + the `permissions` baseline | harness (**merged**, see below) |
66
+ | `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` / `test:prefix` gates + QA-script wiring check | harness (overwrite) |
67
+ | `scripts/backlog.js` | deterministic `BACKLOG.md` editor (list/add/take/archive/freeze) | harness (overwrite) |
68
+ | `.opencode/plugins/backlog.ts` | `backlog_*` custom tools the LLM calls (V2 plugin registering the tools; shells out to the CLI) | harness (overwrite) |
69
+ | `.opencode/plugins/backlog-notify.ts` | structured log whenever an agent mutates the board | harness (overwrite) |
70
+ | `.opencode/plugins/context-guard.ts` | mid-session checkpoint/loop nudges read from `orchestration.md` (core: `scripts/qa/context-guard-core.js`) | harness (overwrite) |
71
+ | `.opencode/plugins/session.ts` | `session_info` tool — reports the primary orchestrator session id (the handoff `session:` join key) + observed cost/tokens/turns | harness (overwrite) |
72
+ | `.opencode/plugins/checkpoint.ts` | `checkpoint_write` / `checkpoint_resume` tools (shell out to `scripts/checkpoint.js`) | harness (overwrite) |
73
+ | `.opencode/commands/checkpoint.md`, `.opencode/commands/resume.md` | mid-session checkpoint + bounded resume-from-checkpoint commands | harness (overwrite) |
74
+ | `scripts/checkpoint.js` | deterministic checkpoint write/replace/read for one session handoff (no timestamps, `unknown` for absent state) | harness (overwrite) |
75
+ | `scripts/ship.js` | deterministic branch lander (`npm run ship`): rebase on `origin/main`, branch gates, direct fast-forward push of `HEAD:main`, then wait for green CI on the landed SHA | harness (overwrite) |
76
+ | `scripts/qa/check-prefix-stability.js` | `test:prefix` gate — fails a volatile value (clock timestamp, machine path, session id) in the always-loaded prompt prefix | harness (overwrite) |
77
+ | `.github/workflows/{ci,deploy-uat,uat-health}.yml` | CI gate, CI-triggered artifact deploy, health probe — the self-contained release cycle `ship` drives | **project** (create-if-missing) |
78
+ | `.husky/pre-push` | pre-push battery (harness process gates + project test gates) | **project** (create-if-missing) |
79
+ | `.vercelignore` | keeps worktree symlinks (`node_modules`, `prisma/generated`) out of the remote build | **project** (create-if-missing) |
80
+ | `docs/ci-cd-pipeline.md` | the pipeline reference (setup, secrets/variables, rollback) | **project** (create-if-missing) |
81
+ | `scripts/agent-report.js` | deterministic dispatch report (`--cost` joins observed provider telemetry; `--json` schema `agent-report/1`) | harness (overwrite) |
82
+ | `scripts/qa/provider-stats.js` | observed cost/token/turn telemetry from the local opencode store (no sqlite dependency) | harness (overwrite) |
83
+ | `scripts/qa/session-recon.js` | tool-habit / context-hygiene recon (shell tool-choice, `cd`-chaining, whole-file + repeated reads, guessed paths, dumps, polling, dispatch sizes; `report:recon`) | harness (overwrite) |
84
+ | `.agents/memory/*` | project data (domain-map, stack-versions, locations, model-routing, orchestration, history, flow-map, product-principles, quality-parameters, test-design-parameters) | **project** (create-if-missing) |
85
+ | `.agents/reviews/*` | project data (durable review/audit deliverables — REPORT.md + scans, tagged by quality-parameters) | **project** (create-if-missing) |
86
+ | `.agents/handoffs/*` | project data (one session handoff file per session — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
87
+ | `.agents/qa-plans/*` | project data (one QA plan file per change — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
88
+ | `.harness.json` | deployed version + project profile + per-file checksums | harness |
89
+ | `.gitignore` | **project-owned** — deployment never reads or rewrites it; harness local-only artifact patterns go to the clone-local `.git/info/exclude` | project |
90
+ | `.gitattributes` | harness-managed section (`BACKLOG.md merge=backlog` — the row-aware merge driver) merged in, project entries preserved | harness (merged) |
91
+
92
+ ### `opencode.json` is merged, not clobbered
93
+
94
+ The harness owns only `$schema`, `model`, its `agents` defaults
95
+ (`title`/`build`/`explore` — the V2 small-model pin lives on `agents.title.model`)
96
+ and the `permissions` baseline. Every other key your project adds — extra
97
+ `permissions`, `mcp.servers`, `plugins`, custom `agents`, etc. — is preserved
98
+ across `init`/`update` (the `permissions` array is unioned and `agents` is
99
+ add-only per agent). This is the **native V2 shape**: there is no V1
100
+ `small_model`, singular `agent`, keyed `permission`, or `instructions` key.
101
+
102
+ ## Placeholders
103
+
104
+ Templates use `{{PROJECT_NAME}}` and `{{PROJECT_DOMAIN}}`; `init` substitutes
105
+ them from `--name` / `--domain` (or prompts, or `.harness.json`). Domain facts
106
+ that are genuinely project-specific (entity model, external sources, visibility
107
+ tiers, trust tiers) live in `.agents/memory/domain-map.md`, which `init`
108
+ scaffolds for you to fill in — the skills and rules reference memory instead of
109
+ hardcoding domain assumptions.
110
+
111
+ **Features (`.agents/features/`)** — the durable, feature-centric plan of record. A
112
+ found item is captured as one light row in the canonical `BACKLOG.md` (repo root; the
113
+ single write-path for all open work: what's known, priority, evidence). When a feature
114
+ is picked up, the `features` persona authors the per-feature doc chain
115
+ (`.agents/features/<slug>/`), each layer routed to its author persona — `intent.md`
116
+ (product-manager) → `scope.md` (system-architect, HIGH-risk only) → `plan.md` (planner)
117
+ → `tests.md` (qa-architect, points to the feature's QA plan). Ceremony is right-sized to blast
118
+ radius: trivial → none, low → single `intent.md`, high (auth/DB/public API/flow-siblings)
119
+ → full chain. Docs live beside the code, are written-back before continuing when
120
+ implementation invalidates them, and are archived on ship. `.agents/features/INDEX.md`
121
+ is a pointer to `BACKLOG.md`. See `.agents/skills/features/SKILL.md`.
122
+
123
+ **Product-first planning (`.agents/memory/product-principles.md`)** — the project-owned
124
+ product concepts (actors, product concepts, UX heuristics, design language, key journeys,
125
+ value-maximization rules) that LEAD planning. The `planner` reads it (plus a feature's
126
+ `intent.md`) before emitting a dispatch plan and sequences work value-first — smallest
127
+ slice that delivers the core outcome first — rather than by tech dependency. `intent.md`
128
+ must define Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first
129
+ sequence + Product concepts applied; `npm run test:product` fails a feature that reaches
130
+ planning/implementation without them (a plan with no intent, or an intent that never
131
+ names a user/need/outcome). Fill `product-principles.md` in at `init`; evolve it as the
132
+ product does — see `.agents/skills/planner/SKILL.md` and
133
+ `.agents/skills/features/SKILL.md`.
134
+
135
+ **Flow map (`.agents/memory/flow-map.md`)** — the project-owned registry powering the
136
+ flow-closure half of `test:qa-plan`. Each user-facing flow lists the code surfaces that
137
+ implement the same behavior across codebases/layers (e.g. web component, `mobile/` sheet,
138
+ API route) plus its optional variants (e.g. `condition-selector-present` vs `-absent`). Fill
139
+ it in so a change to one surface is forced to account for all the others. If empty, the gate
140
+ warns but does not block; the guarantee only applies to registered flows.
141
+
142
+ **Environment registry (`.agents/memory/environments.md`)** — the project-owned
143
+ canonical registry of the three environments: **development** (dirty by design —
144
+ QA/test data lives and dies here), **User Acceptance (`uat`)**, and **production**
145
+ (both enforced clean). The rulebook's non-negotiable law: only **code**, **schema
146
+ migrations** (`prisma migrate deploy`), and **idempotent seeds** move forward
147
+ (dev → uat → prod); **data never does** — no dump/restore across environments.
148
+ Live QA tiers target the `development` DB only. Finalizing a task means deploying
149
+ to **uat**: the Definition of Done routes it through `devops-engineer` →
150
+ `deploy:uat`, then verifies the boundary with `test:data-hygiene -- --env uat`.
151
+ Production is human-gated and out of the per-task flow. The harness scaffolds
152
+ `environments.md` (create-if-missing, project-owned) and reminds projects to wire
153
+ `deploy:uat` / `deploy:prod` / `test:data-hygiene` via `check-qa-scripts.js`.
154
+
155
+ **Orchestration & context budget (`.agents/memory/orchestration.md`)** — the
156
+ project-owned tuning file for the cost/context guards the operating rules
157
+ reference: the main-orchestrator soft turn budget / hard safety ceiling, the
158
+ request-context observe → warn → checkpoint → intervene thresholds, dispatch
159
+ fan-out review bands, and the stuck/retry-loop heuristics. Shipped with sensible
160
+ experimental defaults; tune from post-change data and record why. Scaffolded
161
+ create-if-missing (project-owned).
162
+
163
+ **Bounded orchestration & structured session telemetry** — the harness keeps the
164
+ main context from growing unbounded: one bounded orchestration lifecycle per work
165
+ unit, compact deterministic checkpoints into the session's `.agents/handoffs/<id>.md`
166
+ when a session nears its budget (see `orchestration.md`), and a fresh context that
167
+ resumes from the checkpoint instead of replaying the transcript. The
168
+ **`context-guard` plugin** makes the budgets mechanical: it parses
169
+ `orchestration.md` at runtime (thresholds are never hardcoded) and nudges the
170
+ primary orchestrator session as it crosses them — turn bands AND request-token
171
+ levels (whichever is stronger), flags repeated identical tool calls, whole turns
172
+ with no material state change, and repeated failures sharing a signature, and
173
+ records band/request/loop/no-state/failure crossings in
174
+ `.agents/guard-events.jsonl` (local-only, excluded clone-locally). It also
175
+ **blocks two tool calls outright**: a `git checkout`/`git switch` that would move
176
+ HEAD under another live session in the same checkout, and any code change aimed
177
+ at the shared `main` checkout before the session isolates into its feature
178
+ worktree (`backlog worktree <id>`) — board/`.agents`/docs maintenance on `main`
179
+ stays allowed. A git op is judged by the paths it actually moves (explicit
180
+ pathspecs, or the live index/upstream diff for a whole-index `commit`/`push`)
181
+ against the checkout it selects, so `git -C <main>` is resolved rather than
182
+ bypassed. At the
183
+ checkpoint band the nudge is imperative: write ONE checkpoint, then stop at the
184
+ current **phase boundary** — a fresh bounded context resumes from it. The nudge is
185
+ injected **cache-safely**: it is appended as a synthetic tail message via the V2
186
+ `context` session hook (`ctx.session.hook("context")`), never written into the
187
+ system prompt — a
188
+ system-prompt change on a band crossing evicts the provider's entire prompt cache
189
+ and re-bills the whole transcript at full input price (measured: every full-price
190
+ re-read landed on turn 50/60/80/100). Appending at the tail keeps the cached
191
+ prefix byte-stable. Every handoff can
192
+ carry a `## Session metadata` block (`session`, `work_type`, `outcome`,
193
+ `termination_reason`, `checkpoint_count`, `model_escalation_evidence` —
194
+ controlled vocabularies, never fabricated) that `npm run report` aggregates
195
+ deterministically per feature.
196
+ `npm run report -- --cost --since=14d` (also `npm run report:cost`) closes the
197
+ telemetry loop: the `session_info` tool returns the primary session id, and
198
+ `agent-report` joins it to observed provider data
199
+ (`scripts/qa/provider-stats.js` reads the local opencode store, including
200
+ registered git worktrees) — totals, model mix by tier, cache-read share, P50/P90
201
+ cost and turns, >60-turn sessions, identical-call loop candidates, mid-cycle
202
+ context resets (resume/checkpoint sessions), and **cost per shipped feature**
203
+ (primary session + its subagent sessions = one feature run).
204
+ A primary session observed on an `escalation_models:` model is flagged when no
205
+ `model_escalation_evidence` / `## Escalations` reason is recorded — escalation is
206
+ visible, never assumed. Nothing is inferred from text length.
207
+
208
+ **End-to-end auto-resume (`agent-harness run`)** — chains bounded orchestration
209
+ contexts so a full delivery cycle (pick → plan → implement → QA → gates → ship →
210
+ land → UAT deploy) completes without a manual resume per phase. It runs the
211
+ next-item workflow, and whenever a phase ends with the feature not landed, it
212
+ launches a fresh opencode session that resumes from the checkpoint only. It stops
213
+ on landed (archived row or shipped outcome), the phase cap, an empty queue, or a
214
+ failed phase that did not land. The decision core
215
+ (`scripts/qa/run-loop.js`) is pure and unit-tested; `--dry-run` prints the phase
216
+ plan.
217
+
218
+ ## Model routing & enforcement
219
+
220
+ - Concrete models are set in `.opencode/agents/<name>.md` (`model:
221
+ provider/model#variant`) and `opencode.json` (`model`, plus `agents.title.model`
222
+ for the small-model pin).
223
+ - Personas also carry mechanical guardrails in native V2 `permissions` frontmatter:
224
+ - thinkers (`planner`, `product-manager`) → `edit` deny-by-default with a narrow
225
+ artifact write grant (planner → `.agents/features/<feature>/plan.md`,
226
+ product-manager → `.agents/features/<feature>/intent.md`, each writable in the
227
+ main tree or the feature's `.worktrees` sibling), plus a `shell` deny
228
+ - `qa-architect`, `handoff`, `docs` → a `shell` deny
229
+ - code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
230
+ `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
231
+ `diagnostics-expert`) → an `edit` allow narrowed by denies for
232
+ `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (governance
233
+ and harness files are read-only), plus a `shell` allow
234
+ - deterministic personas → a `#low` **model variant** (`model: <provider/model>#low`) — V2 treats `request.body.temperature` as a no-op, so the old temperature pin was replaced by the variant
235
+ - all personas → a `steps:` cap (cost ceiling)
236
+ - `planner`, `handoff` → `hidden: true`
237
+ - `.agents/skills/*/SKILL.md` carries a `model:` label only (informational).
238
+ - `npx opencode-agent-harness list` prints the persona → model mapping.
239
+ - `npm run test:dispatch` mechanically verifies model pins against
240
+ `scripts/qa/models.allowlist.txt` and that `model-routing.md` does not name a
241
+ stale model no longer pinned anywhere (doc↔config drift). Concrete IDs on the
242
+ machine-readable `opportunistic_models:` / `escalation_models:` lines are
243
+ legal declared targets, not drift.
244
+ - **Opportunistic tier** (`.agents/memory/model-routing.md`): free/low-cost
245
+ models for best-effort bulk exploration/summarization, pinned through
246
+ `opencode.json` `agents.explore.model` (default `opencode-go/glm-5.3-flash`) and
247
+ ADD-ONLY overridable per project — with a mandatory fallback to the persona's
248
+ normal tier and a no-confidential-data caveat. `report` classifies the model
249
+ mix by tier.
250
+ - **Provider priority & fallback**: models run on the **OpenCode Go
251
+ subscription first** (`opencode-go/*`), with **DeepSeek direct**
252
+ (`deepseek/*`) as the pay-per-token fallback — except the **V4 Pro architect
253
+ tier** (`planner`, `qa-architect`, `system-architect`, `security-engineer`),
254
+ which always pins **direct `deepseek/deepseek-v4-pro`**. Every fallback is
255
+ announced immediately (a fallback the user cannot see is a silent process
256
+ change).
257
+ - **Provider funds stop**: a provider funds/quota error (`insufficient
258
+ balance`/`funds`/`credits`, usage limit, HTTP 402) is a hard stop, never a
259
+ silent inline degrade: the orchestrator announces the failed provider/model and
260
+ the exact unfinished step, checkpoints, and waits for the user's explicit
261
+ top-up-complete message. The `context-guard` plugin mechanically detects such
262
+ an error from **structured failure evidence only** — a failed dispatch
263
+ (`task` error), a non-zero-exit command, or a subagent session error — and
264
+ injects the same stop; reading a document that merely quotes the rule (the
265
+ session-start `model-routing.md`, a handoff, a plan) never trips it.
266
+ - **`/switch-model` command** — every deploy ships an opencode command
267
+ (`.opencode/commands/switch-model.md`) plus per-platform twins
268
+ `scripts/switch-reasoning-model.ps1` (Windows PowerShell) and
269
+ `scripts/switch-reasoning-model.sh` (WSL/Linux/macOS; the command invokes this
270
+ one on POSIX). It rewrites the main `opencode.json` `model` and the six
271
+ reasoning-tier agents (planner, system-architect, security-engineer,
272
+ diagnostics-expert, product-manager, qa-architect) in one step — a blunt
273
+ override of the tiered default. Aliases: `go`/`go-flash`/`go-deepseek` →
274
+ `opencode-go/deepseek-v4.1-flash` (default, OpenCode Go), `go-pro` →
275
+ `opencode-go/deepseek-v4-pro` (Go escalation),
276
+ `deepseek`/`flash`/`direct` → `deepseek/deepseek-flash` (direct fallback),
277
+ `deepseek-v4-flash` → `deepseek/deepseek-v4-flash` (legacy V4 pin),
278
+ `pro`/`deepseek-pro`/`deepseek-v4-pro` → `deepseek/deepseek-v4-pro`
279
+ (direct escalation), `nvidia`/`kimi`/`kimi-k3` →
280
+ `nvidia/moonshotai/kimi-k3` (NVIDIA NIM), `nemotron`/`nemotron-ultra` →
281
+ `nvidia/nemotron-3-ultra-550b-a55b:free` (NVIDIA NIM, free),
282
+ `openrouter`/`or`/`minimax-m3`/`m3` → `openrouter/minimax/minimax-m3`
283
+ (OpenRouter), or any explicit `provider/model`. Restart opencode after
284
+ switching (config reads once).
285
+ - **`/board` command** — every deploy ships an opencode command
286
+ (`.opencode/commands/board.md`) that runs the deterministic `scripts/backlog.js
287
+ list` and shows the active rows verbatim — no LLM filtering, no re-ordering, no
288
+ transformation. Read-only, no git — the local file is the source of truth.
289
+
290
+ ### Backlog management — fast, deterministic, no LLM in the loop
291
+
292
+ `BACKLOG.md` is the single source of truth; it is managed by a **deterministic
293
+ Node CLI** (no model round-trip) that both humans and agents share:
294
+
295
+ ```bash
296
+ npm run backlog -- list # In progress + Open, evidence on its own line (add --all for Frozen/Archive, --full to skip truncation)
297
+ npm run backlog -- add "NLI search times out" --p P2 --evidence docs/issues.md
298
+ npm run backlog -- take F-001 --handoff .agents/handoffs/F-001.md
299
+ npm run backlog -- archive F-001 --closed "shipped 2026-09-04"
300
+ npm run backlog -- freeze F-002 --why "not now" --reopen "customer asks"
301
+ ```
302
+
303
+ `list` renders each row on two lines (task on top, evidence/handoff/reopen on a
304
+ labeled line below) and truncates long cells by default for scannability — pass
305
+ `--full` for the untruncated text. The `backlog_list` tool always uses `--full`
306
+ so agents see complete descriptions.
307
+
308
+ - The CLI validates the schema (`P1..P4`, non-empty evidence/handoff/reopen, `Depends on`
309
+ references naming real rows), generates unique IDs, and sorts `Open` by priority — every
310
+ write stays `npm run test:backlog`-green.
311
+ - **Dependencies are machine-readable**: a row's `Depends on` cell (`backlog depends <id>
312
+ --on F-039,F-041` / `backlog add ... --depends-on ...`) lists IDs that must be archived
313
+ first. `/next`, `take`, and `worktree` skip or refuse a row whose dependencies aren't
314
+ archived — no more "until F-041" living in prose.
315
+ - **Isolation is a worktree per feature**: `backlog worktree <id>` (from the MAIN tree)
316
+ creates a `git worktree` + branch and auto-takes the row. The branch is based on the
317
+ current upstream (`origin/main`), never a stale local HEAD, and `--no-track` keeps it
318
+ from silently tracking main. Every feature works in its own checkout — `main` stays
319
+ board + shippable code only — so one session's uncommitted work can't leak into another's
320
+ pre-push gate. Worktrees land in a single hidden container sibling,
321
+ `<repo>/../.worktrees/<repo>/<id>`, so the parent folder (e.g. `C:\develop`) only ever
322
+ holds top-level projects. Pass `--open` to launch the agent CLI *in the new worktree*
323
+ after the board is written, so the session is root-scoped there and its lease + gates
324
+ never land in `main`. If the worktree is instead created **mid-session** (no `--open`),
325
+ the tools forward their session id and the CLI records the target at
326
+ `.serve/sessions/<id>.worktree`; `backlog_*`, `checkpoint_*`, and `session_info` then
327
+ follow the session into the worktree, and `archive` clears the pointer. `backlog archive
328
+ <id>` removes the shipped feature's worktree + merged branch, so a session cleans up
329
+ after itself on close.
330
+ - **Single-authority board (main-checkout freshness)**: because a feature's commits reach
331
+ `origin/main` from its own worktree, the MAIN checkout's board can lag origin until it is
332
+ pulled. Every mutating command in the MAIN checkout is therefore a transaction
333
+ (`scripts/qa/board-sync.js`): fetch → row-aware reconcile against `origin/main` (an
334
+ archived-upstream row wins over a stale local take; local-only rows survive) → apply →
335
+ commit → fast-forward push. Main never carries an uncommitted board copy, so a mutation
336
+ can never resurrect a shipped row; a genuine non-board local edit fails closed with an
337
+ actionable message, while a redundant one (already identical to upstream) is cleared
338
+ losslessly. `ship`'s post-landing convergence runs the same logic under the board lock
339
+ (so it can't race a concurrent `backlog` command) and runs even when CI is red.
340
+ `backlog sync` publishes offline edits later; `agent-harness doctor` warns when the
341
+ checkout is behind. `agent-harness update` likewise fast-forwards a stale target before
342
+ it auto-commits and refuses to commit onto a diverged branch (`--no-fetch` skips the
343
+ network step for `backlog`).
344
+ - **Row-aware merge driver**: `.gitattributes` routes `BACKLOG.md` through
345
+ `scripts/qa/merge-backlog.js` (wired by `init`/`update`), so two sessions editing
346
+ *disjoint* rows merge by ID instead of conflicting — concurrent take/archive no longer
347
+ produces a `BACKLOG.md` merge conflict.
348
+ - **Owned files**: `backlog owns <id> --files "scripts/test-*.ts, scripts/qa/routes.js"`
349
+ records the files a row owns in `.agents/memory/owned-files.md`, sharpening
350
+ `test:concurrency` to fail *exactly* when two In-progress rows own the same file.
351
+ - **Agents use the same path** via opencode custom tools (`backlog_add`,
352
+ `backlog_take`, `backlog_archive`, `backlog_freeze`, `backlog_depends`, `backlog_owns`,
353
+ `backlog_worktree`, `backlog_list`) that shell
354
+ out to the CLI — never hand-edit `BACKLOG.md`.
355
+ - A **notify plugin** (`.opencode/plugins/backlog-notify.ts`) writes a structured
356
+ log the moment an agent mutates the board. V2 server plugins have no TUI, so
357
+ this is a console log (visible in the opencode log), not the V1 toast — but it
358
+ still surfaces "an agent finished an item" without a manual refresh.
359
+
360
+ ### Permission model & limits
361
+
362
+ - **Ordering is last-match-wins, so a project rule can shadow a harness deny.**
363
+ V2 applies `permissions` in order (global → project → agent) and the *last*
364
+ matching rule wins. `init`/`update` append a project's own rules **after** the
365
+ harness rules, so a project-level `allow` can override a harness `deny` (for
366
+ example the credential denies). The deployed baseline is ordered safely
367
+ (denies after the work-root allow), but a hand-added project rule is stronger
368
+ than the baseline — audit project `permissions` whenever a deny must be
369
+ absolute, and treat the project layer as a deliberate escape hatch.
370
+ - **`permissions` gate tool *selection*, not the host.** They are advisory to
371
+ the model; a `shell` call runs with the host user's full authority regardless
372
+ of the rules (V2's own docs say so). The harness compensates with mechanical
373
+ guards — the capacity envelope, the main-checkout / branch-switch guard,
374
+ per-feature worktrees, session leases — not a kernel sandbox. Keep secrets off
375
+ the box, and prefer a container or a dedicated user for untrusted work.
376
+
377
+ ## QA gates
378
+
379
+ - `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity + model-routing↔pin drift check.
380
+ - `npm run test:governance` — session wrap-up dispatch-log enforcement.
381
+ - `npm run test:backlog` — canonical single-backlog gate: `BACKLOG.md` is the one
382
+ source of truth; status/priority enums, frozen-reopen conditions, non-empty
383
+ priority/evidence (and non-empty task/handoff on `In progress` rows), no
384
+ duplicate IDs, `Depends on` cells that name real rows, and `INDEX.md`/`todo.md`
385
+ must be pointers (not live lists). Reports an over-wide row honestly ("row F-127
386
+ has 7 cells, expected 6 — unescaped `|`") instead of surfacing a shifted cell as
387
+ a bogus "depends on unknown row".
388
+ - `npm run test:concurrency` — cross-session working-tree guard. Fails when the
389
+ board shows 2+ `In progress` rows while the tree has uncommitted changes; with
390
+ owned files declared (`.agents/memory/owned-files.md`), it fails *exactly* when
391
+ a dirty file is owned by two In-progress rows (or a tree mixes two sessions'
392
+ WIP). The shared `BACKLOG.md` itself is treated as owned by every In-progress
393
+ row, so a dirty board under 2+ active sessions is a hard failure. It also
394
+ refuses two live *primary sessions* on one checkout via `.serve/sessions/`
395
+ leases written by the context-guard plugin — liveness requires the pid **and** a
396
+ matching process birth token (`bootId` + `/proc` starttime) **and** a fresh
397
+ heartbeat, so a recycled pid or a closed TUI can't masquerade as a live session.
398
+ `node scripts/qa/check-concurrency.js --prune` clears dead/recycled/stale leases
399
+ (the plugin also sweeps at startup).
400
+ - `npm run test:integrate` — pre-push rebase check: fails when the current branch
401
+ is behind `origin/main`, reminding you to `git rebase` and re-run the board +
402
+ concurrency gates before pushing, so conflicts surface early.
403
+ - `npm run test:quality` — **mechanical code-quality gate on new/grown code**:
404
+ flags dead exports (a symbol whose only reference is its own declaration) and
405
+ files that are new or grew past the line limit (default 1000). Runs against the
406
+ diff by default (`--paths a,b` to target files, `--base <ref>` to set the
407
+ baseline, `--strict` for CI). Canonical rubric: `.agents/memory/quality-parameters.md`.
408
+ - `npm run test:wiring` — **orphan-test gate**: every `*.test.*` / `*.spec.*`
409
+ file must be executed by some package script (directly, as a directory prefix,
410
+ or via a glob). An authored test wired into no tier is neither protection nor a
411
+ failure signal — test-design parameter T7. Default-discovery runners (`vitest
412
+ run`, bare `node --test`, …) downgrade unwired files to warnings unless
413
+ `--strict`; a deliberate orphan carries an auditable
414
+ `// test-wiring-waived: reason` comment. Tags: `.agents/memory/test-design-parameters.md`.
415
+ - `npm run test:linger` — **exit-contract gate**: runs `test:quick` by default
416
+ (or an explicit command after `--`), measures real process wall-clock, parses
417
+ the runner's self-reported duration (`node:test` `duration_ms`, jest `Time:`,
418
+ vitest `Duration`), and fails when the process lingers after the tests are done
419
+ (T1/T6/T9) — the measured bug where 22 tests finished in 76 ms but the process
420
+ exited 60.4 s later. Tune with `--max-linger <sec>` / `--ratio <x>`.
421
+ - `npm run test:prefix` — **cache-prefix stability gate**: the always-loaded
422
+ prefix (root `AGENTS.md`, the rulebook, `00-operating.md`, and the session-start
423
+ memory reads) must carry no per-run content — clock timestamps, machine-specific
424
+ absolute paths, or session ids — because one changing byte breaks prompt-cache
425
+ locality for every later turn. Bare historical dates are fine; `BACKLOG.md`,
426
+ handoffs, and feature docs are out of scope.
427
+ - `npm run checkpoint -- write --feature <id> ...` / `resume --feature <id>` —
428
+ deterministic bounded-state checkpoint in `.agents/handoffs/<id>.md`
429
+ (agents: the `checkpoint_write` / `checkpoint_resume` tools, or `/checkpoint` /
430
+ `/resume`). Rewriting identical state is a no-op; changed state increments
431
+ `checkpoint_count`; no timestamps, `unknown` for anything not recorded.
432
+ - `npm run test:product` — **product/UX-first gate**: every feature doc in
433
+ `.agents/features/<slug>/` must define its user before planning/implementation.
434
+ `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md`
435
+ a Value-first sequence + Product concepts applied; a `plan.md` with no `intent.md`
436
+ fails (never plan around an undefined user need). Backward-compatible — no feature
437
+ docs, gate passes.
438
+ - `npm run test:docs` — **docs-as-code gate**: `README.md` / `docs/**` must have no
439
+ un-substituted `{{PLACEHOLDER}}` template vars, no dangling relative links, and every
440
+ ADR (`docs/adr/*.md`) must carry Context → Decision → Consequences + a Status.
441
+ Backward-compatible — no docs, gate passes.
442
+ - `npm run test:qa-plan` — **diff-coverage + flow-closure gate**:
443
+ every changed CODE path must have a covering assertion (or a waivered reason) in
444
+ a QA plan (one per-change file under `.agents/qa-plans/`) before a change is verified — and every touched flow
445
+ (`.agents/memory/flow-map.md`) must have every sibling surface and declared optional
446
+ variant addressed in the plan's `## Parallel-surface & variant audit`. Kills the
447
+ "verified by a suite that never touched the change" failure mode: a tier label never
448
+ proves coverage. It also makes **"Fix One, Fix All" mechanical**: a change to one
449
+ surface (e.g. web) cannot ship while the same flow in another codebase (e.g. `mobile/`)
450
+ silently keeps old behavior — the plan must name each sibling as covered (`->`) or
451
+ out-of-scope (`audited: reason`, e.g. `deferred — logged in handoffs/`).
452
+ - `node scripts/qa/check-qa-scripts.js` — warns (or `--strict` fails) when the
453
+ DoD-referenced runtime QA tiers aren't wired into `package.json`.
454
+
455
+ The harness ships only these gates. The runtime QA tiers (`test:quick`,
456
+ `test:routes`, `test:api`, `test:verify`, `test:security`) and their backing
457
+ scripts are **project-provided** — the rulebook references them, and
458
+ `check-qa-scripts.js` reminds you if they're missing.
459
+
460
+ ## Update
461
+
462
+ ```bash
463
+ npx opencode-agent-harness update --target /path/to/project
464
+ ```
465
+
466
+ - Overwrites harness-owned files, preserves `.agents/memory/*`, `.agents/reviews/*`, `.agents/handoffs/*`, `.agents/qa-plans/*`, and `BACKLOG.md`.
467
+ - **Fails closed on a locally-modified harness-owned file**: if a harness-owned
468
+ file's bytes no longer match the checksum in `.harness.json` (someone hand-edited
469
+ it in the project), `update` aborts *before writing anything* and names the file.
470
+ Port the change into the harness `templates/` (with a drift-guard test for a
471
+ gate/QA script), release, and re-run — or pass `--accept-harness` to overwrite
472
+ deliberately. This prevents the F-289 class of incident, where a project-side
473
+ fix to `scripts/qa/board-sync.js` was silently clobbered by a routine deploy.
474
+ - Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
475
+ `test:qa-plan`, `test:backlog`, `test:product`, `test:docs`, `test:quality`,
476
+ `test:wiring`, `test:linger`, `test:prefix`) plus the `report`,
477
+ `report:cost`, `checkpoint`, and `serve` helpers into the target's `package.json`
478
+ (merged, add-only).
479
+ - **Auto-commits** the harness files it changed (`chore(harness): opencode-agent-harness
480
+ <old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
481
+ modified harness files. Your unrelated uncommitted work is never staged. The push
482
+ uses `--no-verify` — a `chore(harness)` maintenance commit must not be stranded by a
483
+ project pre-push gate that legitimately refuses a direct main push.
484
+ - `--no-commit` to skip commit+push, `--no-push` to commit but not push,
485
+ `--accept-harness` to overwrite a locally-modified harness-owned file.
486
+ - `init` does **not** commit or push by default: pass `--commit` to commit the
487
+ files it scaffolds and `--push` to also push. A first run in an existing repo
488
+ is always reviewable before anything enters git. A pre-existing `AGENTS.md`
489
+ the harness did not create is refused (nothing is written); `--accept-harness`
490
+ overwrites it deliberately after backing it up under `.harness-backup/`.
491
+ - Harness-owned paths are **force-added**, so a project that gitignores deployment
492
+ artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the
493
+ harness commit instead of a raw `git add` failure that silently skips it — force-added
494
+ files are called out in the summary.
495
+ - **`[Nothing-to-Update]` confirmation**: if the target is already at this CLI's version and no
496
+ harness-owned file changed, `update` says so explicitly, writes nothing, and makes no commit —
497
+ a no-op is never mistaken for a sync and never churns `.harness.json`.
498
+ - **Downgrade guard**: `update` refuses to run on a target whose deployed harness is NEWER than
499
+ this CLI (e.g. deployed from a local checkout that was never published) and tells you to publish
500
+ that version first.
501
+ - **Published-version check**: if this CLI's version is not the latest `dist-tags.latest` on npm,
502
+ `update` warns you — catches the "bumped the version and updated a project from a local
503
+ checkout, but never published" gap before it silently forks the projects.
504
+ - **Non-destructive**: a locally-modified harness-owned file is backed up to
505
+ `.harness-backup/<timestamp>/` before any overwrite. With `--accept-harness`,
506
+ after the overwrite the target's own `npm run test:quick` is run **before** the
507
+ harness commit; if it is red the clobbered files and `.harness.json` are rolled
508
+ back and the commit is aborted, so a deploy can never land a broken suite.
509
+ - `opencode.json` is merged (project keys preserved).
510
+ - **Local-only excludes — never `.gitignore`**: the harness's local artifacts
511
+ (`.harness-backup/`, `.backlog.lock`, `.serve/`, `.agents/guard-events.jsonl`)
512
+ are recorded in the clone-local `.git/info/exclude` (add-only; pre-existing
513
+ excludes preserved). That file is untracked and never pushed, so the project's
514
+ committed `.gitignore` is **never** read or rewritten. (A pre-0.1.55 managed
515
+ `.gitignore` section truncated project entries after its marker, silently
516
+ un-ignoring `.env`/`data/` — FamilyBudget F-020.) New harness files are tracked
517
+ (committed), not ignored — so they don't need a gitignore change.
518
+ - **Managed `.gitattributes` + merge driver**: the harness merges a marked section
519
+ (`BACKLOG.md merge=backlog`) into the project's `.gitattributes` and registers the
520
+ row-aware driver in the local `.git/config` (`merge.backlog.driver`). The driver script is
521
+ committed; the config pointer is per-clone, so `init`/`update` (re)register it on every
522
+ deploy.
523
+ - `--dry-run` previews the plan without writing.
524
+
525
+ ### Release cycle & `doctor`
526
+
527
+ `init` seeds a working CI/CD release scaffold create-if-missing (never overwritten,
528
+ so your edits survive `update`): the CI gate, the CI-triggered artifact deploy,
529
+ the UAT health probe, `.husky/pre-push` (process gates), `.vercelignore`, and
530
+ `docs/ci-cd-pipeline.md`. The cycle is:
531
+
532
+ ```
533
+ worktree → npm run ship → direct fast-forward push to main → CI → (on CI success) deploy UAT → health probe
534
+ ```
535
+
536
+ `ship` runs the harness process gates itself (not just via the git hook), lands
537
+ `HEAD:main` with a direct fast-forward push (retrying after a concurrent
538
+ landing), and **waits for CI to go green on the landed SHA** — the deploy runs
539
+ only after CI succeeds. Check readiness at any time with the deterministic report:
540
+
541
+ ```bash
542
+ npx opencode-agent-harness doctor --target /path/to/project
543
+ ```
544
+
545
+ It reports git/remote/branch, `gh` + auth, the CI/deploy workflows, the pre-push
546
+ gate, the Vercel link, and the local-only ignores. Missing infrastructure is a
547
+ warning; a missing prerequisite for the cycle the harness promises is a failure.
548
+
549
+ ### Backlog migration (`migrate-backlog`)
550
+
551
+ ```bash
552
+ npx opencode-agent-harness migrate-backlog --target /path/to/project
553
+ ```
554
+
555
+ Consolidates any live `.agents/features/INDEX.md` F-rows and
556
+ `.agents/memory/todo.md` list items into the canonical `BACKLOG.md`, then rewrites
557
+ both as pointers. Idempotent — re-running never duplicates rows (it only merges into
558
+ an empty board) — and never deletes a source before `BACKLOG.md` is written and
559
+ verified. Logs a summary: `N open · M frozen · K archived`.
560
+
561
+ ## Develop
562
+
563
+ ```bash
564
+ npm test # node --test
565
+ npm run lint # syntax-check the CLI + QA scripts
566
+ node bin/agent-harness.js list
567
+ node bin/agent-harness.js init --target /tmp/demo --name Demo --yes
568
+ ```
569
+
570
+ `npm test` runs the hermetic unit suite **and** `tests/plugin-loader.e2e.js` — a
571
+ **real-loader** check that loads the shipped plugins into a fixture location on a
572
+ running OpenCode service and asserts one guard event fires end-to-end (a session
573
+ lease). It **skips** when no service is running (always the case in CI), so
574
+ `npm run test:plugin-loader` is the explicit invocation on a dev box. See
575
+ `docs/opencode-v2-migration.md` §20.
576
+
577
+ ### Running on WSL2
578
+
579
+ - Keep the checkout and target projects on the Linux filesystem
580
+ (`~/develop/...`), never on `/mnt/c` — Node/npm I/O over the Windows drvfs
581
+ mount is far slower. `init`/`update` warn when a target is on `/mnt/<drive>/`.
582
+ - `.gitattributes` pins `*.sh` to LF (and `*.ps1` to CRLF); the same rules are
583
+ merged into every deployed project, so POSIX scripts survive a Windows-side
584
+ checkout. See the `switch-reasoning-model.sh` POSIX twin, platform-dispatched
585
+ by the `/switch-model` command.
586
+ - Worktrees live in a sibling container (`<repo>/../.worktrees/<repo>/<id>`), so
587
+ allow `~/develop/**` in the global `opencode.jsonc` (an `external_directory`
588
+ allow rule in the `permissions` array), or each worktree access prompts.
589
+
590
+ Clear the data-test except keep `templates/` generic; do not commit a target
591
+ project's `.agents/memory/` into this repo.