opencode-agent-harness 0.0.0-stage → 0.3.14

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