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,174 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * diff — a bounded change view for agents (the missing "inspect the diff"
5
+ * capability behind the 2026-10-16 field review).
6
+ *
7
+ * The thinker personas (`qa-architect`, `planner`, `system-architect`) are
8
+ * dispatched to inspect a change, but have no shell and no `diff` tool: the
9
+ * LibraryOS field showed qa-architect at 799 `Read` / 132 `Grep` / 0 bash, and
10
+ * the single largest cause of its `Maximum steps` truncations (10 all-time).
11
+ * `git diff` returns changed paths + hunks, bounded, so the change is read in
12
+ * one call instead of mass-reading whole files.
13
+ *
14
+ * Usage:
15
+ * node scripts/qa/diff.js [--staged] [--base <ref>] [--paths a,b] [--stat]
16
+ * [--files] [--unified N] [--limit N] [--json] [--root <dir>]
17
+ *
18
+ * Defaults to the working tree vs HEAD (staged + unstaged). Always lists
19
+ * untracked files (they have no diff). Output is capped (`--limit` lines,
20
+ * default 400) so a large change cannot flood the transcript.
21
+ *
22
+ * Dependency-free and injectable (`opts.run`) so bounding and formatting are
23
+ * unit-testable without a repo.
24
+ */
25
+
26
+ const fs = require("fs");
27
+ const path = require("path");
28
+ const { spawnSync } = require("child_process");
29
+
30
+ const DEFAULT_LIMIT = 400;
31
+
32
+ function parseArgs(argv) {
33
+ const out = {
34
+ root: null,
35
+ staged: false,
36
+ base: null,
37
+ paths: [],
38
+ stat: false,
39
+ files: false,
40
+ unified: 3,
41
+ limit: DEFAULT_LIMIT,
42
+ json: false,
43
+ help: false,
44
+ };
45
+ for (let i = 0; i < argv.length; i++) {
46
+ const a = argv[i];
47
+ if (a === "--staged" || a === "--cached") out.staged = true;
48
+ else if (a === "--base" && argv[i + 1]) out.base = argv[++i];
49
+ else if (a.startsWith("--base=")) out.base = a.slice("--base=".length);
50
+ else if (a === "--paths" && argv[i + 1]) out.paths = splitPaths(argv[++i]);
51
+ else if (a.startsWith("--paths=")) out.paths = splitPaths(a.slice("--paths=".length));
52
+ else if (a === "--stat") out.stat = true;
53
+ else if (a === "--files") out.files = true;
54
+ else if (a === "--unified" && argv[i + 1]) out.unified = clamps(Number(argv[++i]), 3, 0, 50);
55
+ else if (a.startsWith("--unified=")) out.unified = clamps(Number(a.slice("--unified=".length)), 3, 0, 50);
56
+ else if (a === "--limit" && argv[i + 1]) out.limit = clamps(Number(argv[++i]), DEFAULT_LIMIT, 20, 5000);
57
+ else if (a.startsWith("--limit=")) out.limit = clamps(Number(a.slice("--limit=".length)), DEFAULT_LIMIT, 20, 5000);
58
+ else if (a === "--json") out.json = true;
59
+ else if (a === "--root" && argv[i + 1]) out.root = path.resolve(argv[++i]);
60
+ else if (a.startsWith("--root=")) out.root = path.resolve(a.slice("--root=".length));
61
+ else if (a === "--help" || a === "-h") out.help = true;
62
+ }
63
+ return out;
64
+ }
65
+
66
+ function clamps(n, fallback, lo, hi) {
67
+ return Number.isFinite(n) ? Math.min(hi, Math.max(lo, Math.trunc(n))) : fallback;
68
+ }
69
+
70
+ /* `a,b,c` / `a b c` / `a, b` → a clean path list. A `--paths` value may be
71
+ * repeated via commas only (the tool builds it from one arg). */
72
+ function splitPaths(raw) {
73
+ return String(raw || "")
74
+ .split(/[,\s]+/)
75
+ .map((p) => p.trim())
76
+ .filter(Boolean);
77
+ }
78
+
79
+ /* The git argv (without the `git`/`-C <root>` prefix) that produces the diff. */
80
+ function gitArgs(opts) {
81
+ const range = opts.staged ? ["--cached"] : opts.base ? [opts.base] : ["HEAD"];
82
+ const args = ["diff"];
83
+ if (opts.files) args.push("--name-status");
84
+ else if (opts.stat) args.push("--stat");
85
+ else args.push("--no-color", `--unified=${opts.unified}`);
86
+ args.push(...range);
87
+ if (opts.paths.length) args.push("--", ...opts.paths);
88
+ return args;
89
+ }
90
+
91
+ function untrackedArgs(opts) {
92
+ const args = ["ls-files", "--others", "--exclude-standard"];
93
+ if (opts.paths.length) args.push("--", ...opts.paths);
94
+ return args;
95
+ }
96
+
97
+ /* Cap `text` to `limit` lines, appending a visible truncation marker. Pure —
98
+ * the whole reason this tool exists is that an unbounded diff floods context. */
99
+ function capLines(text, limit) {
100
+ const lines = String(text || "").replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n");
101
+ if (lines.length <= limit) return { text: lines.join("\n"), truncated: 0 };
102
+ const kept = lines.slice(0, limit);
103
+ return { text: kept.join("\n"), truncated: lines.length - limit };
104
+ }
105
+
106
+ function renderHuman(opts, res) {
107
+ const out = [];
108
+ out.push(res.body || "(no changes)");
109
+ if (res.untracked.length) {
110
+ out.push("");
111
+ out.push(`untracked: ${res.untracked.join(", ")}`);
112
+ }
113
+ if (res.truncated > 0) {
114
+ out.push("");
115
+ out.push(`[diff truncated: ${res.truncated} more line(s) — scope with --paths <glob> or raise --limit]`);
116
+ }
117
+ return out.join("\n");
118
+ }
119
+
120
+ function collect(opts, run) {
121
+ const root = opts.root || process.cwd();
122
+ const diff = run(root, gitArgs(opts));
123
+ const untrackedRaw = run(root, untrackedArgs(opts));
124
+ const untracked = String(untrackedRaw || "")
125
+ .split(/\r?\n/)
126
+ .map((l) => l.trim())
127
+ .filter(Boolean);
128
+ const capped = capLines(diff, opts.limit);
129
+ return { body: capped.text, truncated: capped.truncated, untracked };
130
+ }
131
+
132
+ function main() {
133
+ const opts = parseArgs(process.argv.slice(2));
134
+ if (opts.help) {
135
+ console.log(
136
+ "Usage: node scripts/qa/diff.js [--staged] [--base <ref>] [--paths a,b] [--stat] [--files] [--unified N] [--limit N] [--json] [--root <dir>]"
137
+ );
138
+ return;
139
+ }
140
+ const root = opts.root || process.cwd();
141
+ const run = (dir, args) => {
142
+ const r = spawnSync("git", ["-C", dir, ...args], {
143
+ encoding: "utf8",
144
+ stdio: ["ignore", "pipe", "ignore"],
145
+ timeout: 30000,
146
+ maxBuffer: 32 * 1024 * 1024,
147
+ });
148
+ return r.status === 0 && typeof r.stdout === "string" ? r.stdout : "";
149
+ };
150
+ const res = collect(opts, run);
151
+ if (opts.json) console.log(JSON.stringify({ root, base: opts.base || (opts.staged ? "--cached" : "HEAD"), ...res }, null, 2));
152
+ else console.log(renderHuman(opts, res));
153
+ }
154
+
155
+ if (require.main === module) {
156
+ try {
157
+ main();
158
+ } catch (e) {
159
+ console.error("diff: " + (e && e.message ? e.message : e));
160
+ process.exit(1);
161
+ }
162
+ }
163
+
164
+ module.exports = {
165
+ DEFAULT_LIMIT,
166
+ parseArgs,
167
+ splitPaths,
168
+ gitArgs,
169
+ untrackedArgs,
170
+ capLines,
171
+ collect,
172
+ renderHuman,
173
+ clamps,
174
+ };
@@ -0,0 +1,224 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * feature-scaffold — create the per-feature doc-tree skeletons in one call.
5
+ *
6
+ * The 2026-10 LibraryOS recon measured the "doc chain" (intent/scope/plan/tests)
7
+ * being re-authored from scratch by four sequential persona dispatches for many
8
+ * features. This writes the section skeletons the `test:product` / `test:qa-plan`
9
+ * gates require (so the personas FILL a known shape instead of inventing one),
10
+ * and the matching per-change QA-plan stub. It authors NO content: the
11
+ * product-manager/planner/system-architect/qa-architect personas still write
12
+ * every section — this only removes the blank-page + gate-shape tax.
13
+ *
14
+ * Write-if-missing: an existing doc is never overwritten (the personas own it).
15
+ *
16
+ * Usage:
17
+ * node scripts/qa/feature-scaffold.js --id F-302 --slug f-302-cover-sync \
18
+ * [--title "..."] [--risk low|high] [--root <dir>] [--json]
19
+ */
20
+
21
+ const fs = require("fs");
22
+ const path = require("path");
23
+
24
+ function intentDoc(id, title) {
25
+ return `# ${id} — ${title || "intent"}
26
+
27
+ status: proposed
28
+
29
+ ## Actor(s)
30
+
31
+ (Who has the need — the personas fill this.)
32
+
33
+ ## Need
34
+
35
+ (The problem/desire in the user's words.)
36
+
37
+ ## Outcome
38
+
39
+ (What success looks like for the user.)
40
+
41
+ ## Acceptance criteria
42
+
43
+ - (A user-facing, testable criterion.)
44
+
45
+ ## Boundaries
46
+
47
+ - In scope:
48
+ - Out of scope:
49
+
50
+ ## Open questions
51
+
52
+ - ?
53
+ `;
54
+ }
55
+
56
+ function scopeDoc(id, title) {
57
+ return `# ${id} — scope
58
+
59
+ status: scoped
60
+
61
+ ## Technical constraints
62
+
63
+ (Constraints, dependencies, versions — see stack-versions.md.)
64
+
65
+ ## Blast radius
66
+
67
+ (Files/subsystems touched; cross-surface siblings from flow-map.md.)
68
+
69
+ ## Data-model / API impact
70
+
71
+ (Schema/migration, routes, contracts — or "none".)
72
+ `;
73
+ }
74
+
75
+ function planDoc(id, title) {
76
+ return `# ${id} — plan
77
+
78
+ status: planned
79
+
80
+ ## Value-first sequence
81
+
82
+ 1. (Smallest slice first — cite the actor + outcome each step serves.)
83
+
84
+ ## Product concepts applied
85
+
86
+ (Name the concepts/heuristics from product-principles.md this plan honors.)
87
+ `;
88
+ }
89
+
90
+ function testsDoc(id) {
91
+ return `# ${id} — tests
92
+
93
+ status: planned
94
+
95
+ Intent-level acceptance tests + the minimal tier. Points to
96
+ \`.agents/qa-plans/${id}.md\` (the per-change coverage plan) — never duplicate it.
97
+ `;
98
+ }
99
+
100
+ function qaPlanDoc(id) {
101
+ return `# QA plan — ${id}
102
+
103
+ ## Coverage map
104
+
105
+ | Changed path | Covering assertion / waiver |
106
+ |---|---|
107
+ | ? | ? |
108
+
109
+ ## Parallel-surface & variant audit
110
+
111
+ - ?
112
+
113
+ ## Test budget
114
+
115
+ - wall-clock:
116
+ - teardown:
117
+ - tier:
118
+
119
+ ## Oracle & owner
120
+
121
+ - independent oracle:
122
+ - single owner:
123
+
124
+ ## Test-design self-check
125
+
126
+ - [ ] T1–T10 (test-design-parameters.md)
127
+ `;
128
+ }
129
+
130
+ /* The doc set for a right-sized feature. `risk=high` adds scope.md. Returns a
131
+ * map of repo-relative path -> content. Pure. */
132
+ function skeletons(id, opts = {}) {
133
+ const title = opts.title || "";
134
+ const slug = opts.slug;
135
+ const base = path.posix.join(".agents", "features", slug);
136
+ const out = {};
137
+ out[path.posix.join(base, "intent.md")] = intentDoc(id, title);
138
+ out[path.posix.join(base, "plan.md")] = planDoc(id, title);
139
+ out[path.posix.join(base, "tests.md")] = testsDoc(id);
140
+ out[path.posix.join(".agents", "qa-plans", `${id}.md`)] = qaPlanDoc(id);
141
+ if (opts.risk === "high") out[path.posix.join(base, "scope.md")] = scopeDoc(id, title);
142
+ return out;
143
+ }
144
+
145
+ /* Write every skeleton that does not already exist. Returns { written, skipped }. */
146
+ function scaffold(root, opts) {
147
+ const files = skeletons(opts.id, opts);
148
+ const written = [];
149
+ const skipped = [];
150
+ for (const [rel, content] of Object.entries(files)) {
151
+ const abs = path.join(root, rel);
152
+ if (fs.existsSync(abs)) {
153
+ skipped.push(rel);
154
+ continue;
155
+ }
156
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
157
+ fs.writeFileSync(abs, content, "utf8");
158
+ written.push(rel);
159
+ }
160
+ return { written, skipped, dispatchOrder: dispatchOrder(opts.risk) };
161
+ }
162
+
163
+ /* Which author personas the orchestrator dispatches (never a script). Pure. */
164
+ function dispatchOrder(risk) {
165
+ const chain = ["product-manager (intent)"];
166
+ if (risk === "high") chain.push("system-architect (scope)");
167
+ chain.push("planner (plan)", "qa-architect (qa-plans/<id>.md)");
168
+ return chain;
169
+ }
170
+
171
+ function parseArgs(argv) {
172
+ const out = { id: null, slug: null, title: "", risk: "low", root: null, json: false, help: false };
173
+ for (let i = 0; i < argv.length; i++) {
174
+ const a = argv[i];
175
+ if (a === "--id") out.id = argv[++i];
176
+ else if (a.startsWith("--id=")) out.id = a.slice(5);
177
+ else if (a === "--slug") out.slug = argv[++i];
178
+ else if (a.startsWith("--slug=")) out.slug = a.slice(7);
179
+ else if (a === "--title") out.title = argv[++i];
180
+ else if (a.startsWith("--title=")) out.title = a.slice(8);
181
+ else if (a === "--risk") out.risk = argv[++i];
182
+ else if (a.startsWith("--risk=")) out.risk = a.slice(7);
183
+ else if (a === "--root") out.root = argv[++i];
184
+ else if (a.startsWith("--root=")) out.root = a.slice(7);
185
+ else if (a === "--json") out.json = true;
186
+ else if (a === "--help" || a === "-h") out.help = true;
187
+ }
188
+ return out;
189
+ }
190
+
191
+ function main() {
192
+ const args = parseArgs(process.argv.slice(2));
193
+ if (args.help || !args.id || !args.slug) {
194
+ console.log(
195
+ "Usage: node scripts/qa/feature-scaffold.js --id <F-n> --slug <slug> [--title ...]\n" +
196
+ " [--risk low|high] [--root <dir>] [--json]"
197
+ );
198
+ process.exit(args.help ? 0 : 2);
199
+ }
200
+ if (!/^F-\d+$/i.test(args.id)) {
201
+ console.error(`feature-scaffold: --id must be an F-<n> backlog id (got "${args.id}")`);
202
+ process.exit(2);
203
+ }
204
+ const root = path.resolve(args.root || process.cwd());
205
+ const res = scaffold(root, args);
206
+ if (args.json) console.log(JSON.stringify({ schema: "feature-scaffold/1", id: args.id, ...res }, null, 2));
207
+ else {
208
+ console.log(`feature-scaffold: ${args.id} (${args.slug})`);
209
+ for (const f of res.written) console.log(` + ${f}`);
210
+ for (const f of res.skipped) console.log(` = ${f} (exists — left alone)`);
211
+ console.log(` dispatch: ${res.dispatchOrder.join(" -> ")}`);
212
+ }
213
+ }
214
+
215
+ if (require.main === module) {
216
+ try {
217
+ main();
218
+ } catch (e) {
219
+ console.error("feature-scaffold: " + (e && e.message ? e.message : e));
220
+ process.exit(1);
221
+ }
222
+ }
223
+
224
+ module.exports = { skeletons, scaffold, dispatchOrder, parseArgs };
@@ -0,0 +1,104 @@
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
+ | metrics | Metrics & observability | Community/platform/mobile health telemetry, trends, friction visibility |
36
+ | audits-reviews | Audits & reviews | Security/legal/data audits and editorial-review coverage |
37
+ | user-flows | User flows | Borrow/lend/handoff/return/extension/join journeys and their friction |
38
+ | auth-security | Auth & security | Sessions, 2FA, access control, secret hardening |
39
+ | mobile | Mobile app | Native build/release, iOS polish, mobile-only fixes |
40
+ | data-model | Data & catalog model | Schema, taxonomy, hardcoded-data cleanup |
41
+ | testing | Testing & QA | E2E suites, QA gates, test migration |
42
+ | backlog-tooling | Backlog & dev tooling | The board itself and development tooling |
43
+ | reports | Member reports | Member-submitted bug/improvement reports with evidence |
44
+ | devops | DevOps & platform ops | Runtime/toolchain upgrades, deploy pipeline, CI gates |
45
+
46
+ ## Active / next
47
+
48
+ - _the next few picks (optional): cite each as `ID (P)`._
49
+
50
+ ## In progress
51
+
52
+ Active work — rows a session has picked up and is working on right now. Move a row
53
+ here from `Open`/`Queued` the moment a session starts dealing with it (cite the
54
+ session's handoff), and move it to `Archive (shipped · done)` when it ships — or
55
+ back to `Open` if it stalls.
56
+
57
+ | ID | Epic | Task | Handoff |
58
+ |----|------|------|---------|
59
+ | | | | |
60
+
61
+ _Rows: `| F-004 | epic-key | short desc | .agents/handoffs/F-004.md (or \`?\`) |`_
62
+
63
+ ## Queued
64
+
65
+ Sorted by priority (P1 → P4). Ready-to-pull work allocated to a worker.
66
+
67
+ | ID | P | Epic | Task | Evidence | Depends on |
68
+ |----|---|------|------|----------|------------|
69
+ | | | | | | |
70
+
71
+ _Rows: `| F-005 | P2 | epic-key | short desc | pointer, never a re-derivation | F-004 |`_
72
+
73
+ ## Open
74
+
75
+ Sorted by priority (P1 → P4).
76
+
77
+ | ID | P | Epic | Task | Evidence | Depends on |
78
+ |----|---|------|------|----------|------------|
79
+ | | | | | | |
80
+
81
+ _Rows: `| F-001 | P3 | epic-key | short desc; open questions with \`?\` | pointer | ? |`_
82
+
83
+ ## Frozen
84
+
85
+ Parked, not deleted. Reopen only when the stated condition recurs.
86
+
87
+ | ID | Epic | Task | Why frozen / reopen when |
88
+ |----|------|------|--------------------------|
89
+ | | | | |
90
+
91
+ _Rows: `| F-002 | epic-key | short desc | why + reopen condition (required) |`_
92
+
93
+ ## Archive (shipped · done)
94
+
95
+ | ID | Epic | Task | Closed |
96
+ |----|------|------|--------|
97
+ | | | | |
98
+
99
+ _Rows: `| F-003 | epic-key | short desc | shipped/done + date/commit |`_
100
+
101
+ ## Not tracking (leave-in-place, no action)
102
+
103
+ _One prose note listing built-and-stable items deliberately left in place (no
104
+ investment, no removal). Omit the section if there is nothing to note._
@@ -0,0 +1,174 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:governance — session-governance gate (repo guard).
5
+ *
6
+ * Mechanically enforces the three Step Zero reporting rules that keep dispatch
7
+ * predictable:
8
+ * 1. Every session handoff MUST open a `## Dispatch log` section that
9
+ * contains at least one entry (subagent result, waiver, or degrade).
10
+ * 2. Every `waived:` entry MUST cite a `reason:` on the same line — a waiver
11
+ * without a reason is itself a rules violation.
12
+ * 3. A dispatch log with 5+ entries (the `orchestration.md` fan-out band where
13
+ * justification starts) MUST carry a `## Fan-out justification` section or
14
+ * a `dispatch_justification:` line citing why each dispatch is distinct —
15
+ * the planner's `§Fan-out review` names them. This rule is FORWARD-ONLY
16
+ * (`FANOUT_JUSTIFY_SINCE`): handoffs dated before it shipped, undated
17
+ * legacy handoffs, and the legacy aggregate `.agents/memory/handoff.md`
18
+ * are grandfathered — a gate never retroactively fails history.
19
+ *
20
+ * Handoffs are SHARDED (like QA plans): one file per session under
21
+ * `.agents/handoffs/` (e.g. `F-003.md`, `return-no-condition.md`), so concurrent
22
+ * sessions never collide on a single shared file. The gate reads EVERY `.md`
23
+ * under that directory — plus the legacy single `.agents/memory/handoff.md` for
24
+ * backward compatibility — and requires each to open with a `## Dispatch log`
25
+ * section containing at least one entry.
26
+ */
27
+ const fs = require("fs");
28
+ const path = require("path");
29
+ const root = path.resolve(__dirname, "..", "..");
30
+
31
+ /* Fan-out band 5–7 in `.agents/memory/orchestration.md` = "planner must provide
32
+ * explicit decomposition justification"; this gate enforces that at wrap-up. */
33
+ const FANOUT_JUSTIFY_MIN = 5;
34
+ /* Forward-only: only handoffs dated this day or later are subject to the
35
+ * justification check. Undated legacy handoffs and the legacy aggregate
36
+ * `.agents/memory/handoff.md` are grandfathered. */
37
+ const FANOUT_JUSTIFY_SINCE = "2026-09-12";
38
+ const LEGACY_HANDOFF = path.join(root, ".agents", "memory", "handoff.md");
39
+
40
+ const failures = [];
41
+ const check = (ok, msg) => {
42
+ console.log(` ${ok ? "\u2713" : "\u2717"} ${msg}`);
43
+ if (!ok) failures.push(msg);
44
+ };
45
+
46
+ console.log("governance gate \u2014 wrap-up dispatch log");
47
+
48
+ /* All handoff files to check: every `.md` under `.agents/handoffs/` (recursive),
49
+ * plus the legacy single `.agents/memory/handoff.md` if present (backward compat
50
+ * for projects deployed before sharding). `README.md` files are documentation,
51
+ * not handoffs, so they are skipped. Sorted for deterministic output. */
52
+ function handoffFiles(root) {
53
+ const files = [];
54
+ const collect = (dir) => {
55
+ if (!fs.existsSync(dir)) return;
56
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
57
+ const abs = path.join(dir, entry.name);
58
+ if (entry.isDirectory()) collect(abs);
59
+ else if (
60
+ entry.name.toLowerCase().endsWith(".md") &&
61
+ entry.name.toLowerCase() !== "readme.md"
62
+ )
63
+ files.push(abs);
64
+ }
65
+ };
66
+ collect(path.join(root, ".agents", "handoffs"));
67
+ if (fs.existsSync(LEGACY_HANDOFF)) files.push(LEGACY_HANDOFF);
68
+ return files.sort();
69
+ }
70
+
71
+ /* A dispatch-log entry is either a bullet item (`- subagent -> model -> shipped`)
72
+ * or a markdown table data row (`| subagent | model | shipped ... |`). The gate
73
+ * accepts both so a session that renders its log as a table is not falsely
74
+ * flagged as "empty". Table rows are recognized only AFTER a separator row
75
+ * (`|---|---|`) so the header is never mistaken for an entry. */
76
+ function dispatchCount(section) {
77
+ const lines = section.split(/\r?\n/);
78
+ let seenSeparator = false;
79
+ let count = 0;
80
+ for (const raw of lines) {
81
+ const line = raw.trim();
82
+ if (!line) continue;
83
+ if (/^[-*]\s+\S/.test(line)) {
84
+ count++; // bullet entry
85
+ continue;
86
+ }
87
+ if (/^\|.*\|$/.test(line)) {
88
+ if (/^\|(\s*:?-+:?\s*\|)+\s*$/.test(line)) {
89
+ seenSeparator = true;
90
+ continue;
91
+ }
92
+ if (seenSeparator) count++; // data row after the separator
93
+ }
94
+ }
95
+ return count;
96
+ }
97
+
98
+ /* A fan-out justification is a `## Fan-out justification` / `## Fan-out review`
99
+ * section with content, or a `dispatch_justification: <why>` line anywhere in
100
+ * the file — so a handoff that mirrors the planner's §Fan-out review passes. */
101
+ function hasFanoutJustification(src) {
102
+ if (/^\s*(?:[-*]\s*)?dispatch_justification:\s*\S/im.test(src)) return true;
103
+ const heading = src.match(/^#{1,6}\s*Fan-out\s+(?:review|justification)\s*$/im);
104
+ if (!heading) return false;
105
+ const after = src.slice(heading.index + heading[0].length);
106
+ const tail = after.match(/^#{1,6}\s/m);
107
+ return (tail ? after.slice(0, tail.index) : after).trim().length > 0;
108
+ }
109
+
110
+ /* The handoff's `Date: <YYYY-MM-DD>` line (sessions before the template had it
111
+ * are undated). Used only for forward-only scope, never to fabricate order. */
112
+ function handoffDate(src) {
113
+ const m = src.match(/^Date:\s*(\d{4}-\d{2}-\d{2})\s*$/im);
114
+ return m ? m[1] : null;
115
+ }
116
+
117
+ const files = handoffFiles(root);
118
+
119
+ if (files.length === 0) {
120
+ console.error(
121
+ "FATAL: missing session handoff \u2014 add one under .agents/handoffs/<feature-id>.md"
122
+ );
123
+ process.exit(2);
124
+ }
125
+
126
+ console.log(
127
+ " checked against: " + files.map((f) => path.relative(root, f)).join(", ")
128
+ );
129
+
130
+ const waivers = [];
131
+ for (const file of files) {
132
+ const rel = path.relative(root, file);
133
+ const src = fs.readFileSync(file, "utf8");
134
+
135
+ const heading = src.match(/^#{1,6}\s*Dispatch log\s*$/im);
136
+ check(!!heading, `${rel} opens a \`## Dispatch log\` section`);
137
+ if (heading) {
138
+ const after = src.slice(heading.index + heading[0].length);
139
+ const sectionTail = after.match(/^#{1,6}\s/m);
140
+ const section = (sectionTail ? after.slice(0, sectionTail.index) : after).trim();
141
+ const count = dispatchCount(section);
142
+ check(
143
+ count >= 1,
144
+ `${rel} dispatch log contains at least one entry (subagent result, waived:, or degraded: — bullet or table row)`
145
+ );
146
+ if (count >= FANOUT_JUSTIFY_MIN && file !== LEGACY_HANDOFF) {
147
+ const date = handoffDate(src);
148
+ const inScope = date !== null && date >= FANOUT_JUSTIFY_SINCE;
149
+ if (inScope) {
150
+ check(
151
+ hasFanoutJustification(src),
152
+ `${rel} dispatch log has ${count} entries (fan-out >= ${FANOUT_JUSTIFY_MIN}) but no \`## Fan-out justification\` section / \`dispatch_justification:\` line citing the plan's §Fan-out review`
153
+ );
154
+ }
155
+ }
156
+ }
157
+
158
+ for (const w of src.matchAll(/\bwaived:\s*([^\n,]+)/gi)) {
159
+ const line = src.split(/\r?\n/)[src.slice(0, w.index).split(/\r?\n/).length - 1];
160
+ waivers.push({ line: line.trim(), rel });
161
+ }
162
+ }
163
+
164
+ for (const w of waivers) {
165
+ check(
166
+ /\breason:\s*\S/.test(w.line),
167
+ `every waived entry cites a reason (${w.rel}): \`${w.line}\``
168
+ );
169
+ }
170
+
171
+ console.log(
172
+ `\nRESULT: ${failures.length ? `${failures.length} FAILURE(S)` : "governance green"}`
173
+ );
174
+ process.exit(failures.length ? 1 : 0);