specrails-core 4.12.0 → 5.0.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 (76) hide show
  1. package/README.md +49 -78
  2. package/bin/specrails-core.mjs +18 -98
  3. package/bin/tui-installer.mjs +22 -105
  4. package/commands/doctor.md +1 -1
  5. package/dist/installer/cli.js +12 -2
  6. package/dist/installer/cli.js.map +1 -1
  7. package/dist/installer/commands/doctor.js +3 -5
  8. package/dist/installer/commands/doctor.js.map +1 -1
  9. package/dist/installer/commands/init.js +23 -19
  10. package/dist/installer/commands/init.js.map +1 -1
  11. package/dist/installer/commands/update.js +17 -16
  12. package/dist/installer/commands/update.js.map +1 -1
  13. package/dist/installer/commands/v5-migration.js +119 -0
  14. package/dist/installer/commands/v5-migration.js.map +1 -0
  15. package/dist/installer/phases/install-config.js +3 -6
  16. package/dist/installer/phases/install-config.js.map +1 -1
  17. package/dist/installer/phases/manifest.js +2 -6
  18. package/dist/installer/phases/manifest.js.map +1 -1
  19. package/dist/installer/phases/prereqs.js +0 -1
  20. package/dist/installer/phases/prereqs.js.map +1 -1
  21. package/dist/installer/phases/scaffold.js +38 -148
  22. package/dist/installer/phases/scaffold.js.map +1 -1
  23. package/package.json +1 -1
  24. package/schemas/profile.v1.json +1 -1
  25. package/templates/agents/sr-architect.md +30 -0
  26. package/templates/agents/sr-developer.md +21 -8
  27. package/templates/agents/sr-reviewer.md +44 -31
  28. package/templates/codex-skills/batch-implement/SKILL.md +9 -32
  29. package/templates/codex-skills/implement/SKILL.md +61 -143
  30. package/templates/codex-skills/rails/sr-architect/SKILL.md +38 -20
  31. package/templates/codex-skills/rails/sr-developer/SKILL.md +29 -10
  32. package/templates/codex-skills/rails/sr-reviewer/SKILL.md +21 -10
  33. package/templates/commands/specrails/doctor.md +1 -1
  34. package/templates/commands/specrails/implement.md +117 -288
  35. package/templates/commands/specrails/memory-inspect.md +6 -4
  36. package/templates/commands/specrails/propose-spec.md +1 -1
  37. package/templates/commands/specrails/refactor-recommender.md +8 -51
  38. package/templates/commands/specrails/retry.md +12 -48
  39. package/templates/commands/specrails/telemetry.md +1 -1
  40. package/templates/gemini-commands/implement.toml +9 -0
  41. package/templates/profiles/default.json +5 -18
  42. package/commands/enrich.md +0 -1456
  43. package/templates/agents/sr-backend-developer.md +0 -91
  44. package/templates/agents/sr-backend-reviewer.md +0 -152
  45. package/templates/agents/sr-doc-sync.md +0 -247
  46. package/templates/agents/sr-frontend-developer.md +0 -85
  47. package/templates/agents/sr-frontend-reviewer.md +0 -145
  48. package/templates/agents/sr-merge-resolver.md +0 -195
  49. package/templates/agents/sr-performance-reviewer.md +0 -186
  50. package/templates/agents/sr-product-analyst.md +0 -36
  51. package/templates/agents/sr-product-manager.md +0 -148
  52. package/templates/agents/sr-security-reviewer.md +0 -191
  53. package/templates/agents/sr-test-writer.md +0 -176
  54. package/templates/codex-skills/enrich/SKILL.md +0 -191
  55. package/templates/codex-skills/merge-resolve/SKILL.md +0 -88
  56. package/templates/codex-skills/rails/sr-backend-developer/SKILL.md +0 -93
  57. package/templates/codex-skills/rails/sr-backend-reviewer/SKILL.md +0 -120
  58. package/templates/codex-skills/rails/sr-doc-sync/SKILL.md +0 -124
  59. package/templates/codex-skills/rails/sr-frontend-developer/SKILL.md +0 -106
  60. package/templates/codex-skills/rails/sr-frontend-reviewer/SKILL.md +0 -111
  61. package/templates/codex-skills/rails/sr-merge-resolver/SKILL.md +0 -156
  62. package/templates/codex-skills/rails/sr-performance-reviewer/SKILL.md +0 -109
  63. package/templates/codex-skills/rails/sr-product-analyst/SKILL.md +0 -85
  64. package/templates/codex-skills/rails/sr-product-manager/SKILL.md +0 -131
  65. package/templates/codex-skills/rails/sr-security-reviewer/SKILL.md +0 -121
  66. package/templates/codex-skills/rails/sr-test-writer/SKILL.md +0 -115
  67. package/templates/commands/specrails/auto-propose-backlog-specs.md +0 -312
  68. package/templates/commands/specrails/enrich.md +0 -1456
  69. package/templates/commands/specrails/get-backlog-specs.md +0 -226
  70. package/templates/commands/specrails/merge-resolve.md +0 -172
  71. package/templates/commands/specrails/reconfig.md +0 -80
  72. package/templates/commands/specrails/vpc-drift.md +0 -405
  73. package/templates/commands/test.md +0 -58
  74. package/templates/personas/persona.md +0 -43
  75. package/templates/personas/the-maintainer.md +0 -98
  76. package/templates/settings/perf-thresholds.yml +0 -25
@@ -86,60 +86,37 @@ the pipeline yourself):
86
86
  > Read `jq '.tickets["<TICKET_ID>"]' .specrails/local-tickets.json`
87
87
  > for the full ticket. Follow the `$sr-architect` skill
88
88
  > instructions exactly.
89
- >
90
- > In `design.md`'s `## Context` section, include a
91
- > `Scope: <labels>` line drawn from: `frontend`, `backend`,
92
- > `both`, `security-sensitive`, `performance-sensitive`.
93
89
 
94
90
  - `wait_agent`. Parse reply for the plan path. `close_agent`.
95
- - Open the plan + design.md, parse the `Scope:` line.
91
+ - Open the plan + design.md.
96
92
  - If the architect returned `BLOCKED: …`, mark this ticket
97
93
  as failed for the batch report and **continue to the next
98
94
  ticket** — do not stop the batch.
99
95
 
100
96
  #### 1.b Developer phase (per ticket)
101
97
 
102
- Routing matrix (mirrors `$implement`):
103
-
104
- | scope contains | rails available | spawn |
105
- |---|---|---|
106
- | `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
107
- | `backend` only | `sr-backend-developer` | $sr-backend-developer |
108
- | `frontend` only | (no fe specialist) | $sr-developer |
109
- | `backend` only | (no be specialist) | $sr-developer |
110
- | `both` + both specialists + tagged tasks.md | — | TWO devs parallel |
111
- | else | — | $sr-developer |
98
+ One developer rail. Unless a profile routes the ticket to a
99
+ listed `custom-*` developer, spawn `$sr-developer`.
112
100
 
113
101
  - `spawn_agent`. `send_message`:
114
102
 
115
- > `$<developer-skill>`
103
+ > `$sr-developer`
116
104
  >
117
105
  > Ticket id: `<TICKET_ID>`
118
106
  > Plan: `<PLAN_PATH>`
119
- > Scope: `<comma-separated labels>`
120
107
  >
121
- > Follow the `$<developer-skill>` skill instructions exactly.
108
+ > Follow the `$sr-developer` skill instructions exactly.
122
109
 
123
110
  - `wait_agent`. Capture file list. `close_agent`.
124
111
  - If `BLOCKED: …` → mark ticket as failed in the batch report
125
112
  and move to next ticket.
126
113
 
127
- #### 1.c Reviewer phase (per ticket) — parallel where possible
128
-
129
- Always spawn `$sr-reviewer`. Additionally if installed AND
130
- scope matches:
131
-
132
- | scope flag | additional rail |
133
- |---|---|
134
- | `frontend` | `$sr-frontend-reviewer` |
135
- | `backend` | `$sr-backend-reviewer` |
136
- | `security-sensitive` | `$sr-security-reviewer` |
137
- | `performance-sensitive` | `$sr-performance-reviewer` |
114
+ #### 1.c Reviewer phase (per ticket)
138
115
 
139
- Spawn ALL reviewers in parallel, then `wait_agent` on each.
140
- `close_agent` each.
116
+ Spawn the single `$sr-reviewer` it covers correctness, tests,
117
+ security, and performance. `wait_agent`, then `close_agent`.
141
118
 
142
- Aggregate verdicts (same matrix as `$implement`):
119
+ Verdict (same matrix as `$implement`):
143
120
 
144
121
  - `clean` — every reviewer ≥70, no fix/blocked verdicts.
145
122
  - `fix needed` — any "fix needed", OR score <70 with no
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: implement
3
- description: "Implement a single backlog ticket through a multi-phase pipeline: architect plans (OpenSpec proposal+design+tasks+specs), one or more developers code in TDD order, one or more reviewers validate in parallel. Routing is dynamic the orchestrator inspects which rail skills are installed in .codex/skills/rails/ and spawns the specialists that apply to the change's scope. Reads .specrails/local-tickets.json, closes the ticket in place, reports concisely. Use when the user invokes `$implement #N` or `$implement <free-form>`."
3
+ description: "Implement a single backlog ticket through a multi-phase pipeline: architect plans (OpenSpec proposal+design+tasks+specs), sr-developer codes in TDD order, sr-reviewer validates (correctness, tests, security, performance). A profile may add custom-* rails. Reads .specrails/local-tickets.json, closes the ticket in place, reports concisely. Use when the user invokes `$implement #N` or `$implement <free-form>`."
4
4
  license: MIT
5
5
  compatibility: "Codex-native. Uses spawn_agent / send_message / wait_agent (full-history forks, no agent_type / model / reasoning_effort). Per-role instructions live in the rail skills; this orchestrator only routes."
6
6
  ---
@@ -40,7 +40,7 @@ move on.
40
40
 
41
41
  **A `clean` run is NOT finished until the change is archived.**
42
42
  Archiving (`openspec archive`) is a hard obligation, not an
43
- optional epilogue — see Phase 5. If you mark a ticket `done`
43
+ optional epilogue — see Phase 4. If you mark a ticket `done`
44
44
  without an archived change under `openspec/changes/archive/`,
45
45
  you violated this contract.
46
46
 
@@ -71,27 +71,14 @@ and gives you a single aggregated report.
71
71
 
72
72
  ├─► PHASE 1: $sr-architect
73
73
  │ produces openspec/changes/<slug>/{proposal,design,tasks,specs}
74
- │ + a "Scope" tag in design.md
75
74
 
76
- ├─► PHASE 2: developer(s) — routing depends on scope
77
- scope=frontend $sr-frontend-developer (if installed)
78
- │ scope=backend → $sr-backend-developer (if installed)
79
- │ scope=both → spawn BOTH in parallel (tasks.md must be
80
- │ partitioned), OR fall back to $sr-developer
81
- │ else → $sr-developer
75
+ ├─► PHASE 2: $sr-developer
76
+ implements every task (tests + docs included per task)
82
77
 
83
- ├─► PHASE 3: reviewer(s) — parallel where installed
84
- always: $sr-reviewer (baseline)
85
- │ frontend changes: $sr-frontend-reviewer (if installed)
86
- │ backend changes: $sr-backend-reviewer (if installed)
87
- │ security-sensitive: $sr-security-reviewer (if installed)
88
- │ perf-sensitive: $sr-performance-reviewer (if installed)
78
+ ├─► PHASE 3: $sr-reviewer
79
+ single reviewer — correctness, TDD/spec, security, performance
89
80
 
90
- ├─► PHASE 4 (optional): post-review augmentation
91
- │ coverage dropped + $sr-test-writer installed → spawn
92
- │ public surface changed + $sr-doc-sync installed → spawn
93
-
94
- └─► PHASE 5: close ticket + report
81
+ └─► PHASE 4: close ticket + report
95
82
  ```
96
83
 
97
84
  All spawns are **full-history forks**. NEVER pass `agent_type`,
@@ -109,14 +96,12 @@ the combo and you'll burn a turn on the retry.
109
96
  `jq '.tickets["<ID>"]' .specrails/local-tickets.json`
110
97
  3. **List the installed rail skills**:
111
98
  `ls .codex/skills/rails/`
112
- The output drives routing in phases 2-4. Skills that aren't
113
- listed are not installed never spawn them. The three core
114
- rails (`sr-architect`, `sr-developer`, `sr-reviewer`) are
115
- always present. `sr-merge-resolver` and every layer specialist
116
- are optional spawn them only when listed.
117
- 4. State (≤4 lines) the ticket goal, the stack you detected from
118
- a quick `ls`/`find`, and the optional rails that are
119
- available. Do NOT plan files-to-touch — that's the
99
+ The three core rails (`sr-architect`, `sr-developer`,
100
+ `sr-reviewer`) are always present and are the only first-party
101
+ rails. A profile may add user-owned `custom-*` rails; spawn a
102
+ `custom-*` rail only when it is listed.
103
+ 4. State (≤4 lines) the ticket goal and the stack you detected from
104
+ a quick `ls`/`find`. Do NOT plan files-to-touch that's the
120
105
  architect's job.
121
106
 
122
107
  ### 1. Phase 1 — Architect
@@ -135,161 +120,94 @@ the combo and you'll burn a turn on the retry.
135
120
  > for the full ticket. Follow the `$sr-architect` skill
136
121
  > instructions exactly.
137
122
  >
138
- > In `design.md`'s `## Context` section, include a
139
- > `Scope: <labels>` line. Labels are a comma-separated set
140
- > drawn from: `frontend`, `backend`, `both`, `security-sensitive`,
141
- > `performance-sensitive`. Pick the labels that honestly apply
142
- > to this change. The orchestrator uses these to route
143
- > subsequent phases.
144
- >
145
123
  > Reply with the one-line summary the skill specifies.
146
124
 
147
125
  - `wait_agent`. Read the reply. Extract the plan path.
148
126
  - `close_agent`. Open the plan file + design.md.
149
- - **Parse the Scope line** from design.md's Context section.
150
- Store the set of labels for use in phases 2-3. If the line is
151
- missing, default to scope = `both`.
152
127
 
153
128
  If the architect replied with `BLOCKED: …`, stop the pipeline,
154
129
  write that reason into the final report, and exit without
155
130
  updating the ticket.
156
131
 
157
- ### 2. Phase 2 — Developer(s)
158
-
159
- Routing matrix (`available_rails` is the set from step 0.3,
160
- `scope` is the parsed set from step 1):
161
-
162
- | scope contains | available_rails has | spawn |
163
- |---|---|---|
164
- | `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
165
- | `backend` only | `sr-backend-developer` | $sr-backend-developer |
166
- | `frontend` only | (no fe specialist) | $sr-developer (general) |
167
- | `backend` only | (no be specialist) | $sr-developer (general) |
168
- | `both` | both specialists installed | TWO devs in parallel (see below) |
169
- | `both` | only one or neither specialist | $sr-developer (general) |
170
- | neither/unknown | — | $sr-developer (general) |
132
+ **Design confidence gate.** Read
133
+ `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design-confidence.json`
134
+ (the architect writes it as part of its skill). File missing →
135
+ warn and proceed (backward compatible). `high`/`medium`
136
+ proceed. `low` → **STOP before Phase 2** — implementation is the
137
+ expensive phase and must not run on an unconfident design.
138
+ Report:
171
139
 
172
- **Parallel developer case** (`scope = both` AND both specialists
173
- installed AND `tasks.md` has tasks tagged `[frontend]` /
174
- `[backend]`):
140
+ > `BLOCKED: design confidence low <blocking_question>`
141
+ >
142
+ > Answer the question (edit the ticket description), then re-run
143
+ > `$implement #N`. The OpenSpec artifacts are left in place as a
144
+ > resumable starting point.
175
145
 
176
- - spawn TWO `spawn_agent`s, anonymously named e.g.
177
- `developer-fe-#<TICKET_ID>` and `developer-be-#<TICKET_ID>`.
178
- - `send_message` to the frontend agent: `$sr-frontend-developer
179
- ... only run task blocks tagged [frontend] in tasks.md`.
180
- Symmetric message to the backend agent.
181
- - `wait_agent` on BOTH. Aggregate the changed-files list.
182
- - `close_agent` on both.
146
+ Do NOT update the ticket, do NOT spawn the developer.
183
147
 
184
- If the architect's `tasks.md` doesn't tag task blocks, fall back
185
- to a single `$sr-developer` invocation — the parallel split
186
- needs ordered, non-overlapping cycles.
148
+ ### 2. Phase 2 Developer
187
149
 
188
- **Sequential developer case** (default):
150
+ There is one developer rail. Unless an active profile routes the
151
+ ticket to a `custom-*` developer that is listed in step 0.3, spawn
152
+ `$sr-developer`.
189
153
 
190
154
  - `spawn_agent` (full-history).
191
155
  - `send_message`:
192
156
 
193
- > `$<developer-skill>`
157
+ > `$sr-developer`
194
158
  >
195
159
  > Ticket id: `<TICKET_ID>`
196
160
  > Plan: `<PLAN_PATH>`
197
- > Scope: `<comma-separated labels>`
198
161
  >
199
- > Follow the `$<developer-skill>` skill instructions exactly.
162
+ > Follow the `$sr-developer` skill instructions exactly.
200
163
 
201
164
  - `wait_agent`. Capture file list. `close_agent`.
202
165
 
203
166
  If the developer returned `BLOCKED: …`, surface it to the user
204
167
  in the final report (no review phase, no ticket update).
205
168
 
206
- ### 3. Phase 3 — Reviewer(s) in parallel
169
+ ### 3. Phase 3 — Reviewer
207
170
 
208
- Always spawn `$sr-reviewer`. In addition, spawn each of the
209
- following if the rail is installed AND the scope flag applies:
210
-
211
- | scope flag | rail to add (if installed) |
212
- |---|---|
213
- | `frontend` | `$sr-frontend-reviewer` |
214
- | `backend` | `$sr-backend-reviewer` |
215
- | `security-sensitive` | `$sr-security-reviewer` |
216
- | `performance-sensitive` | `$sr-performance-reviewer` |
217
-
218
- For each reviewer:
171
+ Spawn the single `$sr-reviewer`. It owns every review dimension
172
+ correctness, TDD/spec completeness, code quality, security, and
173
+ performance — scaled to what the change touches.
219
174
 
220
175
  - `spawn_agent` (full-history).
221
176
  - `send_message`:
222
177
 
223
- > `$<reviewer-skill>`
178
+ > `$sr-reviewer`
224
179
  >
225
180
  > Ticket id: `<TICKET_ID>`
226
181
  > Plan: `<PLAN_PATH>`
227
182
  > Changed files:
228
183
  > <one per line>
229
184
  >
230
- > Follow the `$<reviewer-skill>` skill instructions exactly.
231
-
232
- **Spawn all reviewers BEFORE waiting** so they run in parallel.
233
- Then `wait_agent` on each in turn. `close_agent` each as it
234
- returns.
235
-
236
- **Aggregate verdicts**:
237
-
238
- - Per reviewer: parse `Score: N/100` and `Verdict: …` from the
239
- reply.
240
- - Overall score = minimum of the reviewer scores (the harshest
241
- reviewer is the bound).
242
- - Overall verdict:
243
- - `clean` every reviewer scored 70 AND nobody said
244
- fix/blocked
245
- - `fix needed` any reviewer said `fix needed: …`, OR any
246
- score < 70 with no `blocked: …` verdict, OR any reviewer
247
- said `blocked: …` AND the overall score is **in the
248
- recoverable range 30-69**. The recoverable-blocked case is
249
- the common one where the reviewer used "blocked" because
250
- the issue is significant, not because the design itself is
251
- wrong — a single developer fix pass can usually clear it
252
- (e.g. API surface mismatch, missing JSX component shape,
253
- forgotten persistence hook).
254
- - `blocked` — any reviewer said `blocked: …` AND overall
255
- score is **< 30**, OR every reviewer said `blocked: …`.
256
- This is the design-level case where another developer
257
- pass won't help — the architect needs to re-engage.
258
-
259
- ### 4. Phase 4 — Optional augmentation
260
-
261
- Run AFTER review is `clean` (or after the single fix-loop pass).
262
- Skip when the overall verdict is `fix needed` or `blocked` — no
263
- point sugar-coating an unsound change.
264
-
265
- - If `sr-test-writer` is installed AND the reviewer's confidence
266
- artefact reports a coverage gap (`tdd_evidence.all_tasks_have_tests`
267
- is `false`, or `tdd_evidence.tests_are_non_trivial` is `false`),
268
- spawn it with the changed files list. It writes more tests, runs
269
- them, reports. (These are the fields the `$sr-reviewer` skill
270
- actually writes — do not key on a non-existent "coverage" field.)
271
- - If `sr-doc-sync` is installed AND the change touches a
272
- publicly-documented surface (README mentions a renamed
273
- function, AGENTS.md references a removed file, openspec specs
274
- drifted), spawn it.
275
-
276
- These augment, never block. If they return findings, surface in
277
- the final report under "Follow-up" rather than reopening the
278
- ticket.
279
-
280
- ### 5. Optional fix loop (single pass only)
281
-
282
- If phase 3's overall verdict is `fix needed`:
283
-
284
- - Spawn ONE follow-up developer (same routing rules as phase 2)
285
- with a message that includes every reviewer's `issues[]`
286
- array from their confidence artefacts.
185
+ > Follow the `$sr-reviewer` skill instructions exactly.
186
+
187
+ - `wait_agent`. `close_agent`.
188
+
189
+ **Verdict** — parse `Score: N/100` and `Verdict: …` from the reply:
190
+
191
+ - `clean` — score ≥ 70 AND not fix/blocked.
192
+ - `fix needed` — verdict `fix needed: …`, OR score < 70 with no
193
+ `blocked: …`, OR `blocked: …` with score **in the recoverable
194
+ range 30-69** (a single developer fix pass can usually clear it).
195
+ - `blocked` `blocked: …` with score **< 30**. Design-level; a
196
+ developer pass won't help — the architect needs to re-engage.
197
+
198
+ ### 4. Optional fix loop (single pass only)
199
+
200
+ If phase 3's verdict is `fix needed`:
201
+
202
+ - Spawn ONE follow-up developer (`$sr-developer`, or the same
203
+ `custom-*` developer used in phase 2) with a message that
204
+ includes the reviewer's `issues[]` array from its confidence
205
+ artefact.
287
206
  - `wait_agent`. `close_agent`.
288
- - Re-run phase 3 (same reviewer set). If still `fix needed` or
289
- `blocked`, **do not loop again** — surface in the final
290
- report.
207
+ - Re-run phase 3. If still `fix needed` or `blocked`, **do not loop
208
+ again** — surface in the final report.
291
209
 
292
- ### 6. Phase 5 — Archive FIRST, then close + report
210
+ ### 5. Phase 4 — Archive FIRST, then close + report
293
211
 
294
212
  > **INVARIANT.** A ticket may be marked `done` ONLY if its change is
295
213
  > archived (`openspec/changes/archive/<slug>/` exists). A `clean`
@@ -5,6 +5,12 @@ license: MIT
5
5
  compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
6
6
  ---
7
7
 
8
+ **Deterministic repo map.** If `SPECRAILS_REPO_MAP_PATH` is set
9
+ and readable, read that file FIRST — a zero-AI map of the repo
10
+ (packages, ecosystems, sizes) generated by the spawner. Use it to
11
+ orient; do not spend turns on top-level discovery. Unset ⇒ explore
12
+ as normal.
13
+
8
14
  You are the **architect** in the specrails implement pipeline. The
9
15
  orchestrator already loaded the ticket and surveyed the repo before
10
16
  spawning you. Your turn is short, focused, and ends with TWO
@@ -87,18 +93,6 @@ writing code.
87
93
  <one paragraph: the system state today, the constraints the
88
94
  change must respect, the assumptions you are making.>
89
95
 
90
- Scope: <comma-separated labels — pick honestly from:
91
- frontend, backend, both, security-sensitive,
92
- performance-sensitive>
93
- Examples:
94
- - "Scope: frontend"
95
- - "Scope: backend, security-sensitive"
96
- - "Scope: both, performance-sensitive"
97
- The implement orchestrator parses this line to route
98
- the developer + reviewer phases. A missing or wrong
99
- label means the wrong specialists get spawned (or
100
- none at all).
101
-
102
96
  ## Goal
103
97
  <one sentence: what observable behaviour you are adding /
104
98
  changing.>
@@ -155,12 +149,13 @@ the table.
155
149
 
156
150
  ## 1. <First testable behaviour>
157
151
  - [ ] 1.1 Write a failing test in `<test-path>` that asserts
158
- <behaviour>. Run the test runner; the new test MUST fail.
152
+ <behaviour>. Run that test file (scoped); the new test
153
+ MUST fail.
159
154
  - [ ] 1.2 Implement the minimum production code in `<src-path>`
160
- to make the test pass. Run the test runner; ALL tests
161
- MUST pass.
162
- - [ ] 1.3 Refactor if needed without changing behaviour. Run
163
- the test runner; all tests still pass.
155
+ to make the test pass. Re-run that test file (scoped);
156
+ it MUST pass.
157
+ - [ ] 1.3 Refactor if needed without changing behaviour. Re-run
158
+ the test files covering the touched files; still green.
164
159
 
165
160
  ## 2. <Next testable behaviour>
166
161
  - [ ] 2.1 Write a failing test...
@@ -272,13 +267,36 @@ written:
272
267
  If validation reports structural errors, fix the offending
273
268
  artefact and re-run until it passes. Do not hand off a change
274
269
  that fails `openspec validate`.
275
- 2. Reply with two lines:
270
+ 2. **Emit design confidence** (mandatory). Write
271
+ `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design-confidence.json`:
272
+ ```json
273
+ {
274
+ "schema_version": "1",
275
+ "change": "<slug>",
276
+ "agent": "architect",
277
+ "scored_at": "<ISO 8601>",
278
+ "confidence": "high | medium | low",
279
+ "reason": "<1-2 concrete sentences>",
280
+ "blocking_question": "<one focused question when low, else null>"
281
+ }
282
+ ```
283
+ Rubric — **high**: evidence conclusive, exact files/identifiers
284
+ located, design unambiguous. **medium**: likely correct but one
285
+ non-obvious assumption remains (name it in `reason`). **low**:
286
+ multiple plausible designs and you cannot choose without
287
+ information you don't have — `blocking_question` is the SINGLE
288
+ most blocking unknown, phrased so a human can answer it. Never
289
+ inflate: a `low` with a sharp question is a successful output —
290
+ it saves the whole implementation cost of building the wrong
291
+ thing.
292
+ 3. Reply with three lines:
276
293
  ```
277
294
  OpenSpec change: openspec/changes/<slug>/
278
295
  Plan written to <plan-path>; files to touch: <comma-separated list>
296
+ Design confidence: <high|medium|low>[ — blocking question: <question>]
279
297
  ```
280
- 3. End your turn. The orchestrator will read your plan + the
281
- tasks.md and spawn the developer next.
298
+ 4. End your turn. The orchestrator will read your plan + the
299
+ tasks.md and spawn the developer next (or halt on `low`).
282
300
 
283
301
  If you cannot produce a plan (ticket is too ambiguous, repo
284
302
  state is corrupt, etc.), instead reply with:
@@ -72,9 +72,10 @@ note it in your reply — do not block on the architect.
72
72
  a. **RED — write the failing test (step N.1).**
73
73
  - Open the test file the task names. Create it if missing.
74
74
  - Add the test asserting the behaviour the task names.
75
- - Run the test runner. The new test MUST fail. If it
76
- unexpectedly passes, your test is wrong (it isn't
77
- actually asserting the new behaviour) rewrite it.
75
+ - Run **only that test file** (scoped run e.g.
76
+ `npx vitest run <file>`, `pytest <file>`). The new test
77
+ MUST fail. If it unexpectedly passes, your test is wrong
78
+ (it isn't actually asserting the new behaviour) — rewrite it.
78
79
  - Tick `- [x] N.1` in `tasks.md` only when you have
79
80
  observed the test fail.
80
81
 
@@ -83,16 +84,27 @@ note it in your reply — do not block on the architect.
83
84
  modify it.
84
85
  - Write the minimum code to make the failing test pass.
85
86
  Resist adding code unrelated to the test.
86
- - Run the test runner. ALL tests must pass — the new
87
- one AND every prior one.
87
+ - Re-run **only that test file** (`npx vitest run
88
+ <file>`, `pytest <file>`, …). It must pass. The full
89
+ suite runs once, at the validation gate — not after
90
+ every task.
88
91
  - Tick `- [x] N.2`.
89
92
 
90
93
  c. **REFACTOR — clean up (step N.3, if present).**
91
94
  - If the production code can be clearer without changing
92
95
  behaviour, refactor it now.
93
- - Re-run the test runner. All tests still pass.
96
+ - Re-run the test files covering the files you touched.
97
+ Still green.
94
98
  - Tick `- [x] N.3`.
95
99
 
100
+ **Test-execution economy (MANDATORY):** the full project
101
+ suite runs exactly ONCE — at the validation gate below.
102
+ Never run it inside a task cycle. When a scoped run fails,
103
+ carry forward only the failing test names and the relevant
104
+ error excerpt (≤50 lines), never a full runner log. If you
105
+ run the same command 3 times with no intervening code
106
+ change, STOP re-running and change the code or the test.
107
+
96
108
  3. **Honour the design's invariants and edge cases.** When the
97
109
  design's `Public API / surface` says a function takes `(x, y)`
98
110
  and returns `Result<Z>`, your code must match that signature
@@ -115,15 +127,22 @@ The final task block in `tasks.md` is always the validation gate
115
127
  (`## N. Validation gate`). Run it:
116
128
 
117
129
  - Full project test suite (e.g. `npm test`, `pytest`,
118
- `cargo test`). MUST pass.
130
+ `cargo test`). MUST pass. This is the pipeline's SINGLE
131
+ full pass — the per-task loop stayed scoped so this one
132
+ can be exhaustive.
119
133
  - Project build if present (e.g. `npm run build`,
120
134
  `cargo build`). MUST succeed.
121
135
  - A grep for debug breadcrumbs (`console.log`, `print(`, etc.)
122
136
  in the files you touched — none should remain.
123
137
 
124
- If the gate fails, the offending file is your responsibility:
125
- fix it before handing off. Do not push the gate problem onto
126
- the reviewer.
138
+ If the gate fails, the offending file is your responsibility.
139
+ Fix it, re-running **only the failing test files** between
140
+ fixes — you have a budget of 2 fix cycles, then ONE final
141
+ full-suite run to confirm. If failures persist after that,
142
+ reply `"BLOCKED: validation gate failing — <failing tests,
143
+ verbatim>"` and end your turn. Never keep looping, never
144
+ weaken or skip tests to force green, never hand a known
145
+ failure silently to the reviewer.
127
146
 
128
147
  ## What you must NOT do
129
148
 
@@ -109,16 +109,27 @@ a screenshot/manual-check note in the design's
109
109
  "Open questions". A criterion with **no** mapping is a
110
110
  blocker finding.
111
111
 
112
- ### 5. Re-run the full validation gate
113
-
114
- Use the command from the design's `Validation` section in the
115
- plan artefact (or the final block of `tasks.md`):
116
-
117
- - Project test suite (`npm test`, `pytest`, `cargo test`, …).
118
- Confirm it passes. Capture the count.
119
- - Project build if present (`npm run build`, …). Confirm it
120
- succeeds.
121
- - If neither runner exists, run whatever fallback the design
112
+ ### 5. Verify the gate scoped-first
113
+
114
+ The developer's validation gate already ran the full suite
115
+ green; re-running the whole thing on an untouched tree
116
+ re-buys information the pipeline already has. So:
117
+
118
+ - Run the tests SCOPED to the diff — the test files covering
119
+ every changed source file, per-file (`npx vitest run
120
+ <file>`, `pytest <file>`, `cargo test <name>`, …). Confirm
121
+ green; capture the count.
122
+ - Run the full suite yourself ONLY when: you modified
123
+ production code in this review, the diff touches
124
+ build/config/test infrastructure, or a scoped failure has
125
+ an unclear blast radius. Then finish with ONE clean full
126
+ pass (plus the build if present) — never repeated full
127
+ passes between fixes.
128
+ - If you changed nothing and the scoped runs are green,
129
+ record the developer's gate as the pass of record — in the
130
+ confidence artefact set `tests.ran` to the scoped command
131
+ and say so in `tests.details`.
132
+ - If no test runner exists, run whatever fallback the design
122
133
  named (`node --check`, etc.).
123
134
 
124
135
  ### 6. Write the confidence artefact
@@ -35,7 +35,7 @@ Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
35
35
 
36
36
  On all checks passed:
37
37
  ```
38
- All 6 checks passed. Run /specrails:get-backlog-specs to get started.
38
+ All 6 checks passed. Run /specrails:implement to get started.
39
39
  ```
40
40
 
41
41
  On failure: