@tduyng/pi-devos 0.0.0-stage → 0.13.6

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 (138) hide show
  1. package/CHANGELOG.md +1398 -0
  2. package/LICENSE +201 -0
  3. package/README.md +213 -2
  4. package/package.json +45 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +181 -0
  7. package/plugins/devos/pi/extension/devos.ts +615 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +134 -0
  9. package/plugins/devos/scripts/evidence-router.py +252 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
  13. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  14. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  15. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  16. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
  17. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  18. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  19. package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
  20. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
  22. package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
  23. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  24. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  25. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  26. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  27. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  28. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  29. package/plugins/devos/skills/build/SKILL.md +71 -0
  30. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  31. package/plugins/devos/skills/build/references/defect.md +17 -0
  32. package/plugins/devos/skills/build/references/exposure.md +28 -0
  33. package/plugins/devos/skills/build/references/hard.md +39 -0
  34. package/plugins/devos/skills/build/references/refactor.md +66 -0
  35. package/plugins/devos/skills/build/references/routes.md +56 -0
  36. package/plugins/devos/skills/build/references/scale.md +84 -0
  37. package/plugins/devos/skills/build/references/spike.md +19 -0
  38. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  39. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  40. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  41. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  42. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  43. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  44. package/plugins/devos/skills/design-taste/SKILL.md +55 -0
  45. package/plugins/devos/skills/design-taste/references/tells.md +85 -0
  46. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
  47. package/plugins/devos/skills/docs/SKILL.md +22 -0
  48. package/plugins/devos/skills/docs/references/backfill.md +54 -0
  49. package/plugins/devos/skills/docs/references/init.md +43 -0
  50. package/plugins/devos/skills/docs/references/status.md +71 -0
  51. package/plugins/devos/skills/docs/references/update.md +80 -0
  52. package/plugins/devos/skills/explain/SKILL.md +45 -0
  53. package/plugins/devos/skills/explain/references/quiz.md +21 -0
  54. package/plugins/devos/skills/frame/SKILL.md +71 -0
  55. package/plugins/devos/skills/frame/references/boundaries.md +53 -0
  56. package/plugins/devos/skills/frame/references/decompose.md +96 -0
  57. package/plugins/devos/skills/frame/references/impact.md +43 -0
  58. package/plugins/devos/skills/frame/references/interrogate.md +68 -0
  59. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  60. package/plugins/devos/skills/implement/SKILL.md +36 -0
  61. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  62. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  63. package/plugins/devos/skills/implement/references/dod.md +32 -0
  64. package/plugins/devos/skills/implement/references/implement.md +52 -0
  65. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  66. package/plugins/devos/skills/implement/references/plan.md +160 -0
  67. package/plugins/devos/skills/implement/references/resume.md +9 -0
  68. package/plugins/devos/skills/implement/references/scale.md +86 -0
  69. package/plugins/devos/skills/implement/references/verify-close.md +61 -0
  70. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  71. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  72. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  73. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  74. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  75. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  76. package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
  77. package/plugins/devos/skills/init/SKILL.md +100 -0
  78. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  79. package/plugins/devos/skills/init/references/context.md +42 -0
  80. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  81. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  82. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  83. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  84. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  85. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  86. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  87. package/plugins/devos/skills/learn/SKILL.md +29 -0
  88. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  89. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  90. package/plugins/devos/skills/product/SKILL.md +40 -0
  91. package/plugins/devos/skills/product/references/planner.md +54 -0
  92. package/plugins/devos/skills/review/SKILL.md +77 -0
  93. package/plugins/devos/skills/review/references/gaps.md +26 -0
  94. package/plugins/devos/skills/spec/SKILL.md +58 -0
  95. package/plugins/devos/skills/spec/references/prototype.md +21 -0
  96. package/plugins/devos/skills/spec/references/question-craft.md +47 -0
  97. package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
  98. package/plugins/devos/skills/spec/references/write-spec.md +143 -0
  99. package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
  100. package/plugins/devos/skills/status/SKILL.md +67 -0
  101. package/plugins/devos/skills/status/references/cost.md +38 -0
  102. package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
  103. package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
  104. package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
  105. package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
  106. package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
  107. package/plugins/devos/skills/status/scripts/quality-correlation.sh +282 -0
  108. package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
  109. package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
  110. package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
  111. package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
  112. package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
  113. package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
  114. package/plugins/devos/workflows/common/category-file-structure.md +41 -0
  115. package/plugins/devos/workflows/common/feature-line-format.md +10 -0
  116. package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
  117. package/plugins/devos/workflows/common/suggest-categories.md +76 -0
  118. package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
  119. package/plugins/devos/workflows/doc/doc-health.md +137 -0
  120. package/plugins/devos/workflows/doc/doc-writer.md +44 -0
  121. package/plugins/devos/workflows/doc/init-documentation.md +196 -0
  122. package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
  123. package/plugins/devos/workflows/doc/templates/library.md +58 -0
  124. package/plugins/devos/workflows/doc/templates/service.md +61 -0
  125. package/plugins/devos/workflows/doc/update-documentation.md +194 -0
  126. package/plugins/devos/workflows/doc/write-documentation.md +137 -0
  127. package/plugins/devos/workflows/product/create-product-mission.md +45 -0
  128. package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
  129. package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
  130. package/plugins/devos/workflows/product/gather-product-info.md +25 -0
  131. package/plugins/devos/workflows/product/resume-detection.md +70 -0
  132. package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
  133. package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
  134. package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
  135. package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
  136. package/plugins/devos/workflows/product/scan-deep.md +113 -0
  137. package/plugins/devos/workflows/product/scan-git.md +122 -0
  138. package/plugins/devos/workflows/product/scan-light.md +154 -0
@@ -0,0 +1,102 @@
1
+ #!/bin/bash
2
+ # check-scenario-coverage.sh: every scenario the functional spec declares is
3
+ # recorded in the verification report.
4
+ # Deterministic, zero model calls.
5
+ #
6
+ # The verifier is told to read the `SC-n` IDs from spec-functional.md and record
7
+ # each one in verifications/verification.md, and until this script nothing
8
+ # checked that it did. An omission is the one failure a clean-looking report
9
+ # cannot show: every row it carries resolves, the verdict reads CLEAN + PASS,
10
+ # and the scenario nobody executed leaves no trace. This is the omission twin of
11
+ # check-report-locations.sh, which catches a row that points nowhere. The same
12
+ # IDs are checked one hop earlier by validate-spec.sh, spec-functional.md to
13
+ # spec.md; this is the hop from the spec to the report.
14
+ #
15
+ # Presence, not format: a report may record an ID in the criteria table, in a
16
+ # scenario mapping line, or beside the test that proves it. Pinning one layout
17
+ # would reject honest reports for their shape and teach the verifier to write
18
+ # for the gate instead of for the engineer.
19
+ #
20
+ # Usage: check-scenario-coverage.sh <spec-dir | verification.md>
21
+ # Exit 0 = every declared SC-n is recorded (or nothing is declared),
22
+ # 1 = an ID is missing, or the report cites one the spec never declared,
23
+ # 2 = usage or missing report.
24
+ set -u
25
+
26
+ target="${1:-}"
27
+ if [[ -z "$target" ]]; then
28
+ echo "usage: check-scenario-coverage.sh <spec-dir | verification.md>" >&2
29
+ exit 2
30
+ fi
31
+
32
+ report=""
33
+ if [[ -d "$target" ]]; then
34
+ spec="$target"
35
+ report="$spec/verifications/verification.md"
36
+ elif [[ -f "$target" ]]; then
37
+ report="$target"
38
+ spec="$(dirname "$(dirname "$report")")"
39
+ else
40
+ echo "FAIL check-scenario-coverage: no spec or report at '$target'" >&2
41
+ echo " fix: pass a spec folder (devos/specs/<name>) or its verifications/verification.md" >&2
42
+ exit 2
43
+ fi
44
+ if [[ ! -f "$report" ]]; then
45
+ echo "FAIL check-scenario-coverage: $report does not exist" >&2
46
+ echo " fix: run the verifier before checking its report" >&2
47
+ exit 2
48
+ fi
49
+
50
+ sf="$spec/spec-functional.md"
51
+ if [[ ! -f "$sf" ]]; then
52
+ echo "PASS check-scenario-coverage: $spec declares no functional spec"
53
+ exit 0
54
+ fi
55
+
56
+ # A C-route spec says what must not change, so it declares no scenarios and has
57
+ # no IDs to trace. Same heading normalization and exact match as validate-spec.sh,
58
+ # so a feature spec with a "Business invariants" section keeps every check it
59
+ # needs.
60
+ inv=$(awk '/^#+ /{
61
+ h = tolower($0); sub(/^#+[ \t]*/, "", h); sub(/^[0-9]+[.)]?[ \t]*/, "", h)
62
+ sub(/[ \t]+$/, "", h); inv = (h == "invariant"); next
63
+ } inv' "$sf")
64
+ if [[ -n "$inv" ]]; then
65
+ echo "PASS check-scenario-coverage: $(basename "$spec") is an invariant spec, no scenarios declared"
66
+ exit 0
67
+ fi
68
+
69
+ declared=$(grep -E 'Scenario SC-[0-9]+:' "$sf" | grep -oE 'SC-[0-9]+' | sort -u)
70
+ if [[ -z "$declared" ]]; then
71
+ echo "PASS check-scenario-coverage: $sf declares no numbered scenarios"
72
+ exit 0
73
+ fi
74
+ recorded=$(grep -oE 'SC-[0-9]+' "$report" | sort -u)
75
+
76
+ missing=""
77
+ while IFS= read -r id; do
78
+ [[ -n "$id" ]] || continue
79
+ grep -qxF "$id" <<<"$recorded" || missing="${missing}${id} "
80
+ done <<<"$declared"
81
+
82
+ extra=""
83
+ while IFS= read -r id; do
84
+ [[ -n "$id" ]] || continue
85
+ grep -qxF "$id" <<<"$declared" || extra="${extra}${id} "
86
+ done <<<"$recorded"
87
+
88
+ fail=0
89
+ if [[ -n "$missing" ]]; then
90
+ echo "FAIL check-scenario-coverage: $report does not record ${missing% }"
91
+ echo " fix: record each one in this report with what shows it: the test name and file:line, AWAITING HUMAN, or UNVERIFIED. The ID stays in the report, never in the test source. A scenario recorded nowhere was not verified."
92
+ fail=1
93
+ fi
94
+ if [[ -n "$extra" ]]; then
95
+ echo "FAIL check-scenario-coverage: $report cites ${extra% }, which $sf never declares"
96
+ echo " fix: cite the IDs the functional spec declares, or drop the stale row and re-run the verifier if the spec changed"
97
+ fail=1
98
+ fi
99
+ if ((fail == 0)); then
100
+ echo "PASS check-scenario-coverage: $report records every scenario $sf declares"
101
+ fi
102
+ exit $fail
@@ -0,0 +1,204 @@
1
+ #!/usr/bin/env node
2
+ // gate-check.mjs : run the CHECK commands in a gates file, flip boxes, record
3
+ // evidence. Canonical shared logic: every harness runs this same
4
+ // file; adapters wire it into skill prose, not into their own copies.
5
+ //
6
+ // Format (parsed exactly as documented here):
7
+ // - [ ] G1: <outcome>
8
+ // CHECK: <shell command>
9
+ // EXPECT: <substring or /regex/>
10
+ // EVIDENCE: pending
11
+ // ABANDON: G1 <reason>
12
+ //
13
+ // A checked box whose EVIDENCE still reads pending counts UNMET: a checkbox
14
+ // is a claim, evidence is the proof. An ABANDON line is an honest surrender,
15
+ // resolved for enforcement but listed in reports and owed a deferred.md line.
16
+ //
17
+ // Usage:
18
+ // node gate-check.mjs [file ...] run unmet gates' checks, update files
19
+ // node gate-check.mjs --status [file ...] report only, change nothing
20
+ // node gate-check.mjs --timeout 60 ... per-check timeout in seconds (default 120)
21
+ //
22
+ // Files default to GATES.md plus gates/*.md in the current directory.
23
+ // DevOS convention: one gates file per spec, SPEC_DIR/gates.md, written by
24
+ // implement Phase B for outcomes no project test can decide.
25
+ // Exit codes: 0 = all gates met (or honestly abandoned), 1 = unmet gates remain,
26
+ // 2 = usage or parse error.
27
+
28
+ import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
29
+ import { spawnSync } from "node:child_process";
30
+ import { join } from "node:path";
31
+
32
+ const args = process.argv.slice(2);
33
+ const statusOnly = args.includes("--status");
34
+ let timeoutSec = 120;
35
+ const tIdx = args.indexOf("--timeout");
36
+ if (tIdx !== -1) timeoutSec = Number(args[tIdx + 1]) || 120;
37
+ // Only exclude the value after a real --timeout flag; without the guard, index
38
+ // 0 of the file list would be filtered out whenever --timeout is absent.
39
+ const fileArgs = args.filter((a, i) => !a.startsWith("--") && !(tIdx !== -1 && i === tIdx + 1));
40
+
41
+ function defaultFiles(dir) {
42
+ const found = [];
43
+ const top = join(dir, "GATES.md");
44
+ if (existsSync(top)) found.push(top);
45
+ const gdir = join(dir, "gates");
46
+ if (existsSync(gdir)) {
47
+ for (const f of readdirSync(gdir)) {
48
+ if (f.endsWith(".md")) found.push(join(gdir, f));
49
+ }
50
+ }
51
+ return found;
52
+ }
53
+
54
+ const files = fileArgs.length ? fileArgs : defaultFiles(process.cwd());
55
+ if (!files.length) {
56
+ console.error("gate-check: no gate files found (GATES.md or gates/*.md)");
57
+ process.exit(2);
58
+ }
59
+
60
+ const GATE_RE = /^- \[( |x|X)\] (.*)$/;
61
+ const ATTR_RE = /^\s+(CHECK|EXPECT|EVIDENCE):\s?(.*)$/;
62
+ const ABANDON_RE = /^ABANDON:\s*(\S+)\s*(.*)$/;
63
+
64
+ function parse(lines) {
65
+ const gates = [];
66
+ const gateIds = new Set();
67
+ const duplicateIds = new Set();
68
+ const abandoned = new Map(); // id -> reason
69
+ let cur = null;
70
+ lines.forEach((line, i) => {
71
+ const g = line.match(GATE_RE);
72
+ if (g) {
73
+ const id = (g[2].match(/^(\S+?):/) || [null, `line${i + 1}`])[1];
74
+ if (gateIds.has(id)) duplicateIds.add(id);
75
+ gateIds.add(id);
76
+ cur = {
77
+ line: i, checked: g[1].toLowerCase() === "x",
78
+ title: g[2].trim().replace(/^\S+?:\s*/, ""),
79
+ id,
80
+ check: null, expect: null, evidence: null, evidenceLine: -1, lastAttrLine: -1,
81
+ };
82
+ gates.push(cur);
83
+ return;
84
+ }
85
+ const a = cur && line.match(ATTR_RE);
86
+ if (a) {
87
+ const key = a[1].toLowerCase();
88
+ cur[key] = a[2].trim();
89
+ if (key === "evidence") cur.evidenceLine = i;
90
+ cur.lastAttrLine = i;
91
+ return;
92
+ }
93
+ const ab = line.match(ABANDON_RE);
94
+ if (ab) abandoned.set(ab[1].replace(/:$/, ""), ab[2] || "(no reason)");
95
+ if (/^#|^- /.test(line) && !g) cur = null;
96
+ });
97
+ return { gates, abandoned, duplicateIds };
98
+ }
99
+
100
+ function expectMatches(expect, output) {
101
+ const rx = expect.match(/^\/(.+)\/([a-z]*)$/);
102
+ if (rx) {
103
+ try { return new RegExp(rx[1], rx[2]).test(output); } catch { return false; }
104
+ }
105
+ return output.includes(expect);
106
+ }
107
+
108
+ function tail(output, max = 200) {
109
+ const lines = output.split(/\r?\n/).map(s => s.trim()).filter(Boolean);
110
+ const last = lines.slice(-2).join(" | ");
111
+ return (last || "(no output)").slice(0, max);
112
+ }
113
+
114
+ let totalUnmet = 0;
115
+ let totalMet = 0;
116
+ let totalAbandoned = 0;
117
+
118
+ for (const file of files) {
119
+ let text;
120
+ try { text = readFileSync(file, "utf8"); } catch (e) {
121
+ console.error(`gate-check: cannot read ${file}: ${e.message}`);
122
+ process.exit(2);
123
+ }
124
+ const lines = text.split(/\r?\n/);
125
+ const { gates, abandoned, duplicateIds } = parse(lines);
126
+ if (duplicateIds.size) {
127
+ console.error(`gate-check: duplicate gate identifier ${duplicateIds.values().next().value} in ${file}`);
128
+ process.exit(2);
129
+ }
130
+ if (!gates.length) {
131
+ console.log(`${file}: no gates found`);
132
+ continue;
133
+ }
134
+ let changed = false;
135
+
136
+ for (const gate of gates) {
137
+ const isAbandoned = abandoned.has(gate.id);
138
+ const pendingEvidence = !gate.evidence || /^pending$/i.test(gate.evidence);
139
+
140
+ if (isAbandoned) { totalAbandoned++; continue; }
141
+
142
+ // Run checks for gates that are unchecked, or checked but missing evidence.
143
+ const needsRun = !statusOnly && gate.check && (!gate.checked || pendingEvidence);
144
+ if (needsRun) {
145
+ const res = spawnSync(gate.check, {
146
+ shell: true, encoding: "utf8", timeout: timeoutSec * 1000,
147
+ maxBuffer: 8 * 1024 * 1024,
148
+ });
149
+ const output = `${res.stdout || ""}\n${res.stderr || ""}`;
150
+ // With an EXPECT, the match decides (a check may exit non-zero by design);
151
+ // without one, the exit code decides.
152
+ const ok = gate.expect ? expectMatches(gate.expect, output) : res.status === 0;
153
+ if (ok) {
154
+ lines[gate.line] = lines[gate.line].replace(/^- \[ \]/, "- [x]");
155
+ if (gate.evidenceLine !== -1) {
156
+ const indent = lines[gate.evidenceLine].match(/^\s*/)[0];
157
+ lines[gate.evidenceLine] = `${indent}EVIDENCE: ${tail(output)}`;
158
+ } else if (gate.lastAttrLine !== -1) {
159
+ // No EVIDENCE line to rewrite, so add one. A box flipped with no
160
+ // proof is the claim the format exists to prevent: the next run
161
+ // re-parses the file, finds a checked gate with no evidence, and
162
+ // reports UNMET on bytes this run called met. Insert after the last
163
+ // attribute so the evidence stays inside the gate's block.
164
+ const indent = lines[gate.lastAttrLine].match(/^\s*/)[0];
165
+ lines.splice(gate.lastAttrLine + 1, 0, `${indent}EVIDENCE: ${tail(output)}`);
166
+ // Later gates' recorded line numbers just shifted down by one.
167
+ for (const g of gates) {
168
+ if (g.lastAttrLine > gate.lastAttrLine) g.lastAttrLine++;
169
+ if (g.line > gate.lastAttrLine) g.line++;
170
+ if (g.evidenceLine >= 0 && g.evidenceLine > gate.lastAttrLine) g.evidenceLine++;
171
+ }
172
+ }
173
+ gate.checked = true;
174
+ gate.evidence = tail(output);
175
+ changed = true;
176
+ console.log(` PASS ${gate.id}: ${gate.title}`);
177
+ } else {
178
+ const why = res.error ? res.error.message : tail(output);
179
+ console.log(` FAIL ${gate.id}: ${gate.title}\n ${why}`);
180
+ }
181
+ }
182
+
183
+ const evidenceNow = gate.evidence && !/^pending$/i.test(gate.evidence);
184
+ if (gate.checked && evidenceNow) totalMet++;
185
+ else {
186
+ totalUnmet++;
187
+ if (statusOnly) {
188
+ const why = !gate.checked ? "unchecked" : "checked but EVIDENCE pending";
189
+ console.log(` UNMET ${gate.id} (${why}): ${gate.title}`);
190
+ }
191
+ }
192
+ }
193
+
194
+ if (changed) writeFileSync(file, lines.join("\n"));
195
+ console.log(`${file}: ${gates.length} gates`);
196
+ }
197
+
198
+ if (totalUnmet === 0) {
199
+ console.log(`ALL MET (${totalMet} met${totalAbandoned ? `, ${totalAbandoned} abandoned` : ""})`);
200
+ process.exit(0);
201
+ } else {
202
+ console.log(`UNMET: ${totalUnmet} (met: ${totalMet}${totalAbandoned ? `, abandoned: ${totalAbandoned}` : ""})`);
203
+ process.exit(1);
204
+ }
@@ -0,0 +1,208 @@
1
+ #!/bin/bash
2
+ # Route and plan gates for every hook adapter: the shell port of the Pi
3
+ # extension's devos_route and plan gate (plugins/devos/pi/extension/devos.ts).
4
+ #
5
+ # phase-gate.sh --agent <claude|cursor|codex|copilot> prompt UserPromptSubmit-shaped hook
6
+ # phase-gate.sh --agent <...> answer after an AskUserQuestion result
7
+ # phase-gate.sh --agent <...> tool before any tool runs
8
+ # phase-gate.sh next <F|S|M|L|R|B|C|H> the next step for a size
9
+ #
10
+ # Prose rules hold for a model that reads all of them. A smaller model sizes a
11
+ # task M, then edits code on the next "go". So the hook holds the phase:
12
+ # /devos:build leaves project files blocked until `route.sh <size>` commits a
13
+ # size, M, L and C keep them blocked until a spec folder exists, and that
14
+ # spec keeps them blocked until ops.jsonl records plan-approved. Logging
15
+ # plan-approved needs spec.md and a user prompt since spec.md was written,
16
+ # unless DEVOS_HEADLESS=1 says no human can reply.
17
+ #
18
+ # Session state (route, active spec, last human reply) lives under
19
+ # $TMPDIR/devos-phase/<session>, never in the project. Unparseable input
20
+ # allows: a broken adapter must never brick every edit in the session.
21
+ set -u
22
+ GATES="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
23
+ SKILLS="$(cd "$GATES/../../skills" 2>/dev/null && pwd)"
24
+ IMPLEMENT="$SKILLS/implement"
25
+ BUILD_REFS="$SKILLS/build/references"
26
+ ROUTE_CMD="bash $SKILLS/build/scripts/route.sh <F|S|M|L|R|B|C|H> \"<the evidence from the code>\""
27
+
28
+ FRAME_NEXT="Read $SKILLS/frame/SKILL.md whole. A frame changes no production code: it ends with devos/frames/<name>/tickets.md and one re-route per ticket."
29
+
30
+ next_for() {
31
+ local spec_next="Create devos/specs/YYYY-MM-DD-<name>/spec-functional.md now, as $BUILD_REFS/routes.md says for this size. Project files stay blocked until its plan is approved."
32
+ case "$1" in
33
+ S) echo "Say the change in one plain sentence, make it, run the checks that cover it." ;;
34
+ M|L) echo "$spec_next" ;;
35
+ C) echo "Read $BUILD_REFS/refactor.md whole. $spec_next" ;;
36
+ R) echo "Read $BUILD_REFS/spike.md whole. A spike changes no production code." ;;
37
+ F) echo "$FRAME_NEXT" ;;
38
+ B) echo "Read $BUILD_REFS/defect.md whole and reproduce before any fix." ;;
39
+ H) echo "Read $BUILD_REFS/hard.md whole and start the ledger." ;;
40
+ unrouted) echo "Size the task from the code, then run $ROUTE_CMD before changing any file. S only for zero blast radius: a user calling it simple does not make it S." ;;
41
+ plan-missing) echo "Phase A. Read $IMPLEMENT/SKILL.md and $IMPLEMENT/references/plan.md whole, write spec.md in the spec folder, present the plan, and end your turn for the user's yes." ;;
42
+ awaiting-approval) echo "Phase A, plan written, not approved. Present the plan in a few plain lines and end your turn. After the user's unambiguous yes, log ops-log.sh <spec> plan-approved." ;;
43
+ missing) echo "The spec folder is gone without being archived. Ask the user whether to drop it." ;;
44
+ esac
45
+ }
46
+
47
+ if [[ "${1:-}" == "next" ]]; then
48
+ case "${2:-}" in
49
+ F|S|M|L|R|B|C|H) echo "Route $2. $(next_for "$2")"; exit 0 ;;
50
+ *) echo "route.sh: size must be one of F S M L R B C H" >&2; exit 1 ;;
51
+ esac
52
+ fi
53
+
54
+ agent="" event=""
55
+ while [[ $# -gt 0 ]]; do
56
+ case "$1" in
57
+ --agent) agent="${2:-}"; shift 2 || break ;;
58
+ prompt|answer|tool) event="$1"; shift ;;
59
+ *) shift ;;
60
+ esac
61
+ done
62
+
63
+ allow() {
64
+ if [[ "$agent" == cursor && "$event" == tool ]]; then echo '{}'; fi
65
+ if [[ "$agent" == cursor && "$event" == prompt ]]; then echo '{"continue":true}'; fi
66
+ exit 0
67
+ }
68
+
69
+ deny() {
70
+ case "$agent" in
71
+ cursor) jq -cn --arg r "$1" '{permission:"deny",user_message:$r,agent_message:$r}' ;;
72
+ copilot|codex) jq -cn --arg r "$1" '{permissionDecision:"deny",permissionDecisionReason:$r}' ;;
73
+ *) echo "$1" >&2; exit 2 ;;
74
+ esac
75
+ exit 0
76
+ }
77
+
78
+ [[ -n "$agent" && -n "$event" ]] || allow
79
+ command -v jq >/dev/null 2>&1 || allow
80
+ input=$(cat)
81
+ field() { printf '%s' "$input" | jq -r "$1" 2>/dev/null; }
82
+ ARGS='(.tool_input // .toolArgs // {}) | if type == "string" then (fromjson? // {command: .}) else . end'
83
+
84
+ session=$(field '.session_id // .sessionId // .conversation_id // empty')
85
+ cwd=$(field '.cwd // (.workspace_roots // [])[0] // empty')
86
+ cwd="${cwd:-$PWD}"
87
+ root="$cwd"
88
+ key="${session:-$root}"
89
+ STATE="${TMPDIR:-/tmp}/devos-phase/$(printf '%s' "$key" | cksum | cut -d' ' -f1)"
90
+ mkdir -p "$STATE" 2>/dev/null || allow
91
+
92
+ get() { cat "$STATE/$1" 2>/dev/null; }
93
+ put() { printf '%s' "$2" >"$STATE/$1.tmp.$$" && mv "$STATE/$1.tmp.$$" "$STATE/$1"; }
94
+ drop() { rm -f "$STATE/$1"; }
95
+
96
+ if [[ "$event" == prompt || "$event" == answer ]]; then
97
+ put human "$(date +%s)"
98
+ prompt=$(field '.prompt // empty')
99
+ if [[ "$event" == prompt && "$prompt" =~ ^[[:space:]]*(/devos:build|/skill:build|/build|\$build)([[:space:]]|$) ]]; then
100
+ put route unrouted
101
+ if [[ "$agent" == claude || "$agent" == codex ]]; then
102
+ echo "DevOS route gate: project files stay blocked until you route. $(next_for unrouted)"
103
+ fi
104
+ fi
105
+ allow
106
+ fi
107
+
108
+ # GNU first: GNU `stat -f` means filesystem status and succeeds with the wrong output.
109
+ mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; }
110
+
111
+ phase_of() { # phase_of <spec dir>
112
+ local d="$1"
113
+ if [[ ! -d "$d" ]]; then
114
+ [[ -d "$(dirname "$d")/archive/$(basename "$d")" ]] && echo archived || echo missing
115
+ elif [[ ! -f "$d/spec.md" ]]; then echo plan-missing
116
+ elif ! grep -q '"event":"plan-approved"' "$d/ops.jsonl" 2>/dev/null; then echo awaiting-approval
117
+ else echo approved
118
+ fi
119
+ }
120
+
121
+ abs() { case "$1" in /*) echo "$1" ;; *) echo "$cwd/$1" ;; esac; }
122
+
123
+ set_spec() {
124
+ local route
125
+ route=$(get route)
126
+ case "$route" in unrouted|M|L|C) drop route ;; esac
127
+ put spec "$1"
128
+ }
129
+
130
+ tool=$(field '.tool_name // .toolName // empty' | tr '[:upper:]' '[:lower:]')
131
+ path=$(field "$ARGS | .file_path // .path // .target_file // .filePath // empty")
132
+ command=$(field "$ARGS | .command // empty")
133
+ [[ -z "$command" ]] && command=$(field '.command // empty')
134
+
135
+ targets=()
136
+ case "$tool" in
137
+ edit|write|multiedit|notebookedit|create|strreplace|delete|edit_file|delete_file|search_replace)
138
+ [[ -n "$path" ]] && targets+=("$(abs "$path")")
139
+ command="" ;;
140
+ apply_patch)
141
+ while IFS= read -r p; do [[ -n "$p" ]] && targets+=("$(abs "$p")"); done < <(
142
+ printf '%s\n' "$command" | sed -n -E 's/^\*\*\* (Add|Update|Delete) File: (.*)$/\2/p; s/^\*\*\* Move to: (.*)$/\1/p')
143
+ command="" ;;
144
+ esac
145
+
146
+ for t in ${targets[@]+"${targets[@]}"}; do
147
+ if [[ "$t" =~ ^(.*/devos/specs/[^/]+)/(spec-functional|spec)\.md$ && "$t" != */devos/specs/archive/* ]]; then
148
+ set_spec "${BASH_REMATCH[1]}"
149
+ fi
150
+ done
151
+
152
+ if [[ "$command" =~ ops-log\.sh[[:space:]]+(\"[^\"]+\"|[^[:space:]]+)[[:space:]]+(started|plan-approved) ]]; then
153
+ ops_spec=$(abs "${BASH_REMATCH[1]//\"/}")
154
+ if [[ "${BASH_REMATCH[2]}" == plan-approved ]]; then
155
+ [[ -f "$ops_spec/spec.md" ]] ||
156
+ deny "DevOS plan gate: logging plan-approved is blocked, $ops_spec has no spec.md. $(next_for plan-missing)"
157
+ if [[ "${DEVOS_HEADLESS:-}" != 1 && "$(get human || echo 0)" -le "$(mtime "$ops_spec/spec.md")" ]]; then
158
+ deny "DevOS plan gate: the user has not replied since spec.md was last written, so nobody approved this plan. Present it and end your turn. The original request is not the approval."
159
+ fi
160
+ fi
161
+ set_spec "$ops_spec"
162
+ fi
163
+
164
+ [[ "$command" == *devos-phase* ]] && deny "DevOS gate: the gate state belongs to the user. Ask them to release it."
165
+
166
+ route=$(get route)
167
+ if [[ "$command" =~ route\.sh[[:space:]]+\"?([FSMLRBCH])([^[:alnum:]]|$) ]]; then
168
+ size="${BASH_REMATCH[1]}"
169
+ if [[ "$size" == S && -n "$route" && "$route" != unrouted && "$route" != F && "$route" != S ]]; then
170
+ deny "DevOS route gate: refused, this task is already routed $route, and a route never shrinks on the model's word. $(next_for "$route") Ask the user if you think it is S."
171
+ fi
172
+ put route "$size"
173
+ allow
174
+ fi
175
+
176
+ mutates() {
177
+ printf '%s\n' "$1" | grep -Eq '(^|[^[:alnum:]_])sed[^|;&]*[[:space:]]-([[:alpha:]]*i([^[:alnum:]_]|$)|-in-place)|(^|[^[:alnum:]_])perl[^|;&]*[[:space:]]-[[:alpha:]]*i|(^|[^[:alnum:]_])git[[:space:]]+(apply|commit|am)([^[:alnum:]_]|$)'
178
+ }
179
+
180
+ blocked_change() { # blocked_change <project root> -> what, if this call changes a project file
181
+ local t
182
+ for t in ${targets[@]+"${targets[@]}"}; do
183
+ case "$t" in "$1"/devos/*) ;; "$1"/*) echo "Changing ${t#"$1"/}"; return ;; esac
184
+ done
185
+ [[ -n "$command" ]] && mutates "$command" && echo "An in-place edit or commit from the shell"
186
+ }
187
+
188
+ release="Only the user lifts this gate: by approving the plan, or by deleting $STATE."
189
+ case "$route" in
190
+ unrouted|F|M|L|C|R)
191
+ what=$(blocked_change "$root")
192
+ if [[ -n "$what" ]]; then
193
+ [[ "$route" == unrouted ]] && step=$(next_for unrouted) || step="Route $route. $(next_for "$route")"
194
+ deny "DevOS route gate: $what is blocked. $step $release"
195
+ fi ;;
196
+ esac
197
+
198
+ spec=$(get spec)
199
+ if [[ -n "$spec" ]]; then
200
+ phase=$(phase_of "$spec")
201
+ case "$phase" in
202
+ plan-missing|awaiting-approval|missing)
203
+ what=$(blocked_change "$(dirname "$(dirname "$(dirname "$spec")")")")
204
+ [[ -n "$what" ]] && deny "DevOS plan gate: $what is blocked. $spec has no approved plan. $(next_for "$phase") $release" ;;
205
+ archived) drop spec ;;
206
+ esac
207
+ fi
208
+ allow
@@ -0,0 +1,147 @@
1
+ #!/usr/bin/env python3
2
+ """A plan written from the template in plan.md must pass the gates.
3
+
4
+ validate-spec.sh reads spec.md by section name and by literal line. The template in plan.md is what the model copies, so a template
5
+ that drifts from what the scripts parse produces a plan the model cannot ship,
6
+ and nothing in the suite notices until a real run does.
7
+
8
+ Filling the template mechanically is the only version of this check worth
9
+ having: asserting the right headings are present proves the strings exist, while
10
+ running the gates proves the plan the model would actually write is accepted.
11
+ """
12
+ import re
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+ from pathlib import Path
17
+
18
+ # The script lives at plugins/devos/scripts/gates/, so the repo root is four
19
+ # levels up. Resolved from __file__ rather than cwd so the check runs the same
20
+ # from anywhere, including inside a worktree.
21
+ ROOT = Path(__file__).resolve().parents[4]
22
+ SKILLS = ROOT / "plugins/devos/skills"
23
+ PLAN_REF = SKILLS / "implement/references/plan.md"
24
+ VALIDATE = SKILLS / "implement/scripts/validate-spec.sh"
25
+
26
+ # Each entry rewrites a template line (or a heading plus its bracketed
27
+ # guidance) into a value the gates accept. Applied to the block as one string
28
+ # with re.M, so a replacement may span the heading and the line under it.
29
+ FILL = [
30
+ (r"^## Goal / Technical Context.*$", "## Goal\n\nA thing changes."),
31
+ (r"^## Local Craft\n\[.*\]$", "## Local Craft\n\nNone"),
32
+ (r"^### Stack facts\n\[.*\]$", "### Stack facts\n\nnode 22"),
33
+ (r"^- \*\*Direct MVP\*\*: .*$", "- **Direct MVP**: one file"),
34
+ (r"^- \*\*Failed Items\*\*: .*$", "- **Failed Items**: None"),
35
+ (r"^- \*\*Adopted Additions\*\*: .*$", "- **Adopted Additions**: None"),
36
+ (r"^- \*\*Rejected Additions\*\*: .*$", "- **Rejected Additions**: None"),
37
+ (r"^## Specialist skills\n\[.*\]$", "## Specialist skills\n\nnone"),
38
+ (r"^Total: .*$", "Total: 1 task group."),
39
+ (r"^### Task Group 1: .*$", "### Task Group 1: Work"),
40
+ (r"^\*\*Files:\*\* .*$", "**Files:** `src/a.ts`"),
41
+ (r"^- Objective, sub-tasks, tests to write$", "- do the thing"),
42
+ (r"^\*\*Scenarios covered:\*\* .*$", "**Scenarios covered:** SC-1"),
43
+ (r"^\*\*Acceptance Criteria:\*\* .*$", "**Acceptance Criteria:** None"),
44
+ (r"^\*\*Complexity:\*\* .*$", "**Complexity:** Simple"),
45
+ (r"^- \*\*Always\*\* \(in scope\): .*$", "- **Always** (in scope): the change"),
46
+ (r"^- \*\*Ask First\*\* .*$", "- **Ask First** (none)"),
47
+ (r"^- \*\*Never\*\* \(out of scope\): .*$", "- **Never** (out of scope): adjacent work"),
48
+ (r"^## Implementation Notes\n\[.*\]$", "## Implementation Notes\n\n- none"),
49
+ (r"^## Change Log\n\[.*\]$", "## Change Log\n\n- none"),
50
+ ]
51
+ # A bracketed line left over is guidance text, not a field the gates read, so
52
+ # it is dropped. Anything left that is not bracketed would be template prose
53
+ # leaking into the specimen, and `leftover` below catches that.
54
+ DROP = re.compile(r"^\[[^\]]*\]$", re.M)
55
+
56
+
57
+ # Tokens the template must carry verbatim, checked before any substitution.
58
+ # FILL is permissive on purpose, because most of these lines hold guidance
59
+ # rather than a value the gates read, and a permissive rule would substitute for
60
+ # a line the template had dropped. Asserting the literal form of the fields the
61
+ # scripts parse closes that: a template that loses `Total: [N] task groups`, or
62
+ # renames a heading validate-spec.sh looks up, fails here instead of quietly
63
+ # producing a specimen the gates never had to judge.
64
+ REQUIRED = [
65
+ "devos-contract: 1",
66
+ "## Goal",
67
+ "Technical Requirements", # validate-spec.sh matches this as a substring
68
+ "## Local Craft",
69
+ "### Stack facts",
70
+ "## Design Convergence",
71
+ "- **Direct MVP**:",
72
+ "- **Failed Items**:",
73
+ "- **Adopted Additions**:",
74
+ "- **Rejected Additions**:",
75
+ "## Boundaries",
76
+ "**Always**",
77
+ "**Ask First**",
78
+ "**Never**",
79
+ "## Code Map",
80
+ "## Implementation Plan",
81
+ "### Overview",
82
+ "Total: [N] task groups",
83
+ "### Task Group 1:",
84
+ "**Files:**",
85
+ "**Scenarios covered:**",
86
+ "## Implementation Notes",
87
+ "## Change Log",
88
+ ]
89
+
90
+
91
+ def template():
92
+ body = PLAN_REF.read_text()
93
+ block = re.search(r"```markdown\n(.*?)\n```", body, re.S)
94
+ if not block:
95
+ raise SystemExit("FAIL plan-template: no ```markdown template block in plan.md")
96
+ raw = block.group(1)
97
+ absent = [t for t in REQUIRED if t not in raw]
98
+ if absent:
99
+ raise SystemExit(
100
+ "FAIL plan-template: the template no longer carries fields the gates "
101
+ "parse, so every plan written from it is rejected. Missing:\n "
102
+ + "\n ".join(absent))
103
+ # FILL runs before DROP, because several rules match a heading together
104
+ # with the bracketed guidance line under it, and DROP removes that line.
105
+ spec = raw
106
+ for pattern, value in FILL:
107
+ spec = re.sub(pattern, value.replace("\\", "\\\\"), spec, flags=re.M)
108
+ # No drift guard on the bracketed guidance: those lines are what DROP is
109
+ # for, so any guard over them fires on the template working correctly. The
110
+ # specimen run is the real protection, and it is one-directional on purpose.
111
+ # Rename a heading the gates parse and validate-spec rejects the specimen.
112
+ # Add a new required heading to validate-spec.sh and the specimen fails
113
+ # because the template does not carry it. Both directions were checked by
114
+ # hand against this script before it shipped.
115
+ spec = DROP.sub("", spec)
116
+ return spec.rstrip() + "\n"
117
+
118
+
119
+ def main():
120
+ spec = template()
121
+ with tempfile.TemporaryDirectory() as tmp:
122
+ d = Path(tmp) / "spec"
123
+ d.mkdir()
124
+ (d / "spec.md").write_text(spec)
125
+ # validate-spec reads spec-functional.md for the scenario set, so the
126
+ # capsule's SC-n has to exist somewhere it can trace.
127
+ (d / "spec-functional.md").write_text(
128
+ "# F\n\n## 1. Goal\n\nx\n\n## 3. Functionality\n\n"
129
+ "- Scenario SC-1: a / WHEN x THEN y\n\n## 5. Out of Scope\n\n- none\n")
130
+ failures = []
131
+ for name, script, target in (("validate-spec", VALIDATE, d),):
132
+ r = subprocess.run(["bash", str(script), str(target)],
133
+ capture_output=True, text=True)
134
+ if r.returncode != 0:
135
+ failures.append((name, (r.stdout + r.stderr).strip()))
136
+ if failures:
137
+ print("FAIL a plan written from the plan.md template does not pass "
138
+ "the gates, so every plan the model writes from it is rejected:",
139
+ file=sys.stderr)
140
+ for name, out in failures:
141
+ print(f" {name}:\n{out}", file=sys.stderr)
142
+ return 1
143
+ print("PASS a plan written from the plan.md template passes the gates")
144
+ return 0
145
+
146
+
147
+ sys.exit(main())