@tduyng/pi-devos 0.13.6 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +26 -33
  3. package/package.json +1 -2
  4. package/plugins/devos/agents/verifier.md +4 -30
  5. package/plugins/devos/pi/extension/devos.ts +16 -26
  6. package/plugins/devos/scripts/check-evidence-router.sh +7 -1
  7. package/plugins/devos/scripts/evidence-router.py +5 -3
  8. package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
  9. package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
  10. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
  11. package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
  12. package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
  13. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  14. package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
  15. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  16. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  17. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  18. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  19. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  20. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  21. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  22. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  23. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  24. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  25. package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
  26. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
  27. package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
  28. package/plugins/devos/skills/build/SKILL.md +3 -3
  29. package/plugins/devos/skills/build/references/refactor.md +1 -1
  30. package/plugins/devos/skills/build/references/routes.md +4 -4
  31. package/plugins/devos/skills/frame/SKILL.md +22 -39
  32. package/plugins/devos/skills/frame/references/template.md +115 -0
  33. package/plugins/devos/skills/implement/SKILL.md +4 -4
  34. package/plugins/devos/skills/implement/references/dod.md +6 -1
  35. package/plugins/devos/skills/implement/references/implement.md +3 -1
  36. package/plugins/devos/skills/implement/references/plan.md +9 -27
  37. package/plugins/devos/skills/implement/references/resume.md +1 -1
  38. package/plugins/devos/skills/implement/references/verify-close.md +4 -3
  39. package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
  40. package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
  41. package/plugins/devos/skills/init/references/context.md +1 -1
  42. package/plugins/devos/skills/review/SKILL.md +24 -47
  43. package/plugins/devos/skills/review/references/comments.md +13 -0
  44. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  45. package/plugins/devos/skills/review/references/routing.md +35 -0
  46. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  47. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  48. package/plugins/devos/skills/spec/SKILL.md +5 -6
  49. package/plugins/devos/skills/spec/references/write-spec.md +36 -51
  50. package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
  51. package/plugins/devos/skills/status/SKILL.md +4 -4
  52. package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
  53. package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
  54. package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
  55. package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
  56. package/plugins/devos/skills/design-taste/SKILL.md +0 -55
  57. package/plugins/devos/skills/design-taste/references/tells.md +0 -85
  58. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
  59. package/plugins/devos/skills/docs/SKILL.md +0 -22
  60. package/plugins/devos/skills/docs/references/backfill.md +0 -54
  61. package/plugins/devos/skills/docs/references/init.md +0 -43
  62. package/plugins/devos/skills/docs/references/status.md +0 -71
  63. package/plugins/devos/skills/docs/references/update.md +0 -80
  64. package/plugins/devos/skills/explain/SKILL.md +0 -45
  65. package/plugins/devos/skills/explain/references/quiz.md +0 -21
  66. package/plugins/devos/skills/frame/references/boundaries.md +0 -53
  67. package/plugins/devos/skills/frame/references/decompose.md +0 -96
  68. package/plugins/devos/skills/frame/references/impact.md +0 -43
  69. package/plugins/devos/skills/frame/references/interrogate.md +0 -68
  70. package/plugins/devos/skills/product/SKILL.md +0 -40
  71. package/plugins/devos/skills/product/references/planner.md +0 -54
  72. package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
  73. package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
  74. package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
  75. package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
  76. package/plugins/devos/workflows/common/category-file-structure.md +0 -41
  77. package/plugins/devos/workflows/common/feature-line-format.md +0 -10
  78. package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
  79. package/plugins/devos/workflows/common/suggest-categories.md +0 -76
  80. package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
  81. package/plugins/devos/workflows/doc/doc-health.md +0 -137
  82. package/plugins/devos/workflows/doc/doc-writer.md +0 -44
  83. package/plugins/devos/workflows/doc/init-documentation.md +0 -196
  84. package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
  85. package/plugins/devos/workflows/doc/templates/library.md +0 -58
  86. package/plugins/devos/workflows/doc/templates/service.md +0 -61
  87. package/plugins/devos/workflows/doc/update-documentation.md +0 -194
  88. package/plugins/devos/workflows/doc/write-documentation.md +0 -137
  89. package/plugins/devos/workflows/product/create-product-mission.md +0 -45
  90. package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
  91. package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
  92. package/plugins/devos/workflows/product/gather-product-info.md +0 -25
  93. package/plugins/devos/workflows/product/resume-detection.md +0 -70
  94. package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
  95. package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
  96. package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
  97. package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
  98. package/plugins/devos/workflows/product/scan-deep.md +0 -113
  99. package/plugins/devos/workflows/product/scan-git.md +0 -122
  100. package/plugins/devos/workflows/product/scan-light.md +0 -154
package/CHANGELOG.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.14.0: 2026-11-16
4
+
5
+ ### Added
6
+ - Report the settled findings the code no longer shows
7
+ - --comments drafts answers to a teammate's review comments
8
+
9
+ ### Changed
10
+ - Keep the frame skill smaller, generate only one markdown file
11
+ - Build the packet in a script, hand the reviewer its rubric
12
+ - Gates read the contract from spec.md, legacy spec-functional.md still accepted
13
+ - One spec.md carries contract and plan, docs and skills drop spec-functional.md
14
+ - Plan appends to spec.md below the contract, one Technical Requirements heading
15
+ - Drop the spec-functional.md fallback, fixtures and evals use spec.md only
16
+ - Out of scope lives in the contract only, Boundaries drops its Never tier
17
+ - Drop the team handoff gate, devos is solo
18
+ - Notes hold Q&A and assumptions only, anchors are written once in spec.md
19
+ - Split test-gates.sh into suite/ parts
20
+ - Plan.md drops the restated gate list and anchor bullet
21
+ - Drop the docs and product skills and their workflows
22
+ - Drop the grep cookbook and rationalization table
23
+ - Run the test-gates suite parts in parallel, each with its own workspace
24
+ - Fold the discipline skills into implement, drop design-taste and explain, write pr.md at close
25
+
3
26
  ## 0.13.6: 2026-11-11
4
27
 
5
28
  ### Added
package/README.md CHANGED
@@ -20,7 +20,7 @@ DevOS reads the request, looks at the code it touches, and picks a route. There
20
20
 
21
21
  | Size | The request looks like | What DevOS runs |
22
22
  | -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- |
23
- | **F** fog | a bare ticket title, a wish, an epic: it does not say what to change | frames it into tickets you can route, no code |
23
+ | **F** fog | a bare ticket title, a wish, an epic: it does not say what to change | frames it into tickets you can route, no code |
24
24
  | **S** small | a typo, a one-line fix, an obvious tweak | just does it, no spec, no gate |
25
25
  | **M** medium | a few files, clear behavior, a couple of edge cases | a one-page mini-spec, your go, then implement |
26
26
  | **L** large | a user-visible feature, several files, requirements you would have to guess | `/devos:spec` then `/devos:implement` |
@@ -65,13 +65,13 @@ Every route lands somewhere on the same five stages. Only the size decides how m
65
65
  │ │ ══ GATE: you approve the plan ══
66
66
  │ │
67
67
  │ └─ /devos:build or /devos:spec
68
- │ interview, then spec-functional.md
68
+ │ interview, then spec.md
69
69
  │
70
70
  └─ /devos:frame only when the ask does not say what to change
71
71
  brief · impact · questions · tickets, then one route per ticket
72
72
  ```
73
73
 
74
- Every entry command: `build` is the router, `spec` drives the interview yourself, `implement` runs an approved spec (and resumes it), `init` runs once per project. `status`, `review`, `explain`, and `learn` inspect or close work at any point.
74
+ Every entry command: `build` is the router, `spec` drives the interview yourself, `implement` runs an approved spec (and resumes it), `init` runs once per project. `status`, `review`, and `learn` inspect or close work at any point.
75
75
 
76
76
  Two gates block mechanically, not by asking the model nicely. Nothing is built before you approve the plan, and nothing is called done without a verification report that names the commands that passed. On an S route there is no plan to approve, and that is correct.
77
77
 
@@ -121,7 +121,7 @@ Before I start:
121
121
 
122
122
  > admins only, line items, cap at 10k rows
123
123
 
124
- Wrote the spec: devos/specs/2026-09-13-invoice-export/spec-functional.md
124
+ Wrote the spec: devos/specs/2026-09-13-invoice-export/spec.md
125
125
  Read the Behavior delta, then I'll plan.
126
126
 
127
127
  $ (you read it, say go)
@@ -139,22 +139,19 @@ Verdict: DONE. verification.md written.
139
139
 
140
140
  You only need the first one. The rest are for when you want to drive a stage yourself or look something up.
141
141
 
142
- | Command | What it does |
143
- | -------------------------------------------- | ---------------------------------------------------------------------------------------- |
144
- | `/devos:build "..."` | Size any change and run the right process. Start here. |
145
- | `/devos:frame "..."` | Turn a bare ticket or a wish into a brief, an impact map, owned questions and tickets. |
146
- | `/devos:absorb <source>` | Record what the product promises from a help centre or a published policy. |
147
- | `/devos:spec` | Interview you and write the functional spec, without building. |
148
- | `/devos:implement` | Plan, build, and verify an approved spec. Resume-aware. |
149
- | `/devos:init` | Map the codebase, define vocabulary, wire AGENTS.md. Once per project. |
150
- | `/devos:status` | Where every spec stands. `--cost` for framework cost, `--compare a b` for a spec diff. |
151
- | `/devos:review` | Review a diff against this project's own conventions. `--gaps` for a completeness check. |
152
- | `/devos:explain` | Walk back a change you did not watch happen. |
153
- | `/devos:learn` | File a durable lesson so it stops recurring. |
154
- | `/devos:product` | Mission, roadmap, backlog, tech stack. Plans read them when present. |
155
- | `/devos:docs init\|update\|backfill\|status` | Human-facing documentation built from your specs. The pipeline never reads it. |
156
-
157
- Four rules load on their own, with no command to type: stay inside the agreed scope, never weaken a test to make it pass, name the evidence before claiming done, and follow the project's declared design direction.
142
+ | Command | What it does |
143
+ | ------------------------ | ---------------------------------------------------------------------------------------- |
144
+ | `/devos:build "..."` | Size any change and run the right process. Start here. |
145
+ | `/devos:frame "..."` | Turn a bare ticket or a wish into a brief, an impact map, owned questions and tickets. |
146
+ | `/devos:absorb <source>` | Record what the product promises from a help centre or a published policy. |
147
+ | `/devos:spec` | Interview you and write the functional spec, without building. |
148
+ | `/devos:implement` | Plan, build, and verify an approved spec. Resume-aware. |
149
+ | `/devos:init` | Map the codebase, define vocabulary, wire AGENTS.md. Once per project. |
150
+ | `/devos:status` | Where every spec stands. `--cost` for framework cost, `--compare a b` for a spec diff. |
151
+ | `/devos:review` | Review a diff against this project's own conventions. `--gaps` for a completeness check. |
152
+ | `/devos:learn` | File a durable lesson so it stops recurring. |
153
+
154
+ Three rules ride inside `implement`, with no command to type: stay inside the agreed scope, never weaken a test to make it pass, and name the evidence before claiming done. A hook enforces the second on every edit, on every route.
158
155
 
159
156
  ## What lives in your repo
160
157
 
@@ -174,13 +171,10 @@ devos/
174
171
  │ ├── constraints.md what law, contracts and platforms forbid
175
172
  │ ├── knowledge/ rules distilled from sources outside the repo
176
173
  │ └── behaviors/ what the product does today
177
- ├── frames/2026-11-11-kol-1234/
178
- │ ├── brief.md the problem, the actor, today's behavior
179
- │ ├── impact.md every dimension, with evidence or where you looked
180
- │ ├── questions.md open forks, by owner, each with a default
181
- │ └── tickets.md the split, the fog, the out of scope
174
+ ├── frames/2026-11-11-feat-1234/
175
+ │ └── frame.md context, today, expected, rules, impact, scope, questions, tickets
182
176
  ├── specs/2026-09-13-invoice-export/
183
- │ ├── spec-functional.md the contract
177
+ │ ├── spec.md the contract
184
178
  │ ├── spec.md the approved plan
185
179
  │ ├── decisions.md the choices made, and the ones rejected
186
180
  │ ├── gates.md the checks a test cannot decide, when there are any
@@ -193,7 +187,7 @@ There is no state file. Progress is derived from which files exist, so any sessi
193
187
 
194
188
  ## Why it stays cheap
195
189
 
196
- About 576 tokens per session in pi: the skill catalog the harness renders at startup. The always-on rules' descriptions are about 177 of that, and nothing else loads until you type a command. `/devos:status --cost` shows the numbers for your install.
190
+ About 298 tokens per session in pi: the skill catalog the harness renders at startup. Nothing else loads until you type a command, and the scope, test and evidence rules load with `implement`, where they apply. `/devos:status --cost` shows the numbers for your install.
197
191
 
198
192
  ## The evidence router
199
193
 
@@ -201,13 +195,12 @@ The review and planning stages read your declared evidence through a small scrip
201
195
 
202
196
  ## Docs
203
197
 
204
- | Page | What it covers |
205
- | ---------------------------------------------------- | ---------------------------------- |
206
- | [`docs/getting-started.md`](docs/getting-started.md) | First project, step by step |
207
- | [`docs/concepts.md`](docs/concepts.md) | The moving parts and the lifecycle |
208
- | [`docs/commands/`](docs/commands/) | One short page per command |
198
+ | Page | What it covers |
199
+ | ---------------------------------------------------- | ---------------------------------------- |
200
+ | [`docs/getting-started.md`](docs/getting-started.md) | First project, step by step |
201
+ | [`docs/concepts.md`](docs/concepts.md) | The moving parts and the lifecycle |
209
202
  | [`docs/evidence-router.md`](docs/evidence-router.md) | The optional evidence selector, measured |
210
- | [`docs/README.md`](docs/README.md) | Everything else |
203
+ | [`docs/README.md`](docs/README.md) | Everything else |
211
204
 
212
205
  ## License
213
206
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tduyng/pi-devos",
3
- "version": "0.13.6",
3
+ "version": "0.14.0",
4
4
  "type": "module",
5
5
  "description": "DevOS for Pi. The Pi package for DevOS, a lazy SDD framework for one engineer or a small team: adaptive sizing, a spec-driven pipeline with an approval gate, evidence-based verification. Install with `pi install npm:@tduyng/pi-devos`. Zero dependencies.",
6
6
  "keywords": [
@@ -38,7 +38,6 @@
38
38
  },
39
39
  "files": [
40
40
  "plugins/devos/skills/",
41
- "plugins/devos/workflows/",
42
41
  "plugins/devos/scripts/",
43
42
  "plugins/devos/agents/",
44
43
  "plugins/devos/pi/extension/devos.ts",
@@ -22,7 +22,7 @@ First check, before reading any code: run `bash ${CLAUDE_PLUGIN_ROOT}/skills/imp
22
22
  - Explicit markers: TODO/FIXME/XXX/HACK introduced by this implementation
23
23
  - Spec-vs-code: every task group in spec.md's Implementation Plan has a real implementation. Every file it names exists.
24
24
  - Local Craft fit: when spec.md has a `## Local Craft` section, check each named file, helper, syntax, data structure, algorithm, or installed-package fact against the diff. A missing named helper or an unexplained replacement is a finding. `None` has no Local Craft check. Report only project-specific mismatches, not generic style advice.
25
- Scenario coverage uses `SC-n` as an internal index. Read the IDs from `spec-functional.md` and the `Scenarios covered` lines in `spec.md`. Inspect the tests in each group's `Files` list and the runner's executed-test output. Record the natural test name and `file:line`, an acceptance criterion, or `AWAITING HUMAN` for each ID in `SPEC_DIR/verifications/verification.md`, written as `SC-n`. The DoD gate blocks a DONE claim that leaves one unrecorded, and an ID recorded nowhere is the omission no clean-looking report can show. Do not add an ID to a test to make the mapping pass. A missing or skipped test is a finding. For a legacy spec without internal evidence, compare the scenario text with test names and mark the result `JUDGED`. Skip this lens for an `## Invariant` spec. Lens 3 owns that route.
25
+ Scenario coverage uses `SC-n` as an internal index. Read the IDs from the `## Scenarios` section of `spec.md` and the `Scenarios covered` lines in `spec.md`. Inspect the tests in each group's `Files` list and the runner's executed-test output. Record the natural test name and `file:line`, an acceptance criterion, or `AWAITING HUMAN` for each ID in `SPEC_DIR/verifications/verification.md`, written as `SC-n`. The DoD gate blocks a DONE claim that leaves one unrecorded, and an ID recorded nowhere is the omission no clean-looking report can show. Do not add an ID to a test to make the mapping pass. A missing or skipped test is a finding. For a legacy spec without internal evidence, compare the scenario text with test names and mark the result `JUDGED`. Skip this lens for an `## Invariant` spec. Lens 3 owns that route.
26
26
 
27
27
  Implementation output has a hard boundary. For each changed code or test file, run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/gates/check-implementation-boundary.sh" --scan --file <changed-code-file>`. Files outside `devos/` may contain project behavior only. Treat an `SC-n` ID, scenario ID label, framework name, internal rule, spec path, or process attribution as BLOCKING. Remove the metadata from the file and keep the trace in the internal report.
28
28
  - Spec dependency: unmet `Requires:` targets (see `check-requires.py --verify` above)
@@ -39,7 +39,7 @@ Implementation output has a hard boundary. For each changed code or test file, r
39
39
  - Acceptance criteria from spec.md are met. Criteria marked `[human-check]` (visual design, feel, wording) are listed as **AWAITING HUMAN**, never counted toward PASS, never dropped.
40
40
  - Project conventions respected (read `devos/standards/conventions.md` if present)
41
41
 
42
- ## Lens 3: Invariant (only when `spec-functional.md` has an `## Invariant` section)
42
+ ## Lens 3: Invariant (only when `spec.md` has an `## Invariant` section)
43
43
 
44
44
  The C route inverts the contract: the spec says what must NOT change, so the question is not "does the code do the new thing" but "does it still do exactly the old thing". Replaces Lens 1's scenario coverage; Lens 2 still runs as written.
45
45
 
@@ -75,27 +75,7 @@ Check what a browser can actually answer, not what looks nice — an aesthetic o
75
75
 
76
76
  ## Detection reference
77
77
 
78
- Scope to the implementation's diff (`git diff --name-status` against the pre-implementation commit, or the files named in spec.md's plan), not the whole tree.
79
-
80
- ```bash
81
- # Explicit markers
82
- grep -rn -E "TODO|FIXME|XXX|HACK|NotImplemented|PLACEHOLDER|STUB" \
83
- --exclude-dir={node_modules,.git,dist,build,vendor,.next,__pycache__} [files]
84
- # Suspicious hardcoded returns
85
- grep -rn -E "return \[\]|return \{\}|return null|return undefined|return ''" [files]
86
- # Empty or console-only bodies
87
- grep -rn -E "\{\s*(console\.log|// |/\*|return;?\s*)\s*\}" [files]
88
- # Fake data outside tests/fixtures
89
- grep -rn -E "\"fake|\"dummy|\"mock-|\"lorem|\"sample" [files]
90
- # Python: pass / ... bodies
91
- grep -rn -E "def .+:\s*(pass|\.\.\.)" [files]
92
- # Multi-line empty bodies (brace languages): `{` line followed by nothing but blanks/comments until `}`
93
- awk '/\{[[:space:]]*$/{o=NR;b=0;next} o&&/^[[:space:]]*\}/{if(!b)print FILENAME":"o": empty body";o=0;next} o&&!/^[[:space:]]*(\/\/|\/\*|\*|$)/{b=1}' [file]
94
- # Python multi-line: def whose first non-blank body line is pass / ...
95
- awk '/^[[:space:]]*def .+:[[:space:]]*$/{d=NR;next} d&&/[^[:space:]]/{if($0~/^[[:space:]]*(pass|\.\.\.)[[:space:]]*$/)print FILENAME":"d": stub def";d=0}' [file]
96
- ```
97
-
98
- The greps catch single-line patterns, the awk passes catch empty multi-line shapes. Still read the diffed files for what neither can see (a body that only logs, a handler returning a constant). Exclude test dirs from the implicit scans (mocks are normal there).
78
+ Scope to the implementation's diff (`git diff --name-status` against the pre-implementation commit, or the files named in spec.md's plan), not the whole tree. Grep it for `TODO|FIXME|XXX|HACK|NotImplemented|PLACEHOLDER|STUB`, constant returns (`return []`, `null`), empty bodies and `fake|dummy|mock-|lorem|sample` data, then read what a grep cannot see (a body that only logs, a handler returning a constant). Skip test dirs for the implicit scans.
99
79
 
100
80
  | Category | Example | Level |
101
81
  |----------|---------|-------|
@@ -116,7 +96,7 @@ For each candidate finding, try to kill it:
116
96
  1. Is it in a test file / fixture? (mocks are normal)
117
97
  2. Did it exist before this implementation? (`git log -1 -- file`, diff scope) Pre-existing issues are out of scope, mention only if BLOCKING
118
98
  3. Is the pattern legitimate in context? (`return []` in an intentionally-empty filter is fine)
119
- 4. Is it explicitly listed in spec.md's Boundaries (Never / out of scope), or already recorded in `devos/deferred.md`?
99
+ 4. Is it explicitly listed in spec.md's Out of scope, or already recorded in `devos/deferred.md`?
120
100
 
121
101
  Only findings that survive get reported. A refuted finding costs the engineer nothing; a false one costs a re-verification round. When a surviving finding's level is uncertain, downgrade it, never promote: a false BLOCKING costs trust, a true INFO costs one line. Every finding states its concrete fix; one that can only say "review this area" is not a finding.
122
102
 
@@ -130,12 +110,6 @@ Only findings that survive get reported. A refuted finding costs the engineer no
130
110
  - A check you couldn't run is reported as SKIPPED with the reason, never silently omitted
131
111
  - **Every acceptance criterion gets its own row, on a clean run too**: the criterion, pass or fail, and what shows it (a test name, a command's output, `file:line`). A criterion whose evidence you can only state as "implemented" is not evidenced, report it UNVERIFIED. `[human-check]` items are rows too, marked AWAITING HUMAN, never judged. An aggregate "acceptance criteria met" is the last claim in this report with nothing behind it, and it is the one the human acts on: the commands are already itemized, the findings already carry `file:line`, and the criteria, the thing the spec was actually written to get, ride as a summary word.
132
112
 
133
- | Rationalization | Rebuttal |
134
- |---|---|
135
- | "The code obviously passes, no need to run tests" | Run them. "Obviously" is how false PASSes ship. |
136
- | "This file looks fine from its name/structure" | Grep it. Placeholders live inside plausible-looking files. |
137
- | "Too many files to check them all" | Then say which subset you checked. Don't report full coverage. |
138
-
139
113
  ## Need-fit check (fresh frame, after both lenses)
140
114
 
141
115
  One question neither lens asks: does the delivered logic actually serve the real need end to end, even though tests pass and the acceptance criteria are checked off? Read the spec's Goal section fresh, as if you hadn't just read the implementation, and ask whether a user acting on that goal would get what they came for. This catches the gap where every checkbox is honestly true and the feature still misses the point (the criteria were satisfied by an interpretation the goal didn't intend).
@@ -12,12 +12,11 @@
12
12
  // every other adapter, the payload
13
13
  // field names are typed rather than guessed: `edit` is
14
14
  // `{path, edits: [{oldText, newText}]}` and `write` is `{path, content}`.
15
- // - Definition-of-Done + handoff: no blocking turn-end event exists
16
- // (`turn_end` / `agent_end` / `agent_settled` all return void), so these
17
- // gates enforce at the close protocol's own chokepoints instead: a
15
+ // - Definition-of-Done: no blocking turn-end event exists
16
+ // (`turn_end` / `agent_end` / `agent_settled` all return void), so this
17
+ // gate enforces at the close protocol's own chokepoint instead: a
18
18
  // `tool_call` hard block denies `ops-log.sh <spec> closed` while the spec
19
- // lacks its verification report, and denies phase transitions that fail
20
- // check-handoff.sh. On top of that, `turn_end` carries `message` directly
19
+ // lacks its verification report. On top of that, `turn_end` carries `message` directly
21
20
  // and `pi.sendUserMessage()` injects a follow-up correction for a false
22
21
  // DONE claim, as a backstop with a progress-aware budget.
23
22
  //
@@ -193,7 +192,7 @@ function textOf(message) {
193
192
  // may change, derived from its files on every call.
194
193
  const ACTIVE_SPEC_ENTRY = "devos-active-spec";
195
194
  const IMPLEMENT_DIR = path.join(DEVOS_ROOT, "plugins/devos/skills/implement");
196
- const SPEC_FILE_RE = /^(.*\/devos\/specs\/(?!archive\/)[^/]+)\/(?:spec-functional|spec)\.md$/;
195
+ const SPEC_FILE_RE = /^(.*\/devos\/specs\/(?!archive\/)[^/]+)\/spec\.md$/;
197
196
  const OPS_EVENT_RE = /ops-log\.sh\s+("[^"]+"|\S+)\s+(started|plan-approved|implemented|verified|closed)(?:\s|"|'|$)/;
198
197
  const BASH_MUTATION_RE =
199
198
  /\bsed\b[^|;&]*\s-(?:[a-zA-Z]*i\b|-in-place)|\bperl\b[^|;&]*\s-[a-zA-Z]*i|\bgit\s+(?:apply|commit|am)\b/;
@@ -242,11 +241,11 @@ const PHASES = {
242
241
  const ROUTE_ENTRY = "devos-route";
243
242
  const BUILD_REFS = path.join(DEVOS_ROOT, "plugins/devos/skills/build/references");
244
243
  const SPEC_ROUTE_NEXT =
245
- "Create devos/specs/YYYY-MM-DD-<name>/spec-functional.md now, as " +
244
+ "Create devos/specs/YYYY-MM-DD-<name>/spec.md now, as " +
246
245
  `${BUILD_REFS}/routes.md says for this size. Project files stay blocked until its plan is approved.`;
247
246
  const FRAME_NEXT =
248
247
  `Read ${path.join(DEVOS_ROOT, "plugins/devos/skills/frame")}/SKILL.md whole. A frame changes no production code: ` +
249
- "it ends with devos/frames/<name>/tickets.md and one re-route per ticket.";
248
+ "it ends with devos/frames/<name>/frame.md and one re-route per ticket.";
250
249
  const ROUTES = {
251
250
  F: { blocksCode: true, next: FRAME_NEXT },
252
251
  S: { blocksCode: false, next: "Say the change in one plain sentence, make it, run the checks that cover it." },
@@ -268,12 +267,18 @@ export function specPhase(specDir) {
268
267
  }
269
268
  // A spike folder holds findings.md only, so it is a finished spike, not a spec without a plan.
270
269
  if (!has("spec.md") && has("findings.md")) return "spike";
271
- if (!has("spec.md")) return "plan-missing";
270
+ if (!hasPlan(specDir)) return "plan-missing";
272
271
  const ops = has("ops.jsonl") ? fs.readFileSync(path.join(specDir, "ops.jsonl"), "utf8") : "";
273
272
  if (!ops.includes('"event":"plan-approved"')) return "awaiting-approval";
274
273
  return has("verifications/verification.md") ? "close-pending" : "verify-pending";
275
274
  }
276
275
 
276
+ function hasPlan(specDir) {
277
+ const plan = path.join(specDir, "spec.md");
278
+ if (!fs.existsSync(plan)) return false;
279
+ return /^## Implementation Plan/m.test(fs.readFileSync(plan, "utf8"));
280
+ }
281
+
277
282
  function projectRootOf(specDir) {
278
283
  return path.dirname(path.dirname(path.dirname(specDir)));
279
284
  }
@@ -469,7 +474,7 @@ export default function devosExtension(pi) {
469
474
  const opsSpec = opsEvent ? path.resolve(ctx?.cwd || ".", opsEvent[1].replace(/^"|"$/g, "")) : null;
470
475
  if (opsEvent?.[2] === "started") setActiveSpec(opsSpec);
471
476
  if (opsEvent?.[2] === "plan-approved") {
472
- if (!fs.existsSync(path.join(opsSpec, "spec.md"))) {
477
+ if (!hasPlan(opsSpec)) {
473
478
  return { block: true, reason: planGateReason(opsSpec, "plan-missing", "Logging plan-approved") };
474
479
  }
475
480
  const planAt = fs.statSync(path.join(opsSpec, "spec.md")).mtimeMs;
@@ -506,7 +511,7 @@ export default function devosExtension(pi) {
506
511
  }
507
512
 
508
513
  if (event.toolName === "bash" && input.command) {
509
- // Phase-transition chokepoints carry DoD and handoff as HARD BLOCKS.
514
+ // Phase-transition chokepoints carry DoD as a HARD BLOCK.
510
515
  // turn_end cannot veto (header), but closing or advancing a spec routes
511
516
  // through these bash invocations, so denying them denies the false
512
517
  // done. Filesystem decision only: a spec with a plan may not log
@@ -531,12 +536,6 @@ export default function devosExtension(pi) {
531
536
  reason: `DoD gate: ${specArg} has no verifications/verification.md - run Phase C before closing.`,
532
537
  };
533
538
  }
534
- // Team mode records a handoff per reached phase; the same decision
535
- // the turn-end gate corrects, enforced here at the transition itself.
536
- const handoff = runGate("check-handoff.sh", [ctx?.cwd || "."]);
537
- if (handoff.code === 2) {
538
- return { block: true, reason: `handoff gate: ${handoff.stderr}` };
539
- }
540
539
  }
541
540
  }
542
541
 
@@ -591,15 +590,6 @@ export default function devosExtension(pi) {
591
590
  fs.rmSync(tmp, { force: true });
592
591
  }
593
592
 
594
- // Handoff gate on the same surface and the same correction budget. It
595
- // reads members.md and the active spec, so it needs no transcript. DoD
596
- // first: a missing verification report is also what a verification-phase
597
- // handoff would be blocked on.
598
- if (!reason) {
599
- const handoff = runGate("check-handoff.sh", [ctx?.cwd || "."]);
600
- if (handoff.code === 2) reason = `handoff gate: ${handoff.stderr}`;
601
- }
602
-
603
593
  if (reason) {
604
594
  const stateHash = repoState(ctx?.cwd);
605
595
  if (!lastStateHash || stateHash !== lastStateHash) stalled = 0;
@@ -126,7 +126,13 @@ out=$(python3 "$ROUTER" --root "$tmp/empty" --task 'anything at all' --files src
126
126
  check "empty: exits 0" 0 $?
127
127
  has "empty: reports zero candidates" "kept 0 of 0 candidates" "$out"
128
128
 
129
- # --- 7. a missing task is a usage error ----------------------------------
129
+ # --- 7. --terms adds vocabulary the task does not carry -------------------
130
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --files src/x.ts)
131
+ hasnt "terms: without terms the Commits block is dropped" "## Commits" "$out"
132
+ out=$(python3 "$ROUTER" --root "$proj" --task 'how should tests be named' --terms 'conventional commit' --files src/x.ts)
133
+ has "terms: the extra terms bring the Commits block back" "## Commits" "$out"
134
+
135
+ # --- 8. a missing task is a usage error ----------------------------------
130
136
  python3 "$ROUTER" --root "$proj" --files src/x.ts >/dev/null 2>&1
131
137
  check "usage: --task is required" 2 $?
132
138
 
@@ -4,7 +4,7 @@
4
4
  Given a task and the files it touches, index the project's declared evidence
5
5
  (devos/standards/conventions.md sections, devos/standards/rules/*.md,
6
6
  devos/product/behaviors/*.md, devos/product/domain-model.md sections, and a spec
7
- folder's spec-functional.md / spec.md sections), select the smallest set worth
7
+ folder's spec.md sections), select the smallest set worth
8
8
  loading, and print it quoted with file:line ranges.
9
9
 
10
10
  Selection is deterministic: a rules file whose `globs:` matches a touched file is
@@ -159,7 +159,7 @@ def collect(root: Path, spec: Path | None) -> list[Candidate]:
159
159
  for p in sorted(behaviors.glob("*.md")):
160
160
  cands.append(whole_file(p, p.relative_to(root).as_posix(), root))
161
161
  if spec:
162
- for name in ("spec-functional.md", "spec.md"):
162
+ for name in ("spec.md",):
163
163
  p = spec / name
164
164
  if p.is_file():
165
165
  cands += sectionize(p, p.relative_to(root).as_posix() if p.is_relative_to(root) else str(p))
@@ -206,6 +206,7 @@ def main() -> int:
206
206
  ap.add_argument("--task")
207
207
  ap.add_argument("--task-file")
208
208
  ap.add_argument("--files", default="")
209
+ ap.add_argument("--terms", default="", help="extra query terms, e.g. the identifiers a diff adds")
209
210
  ap.add_argument("--spec")
210
211
  ap.add_argument("--root", default=".")
211
212
  ap.add_argument("--keep", type=int, default=6, help="blocks to keep, clamped to 3-8")
@@ -228,13 +229,14 @@ def main() -> int:
228
229
  keep = max(3, min(8, args.keep))
229
230
 
230
231
  cands = collect(root, spec)
231
- qtokens = tokens(task) | {t for f in files for t in tokens(f.replace("/", " ").replace(".", " ").replace("-", " ").replace("_", " "))}
232
+ qtokens = tokens(task) | tokens(args.terms) | {t for f in files for t in tokens(f.replace("/", " ").replace(".", " ").replace("-", " ").replace("_", " "))}
232
233
  kept = select_lexical(cands, qtokens, files, keep)
233
234
 
234
235
  if args.format == "json":
235
236
  print(json.dumps({
236
237
  "task": task.strip()[:200],
237
238
  "files": files,
239
+ "terms": args.terms.strip()[:400],
238
240
  "keep": keep,
239
241
  "candidates": len(cands),
240
242
  "kept": [{
@@ -208,8 +208,9 @@ fi
208
208
  # Silent when no Behavior delta section exists at all: pre-v0.4.0 specs,
209
209
  # M-route inline specs, and a delta with nothing changed are all legitimate
210
210
  #.
211
- sf="$spec/spec-functional.md"
212
- if [[ -f "$sf" ]] && grep -qiE '^#+ .*behavior delta' "$sf"; then
211
+ sf=$(mktemp)
212
+ bash "$(dirname "${BASH_SOURCE[0]}")/spec-contract.sh" "$spec" >"$sf" 2>/dev/null
213
+ if grep -qiE '^#+ .*behavior delta' "$sf"; then
213
214
  spec_name="$(basename "$spec")"
214
215
  while IFS= read -r line; do
215
216
  marker=$(printf '%s' "$line" | grep -oE '\*\*(Added|Modified|Removed)\*\*')
@@ -231,6 +232,7 @@ if [[ -f "$sf" ]] && grep -qiE '^#+ .*behavior delta' "$sf"; then
231
232
  fi
232
233
  done < <(grep -E '\*\*(Added|Modified|Removed)\*\*.*capability:' "$sf")
233
234
  fi
235
+ rm -f "$sf"
234
236
 
235
237
  # Every `path:line` the report cites is re-derived from the tree. A finding's
236
238
  # position is the part of it a candidate can get right in prose and wrong in
@@ -249,7 +251,7 @@ fi
249
251
 
250
252
  # The other half of the same reflection: the citation pass catches a row that
251
253
  # points nowhere, this catches the row that was never written. The verifier is
252
- # told to record every SC-n from spec-functional.md, and an omitted scenario is
254
+ # told to record every SC-n from the spec's Scenarios, and an omitted scenario is
253
255
  # invisible exactly where the report reads cleanest. A missing or broken script
254
256
  # fails open, a missing ID blocks, the same contract as the pass above.
255
257
  cov_out=$(bash "$(dirname "${BASH_SOURCE[0]}")/check-scenario-coverage.sh" "$spec" 2>&1)
@@ -102,7 +102,7 @@ fi
102
102
  # port reads, and the spec file is what the port answers to, so whichever
103
103
  # landed first is the state the port started from.
104
104
  base=""
105
- for rel in "manifest.tsv" "spec-functional.md" "spec.md"; do
105
+ for rel in "manifest.tsv" "spec.md"; do
106
106
  p="$spec_rel/$rel"
107
107
  [[ -f "$ROOT/$p" ]] || continue
108
108
  c=$(git -C "$ROOT" log --format=%H --diff-filter=A --follow -- "$p" 2>/dev/null | tail -1)
@@ -3,14 +3,14 @@
3
3
  # recorded in the verification report.
4
4
  # Deterministic, zero model calls.
5
5
  #
6
- # The verifier is told to read the `SC-n` IDs from spec-functional.md and record
6
+ # The verifier is told to read the `SC-n` IDs from spec.md and record
7
7
  # each one in verifications/verification.md, and until this script nothing
8
8
  # checked that it did. An omission is the one failure a clean-looking report
9
9
  # cannot show: every row it carries resolves, the verdict reads CLEAN + PASS,
10
10
  # and the scenario nobody executed leaves no trace. This is the omission twin of
11
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.
12
+ # IDs are checked one hop earlier by validate-spec.sh, the contract to
13
+ # the plan; this is the hop from the spec to the report.
14
14
  #
15
15
  # Presence, not format: a report may record an ID in the criteria table, in a
16
16
  # scenario mapping line, or beside the test that proves it. Pinning one layout
@@ -47,11 +47,13 @@ if [[ ! -f "$report" ]]; then
47
47
  exit 2
48
48
  fi
49
49
 
50
- sf="$spec/spec-functional.md"
51
- if [[ ! -f "$sf" ]]; then
50
+ sf=$(mktemp)
51
+ trap 'rm -f "$sf"' EXIT
52
+ if ! bash "$(dirname "${BASH_SOURCE[0]}")/spec-contract.sh" "$spec" >"$sf"; then
52
53
  echo "PASS check-scenario-coverage: $spec declares no functional spec"
53
54
  exit 0
54
55
  fi
56
+ sfname=spec.md
55
57
 
56
58
  # A C-route spec says what must not change, so it declares no scenarios and has
57
59
  # no IDs to trace. Same heading normalization and exact match as validate-spec.sh,
@@ -68,7 +70,7 @@ fi
68
70
 
69
71
  declared=$(grep -E 'Scenario SC-[0-9]+:' "$sf" | grep -oE 'SC-[0-9]+' | sort -u)
70
72
  if [[ -z "$declared" ]]; then
71
- echo "PASS check-scenario-coverage: $sf declares no numbered scenarios"
73
+ echo "PASS check-scenario-coverage: $spec/$sfname declares no numbered scenarios"
72
74
  exit 0
73
75
  fi
74
76
  recorded=$(grep -oE 'SC-[0-9]+' "$report" | sort -u)
@@ -92,11 +94,11 @@ if [[ -n "$missing" ]]; then
92
94
  fail=1
93
95
  fi
94
96
  if [[ -n "$extra" ]]; then
95
- echo "FAIL check-scenario-coverage: $report cites ${extra% }, which $sf never declares"
97
+ echo "FAIL check-scenario-coverage: $report cites ${extra% }, which $spec/$sfname never declares"
96
98
  echo " fix: cite the IDs the functional spec declares, or drop the stale row and re-run the verifier if the spec changed"
97
99
  fail=1
98
100
  fi
99
101
  if ((fail == 0)); then
100
- echo "PASS check-scenario-coverage: $report records every scenario $sf declares"
102
+ echo "PASS check-scenario-coverage: $report records every scenario $spec/$sfname declares"
101
103
  fi
102
104
  exit $fail
@@ -25,10 +25,10 @@ IMPLEMENT="$SKILLS/implement"
25
25
  BUILD_REFS="$SKILLS/build/references"
26
26
  ROUTE_CMD="bash $SKILLS/build/scripts/route.sh <F|S|M|L|R|B|C|H> \"<the evidence from the code>\""
27
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."
28
+ FRAME_NEXT="Read $SKILLS/frame/SKILL.md whole. A frame changes no production code: it ends with devos/frames/<name>/frame.md and one re-route per ticket."
29
29
 
30
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."
31
+ local spec_next="Create devos/specs/YYYY-MM-DD-<name>/spec.md now, as $BUILD_REFS/routes.md says for this size. Project files stay blocked until its plan is approved."
32
32
  case "$1" in
33
33
  S) echo "Say the change in one plain sentence, make it, run the checks that cover it." ;;
34
34
  M|L) echo "$spec_next" ;;
@@ -112,7 +112,7 @@ phase_of() { # phase_of <spec dir>
112
112
  local d="$1"
113
113
  if [[ ! -d "$d" ]]; then
114
114
  [[ -d "$(dirname "$d")/archive/$(basename "$d")" ]] && echo archived || echo missing
115
- elif [[ ! -f "$d/spec.md" ]]; then echo plan-missing
115
+ elif ! bash "$GATES/spec-contract.sh" --has-plan "$d"; then echo plan-missing
116
116
  elif ! grep -q '"event":"plan-approved"' "$d/ops.jsonl" 2>/dev/null; then echo awaiting-approval
117
117
  else echo approved
118
118
  fi
@@ -144,7 +144,7 @@ case "$tool" in
144
144
  esac
145
145
 
146
146
  for t in ${targets[@]+"${targets[@]}"}; do
147
- if [[ "$t" =~ ^(.*/devos/specs/[^/]+)/(spec-functional|spec)\.md$ && "$t" != */devos/specs/archive/* ]]; then
147
+ if [[ "$t" =~ ^(.*/devos/specs/[^/]+)/spec\.md$ && "$t" != */devos/specs/archive/* ]]; then
148
148
  set_spec "${BASH_REMATCH[1]}"
149
149
  fi
150
150
  done
@@ -152,8 +152,8 @@ done
152
152
  if [[ "$command" =~ ops-log\.sh[[:space:]]+(\"[^\"]+\"|[^[:space:]]+)[[:space:]]+(started|plan-approved) ]]; then
153
153
  ops_spec=$(abs "${BASH_REMATCH[1]//\"/}")
154
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)"
155
+ bash "$GATES/spec-contract.sh" --has-plan "$ops_spec" ||
156
+ deny "DevOS plan gate: logging plan-approved is blocked, $ops_spec has no Implementation Plan in spec.md. $(next_for plan-missing)"
157
157
  if [[ "${DEVOS_HEADLESS:-}" != 1 && "$(get human || echo 0)" -le "$(mtime "$ops_spec/spec.md")" ]]; then
158
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
159
  fi
@@ -27,7 +27,7 @@ VALIDATE = SKILLS / "implement/scripts/validate-spec.sh"
27
27
  # guidance) into a value the gates accept. Applied to the block as one string
28
28
  # with re.M, so a replacement may span the heading and the line under it.
29
29
  FILL = [
30
- (r"^## Goal / Technical Context.*$", "## Goal\n\nA thing changes."),
30
+ (r"^## Technical Requirements\n\[.*\]$", "## Technical Requirements\n\nA thing changes."),
31
31
  (r"^## Local Craft\n\[.*\]$", "## Local Craft\n\nNone"),
32
32
  (r"^### Stack facts\n\[.*\]$", "### Stack facts\n\nnode 22"),
33
33
  (r"^- \*\*Direct MVP\*\*: .*$", "- **Direct MVP**: one file"),
@@ -44,7 +44,6 @@ FILL = [
44
44
  (r"^\*\*Complexity:\*\* .*$", "**Complexity:** Simple"),
45
45
  (r"^- \*\*Always\*\* \(in scope\): .*$", "- **Always** (in scope): the change"),
46
46
  (r"^- \*\*Ask First\*\* .*$", "- **Ask First** (none)"),
47
- (r"^- \*\*Never\*\* \(out of scope\): .*$", "- **Never** (out of scope): adjacent work"),
48
47
  (r"^## Implementation Notes\n\[.*\]$", "## Implementation Notes\n\n- none"),
49
48
  (r"^## Change Log\n\[.*\]$", "## Change Log\n\n- none"),
50
49
  ]
@@ -62,9 +61,7 @@ DROP = re.compile(r"^\[[^\]]*\]$", re.M)
62
61
  # renames a heading validate-spec.sh looks up, fails here instead of quietly
63
62
  # producing a specimen the gates never had to judge.
64
63
  REQUIRED = [
65
- "devos-contract: 1",
66
- "## Goal",
67
- "Technical Requirements", # validate-spec.sh matches this as a substring
64
+ "## Technical Requirements", # validate-spec.sh matches this as a substring
68
65
  "## Local Craft",
69
66
  "### Stack facts",
70
67
  "## Design Convergence",
@@ -75,7 +72,6 @@ REQUIRED = [
75
72
  "## Boundaries",
76
73
  "**Always**",
77
74
  "**Ask First**",
78
- "**Never**",
79
75
  "## Code Map",
80
76
  "## Implementation Plan",
81
77
  "### Overview",
@@ -121,12 +117,10 @@ def main():
121
117
  with tempfile.TemporaryDirectory() as tmp:
122
118
  d = Path(tmp) / "spec"
123
119
  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")
120
+ contract = (
121
+ "---\ndevos-contract: 1\n---\n\n# F\n\n## Goal\n\nx\n\n## Scenarios\n\n"
122
+ "- Scenario SC-1: a / WHEN x / THEN y\n\n## Out of scope\n\n- none\n\n")
123
+ (d / "spec.md").write_text(contract + spec)
130
124
  failures = []
131
125
  for name, script, target in (("validate-spec", VALIDATE, d),):
132
126
  r = subprocess.run(["bash", str(script), str(target)],
@@ -0,0 +1,19 @@
1
+ #!/bin/bash
2
+ # spec-contract.sh <spec-dir>: print the contract sections of spec.md (Goal,
3
+ # Scenarios, Functionality, Behavior delta, Invariant, Functional constraints,
4
+ # Out of scope) plus any Requires: line. Exit 1 with no output when spec.md is missing.
5
+ # spec-contract.sh --has-plan <spec-dir>: exit 0 when spec.md carries an Implementation Plan.
6
+ if [[ "${1:-}" == "--has-plan" ]]; then
7
+ grep -q '^## Implementation Plan' "${2:-}/spec.md" 2>/dev/null
8
+ exit
9
+ fi
10
+ dir="${1:-}"
11
+ [[ -f "$dir/spec.md" ]] || exit 1
12
+ awk '
13
+ /^## / {
14
+ h = tolower($0); sub(/^##[ \t]*/, "", h); sub(/^[0-9]+[.)]?[ \t]*/, "", h)
15
+ keep = (h ~ /^(goal|scenarios|functionality|behavior delta|invariant|functional constraints|out of scope)/)
16
+ }
17
+ /^Requires:/ { print; next }
18
+ keep { print }
19
+ ' "$dir/spec.md"