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,187 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:prefix — cache-prefix stability gate.
5
+ *
6
+ * The intended leading context is the root `AGENTS.md` (the always-loaded
7
+ * dispatcher under V2), the discovered rulebook + operating-rules summary, and
8
+ * the session-start memory reads — the prompt prefix every turn is billed
9
+ * against. Under V2 only the root `AGENTS.md` is auto-loaded:
10
+ * `.agents/AGENTS.md` is discovered lazily (it is an `AGENTS.md`), and
11
+ * `.agents/rules/00-operating.md` is never auto-loaded (the root file links it).
12
+ * So this set is a budget proxy for the context the rules *deliberately* pull
13
+ * in, not a byte-for-byte copy of the live prefix. At ~97% cache-read share, one
14
+ * volatile byte in that context (a clock timestamp, a machine-specific path, a
15
+ * session id) breaks cache locality for every following turn — a silent,
16
+ * recurring cost. This gate fails when a volatile value is found in a prefix file.
17
+ *
18
+ * Scoped to the prefix files only: project memory that legitimately records
19
+ * historical dates, feature docs, handoffs, and the live BACKLOG.md are out of
20
+ * scope, so the check never flags honest history. A date alone is stable; a
21
+ * timestamp with a clock time, an absolute user/home path, or a session id is
22
+ * per-run content and fails.
23
+ *
24
+ * It also enforces a SIZE budget on the harness-owned prefix files (the
25
+ * rulebook + operating summary). The prefix is billed every turn, so unchecked
26
+ * growth silently raises the floor cost of every session; the budget is set a
27
+ * little above the current size and forces a deliberate check before it grows
28
+ * again. Project-owned memory files are unbounded (they legitimately vary).
29
+ * `AGENT_PREFIX_STRICT=0` disables the size check; `AGENT_PREFIX_MAX_BYTES`
30
+ * overrides the combined harness-owned ceiling.
31
+ *
32
+ * Usage: node scripts/qa/check-prefix-stability.js [--root <dir>] [--json]
33
+ */
34
+
35
+ const fs = require("fs");
36
+ const path = require("path");
37
+ const argv = process.argv.slice(2);
38
+ const rootFlag = argv.indexOf("--root");
39
+ const root = path.resolve(rootFlag !== -1 && argv[rootFlag + 1] ? argv[rootFlag + 1] : path.resolve(__dirname, "..", ".."));
40
+ const jsonOut = argv.includes("--json");
41
+ const strict = process.env.AGENT_PREFIX_STRICT !== "0";
42
+
43
+ /* Per-file size ceilings (bytes) for the harness-owned prefix files. Set just
44
+ * above the shipped size so a real growth must be a deliberate bump, not a
45
+ * quiet accumulation. Memory files are project-owned and deliberately absent.
46
+ * 0.1.164: raised the AGENTS.md ceiling 10 -> 11 KiB for the "prefer the
47
+ * harness tools over the shell" rule (W4 discoverability).
48
+ * 0.3.5: trimmed the rulebook to standards-only (47 -> 27 KiB) by replacing
49
+ * duplicated operating mechanics with pointers; lowered its ceiling to match so
50
+ * the dedupe cannot silently regrow. */
51
+ const SIZE_BUDGET = {
52
+ "AGENTS.md": 11264,
53
+ ".agents/AGENTS.md": 28672,
54
+ ".agents/rules/00-operating.md": 30720,
55
+ };
56
+ /* Combined harness-owned ceiling (the sum of the per-file ceilings);
57
+ * `AGENT_PREFIX_MAX_BYTES` overrides. */
58
+ const DEFAULT_TOTAL_BUDGET = 70656; // ≈ 69 KB
59
+ const totalBudget = (() => {
60
+ const n = Number(process.env.AGENT_PREFIX_MAX_BYTES);
61
+ return Number.isFinite(n) && n > 0 ? n : DEFAULT_TOTAL_BUDGET;
62
+ })();
63
+
64
+ /* The intended always-on prefix: root dispatcher -> rulebook -> rules summary,
65
+ * then the memory files the operating rules name as session-start reads. Under
66
+ * V2 only the root `AGENTS.md` is auto-loaded; the rest are discovered lazily or
67
+ * read on demand, so this list is the deliberate-context budget proxy, not the
68
+ * literal live prefix. BACKLOG.md is deliberately excluded — it is a live board
69
+ * that changes every session.
70
+ * `locations.md` is the locations map: absolute machine paths are its whole
71
+ * purpose, so machine paths are allowed there (clock timestamps and session ids
72
+ * are still flagged). */
73
+ const PREFIX_FILES = [
74
+ { rel: "AGENTS.md" },
75
+ { rel: ".agents/AGENTS.md" },
76
+ { rel: ".agents/rules/00-operating.md" },
77
+ { rel: ".agents/memory/locations.md", allowMachinePaths: true },
78
+ { rel: ".agents/memory/model-routing.md" },
79
+ { rel: ".agents/memory/orchestration.md" },
80
+ { rel: ".agents/memory/product-principles.md" },
81
+ { rel: ".agents/memory/environments.md" },
82
+ ];
83
+
84
+ /* Volatile-value patterns. Each is per-run content, never legitimate stable
85
+ * guidance: clock timestamps (a bare date stays allowed), machine-specific
86
+ * absolute paths (Windows drive letters, POSIX user/home dirs, WSL `/mnt/<drive>/`
87
+ * mounts, and `\\wsl.localhost\` / `\\wsl$\` UNC paths — the `\b` keeps URL
88
+ * schemes like `https://` from matching), and opencode session ids. */
89
+ const PATTERNS = [
90
+ { name: "clock timestamp", re: /\b\d{4}-\d{2}-\d{2}[T ]\d{1,2}:\d{2}/ },
91
+ {
92
+ name: "machine-specific absolute path",
93
+ re: /(?:\b[A-Za-z]:[\\/]|\/(?:Users|home)\/[A-Za-z0-9._-]+\/|\/mnt\/[a-z]\/|wsl(?:\.localhost|\$)[\\/])/i,
94
+ machinePath: true,
95
+ },
96
+ { name: "opencode session id", re: /\bses_[A-Za-z0-9]{6,}\b/ },
97
+ ];
98
+
99
+ const findings = [];
100
+ const warnings = [];
101
+ const checked = [];
102
+ let budgetedTotal = 0;
103
+ const sizes = [];
104
+
105
+ for (const entry of PREFIX_FILES) {
106
+ const rel = entry.rel;
107
+ const abs = path.join(root, rel);
108
+ if (!fs.existsSync(abs)) {
109
+ warnings.push(`missing prefix file: ${rel}`);
110
+ continue;
111
+ }
112
+ const bytes = fs.statSync(abs).size;
113
+ sizes.push({ rel, bytes, maxBytes: SIZE_BUDGET[rel] || null });
114
+ if (SIZE_BUDGET[rel]) budgetedTotal += bytes;
115
+ const src = fs.readFileSync(abs, "utf8");
116
+ checked.push(rel);
117
+ src.split(/\r?\n/).forEach((line, i) => {
118
+ for (const p of PATTERNS) {
119
+ if (p.machinePath && entry.allowMachinePaths) continue;
120
+ if (p.re.test(line)) {
121
+ findings.push(`${rel}:${i + 1} — ${p.name}: ${line.trim().slice(0, 120)}`);
122
+ }
123
+ }
124
+ });
125
+ }
126
+
127
+ const sizeFindings = [];
128
+ if (strict) {
129
+ for (const s of sizes) {
130
+ if (s.maxBytes && s.bytes > s.maxBytes) {
131
+ sizeFindings.push(`${s.rel}: ${s.bytes} bytes exceeds the ${s.maxBytes}-byte budget (+${s.bytes - s.maxBytes})`);
132
+ }
133
+ }
134
+ if (budgetedTotal > totalBudget) {
135
+ sizeFindings.push(`harness-owned prefix total: ${budgetedTotal} bytes exceeds the ${totalBudget}-byte budget (+${budgetedTotal - totalBudget})`);
136
+ }
137
+ }
138
+
139
+ if (jsonOut) {
140
+ console.log(
141
+ JSON.stringify(
142
+ {
143
+ schema: "prefix-stability/1",
144
+ strict,
145
+ files: sizes,
146
+ budgetedTotal,
147
+ totalBudget,
148
+ volatile: findings,
149
+ size: sizeFindings,
150
+ warnings,
151
+ },
152
+ null,
153
+ 2
154
+ )
155
+ );
156
+ process.exit(findings.length || sizeFindings.length ? 1 : 0);
157
+ }
158
+
159
+ console.log("cache-prefix stability \u2014 always-loaded files carry no per-run content");
160
+ for (const s of sizes) {
161
+ const budget = s.maxBytes ? ` / ${s.maxBytes} budget` : "";
162
+ console.log(` \u2713 ${s.rel} (${s.bytes}${budget} bytes)`);
163
+ }
164
+ for (const w of warnings) console.log(` \u26a0 ${w}`);
165
+ if (strict && budgetedTotal) {
166
+ console.log(` harness-owned prefix total: ${budgetedTotal} / ${totalBudget} bytes`);
167
+ }
168
+
169
+ if (findings.length) {
170
+ console.log("\nVolatile values found in the always-loaded prefix:");
171
+ for (const f of findings) console.log(` \u2717 ${f}`);
172
+ console.log(
173
+ "\nA per-run value in the prefix breaks prompt-cache locality every turn. Move it to a" +
174
+ "\nnon-prefix file (a handoff, memory note, or state file) or remove it."
175
+ );
176
+ process.exit(1);
177
+ }
178
+ if (sizeFindings.length) {
179
+ console.log("\nPrefix size budget exceeded:");
180
+ for (const f of sizeFindings) console.log(` \u2717 ${f}`);
181
+ console.log(
182
+ "\nThe always-loaded prefix is billed every turn. Trim it, or bump the budget in" +
183
+ "\ntemplates/scripts/qa/check-prefix-stability.js deliberately if the growth is intended."
184
+ );
185
+ process.exit(1);
186
+ }
187
+ console.log(`\nRESULT: ${checked.length} prefix file(s) byte-stable, 0 volatile values, within size budget.`);
@@ -0,0 +1,177 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:product — product/UX-first gate (harness-shipped).
5
+ *
6
+ * Enforces "product & UX first" at the PLANNING phase, the same way test:qa-plan
7
+ * enforces coverage at the VERIFY phase. A feature that reaches the planning or
8
+ * implementation stage must have defined its user (actor), their need, the
9
+ * outcome, and the acceptance criteria — and a plan (plan.md) must sequence the
10
+ * work value-first and name the product concepts it honors. Tech-first features
11
+ * (a plan with no intent, or an intent that never names a user/need/outcome) fail.
12
+ *
13
+ * Checked against `.agents/features/<slug>/` (project-authored; see
14
+ * .agents/skills/features/SKILL.md and .agents/skills/planner/SKILL.md):
15
+ *
16
+ * 1. A feature with a `plan.md` MUST also have an `intent.md` (never plan an
17
+ * implementation around an undefined user need).
18
+ * 2. Every `intent.md` must carry the four product sections, each non-empty:
19
+ * ## Actor(s)/Who · ## Need/Why · ## Outcome · ## Acceptance criteria
20
+ * 3. Every `plan.md` must carry the two value-led sections, each non-empty:
21
+ * ## Value-first sequence · ## Product concepts applied
22
+ *
23
+ * Backward compatible: with no feature docs (or no `.agents/features/` tree) the
24
+ * gate warns and passes — projects opt in by authoring feature docs. A missing
25
+ * `.agents/memory/product-principles.md` is a warning, not a failure.
26
+ *
27
+ * node scripts/qa/check-product.js
28
+ *
29
+ * Exit 0 on: no feature docs, or every feature doc satisfying its contract.
30
+ * Exit 1 on: any feature doc missing a required product section.
31
+ */
32
+ const fs = require("fs");
33
+ const path = require("path");
34
+
35
+ const root = path.resolve(__dirname, "..", "..");
36
+ const FEATURES_DIR = path.join(root, ".agents", "features");
37
+
38
+ const failures = [];
39
+ const pass = (m) => console.log(" \u2713 " + m);
40
+ const fail = (m) => {
41
+ failures.push(m);
42
+ console.log(" \u2717 " + m);
43
+ };
44
+ const warn = (m) => console.log(" \u26a0 " + m);
45
+
46
+ console.log("product gate \u2014 planning is product/UX-first (intent \u2192 value-led plan)");
47
+
48
+ // ---- heading contracts ------------------------------------------------------
49
+ const H = {
50
+ actor: /^#{1,6}\s*(Actors?|Who)\b/i,
51
+ need: /^#{1,6}\s*(Need|Why)\b/i,
52
+ outcome: /^#{1,6}\s*Outcome\b/i,
53
+ acceptance: /^#{1,6}\s*Acceptance\s+criteria\b/i,
54
+ sequence: /^#{1,6}\s*(Value[ -]first\s+(sequence|order)|Sequence)\b/i,
55
+ concepts: /^#{1,6}\s*Product\s+concepts\s+applied\b/i,
56
+ };
57
+
58
+ /* Lines that count as "content" in a section: skip blanks, HTML comments, and
59
+ * unfilled `_TODO:` placeholders. */
60
+ function isFilled(line) {
61
+ if (!line) return false;
62
+ if (/^<!--/.test(line) || /-->$/.test(line)) return false;
63
+ if (/_TODO:/.test(line)) return false;
64
+ return true;
65
+ }
66
+
67
+ /* Return the filled body lines of the first section matching `re` (from the
68
+ * heading up to the next heading). [] when the heading is absent or empty. */
69
+ function section(src, re) {
70
+ const lines = src.split(/\r?\n/);
71
+ let inSec = false;
72
+ const body = [];
73
+ for (const raw of lines) {
74
+ const line = raw.trim();
75
+ if (!inSec) {
76
+ if (re.test(line)) inSec = true;
77
+ continue;
78
+ }
79
+ if (/^#{1,6}\s/.test(line)) break;
80
+ if (isFilled(line)) body.push(line);
81
+ }
82
+ return body;
83
+ }
84
+
85
+ function hasSection(src, re) {
86
+ return section(src, re).length > 0;
87
+ }
88
+
89
+ /* Acceptance criteria must be an actual list of criteria (bullets/numbers). */
90
+ function hasAcceptance(src) {
91
+ const body = section(src, H.acceptance);
92
+ return body.some((l) => /^[-*+]\s+\S/.test(l) || /^\d+[.)]\s+\S/.test(l));
93
+ }
94
+
95
+ function readMd(p) {
96
+ return fs.readFileSync(p, "utf8");
97
+ }
98
+
99
+ function checkIntent(slug, src) {
100
+ const missing = [];
101
+ if (!hasSection(src, H.actor)) missing.push("## Actor(s)/Who");
102
+ if (!hasSection(src, H.need)) missing.push("## Need/Why");
103
+ if (!hasSection(src, H.outcome)) missing.push("## Outcome");
104
+ if (!hasAcceptance(src)) missing.push("## Acceptance criteria (list)");
105
+ if (missing.length) {
106
+ fail(`${slug}/intent.md: missing product section(s) \u2014 ${missing.join(", ")}`);
107
+ } else {
108
+ pass(`${slug}/intent.md: actor \u2192 need \u2192 outcome \u2192 acceptance criteria present`);
109
+ }
110
+ }
111
+
112
+ function checkPlan(slug, src) {
113
+ const missing = [];
114
+ if (!hasSection(src, H.sequence)) missing.push("## Value-first sequence");
115
+ if (!hasSection(src, H.concepts)) missing.push("## Product concepts applied");
116
+ if (missing.length) {
117
+ fail(`${slug}/plan.md: missing value-led section(s) \u2014 ${missing.join(", ")}`);
118
+ } else {
119
+ pass(`${slug}/plan.md: value-first sequence + product concepts applied present`);
120
+ }
121
+ }
122
+
123
+ // ---- feature tree -----------------------------------------------------------
124
+ if (!fs.existsSync(FEATURES_DIR)) {
125
+ warn("no .agents/features/ tree \u2014 nothing to enforce");
126
+ console.log("\nRESULT: green (no feature docs)");
127
+ process.exit(0);
128
+ }
129
+
130
+ const dirs = fs
131
+ .readdirSync(FEATURES_DIR, { withFileTypes: true })
132
+ .filter((d) => d.isDirectory() && d.name !== "archive" && !d.name.startsWith("."))
133
+ .map((d) => d.name)
134
+ .sort();
135
+
136
+ if (dirs.length === 0) {
137
+ warn("no live feature docs \u2014 nothing to enforce");
138
+ console.log("\nRESULT: green (no feature docs)");
139
+ process.exit(0);
140
+ }
141
+
142
+ for (const slug of dirs) {
143
+ const dir = path.join(FEATURES_DIR, slug);
144
+ const intentPath = path.join(dir, "intent.md");
145
+ const planPath = path.join(dir, "plan.md");
146
+ const hasIntent = fs.existsSync(intentPath);
147
+ const hasPlan = fs.existsSync(planPath);
148
+
149
+ if (!hasIntent && !hasPlan) {
150
+ pass(`${slug}: no intent.md/plan.md yet \u2014 not at the planning stage`);
151
+ continue;
152
+ }
153
+
154
+ // 1. plan without intent = tech-first
155
+ if (hasPlan && !hasIntent) {
156
+ fail(`${slug}: has plan.md but no intent.md \u2014 never plan around an undefined user need`);
157
+ continue;
158
+ }
159
+
160
+ if (hasIntent) checkIntent(slug, readMd(intentPath));
161
+ if (hasPlan) checkPlan(slug, readMd(planPath));
162
+ }
163
+
164
+ const principlesPath = path.join(root, ".agents", "memory", "product-principles.md");
165
+ if (!fs.existsSync(principlesPath)) {
166
+ warn(
167
+ "no .agents/memory/product-principles.md \u2014 fill it in so plans are led by the project's product concepts"
168
+ );
169
+ }
170
+
171
+ console.log(
172
+ "\nRESULT: " +
173
+ (failures.length
174
+ ? `${failures.length} FAILURE(S) \u2014 every feature doc must define its user (actor/need/outcome/acceptance) and plan value-first`
175
+ : "green \u2014 planning is product/UX-first")
176
+ );
177
+ process.exit(failures.length ? 1 : 0);