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
@@ -0,0 +1,70 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // `where` — a bounded symbol/owner lookup. The 2026-10 LibraryOS recon measured
5
+ // `grep` as the most common shell command (1,081 / 14 days) and 95 failed reads
6
+ // on guessed paths. This returns a bounded `file:line: text` hit list for a term
7
+ // (index-first via `git grep`; tracked files only, never node_modules/build),
8
+ // annotates each hit with the feature row(s) that own the file, and offers an
9
+ // inverse `--owner <glob>` mode. Prefer it over shell `grep` for locating a
10
+ // symbol; use `Grep` for a bounded pattern read.
11
+ //
12
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
13
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
14
+ // paired with the call's sessionID for tool-lib's sessionRoot reroot.
15
+
16
+ export default {
17
+ id: "where-tools",
18
+ async setup(ctx) {
19
+ const directory = ctx.location.directory
20
+ const h = (context: any) => ({
21
+ directory,
22
+ sessionID: context?.sessionID,
23
+ agent: context?.agent,
24
+ })
25
+ await ctx.tool.transform((editor) => {
26
+ editor.add({
27
+ name: "where",
28
+ description:
29
+ "Locate a symbol/term as a bounded `file:line: text` list (index-first, tracked files only), annotated with the backlog row(s) that own each hit file. Modes: default content search; files (match paths); owner (which rows own a glob). Use it instead of shell `grep` for symbol lookup.",
30
+ input: {
31
+ type: "object",
32
+ properties: {
33
+ term: {
34
+ type: "string",
35
+ description: "the symbol/term to locate (omit when using owner)",
36
+ },
37
+ files: {
38
+ type: "boolean",
39
+ description: "match file paths instead of file contents",
40
+ },
41
+ owner: {
42
+ type: "string",
43
+ description: "inverse mode: list the backlog row(s) that own this glob/path",
44
+ },
45
+ limit: {
46
+ type: "number",
47
+ description: "max hits (default 40)",
48
+ },
49
+ },
50
+ required: [],
51
+ additionalProperties: false,
52
+ },
53
+ async execute(input, context) {
54
+ const helper = h(context)
55
+ const argv = ["--root", toolLib.sessionRoot(helper, "")]
56
+ if (input.owner) argv.push("--owner", input.owner)
57
+ if (input.term) argv.push(input.term)
58
+ if (input.files) argv.push("--files")
59
+ if (input.limit) argv.push("--limit", String(input.limit))
60
+ return {
61
+ content: toolLib.runScript(helper, "scripts/qa/where.js", argv, {
62
+ label: "where",
63
+ timeout: 30000,
64
+ }),
65
+ }
66
+ },
67
+ })
68
+ })
69
+ },
70
+ } satisfies Plugin
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: bounded-explore
3
+ description: Use before dispatching the explore subagent for broad codebase search — fixes the bounded input (paths + exact question + result budget) and the output contract (file:line pointers + a short summary, no whole-file dumps).
4
+ ---
5
+
6
+ # Bounded explore dispatch
7
+
8
+ Load this before every `explore` dispatch. An unbounded explore is the most
9
+ expensive dispatch in the harness (the `0.1.120` recon measured ~465K input
10
+ tokens per call). The fix is not to stop exploring — it is to bound the ask and
11
+ the answer.
12
+
13
+ ## Input contract (what the dispatch prompt must carry)
14
+
15
+ 1. **Paths** — the exact directories/files to search (`app/api/**`,
16
+ `mobile/src/screens/**`), never "the codebase". A path list is what keeps the
17
+ subagent out of `node_modules`/build trees and unrelated surfaces.
18
+ 2. **The exact question** — one answerable question ("where is the session token
19
+ refreshed on 401?"), not a topic ("look into auth"). If you cannot phrase it
20
+ as a question with a definite answer, do the read yourself first.
21
+ 3. **Result budget** — state it in the prompt: *"return ≤ N file:line pointers
22
+ plus a ≤ M line summary; no whole-file contents, no transcript replay."*
23
+ Default N=20, M=15 unless the task needs more.
24
+
25
+ ## Output contract (what explore must return)
26
+
27
+ - **`file:line` pointers** to the answer, each with a one-line note on why it
28
+ matters.
29
+ - **A short summary** (≤15 lines) of the mechanism, in the reader's words.
30
+ - **No whole-file dumps, no diffs, no transcript replay.** If a full file is
31
+ genuinely required, return its path and the relevant line range instead.
32
+
33
+ ## When NOT to dispatch explore
34
+
35
+ - A known path (use `Read` with `offset`/`limit`), a single-file lookup
36
+ (`Grep`/`Glob`), or a tracked-symbol search (`git grep -n <symbol>`) is
37
+ orchestrator work — do it inline. Explore is for *broad, multi-file,
38
+ question-shaped* search the main model cannot cheaply do itself.
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: dev-loop
3
+ description: Use when running or choosing a test tier, running a single test, seeding or resetting the dev database, booting the emulator, starting/stopping the dev server, or picking the cheapest scoped gate for a change.
4
+ ---
5
+
6
+ # Dev loop — run, verify, debug
7
+
8
+ The universal run/verify loop for {{PROJECT_NAME}}. Load this before
9
+ hand-deriving how to run, seed, boot, or check something; the *how-to-run-things*
10
+ knowledge is re-derived every session otherwise. The **project-specific**
11
+ commands (tiers, single-test invocation, seed/reset, emulator/Metro, ports) live
12
+ in `.agents/memory/dev-loop.md` — read that file for the concrete commands, then
13
+ run.
14
+
15
+ ## The loop
16
+
17
+ 1. **Orient first, don't guess.** `node scripts/orient.js` (the `orient` tool)
18
+ returns the tree/branch/HEAD/dirty, the active feature + checkpoint, board
19
+ rows, owned files, the live serve jobs + capacity verdict, and a bounded
20
+ digest of the session-start memory files (including `dev-loop.md`). Use it
21
+ instead of re-reading memory files whole. Find a symbol with the `where` tool
22
+ (`where <term>`), not a shell `grep`/`find` — it is tree-aware and bounded.
23
+ 2. **Pick the cheapest gate that actually exercises your change** — coverage,
24
+ not the path label. The `gates` tool (`gates --phase=quick`) runs the scoped
25
+ harness gates and bounds the output for you (never `npm run test:quick | tail`);
26
+ the project test tiers are in
27
+ `.agents/memory/dev-loop.md`. A one-file change gets a single test, not the
28
+ full regression.
29
+ 3. **Run one test, not a suite, while iterating.** Use the project's single-test
30
+ invocation (`... --test-name-pattern`, or a direct file run) until the batch
31
+ is coherent, then run the tier once.
32
+ 4. **Read the failing gate; don't re-run it blind.** Every harness gate's
33
+ purpose and how to satisfy/waive it is in `docs/gates.md`
34
+ (`agent-harness explain <gate>`). Re-running an unchanged gate with no state
35
+ change is a retry loop, not a retry — change something material or report.
36
+ 5. **A live tier needs a server.** Start it detached through `serve.js`
37
+ (`node scripts/serve.js start --cmd "<dev command>" --url <health url>`),
38
+ never backgrounded in your own shell; stop it when the tier passes
39
+ (`node scripts/serve.js stop --name <label>`). Wait with the bounded waiter,
40
+ never `sleep`-and-pray.
41
+ 6. **Clean up after every live-data run** — reset/clean test data every time,
42
+ not on request (project command in `dev-loop.md`; boundaries in
43
+ `.agents/memory/environments.md`).
44
+
45
+ ## serve.js lifecycle
46
+
47
+ - `node scripts/serve.js list` — what is up, per-process age, and the machine
48
+ capacity verdict.
49
+ - `node scripts/serve.js start --cmd "<command>" [--url <health url> | --port <n>] [--name <label>]`
50
+ — detached (returns immediately); checks the capacity envelope + machine-wide
51
+ heavy lock and **refuses** an over-budget heavy start, naming what is already
52
+ up (`--force` overrides).
53
+ - `node scripts/serve.js run --cmd "<heavy one-shot>" [--mem-max 3G]` — a capped
54
+ synchronous heavy build/tier; never run a heavy build inline uncapped.
55
+ - `node scripts/serve.js stop --name <label>` / `stop-all`; `prune [--worktrees]`
56
+ clears dead records.
57
+ - Wait, don't poll: `node scripts/wait-for.js --health <url> | --port <n> | --file <log> --grep <re>`
58
+ (or the `wait` tool) blocks until ready and returns a terminal status on
59
+ timeout.
60
+
61
+ ## Guardrails
62
+
63
+ - Live/QA tiers target the **development** database only
64
+ (`.agents/memory/environments.md`); never uat/prod.
65
+ - One heavy tier at a time, machine-wide — `serve.js` enforces it. Do not bypass
66
+ it by backgrounding a process by hand.
67
+ - If a launch or a live-tier call is interrupted, verify state
68
+ (`serve.js list`, `.serve/<name>.out.log`, the health URL) — never infer it
69
+ from the abort. Never kill a process on a port you didn't start.
70
+ - **Never `pkill -f <pattern>`** from a shell tool: `-f` matches the FULL command
71
+ line of every process, *including the `bash -c` shell running the `pkill`*, so
72
+ the pattern matches its own command and SIGTERMs your shell (the turn dies
73
+ mid-step). Kill by the recorded PID (`kill <pid>`), or write the pattern so it
74
+ cannot match its own line (e.g. `port 4[7]44`). `pkill <name>` (no `-f`) is
75
+ unaffected. The `context-guard` blocks the self-matching form.
76
+ - **A `Grep` that fails on a very long line** ("Ripgrep JSON record exceeded
77
+ 65536 bytes" / "Invalid ripgrep match output" — generated bundles and i18n
78
+ dicts) is the tool hitting one enormous line, not a missing match. Don't retry
79
+ it or fall back to a shell `grep`: `Read` the file with `offset`/`limit`, or
80
+ narrow the pattern/file set.
81
+
82
+ ## Where the concrete commands live
83
+
84
+ `.agents/memory/dev-loop.md` is the project-owned half of this skill (test
85
+ tiers, single-test invocation, seed/reset, emulator/Metro, ports, log paths).
86
+ `orient` digests it at session start. If a command there is wrong or stale, fix
87
+ it in the same session — a stale run command is worse than none.
@@ -0,0 +1,16 @@
1
+ # Vercel build context hygiene (harness-scaffolded; project-owned — edit freely).
2
+ #
3
+ # A git worktree links `prisma/generated` and `node_modules` as symlinks into the
4
+ # main checkout (scripts/worktree-setup.js). The Vercel remote build does not
5
+ # follow those the way a local run does, so they must never be uploaded. Without
6
+ # this, a worktree deploy can fail with
7
+ # ENOTDIR mkdir '/vercel/path0/prisma/generated'
8
+ # and the alias silently stays on the previous deployment.
9
+ node_modules/
10
+ .prisma/
11
+ prisma/generated/
12
+ .agents/
13
+ .harness-backup/
14
+ .serve/
15
+ .next/cache/
16
+ *.log
@@ -0,0 +1,27 @@
1
+ # {{PROJECT_NAME}} — Agent Operating Rules
2
+
3
+ OpenCode V2 loads this file as always-on instructions (V1 `instructions` is ignored). Expanded rules: [`.agents/rules/00-operating.md`](.agents/rules/00-operating.md); rulebook: [`.agents/AGENTS.md`](.agents/AGENTS.md). Read both before non-trivial work.
4
+
5
+ It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
6
+
7
+ - **Dispatch personas** via the `subagent` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
8
+ - **Todo list discipline**: for multi-step work keep opencode's right-hand todo panel current with the `todowrite` tool — create it before the second/third step, exactly ONE item `in_progress`, mark each item `completed` immediately after its own verification step, and close every finished item before you checkpoint/report. A single-step/single-file fix needs no list; a panel that lags the work is worse than none. The context-guard nudges "create / sync / close" mechanically when it falls behind.
9
+ - **Features**: capture a found item as one light row on the canonical board (the shared board service, ADR 0001) — `features` is a registrar only. Update the board with the `backlog_*` tools (or `node scripts/backlog.js`); never hand-edit a board file. The board is **project-scoped**: a write from a feature worktree lands on the shared service or main board, never a worktree copy. When a feature is picked up, author the per-feature doc chain (intent/scope/plan/tests) by dispatching each author persona **directly** (`product-manager` → intent, `system-architect` → scope, `planner` → plan, `qa-architect` → tests) — never via `features`. For an "investigate + plan" request, dispatch `planner` / `product-manager` directly.
10
+ - **Provider funds stop**: a provider funds/quota error (`insufficient balance`/`funds`/`credits`, usage limit, 402) pauses the session — announce the failed provider/model and the exact unfinished step, checkpoint, and wait for the user's explicit top-up-complete message; never retry, degrade inline, or silently skip. Model priority is OpenCode Go (`opencode-go/*`) first, DeepSeek direct (`deepseek/*`) fallback — the V4 Pro architect tier (`planner`/`qa-architect`/`system-architect`/`security-engineer`) pins `opencode-go/deepseek-v4-pro#high`, with direct `deepseek/deepseek-v4-pro` as the announced fallback — announce every fallback immediately.
11
+ - **Product-first planning**: planning is value-led, not tech-led — define the user (actor/need/outcome/acceptance) before code, sequence work value-first against `.agents/memory/product-principles.md`, and let `npm run test:product` enforce it.
12
+ - **Report value-first, at the reader's level**: completion reports open with what value shipped (plain language — what the user now gets, why it matters) + the main "how", before any file/test/commit detail. Write for someone who knows the product, not the code: lead with behavior in plain terms and use a code identifier only when precision needs it (glossed on first use); stay concrete and technical, never abstract.
13
+ - **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs / every shipped commit has a changelog entry.
14
+ - **Finalize with one call**: `npm run finalize -- --feature <id>` archives the row, commits the tail, and runs `ship` — which integrates on `origin/main`, runs the branch gates (and, when no pre-push hook is installed, the harness process gates itself, so a missing hook cannot skip them), lands the branch with a **direct fast-forward push to `main`**, and then waits (bounded) for **CI to go green on the landed SHA**. There is no PR, no landing label, and no merge train; the deploy runs after CI (`.github/workflows/deploy-uat.yml`). A direct `git push origin main` is the sanctioned route; a concurrent landing is resolved by re-fetch + rebase + retry. `ship` exits 0 only when landed + CI green; a red CI is a blocker to record. **`finalize` is one blocking call, so when only the tail remains run it once and let it complete — do NOT checkpoint-and-stop** (the `/finish` command is the short fresh context that writes the CHANGELOG first). `agent-harness doctor --target .` reports whether the cycle is ready.
15
+ - **Every change touching code paths gets a QA plan** (a per-change file under `.agents/qa-plans/`) from `qa-architect` — if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address. The plan also carries the test-design record (`## Test budget`, `## Oracle & owner`, `## Test-design self-check`); `npm run test:wiring` fails orphaned tests and the linger check flags passing-but-idling suites (T1–T10 → `.agents/memory/test-design-parameters.md`).
16
+ - **Three environments**: `development` (dirty by design — QA/test data lives here), `uat`, and `production` (both enforced clean). Only code + schema migrations + idempotent seeds move forward; data never crosses the boundary (`.agents/memory/environments.md`). Finalizing a task means the branch is landed on `main` and **CI deploys the landed SHA** to **uat** (`.github/workflows/deploy-uat.yml`, triggered after CI succeeds), then `test:data-hygiene -- --env uat`; a local `deploy:uat` is the emergency path only; production is human-gated.
17
+ - **At session start**, run `node scripts/orient.js` (the `orient` tool) — one call returning the tree/branch/HEAD/dirty, active feature, checkpoint, board rows, owned files, live serve jobs + capacity, last device-run summary, **and a bounded digest of the session-start memory files** (`locations.md`, `model-routing.md`, `orchestration.md` budgets, `product-principles.md`, `environments.md`, `dev-loop.md` — each digest carries the file's `##` section index and its first table). Use that digest; open a memory file (or `Grep` a section) only when a specific fact is not in it. The board lives in the shared board service (see `node scripts/backlog.js list` / the `backlog_list` tool; ADR 0001). For review work, read `.agents/memory/quality-parameters.md` (the P1–P8 rubric) and write deliverables under `.agents/reviews/<id>/` (never `.agents/features/`).
18
+ - **Run/verify via the `dev-loop` skill**: before running a test tier, a single test, a seed/reset, the emulator, or the dev server, load the `dev-loop` skill (`skill` tool → `dev-loop`) and read `.agents/memory/dev-loop.md` (project-owned concrete commands). It carries the tier map, the single-test invocation, the `serve.js` start/stop/run lifecycle, `gates`/`where`, and "read the failing gate, don't re-run it blind". Bound an `explore` dispatch with the `bounded-explore` skill (paths + one question + file:line budget) — it is the most expensive dispatch otherwise.
19
+ - **Prefer the harness tools over the shell**: `gates --phase=quick` runs a tier with bounded output, `where <term>` finds a symbol, `orient` re-orients — use them instead of `npm run … | tail` or shell `grep`/`find`/`cat`/`ls` (the dedicated `Read`/`Glob`/`Grep` tools are capped and ignore-aware).
20
+ - **MCP is per-agent and dev-only**: every MCP tool schema is billed on every request, and opencode spawns MCP servers outside the `serve.js` capacity envelope. Wire MCP project-side in `opencode.json`, deny the server's tools globally (a `<server>_*` rule in `permissions`) and re-enable only for the persona that needs live external state; point any DB server at the **development** database only; do not enable GitHub MCP. Details: `docs/mcp-integrations.md`.
21
+ - **Bounded orchestration**: one bounded context per work unit — checkpoint into the session's `.agents/handoffs/<feature-id>.md` when approaching the budgets in `.agents/memory/orchestration.md`, and prefer a fresh context that resumes from the checkpoint over unbounded transcript growth.
22
+ - **Ignore-aware search**: never `rg --no-ignore`/`-u` (it walks `node_modules`/build trees and floods time + context). Use `npm run search -- <pattern>` (`scripts/agent-search.sh`, honours the canonical `.ignore`, capped, `--files` for cheap discovery) for content search, and `git grep -n <symbol>` for tracked-symbol searches (tracked files only, reads the index). Details: `docs/wsl-optimizations.md`.
23
+ - **RAM-backed caches**: on WSL2, `npm run ramdisk` (`scripts/setup-tmpfs.sh`) mounts a tmpfs cache root and exports the build/cache env vars for installed toolchains; `install` persists it per boot/shell. It is **volatile** — caches/build artifacts only, never source or git state. Details: `docs/wsl-optimizations.md`.
24
+ - **Machine capacity guardrail**: parallel sessions are fine, parallel **heavy tiers** are not — WSL2 is one VM, and an emulator + agents + `next dev` exhausts RAM and freezes every terminal at once. Launch long-lived processes through `node scripts/serve.js` (it checks the envelope + a machine-wide heavy lock and refuses an over-budget heavy start; heavy tiers are capped **by default** in a transient `user.slice` cgroup at `heavy_mem_max_mb` — `--mem-max`/`--cpu-max` override, `--no-cap` opts out), run a heavy **one-shot** (an APK/Gradle build, a heavy test tier) capped through `node scripts/serve.js run --cmd "<cmd>"` (never inline uncapped), and note that a `--group` shares ONE combined `group_mem_max_mb` budget so emulator + dev server cannot each take the full per-process cap. Stop dev servers when a tier passes and the emulator at session end (`stop-all`; `prune` clears dead records), and check pressure with `npm run test:capacity`. One-time VM tuning: `sudo bash scripts/wsl-tune.sh apply` (sysctls + user.slice ceiling + a soft `init.scope` backstop + `.wslconfig`; then `wsl --shutdown` on Windows). One-time GPU enablement: `bash scripts/wsl-gpu.sh apply` (loads `vgem` + selects Mesa `d3d12` so the device emulator renders on the Windows GPU instead of CPU llvmpipe; no-op off WSL) — `boot-emulator.sh` probes for it and uses `-gpu host` automatically. Envelope: `.agents/memory/orchestration.md`; details: `docs/wsl-optimizations.md`.
25
+ - **Session telemetry**: at wrap-up, record the `session:` line from the `session_info` tool in the handoff's `## Session metadata`, alongside `work_type` / `outcome` / `termination_reason`. `npm run report -- --cost --since=14d` then joins observed provider cost/tokens/turns to the feature.
26
+
27
+ > Deployed and maintained by `opencode-agent-harness` (`npx opencode-agent-harness init` / `update`). Harness-owned files (`scripts/qa/**`, `scripts/*.js`, `.opencode/**`, `.agents/skills/**`, `.agents/rules/**`, `.agents/AGENTS.md`, `AGENTS.md`, opencode config) must be fixed **upstream in the harness `templates/`**, not hand-edited here — `update` fails closed on a hand-edit and points at `templates/`; `--accept-harness` overwrites deliberately after a backup.
@@ -0,0 +1,95 @@
1
+ # BACKLOG — canonical task list
2
+
3
+ Single source of truth for **all** open work: features, bugs, follow-ups, audits,
4
+ roadmaps, ideas. Every other list (`.agents/features/INDEX.md`,
5
+ `.agents/memory/todo.md`, historical docs) points here. One row per task — if it's
6
+ not a row, it doesn't exist.
7
+
8
+ **Status ladder:** `backlog → ready → in-progress → testing → shipped → archived`,
9
+ plus `frozen` (parked — keep a *why* and a *reopen condition*, never delete).
10
+ The board maps status to section: `backlog`/`ready` → **Open**,
11
+ `in-progress`/`testing` → **In progress** (active work), `shipped`/`archived` →
12
+ **Archive**, `frozen` → **Frozen**. A **Queued** row is a ready-to-pull lane:
13
+ `backlog queue <id>` allocates an `Open` row into it, and `/next` (or
14
+ `backlog next --take`) pulls the top-priority Queued row into `In progress`.
15
+ **Priority (`P`):** `P1` blocking · `P2` important · `P3` nice-to-have · `P4` later.
16
+ Priority applies to open/queued rows only. **Evidence** = a pointer
17
+ (file/log/ticket/words), never a re-derivation. **Epic** = a declared `## Epics`
18
+ key (or `?` when unassigned). **Depends on** = comma-separated row IDs that must
19
+ be archived before this row is picked up (`?` when none); `/next`/`take`/`worktree`
20
+ skip or refuse a row whose dependencies aren't archived. Leave `?` where unknown —
21
+ don't invent.
22
+
23
+ > Updated in the same session the work happens. Pick up a row by moving it
24
+ > `Open`/`Queued` → `In progress`; archive `shipped` rows; freeze don't-delete.
25
+ > Historical design docs are aspirational — verify against live code.
26
+
27
+ ## Epics
28
+
29
+ Group work into logical containers. Declare an epic here (`Key` / `Label` / `Goal`),
30
+ then set a row's `Epic` cell to the key — or leave `?` when unassigned. Editable
31
+ in-file; no code change needed.
32
+
33
+ | Key | Label | Goal |
34
+ |-----|-------|------|
35
+ | | | |
36
+
37
+ ## Active / next
38
+
39
+ - _the next few picks (optional): cite each as `ID (P)`._
40
+
41
+ ## In progress
42
+
43
+ Active work — rows a session has picked up and is working on right now. Move a row
44
+ here from `Open`/`Queued` the moment a session starts dealing with it (cite the
45
+ session's handoff), and move it to `Archive (shipped · done)` when it ships — or
46
+ back to `Open` if it stalls.
47
+
48
+ | ID | Epic | Task | Handoff |
49
+ |----|------|------|---------|
50
+ | | | | |
51
+
52
+ _Rows: `| F-004 | epic-key | short desc | .agents/handoffs/F-004.md (or \`?\`) |`_
53
+
54
+ ## Queued
55
+
56
+ Sorted by priority (P1 → P4). Ready-to-pull work allocated to a worker.
57
+
58
+ | ID | P | Epic | Task | Evidence | Depends on |
59
+ |----|---|------|------|----------|------------|
60
+ | | | | | | |
61
+
62
+ _Rows: `| F-005 | P2 | epic-key | short desc | pointer, never a re-derivation | F-004 |`_
63
+
64
+ ## Open
65
+
66
+ Sorted by priority (P1 → P4).
67
+
68
+ | ID | P | Epic | Task | Evidence | Depends on |
69
+ |----|---|------|------|----------|------------|
70
+ | | | | | | |
71
+
72
+ _Rows: `| F-001 | P3 | epic-key | short desc; open questions with \`?\` | pointer | ? |`_
73
+
74
+ ## Frozen
75
+
76
+ Parked, not deleted. Reopen only when the stated condition recurs.
77
+
78
+ | ID | Epic | Task | Why frozen / reopen when |
79
+ |----|------|------|--------------------------|
80
+ | | | | |
81
+
82
+ _Rows: `| F-002 | epic-key | short desc | why + reopen condition (required) |`_
83
+
84
+ ## Archive (shipped · done)
85
+
86
+ | ID | Epic | Task | Closed |
87
+ |----|------|------|--------|
88
+ | | | | |
89
+
90
+ _Rows: `| F-003 | epic-key | short desc | shipped/done + date/commit |`_
91
+
92
+ ## Not tracking (leave-in-place, no action)
93
+
94
+ _One prose note listing built-and-stable items deliberately left in place (no
95
+ investment, no removal). Omit the section if there is nothing to note._
@@ -0,0 +1,81 @@
1
+ # CI/CD pipeline — {{PROJECT_NAME}}
2
+
3
+ The integration model: **a session lands its gated feature branch directly on
4
+ `main` with a fast-forward push; CI gates the landed SHA; the deploy runs only
5
+ after CI is green.** There is no pull request, no landing label, and no merge
6
+ train — the cycle is deliberately synchronous and simple. A session waits for CI
7
+ on the SHA it just landed and is done; the deploy follows automatically.
8
+
9
+ ```
10
+ agent worktree (branch)
11
+ │ commit
12
+ │ npm run ship (rebase on origin/main, branch gates, git push HEAD:main, wait for CI)
13
+ ▼
14
+ CI (.github/workflows/ci.yml) gates the landed SHA
15
+ ▼
16
+ deploy (.github/workflows/deploy-uat.yml) after CI success: immutable SHA -> prebuilt artifact -> UAT + hygiene
17
+ ▼
18
+ UAT health (.github/workflows/uat-health.yml) scheduled probe
19
+ ```
20
+
21
+ A concurrent landing (two sessions pushing around the same time) is normal git
22
+ contention: the second `git push HEAD:main` is rejected non-fast-forward, and
23
+ `ship` re-fetches, rebases, and retries automatically. The per-feature worktree
24
+ (`backlog worktree <id>`) is what keeps two sessions from sharing a checkout.
25
+
26
+ ## What each piece owns
27
+
28
+ - **`ci.yml`** — the gate on `main`. Runs on every push to `main` (and on a pull
29
+ request if one is ever opened). Extend the `static` job with the harness process
30
+ gates once the harness is CI-installable; enable the DB-backed `runtime` job
31
+ with repository variable `CI_RUNTIME=true`.
32
+ - **`deploy-uat.yml`** — triggered by the `CI` workflow completing **successfully**
33
+ on `main` (and by manual dispatch of any ref for rollback). Runs
34
+ `npm run deploy:uat` with `DEPLOY_CI=1`: link from
35
+ `VERCEL_ORG_ID`/`VERCEL_PROJECT_ID`, build once (`vercel build`), ship the
36
+ prebuilt artifact, migrate, seed, alias + commit-parity verify, smoke, hygiene.
37
+ **Fail-closed once configured:** set repository variable
38
+ `UAT_DEPLOY_CONFIGURED=true` and the required secrets; from then on a missing
39
+ secret is a red failure, not a silent skip.
40
+ - **`uat-health.yml`** — scheduled probe of `$UAT_ALIAS`; set repository variable
41
+ `UAT_ALIAS`. Every **2 hours** (`0 */2 * * *`) — a sub-minute probe on a tight
42
+ cron is still a *billed* job every run (`*/30` ≈ 1,440 jobs/mo), and
43
+ `npm run test:ci-policy` fails a workflow that reintroduces a sub-hourly cron.
44
+ - **`nightly.yml`** — scheduled off-hours E2E (unit/API/routes/browser), **Mon/Wed/Fri**
45
+ (`0 3 * * 1,3,5`), not daily: the push `CI` workflow already runs the same lint +
46
+ quick tier on every landing. The
47
+ heavy device/Maestro tier runs locally via `agent-harness install-nightly`
48
+ (see `docs/nightly-testing.md`); nightly is also where the board is reconciled
49
+ (`reopen` a fix that is still failing, validate one that now passes).
50
+
51
+ **Cost control.** `CI` sets `cancel-in-progress: true` so a superseded run on the
52
+ same ref does not stack billed minutes. Before a cost-visible change (a new
53
+ schedule, an expensive runner), run `npm run ci-triage -- --preflight
54
+ .github/workflows/<file>.yml` for the dispatch estimate, and `agent-harness
55
+ doctor` for the 30-day floor (`ciBudget` in `.harness.json`, when present). The
56
+ gate `npm run test:ci-policy` blocks the workflow shapes behind the 2026-10
57
+ billing outage; the model is `scripts/qa/ci-usage-lib.js`.
58
+
59
+ ## One-time setup (human-gated)
60
+
61
+ 1. Keep the Vercel Git integration **disconnected** — CLI/CI is the single deploy
62
+ path. Create a token and read `orgId`/`projectId` from `.vercel/project.json`.
63
+ 2. Repository secrets: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`,
64
+ `DATABASE_URL_UAT` (optional `DATABASE_URL_UAT_DIRECT`).
65
+ 3. Repository variables: `UAT_DEPLOY_CONFIGURED=true`, `UAT_ALIAS`,
66
+ `CI_RUNTIME=true` (when the runtime job is validated).
67
+ 4. Branch protection on `main` (where the plan supports it): allow direct pushes
68
+ (or exempt the landing account), and require the CI check. The harness lands by
69
+ pushing `HEAD:main`, so a rule that forbids direct pushes will reject it.
70
+ 5. Fill in `.agents/memory/environments.md` with the real dev/uat/prod registry.
71
+
72
+ ## Rollback
73
+
74
+ Re-deploy a known-good SHA through the same workflow:
75
+
76
+ ```bash
77
+ gh workflow run deploy-uat.yml --ref main -f ref=<previous-good-sha>
78
+ ```
79
+
80
+ The local `npm run deploy:uat` (with `DEPLOY_CI` unset, from the linked main
81
+ checkout) is the emergency path only.
@@ -0,0 +1,128 @@
1
+ # Gate reference (`npm run <gate>`)
2
+
3
+ Every harness-shipped gate in one place: what it enforces, how to satisfy it, and
4
+ how to waive it. The gates are wired into `package.json` by `init`/`update`
5
+ (`HARNESS_SCRIPTS`) and run in the pre-push hook, in `ship`, and in CI. Read this
6
+ instead of reverse-engineering the check script — the 2026-09 LibraryOS recon
7
+ found `scripts/backlog.js` read 45× and `check-qa-plan.js` 16× for exactly this.
8
+
9
+ `agent-harness explain <gate>` prints the matching section.
10
+
11
+ **Choosing a gate:** load the `dev-loop` skill (`skill` tool → `dev-loop`) —
12
+ it carries the cheapest-scoped-check rule (`npm run gates -- --phase=quick`),
13
+ the project test-tier map in `.agents/memory/dev-loop.md`, and "read the failing
14
+ gate, don't re-run it blind". `npm run where` / the `where` tool maps a changed
15
+ path to its owning tier.
16
+
17
+ ---
18
+
19
+ ## `test:dispatch` — dispatch-config preflight
20
+ `node scripts/qa/check-dispatch-config.js`
21
+ Every `.opencode/agents/<name>.md` pins a `model:` that is a real, allow-listed
22
+ model (`scripts/qa/models.allowlist.txt`), and every persona referenced by the
23
+ rules exists. **Satisfy:** add a persona → give it a valid `model:`; add a model →
24
+ its provider to the allowlist. **Waive:** none — a broken dispatch target must not
25
+ ship.
26
+
27
+ ## `test:governance` — session-governance gate
28
+ `node scripts/qa/governance.js`
29
+ Each session handoff opens a `## Dispatch log` (`subagent → model →
30
+ shipped/deferred`), and a log with 5+ entries carries a `## Fan-out
31
+ justification`. **Satisfy:** fill the handoff's dispatch log. **Waive:** none.
32
+
33
+ ## `test:qa-plan` — diff-coverage gate
34
+ `node scripts/qa/check-qa-plan.js [--base=origin/main]`
35
+ Every changed code path has a covering assertion or a waiver in the change's
36
+ `.agents/qa-plans/<id>.md`, and every touched flow (`.agents/memory/flow-map.md`)
37
+ has its sibling surfaces + declared variants addressed in the plan's
38
+ `## Parallel-surface & variant audit`. Run scoped: `--base=origin/main` (a bare
39
+ `--base=HEAD` is an empty diff). **Satisfy:** author the plan (qa-architect, or the
40
+ orchestrator in its place). **Waive:** an explicit `audited:`/waiver line per path.
41
+
42
+ ## `test:backlog` — canonical-single-backlog gate
43
+ `node scripts/qa/check-backlog.js`
44
+ The shared board service is the only source of truth (ADR 0001); when the service
45
+ backend is active the gate validates its board, otherwise it validates the legacy
46
+ `BACKLOG.md`. `.agents/features/INDEX.md` and `.agents/memory/todo.md` are
47
+ pointers, never duplicate lists. **Satisfy:** edit the board via `backlog_*` /
48
+ `node scripts/backlog.js`, never a second list.
49
+
50
+ ## `test:product` — product/UX-first gate
51
+ `node scripts/qa/check-product.js`
52
+ Feature work has an `intent.md` (Actor(s) → Need → Outcome → Acceptance) and a
53
+ value-led `plan.md`; a `plan.md` with no `intent.md` fails. **Satisfy:** dispatch
54
+ `product-manager` (intent) → `planner` (plan). **Waive:** non-feature work (no
55
+ feature doc tree) is out of scope.
56
+
57
+ ## `test:docs` — documentation hygiene gate
58
+ `node scripts/qa/check-docs.js`
59
+ No un-substituted `{{PLACEHOLDER}}`, no dangling links, well-formed ADRs, and every
60
+ shipped commit is cited in `CHANGELOG.md` by short hash. **Satisfy:** add the
61
+ CHANGELOG line in the same commit (a docs-only `chore` commit is not enough).
62
+
63
+ ## `test:concurrency` — cross-session working-tree guard
64
+ `node scripts/qa/check-concurrency.js`
65
+ Fails when a dirty tree's files are attributed to two In-progress rows that own
66
+ the same file (the provable collision), or a tree mixes two sessions' WIP. The
67
+ live-session report is advisory. **Satisfy:** `backlog owns <id> --files "glob"`
68
+ per row, isolate with `backlog worktree <id>`. **Waive:** `--prune` clears
69
+ dead/stale leases.
70
+
71
+ ## `test:integrate` — pre-push rebase check
72
+ `node scripts/qa/check-integrate.js`
73
+ Fails when the branch is behind its upstream so conflicts surface before push.
74
+ **Satisfy:** `git fetch origin && git rebase origin/main` (ship does this).
75
+
76
+ ## `test:quality` — mechanical code-quality gate (NEW/CHANGED code)
77
+ `node scripts/qa/check-quality.js [--strict]`
78
+ No dead exports / oversized files introduced in NEW or GROWN code (rubric
79
+ `.agents/memory/quality-parameters.md` P1/P3/P4). **Satisfy:** extract/split on
80
+ growth; leave legacy debt alone.
81
+
82
+ ## `test:wiring` — orphan-test detector
83
+ `node scripts/qa/check-test-wiring.js`
84
+ Every `*.test.*` / `*.spec.*` file is executed by some package script (T7).
85
+ **Satisfy:** wire the test into a tier script.
86
+
87
+ ## `test:linger` — process-vs-tests linger detector
88
+ `node scripts/qa/check-linger.js -- <tier command>`
89
+ Flags a suite whose process lingers far past its runner-reported test time (an
90
+ open handle / teardown bug — T1/T6/T9). **Satisfy:** close pools/sockets/timers.
91
+
92
+ ## `test:capacity` — machine capacity envelope gate
93
+ `node scripts/qa/check-capacity.js`
94
+ Reports free RAM / swap / PSI load / live serves and fails when the envelope
95
+ (`.agents/memory/orchestration.md`) is already exceeded. **Satisfy:** stop idle
96
+ serves (`serve.js stop-all`, `prune`).
97
+
98
+ ## `test:ci-policy` — Actions cost-policy gate
99
+ `node scripts/qa/check-ci-policy.js`
100
+ Fails (or warns) on the workflow *shapes* that quietly leave the GitHub Actions
101
+ free tier: a sub-hourly `cron:` (`scheduled-too-frequent`), a macOS/Windows runner
102
+ on an unfiltered `push` (`expensive-every-push`), a `-large`/`-xlarge` runner
103
+ (`larger-runner`, warn), and two expensive workflows on the same unfiltered push
104
+ (`duplicate-expensive-push`). A project with no `.github/workflows` passes.
105
+ **Satisfy:** path-filter the expensive workflow (`paths:`), widen the cron to
106
+ ≥6-hourly, or move it off the push trigger; price a change first with
107
+ `npm run ci-triage -- --preflight .github/workflows/<file>.yml`.
108
+
109
+ ## `test:prefix` — cache-prefix stability gate
110
+ `node scripts/qa/check-prefix-stability.js`
111
+ No volatile value (clock timestamp, machine path, session id) in an always-loaded
112
+ prefix file (root dispatcher, rulebook, operating rules, session-start memory).
113
+ **Satisfy:** move per-run values into handoffs/state files.
114
+
115
+ ---
116
+
117
+ ## Non-test harness commands referenced by the rules
118
+ - `node scripts/orient.js` — one-call session orientation (tree/feature/checkpoint/board/serves/capacity/last-E2E) **plus a bounded digest of the session-start memory files** (`--brief` for session-start injection).
119
+ - `node scripts/qa/run-gates.js` — run the gate battery in ONE call (`npm run gates [-- --phase=pre-push|process|quick|all] [--base=<ref>] [--continue]`). Phases run in order, stop at the first failure, and skip a gate the project has not wired. **The pre-push hook delegates here** (`gates --phase=pre-push`), so the hook and the `gates` tool share one gate list.
120
+ - `node scripts/qa/where.js` — bounded symbol/owner lookup (`npm run where -- <term>`): index-first `file:line` hits annotated with the backlog row(s) owning each file, plus `--owner <glob>`. Use it instead of shell `grep` for locating a symbol.
121
+ - `node scripts/qa/feature-scaffold.js` — write the per-feature doc-tree skeletons (intent/scope/plan/tests) + the QA-plan stub in one call (`npm run feature:scaffold -- --id <F-n> --slug <slug> [--risk high]`), so the author personas fill a `test:product`-shaped structure instead of a blank page. Write-if-missing; authors no content.
122
+ - `node scripts/qa/session-recon.js` — tool-habit / context-hygiene recon (`npm run report:recon`).
123
+ - `node scripts/qa/ci-triage.js` — name a red Actions run for what it is (`green` / `infra-block` — no runner, a billing artifact — / `failed`, exit 0/1/2) and price a dispatch (`--preflight .github/workflows/<file>.yml`) against the recent-run median + budget (`npm run ci-triage`).
124
+ - `node scripts/wait-for.js` — bounded blocking wait (`--job`/`--ci`/`--health`/`--port`/`--file --grep`); `npm run wait`.
125
+ - `node scripts/checkpoint.js` — deterministic checkpoint (`write`/`resume`).
126
+ - `node scripts/backlog.js` — board read/write (single write path; service backend per ADR 0001).
127
+ - `node scripts/serve.js` — detached long-lived process launcher + capacity/lock gate.
128
+ - `node scripts/ship.js` / `finalize.js` — integrate, gate, land on `main`, confirm CI.