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.
- package/CHANGELOG.md +217 -0
- package/LICENSE +21 -0
- package/README.md +636 -2
- package/bin/agent-harness.js +3182 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +86 -4
- package/templates/.agents/AGENTS.md +148 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1924 -0
- package/templates/scripts/board-service.sh +214 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +416 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +323 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +499 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +434 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +288 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +187 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/check-worktrees.js +93 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +213 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/worktree-hygiene.js +217 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- 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);
|