opencode-agent-harness 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
@@ -0,0 +1,83 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * run-clean — run a project gate against the COMMITTED state, not the live tree.
5
+ *
6
+ * The pre-push floor (`npm run test:quick`) verifies the working tree, so a
7
+ * concurrent session's half-done files (e.g. a page referencing translation keys
8
+ * not yet in messages/*.json) fail YOUR push. Wrap the gate with this to verify
9
+ * only what you committed:
10
+ *
11
+ * node scripts/qa/run-clean.js -- npm run test:quick
12
+ *
13
+ * If the working tree is clean, the command runs in place. If it is dirty, the
14
+ * wrapper stashes every uncommitted + untracked file (gitignored files like
15
+ * node_modules are untouched, so the gate still resolves its deps), runs the
16
+ * command, then restores the stash. It never silently swallows the stash: a
17
+ * failed `stash pop` leaves the work in the stash and prints a recovery hint.
18
+ *
19
+ * Args are passed through the shell, so quote arguments that need quoting
20
+ * (e.g. `-- npm run test:quick -- --grep "a b"`).
21
+ */
22
+ const { spawnSync } = require("child_process");
23
+ const path = require("path");
24
+
25
+ const root = path.resolve(__dirname, "..", "..");
26
+ const argv = process.argv.slice(2);
27
+ if (argv[0] === "--") argv.shift();
28
+ if (argv.length === 0) {
29
+ console.error("run-clean: usage: node scripts/qa/run-clean.js -- <command> [args...]");
30
+ process.exit(2);
31
+ }
32
+
33
+ function git(args) {
34
+ return spawnSync("git", args, {
35
+ cwd: root,
36
+ encoding: "utf8",
37
+ stdio: ["ignore", "pipe", "pipe"],
38
+ });
39
+ }
40
+
41
+ function runCmd(args) {
42
+ const r = spawnSync(args.join(" "), { cwd: root, stdio: "inherit", shell: true });
43
+ return r.status == null ? 1 : r.status;
44
+ }
45
+
46
+ const inRepo = git(["rev-parse", "--is-inside-work-tree"]).status === 0;
47
+ const dirty = inRepo && (git(["status", "--porcelain"]).stdout || "").trim() !== "";
48
+
49
+ if (!dirty) {
50
+ process.exit(runCmd(argv));
51
+ }
52
+
53
+ console.log(
54
+ "run-clean: working tree is dirty \u2014 stashing to verify the committed state " +
55
+ "(another session's WIP will not leak into this gate):"
56
+ );
57
+ console.log(git(["status", "--porcelain"]).stdout.trimEnd());
58
+
59
+ const stamp = new Date().toISOString();
60
+ const st = git(["stash", "push", "--include-untracked", "-m", `agent-harness run-clean ${stamp}`]);
61
+ if (st.status !== 0) {
62
+ console.error("run-clean: git stash failed \u2014 refusing to run on a dirty tree:\n" + (st.stderr || "").trim());
63
+ process.exit(1);
64
+ }
65
+
66
+ let exit;
67
+ try {
68
+ exit = runCmd(argv);
69
+ } finally {
70
+ const pop = git(["stash", "pop"]);
71
+ if (pop.status !== 0) {
72
+ console.error(
73
+ "\nrun-clean: WARNING \u2014 `git stash pop` failed. Your changes are still in the stash:\n" +
74
+ (pop.stderr || "").trim()
75
+ );
76
+ console.error(
77
+ "run-clean: recover with `git stash list` then `git stash pop` (or `git stash apply stash@{0}`)."
78
+ );
79
+ } else {
80
+ console.log("\nrun-clean: restored the working tree from the stash.");
81
+ }
82
+ }
83
+ process.exit(exit);
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * gates — run the harness gate battery as ONE call.
5
+ *
6
+ * The 2026-10 LibraryOS recon measured ~700 individual gate invocations in 14
7
+ * days (`tsc` 125, `test:quick` 120, `test:qa-plan` 50, …): each is a separate
8
+ * shell round-trip that re-enters the tool, re-reads nothing, and prints its
9
+ * own banner. This runs a coherent phase in order, stops at the first failure,
10
+ * and returns a compact per-gate PASS/FAIL summary, so an agent spends one tool
11
+ * call instead of a dozen.
12
+ *
13
+ * Semantics match the pre-push hook: a gate the project has not wired
14
+ * (`package.json` scripts) is SKIPPED, never failed — `--if-present`. The
15
+ * pre-push hook calls `npm run gates -- --phase=pre-push` so the gate list has
16
+ * one owner (this file) and the hook can never drift from it.
17
+ *
18
+ * Usage:
19
+ * node scripts/qa/run-gates.js [--phase=pre-push|process|quick|all]
20
+ * [--base=<ref>] [--continue] [--json] [--root <dir>]
21
+ * [--list]
22
+ *
23
+ * Dependency-free and injectable (`opts.runner`) so phase selection, skipping,
24
+ * stop-at-first-failure, and arg forwarding are unit-testable.
25
+ */
26
+
27
+ const fs = require("fs");
28
+ const path = require("path");
29
+ const { spawnSync } = require("child_process");
30
+
31
+ /* Gate phases. `process` = the harness process gates that need only the board/
32
+ * repo; `quick` = the project's own stack gates (lint/typecheck/tests). An
33
+ * entry is `[script, ...extraArgs]`; `{base}` is replaced from --base. */
34
+ const PHASES = {
35
+ process: [
36
+ ["test:dispatch"],
37
+ ["test:governance"],
38
+ ["test:concurrency"],
39
+ ["test:capacity"],
40
+ ["test:ci-policy"],
41
+ ["test:backlog"],
42
+ ["test:wiring"],
43
+ ["test:integrate"],
44
+ ["test:qa-plan", "--base={base}"],
45
+ ["test:product"],
46
+ ["test:docs"],
47
+ ["test:quality"],
48
+ ],
49
+ quick: [["lint:hooks"], ["test:schema"], ["test:quick"]],
50
+ };
51
+ PHASES["pre-push"] = [...PHASES.process, ...PHASES.quick];
52
+
53
+ function readScripts(root) {
54
+ try {
55
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
56
+ return pkg && typeof pkg.scripts === "object" && pkg.scripts ? pkg.scripts : {};
57
+ } catch (_) {
58
+ return {};
59
+ }
60
+ }
61
+
62
+ /* Resolve a phase name to the concrete gate list, expanding `{base}`. `all`
63
+ * de-duplicates every gate across phases (first occurrence wins). Pure given
64
+ * the phase table; no IO. */
65
+ function resolveGates(phase, base) {
66
+ if (phase === "all") {
67
+ const seen = new Set();
68
+ const out = [];
69
+ for (const key of ["process", "quick"]) {
70
+ for (const gate of PHASES[key]) {
71
+ if (!seen.has(gate[0])) {
72
+ seen.add(gate[0]);
73
+ out.push(gate.slice());
74
+ }
75
+ }
76
+ }
77
+ return out;
78
+ }
79
+ const list = PHASES[phase];
80
+ if (!list) return null;
81
+ return list.map((gate) => gate.map((a) => a.replace("{base}", base)));
82
+ }
83
+
84
+ function parseArgs(argv) {
85
+ const out = {
86
+ phase: "pre-push",
87
+ base: "origin/main",
88
+ cont: false,
89
+ json: false,
90
+ list: false,
91
+ root: null,
92
+ help: false,
93
+ };
94
+ for (let i = 0; i < argv.length; i++) {
95
+ const a = argv[i];
96
+ if (a === "--phase") out.phase = argv[++i];
97
+ else if (a.startsWith("--phase=")) out.phase = a.slice("--phase=".length);
98
+ else if (a === "--base") out.base = argv[++i];
99
+ else if (a.startsWith("--base=")) out.base = a.slice("--base=".length);
100
+ else if (a === "--continue") out.cont = true;
101
+ else if (a === "--json") out.json = true;
102
+ else if (a === "--list") out.list = true;
103
+ else if (a === "--root") out.root = argv[++i];
104
+ else if (a.startsWith("--root=")) out.root = a.slice("--root=".length);
105
+ else if (a === "--help" || a === "-h") out.help = true;
106
+ }
107
+ return out;
108
+ }
109
+
110
+ function npmBin() {
111
+ return process.platform === "win32" ? "npm.cmd" : "npm";
112
+ }
113
+
114
+ /* Run one gate via `npm run <script> -- <args>`. Injectable runner returns
115
+ * { code, stdout, stderr }. */
116
+ function defaultRunner(root, script, args) {
117
+ const r = spawnSync(npmBin(), ["run", script, "--", ...args], {
118
+ cwd: root,
119
+ encoding: "utf8",
120
+ stdio: ["ignore", "pipe", "pipe"],
121
+ env: process.env,
122
+ });
123
+ return { code: r.status == null ? 1 : r.status, stdout: r.stdout || "", stderr: r.stderr || "" };
124
+ }
125
+
126
+ /* Execute a resolved gate list. Returns { results, failed, skipped, ok }. */
127
+ function runGates(root, gates, opts = {}) {
128
+ const scripts = opts.scripts || readScripts(root);
129
+ const run = opts.runner || defaultRunner;
130
+ const results = [];
131
+ let failed = false;
132
+ for (const [script, ...args] of gates) {
133
+ if (!(script in scripts)) {
134
+ results.push({ script, status: "skipped", reason: "not wired in package.json" });
135
+ continue;
136
+ }
137
+ if (failed && !opts.cont) {
138
+ results.push({ script, status: "pending", reason: "skipped after an earlier failure" });
139
+ continue;
140
+ }
141
+ const started = Date.now();
142
+ const res = run(root, script, args);
143
+ const ms = Date.now() - started;
144
+ if (res.code === 0) {
145
+ results.push({ script, status: "pass", ms });
146
+ } else {
147
+ failed = true;
148
+ results.push({ script, status: "fail", ms, code: res.code, output: (res.stdout || "") + (res.stderr || "") });
149
+ }
150
+ }
151
+ return {
152
+ results,
153
+ failed,
154
+ skipped: results.filter((r) => r.status === "skipped").length,
155
+ passed: results.filter((r) => r.status === "pass").length,
156
+ };
157
+ }
158
+
159
+ const MARKS = { pass: "\u2713", fail: "\u2717", skipped: "-", pending: "\u00b7" };
160
+
161
+ function printHuman(phase, base, outcome) {
162
+ console.log(`gates — phase ${phase}${phase === "all" ? "" : ""} (base ${base})`);
163
+ for (const r of outcome.results) {
164
+ const tail = r.status === "pass" || r.status === "fail" ? ` (${(r.ms / 1000).toFixed(1)}s)` : "";
165
+ console.log(` ${MARKS[r.status] || "?"} ${r.script}${tail}${r.status === "skipped" ? " — skipped (not wired)" : ""}`);
166
+ if (r.status === "fail") {
167
+ const out = String(r.output || "").trim();
168
+ if (out) console.log(out.split(/\r?\n/).slice(-15).map((l) => " " + l).join("\n"));
169
+ }
170
+ }
171
+ const verdict = outcome.failed ? "FAIL" : "PASS";
172
+ console.log(`\nRESULT: ${verdict} — ${outcome.passed} passed, ${outcome.results.filter((r) => r.status === "fail").length} failed, ${outcome.skipped} skipped`);
173
+ }
174
+
175
+ function main() {
176
+ const args = parseArgs(process.argv.slice(2));
177
+ if (args.help) {
178
+ console.log(
179
+ "Usage: node scripts/qa/run-gates.js [--phase=pre-push|process|quick|all] [--base=<ref>]\n" +
180
+ " [--continue] [--json] [--list] [--root <dir>]"
181
+ );
182
+ return;
183
+ }
184
+ const root = path.resolve(args.root || process.cwd());
185
+ const gates = resolveGates(args.phase, args.base);
186
+ if (!gates) {
187
+ console.error(`gates: unknown phase "${args.phase}" (expected: ${Object.keys(PHASES).join(", ")}, all)`);
188
+ process.exit(2);
189
+ }
190
+ if (args.list) {
191
+ for (const g of gates) console.log(g.join(" "));
192
+ return;
193
+ }
194
+ const outcome = runGates(root, gates, { cont: args.cont });
195
+ if (args.json) {
196
+ console.log(JSON.stringify({ schema: "gates/1", phase: args.phase, base: args.base, ...outcome }, null, 2));
197
+ } else {
198
+ printHuman(args.phase, args.base, outcome);
199
+ }
200
+ process.exit(outcome.failed ? 1 : 0);
201
+ }
202
+
203
+ if (require.main === module) {
204
+ try {
205
+ main();
206
+ } catch (e) {
207
+ console.error("gates: " + (e && e.message ? e.message : e));
208
+ process.exit(1);
209
+ }
210
+ }
211
+
212
+ module.exports = { PHASES, resolveGates, parseArgs, readScripts, runGates, defaultRunner };
@@ -0,0 +1,220 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * run-loop — pure decision core for the end-to-end auto-resume runner
5
+ * (`agent-harness run`).
6
+ *
7
+ * The problem it solves: a full agentic dev cycle (pick → plan → implement → QA
8
+ * → gates → ship → land → UAT deploy) needs more turns than one bounded context
9
+ * can hold, and the context-guard's soft budget therefore stops the session
10
+ * mid-phase. A primary session cannot spawn its own replacement, so without a
11
+ * runner the "fresh bounded context" half of the policy is a manual `/resume`
12
+ * per phase. This module encodes the deterministic decision — "is the feature
13
+ * landed, should we resume a fresh bounded context, or stop?" — so the CLI can
14
+ * chain phases automatically and stop on a real boundary.
15
+ *
16
+ * Pure and dependency-free: every input is text the CLI already has, so the
17
+ * whole loop is unit-testable without invoking opencode.
18
+ */
19
+
20
+ /* Body of a `## <heading>` section, up to the next heading (mirrors
21
+ * agent-report.js). Tolerant of a trailing qualifier in the heading. */
22
+ function sectionText(src, heading) {
23
+ const re = new RegExp("^#{1,6}\\s*" + heading + "\\b.*$", "im");
24
+ const m = String(src || "").match(re);
25
+ if (!m) return "";
26
+ const after = String(src).slice(m.index + m[0].length);
27
+ const tail = after.match(/^#{1,6}\s/m);
28
+ return (tail ? after.slice(0, tail.index) : after).trim();
29
+ }
30
+
31
+ /* First data row's first cell in a section, skipping the header + separator.
32
+ * `| F-256 | P1 | user-flows | ... |` -> `F-256`. */
33
+ function firstRowId(sectionSrc) {
34
+ let header = false;
35
+ for (const raw of String(sectionSrc || "").split(/\r?\n/)) {
36
+ const line = raw.trim();
37
+ if (!/^\|.*\|$/.test(line)) continue;
38
+ if (/^\|(\s*:?-+:?\s*\|)+\s*$/.test(line)) continue;
39
+ const cells = line.slice(1, -1).split("|").map((c) => c.trim());
40
+ if (!header) {
41
+ header = true;
42
+ continue; // header row
43
+ }
44
+ if (cells[0]) return cells[0];
45
+ }
46
+ return null;
47
+ }
48
+
49
+ /* The feature currently In progress on the board, or null. Used after the first
50
+ * phase to learn the id the `/next` workflow claimed. */
51
+ function inProgressFeature(backlogText) {
52
+ return firstRowId(sectionText(backlogText, "In progress"));
53
+ }
54
+
55
+ /* A feature is landed once `backlog_archive` moved its row into the Archive
56
+ * section (the archive is the completion contract). */
57
+ function isArchived(backlogText, feature) {
58
+ if (!feature) return false;
59
+ const archive = sectionText(backlogText, "Archive");
60
+ return new RegExp("^\\|\\s*" + feature.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*\\|", "m").test(archive);
61
+ }
62
+
63
+ /* The handoff's recorded outcome, if any (`## Session metadata` bullet). */
64
+ function handoffOutcome(handoffText) {
65
+ const meta = sectionText(handoffText, "Session metadata");
66
+ const m = meta.match(/^[-*]\s*outcome\s*:\s*(.+)$/im);
67
+ return m ? m[1].trim().toLowerCase() : null;
68
+ }
69
+
70
+ /* The terminal success outcomes (mirror agent-report.js OUTCOMES). */
71
+ const DONE_OUTCOMES = new Set(["shipped", "resolved"]);
72
+
73
+ /* The plain-language resume instruction. Deliberately NOT a slash command:
74
+ * `opencode run` receives a message, so the runner must work without assuming
75
+ * the TUI's command surface. */
76
+ function resumePrompt(feature) {
77
+ return (
78
+ `Resume the bounded work unit ${feature} from its checkpoint only. ` +
79
+ `Run \`node scripts/checkpoint.js resume --feature ${feature}\` and treat that ` +
80
+ `block as the full state of the work — do not replay any previous transcript. ` +
81
+ `Continue from its next_action through the gates, then run ` +
82
+ `\`npm run finalize -- --feature ${feature}\` (archive + commit + land on main + ` +
83
+ `confirm green CI), and record the handoff.`
84
+ );
85
+ }
86
+
87
+ /* The finalization-phase instruction: implementation + verification are done, so
88
+ * the fresh context must NOT re-run the doc chain or the gates — it only has to
89
+ * land the change. `npm run finalize` archives, commits, lands the branch on
90
+ * main, and confirms CI in one blocking call, which is short enough to survive
91
+ * any remaining budget. */
92
+ function finalizePrompt(feature) {
93
+ return (
94
+ `Finalize the bounded work unit ${feature} — implementation + verification are ` +
95
+ `already complete; do NOT replay the doc chain, re-read the transcript, or re-run ` +
96
+ `the full gates. Run \`node scripts/checkpoint.js resume --feature ${feature}\` to ` +
97
+ `read the state, ensure the CHANGELOG entry exists (one \`docs\` dispatch if it is ` +
98
+ `missing), then run \`npm run finalize -- --feature ${feature}\` ONCE and let it ` +
99
+ `run to completion: it archives the row, commits the tail, lands the branch ` +
100
+ `directly on main, and waits for green CI. The deploy runs after CI.`
101
+ );
102
+ }
103
+
104
+ /* The checkpoint's `phase` / `next_action` values, when recorded. Used to send a
105
+ * resumed context straight to finalization instead of the generic resume. */
106
+ function checkpointPhase(handoffText) {
107
+ const block = sectionText(handoffText, "Checkpoint");
108
+ const m = block.match(/^-\s*phase:\s*(.+)$/im);
109
+ return m ? m[1].trim() : null;
110
+ }
111
+
112
+ function checkpointNextAction(handoffText) {
113
+ const block = sectionText(handoffText, "Checkpoint");
114
+ const m = block.match(/^-\s*next_action:\s*(.+)$/im);
115
+ return m ? m[1].trim() : null;
116
+ }
117
+
118
+ /* True when the checkpoint shows only the deterministic tail remains: the phase
119
+ * names a verify/finalize/ship state, or next_action points at archive/ship. */
120
+ function finalizationReady(handoffText) {
121
+ const phase = String(checkpointPhase(handoffText) || "");
122
+ const next = String(checkpointNextAction(handoffText) || "");
123
+ return /(final|verif|ship|deploy|done|complete)/i.test(phase) || /(finaliz|ship|deploy|archive)/i.test(next);
124
+ }
125
+
126
+ function initialPrompt() {
127
+ return (
128
+ "Pull the next item off the Queue and start working on it — no confirmation " +
129
+ "needed; this is the explicit go. Follow .opencode/commands/next.md, report the " +
130
+ "picked row first, and work it through to a landed change."
131
+ );
132
+ }
133
+
134
+ /*
135
+ * Decide the runner's next step.
136
+ *
137
+ * { action: "done", reason, feature } — landed (archived / shipped outcome)
138
+ * { action: "resume", reason, feature, prompt }
139
+ * { action: "stop", reason, feature } — phase cap / no work / non-zero exit
140
+ *
141
+ * The order matters: a landed feature is always done, even at the phase cap; a
142
+ * missing feature is never resumed (no guessing); a non-zero phase exit stops
143
+ * unless the board already proves the work landed.
144
+ */
145
+ function decideRunLoop(input) {
146
+ const feature = input && input.feature ? String(input.feature) : null;
147
+ const phasesRun = Number(input && input.phasesRun) || 0;
148
+ const maxPhases = Number(input && input.maxPhases) || 4;
149
+
150
+ if (feature && isArchived(input.backlogText, feature)) {
151
+ return { action: "done", reason: `${feature} is archived on the board (landed)`, feature };
152
+ }
153
+ const outcome = handoffOutcome(input.handoffText);
154
+ if (feature && outcome && DONE_OUTCOMES.has(outcome)) {
155
+ return { action: "done", reason: `${feature} handoff outcome is \`${outcome}\``, feature };
156
+ }
157
+
158
+ if (phasesRun >= maxPhases) {
159
+ return { action: "stop", reason: `phase cap reached (${maxPhases}) before landing`, feature };
160
+ }
161
+
162
+ // A failed phase stops the loop unless the board/handoff above proved landing.
163
+ if (Number.isFinite(input.lastExit) && input.lastExit !== 0) {
164
+ return {
165
+ action: "stop",
166
+ reason: `phase exited ${input.lastExit} and the work is not landed — inspect before resuming`,
167
+ feature,
168
+ };
169
+ }
170
+
171
+ if (phasesRun === 0) {
172
+ return feature
173
+ ? {
174
+ action: "resume",
175
+ reason: `starting on ${feature}`,
176
+ feature,
177
+ prompt: finalizationReady(input.handoffText) ? finalizePrompt(feature) : resumePrompt(feature),
178
+ }
179
+ : {
180
+ action: "resume",
181
+ reason: "starting the next-item workflow",
182
+ feature: null,
183
+ prompt: initialPrompt(),
184
+ };
185
+ }
186
+
187
+ const next = feature || inProgressFeature(input.backlogText);
188
+ if (!next) {
189
+ return {
190
+ action: "stop",
191
+ reason: "no In-progress feature found after the phase — cannot resume safely",
192
+ feature: null,
193
+ };
194
+ }
195
+ const finalizing = finalizationReady(input.handoffText);
196
+ return {
197
+ action: "resume",
198
+ reason: finalizing
199
+ ? `finalizing ${next} in a fresh bounded context (implementation complete)`
200
+ : `resuming ${next} in a fresh bounded context`,
201
+ feature: next,
202
+ prompt: finalizing ? finalizePrompt(next) : resumePrompt(next),
203
+ };
204
+ }
205
+
206
+ module.exports = {
207
+ sectionText,
208
+ firstRowId,
209
+ inProgressFeature,
210
+ isArchived,
211
+ handoffOutcome,
212
+ DONE_OUTCOMES,
213
+ resumePrompt,
214
+ finalizePrompt,
215
+ checkpointPhase,
216
+ checkpointNextAction,
217
+ finalizationReady,
218
+ initialPrompt,
219
+ decideRunLoop,
220
+ };