@oscaner-skills/cdd-engine 1.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.
- package/LICENSE +21 -0
- package/README.md +52 -0
- package/README.zh-CN.md +54 -0
- package/dist/chunks/branch.mjs +480 -0
- package/dist/chunks/docs.mjs +253 -0
- package/dist/chunks/task.mjs +913 -0
- package/dist/cli.mjs +5457 -0
- package/dist/documents/schema/add-phase-protocol.json +126 -0
- package/dist/documents/schema/overall.json +361 -0
- package/dist/documents/schema/phase-spec.json +145 -0
- package/dist/documents/schema/plan.json +191 -0
- package/dist/documents/schema/skill-anatomy.json +233 -0
- package/dist/resources/harness-registry.json +49 -0
- package/dist/shared/cdd-engine.liioziig.mjs +184 -0
- package/package.json +51 -0
- package/templates/engine-config.json +302 -0
- package/templates/report/issue-body.json +204 -0
- package/templates/schema/cache-profile-schema.json +23 -0
- package/templates/schema/docs-handoff-schema.json +129 -0
- package/templates/schema/task-handoff-schema.json +332 -0
- package/templates/template-contract.json +231 -0
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"description": "CDD task handoff contract (implement / review / fix / branch-review). The engine writes or materializes this file; the agent's job is the content of findings[] and the declared work fields below. Write findings, not status — the engine derives status from findings. Each property below documents its rule.",
|
|
4
|
+
"type": "object",
|
|
5
|
+
"required": [
|
|
6
|
+
"tasks",
|
|
7
|
+
"phase",
|
|
8
|
+
"artifacts",
|
|
9
|
+
"findings"
|
|
10
|
+
],
|
|
11
|
+
"properties": {
|
|
12
|
+
"tasks": {
|
|
13
|
+
"type": "array",
|
|
14
|
+
"items": {
|
|
15
|
+
"type": "integer",
|
|
16
|
+
"minimum": 1
|
|
17
|
+
},
|
|
18
|
+
"minItems": 1,
|
|
19
|
+
"uniqueItems": true,
|
|
20
|
+
"description": "The dispatch group's task numbers (1-indexed; the plan's `### Task N:` ids) — the carrier's single task identity (single-data-model: no separate top-level `task` scalar; `--tasks 1` → [1], `--tasks 1,2` → [1,2])."
|
|
21
|
+
},
|
|
22
|
+
"phase": {
|
|
23
|
+
"type": "string",
|
|
24
|
+
"enum": [
|
|
25
|
+
"implement",
|
|
26
|
+
"review",
|
|
27
|
+
"fix",
|
|
28
|
+
"branch-review"
|
|
29
|
+
],
|
|
30
|
+
"description": "dispatch phase; determined by the engine, not authored by the agent."
|
|
31
|
+
},
|
|
32
|
+
"status": {
|
|
33
|
+
"type": "string",
|
|
34
|
+
"enum": [
|
|
35
|
+
"APPROVED",
|
|
36
|
+
"BLOCKED",
|
|
37
|
+
"CHANGES_REQUESTED",
|
|
38
|
+
"REVIEW_FIX",
|
|
39
|
+
"TIMEOUT"
|
|
40
|
+
],
|
|
41
|
+
"description": "The round conclusion (this dispatch's terminal result) — APPROVED: done; CHANGES_REQUESTED: fix the findings (terminal conclusion of a review round; the fix loop runs as its own dispatch); REVIEW_FIX: the warn/nit-only review conclusion (收口态 — the review closed and its fix round routes the task to complete without a re-review, #278); BLOCKED: the round cannot proceed — the failure mechanism lives in failure_category, the reason in blocker; TIMEOUT: budget or liveness exceeded. Orthogonal surfaces: failure_category (mechanism channel) and unverifiable[]/plan_conflicts[] (content-level notes) never fold into status. The review family (review / branch-review) may omit this field — the engine derives it from findings; implement / fix (work types) must declare it. Write findings, not status."
|
|
42
|
+
},
|
|
43
|
+
"failure_category": {
|
|
44
|
+
"type": "string",
|
|
45
|
+
"enum": [
|
|
46
|
+
"TIMEOUT",
|
|
47
|
+
"CONTRACT_VIOLATION",
|
|
48
|
+
"ENGINE_SELF_WRITTEN",
|
|
49
|
+
"EXECUTION_FAILURE",
|
|
50
|
+
"UNVERIFIABLE",
|
|
51
|
+
"PLAN_CONFLICT"
|
|
52
|
+
],
|
|
53
|
+
"description": "Failure mechanism channel — which mechanism ended the round (TIMEOUT / CONTRACT_VIOLATION / ENGINE_SELF_WRITTEN / EXECUTION_FAILURE / UNVERIFIABLE / PLAN_CONFLICT). Orthogonal to status (the round conclusion) and to the content-level unverifiable[]/plan_conflicts[] notes. Engine-written on failure paths; declared by the agent only when it reports one. A BLOCKED round may satisfy its grounding via this field (see allOf)."
|
|
54
|
+
},
|
|
55
|
+
"commits": {
|
|
56
|
+
"type": "object",
|
|
57
|
+
"required": [
|
|
58
|
+
"base"
|
|
59
|
+
],
|
|
60
|
+
"description": "commit identity of the dispatch's review/fix range; the template-contract review range check at 13.5 validates it.",
|
|
61
|
+
"properties": {
|
|
62
|
+
"base": {
|
|
63
|
+
"type": "string",
|
|
64
|
+
"pattern": "^[0-9a-f]{40}$",
|
|
65
|
+
"description": "range base (TASK_BASE / FIXED_POINT): full 40-char SHA; never --short / %h / any truncated form."
|
|
66
|
+
},
|
|
67
|
+
"head": {
|
|
68
|
+
"type": "string",
|
|
69
|
+
"pattern": "^[0-9a-f]{40}$",
|
|
70
|
+
"description": "full 40-char SHA; never --short / %h / any truncated form. Optional — omitted when the round has no head yet (e.g. some BLOCKED branch-review payloads)."
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
},
|
|
74
|
+
"complexity": {
|
|
75
|
+
"type": "string",
|
|
76
|
+
"enum": [
|
|
77
|
+
"simple",
|
|
78
|
+
"moderate",
|
|
79
|
+
"complex"
|
|
80
|
+
],
|
|
81
|
+
"description": "agent-declared complexity estimate; optional."
|
|
82
|
+
},
|
|
83
|
+
"review_scope": {
|
|
84
|
+
"type": "string",
|
|
85
|
+
"enum": [
|
|
86
|
+
"task",
|
|
87
|
+
"branch"
|
|
88
|
+
],
|
|
89
|
+
"description": "review dispatch scope (task vs branch); determined by the dispatch, not authored."
|
|
90
|
+
},
|
|
91
|
+
"artifacts": {
|
|
92
|
+
"type": "object",
|
|
93
|
+
"description": "point at files, do not embed report bodies — values are paths (brief / report / test_evidence), never inline content."
|
|
94
|
+
},
|
|
95
|
+
"findings": {
|
|
96
|
+
"type": "array",
|
|
97
|
+
"items": {
|
|
98
|
+
"type": "object",
|
|
99
|
+
"properties": {
|
|
100
|
+
"lens": {
|
|
101
|
+
"type": "string",
|
|
102
|
+
"description": "review lens label (one of the round's REVIEW_LENS_GUIDE — prevents axis mixing)."
|
|
103
|
+
},
|
|
104
|
+
"severity": {
|
|
105
|
+
"type": "string",
|
|
106
|
+
"enum": [
|
|
107
|
+
"blocker",
|
|
108
|
+
"warn",
|
|
109
|
+
"nit"
|
|
110
|
+
],
|
|
111
|
+
"description": "blocker → CHANGES_REQUESTED; warn/nit → REVIEW_FIX (收口态 — the engine rolls findings up to status, #278)."
|
|
112
|
+
},
|
|
113
|
+
"section": {
|
|
114
|
+
"type": "string",
|
|
115
|
+
"description": "section or file the finding anchors to."
|
|
116
|
+
},
|
|
117
|
+
"file": {
|
|
118
|
+
"type": "string",
|
|
119
|
+
"description": "repo-relative file the finding anchors to."
|
|
120
|
+
},
|
|
121
|
+
"line": {
|
|
122
|
+
"type": "integer",
|
|
123
|
+
"minimum": 1,
|
|
124
|
+
"description": "1-indexed line the finding anchors to."
|
|
125
|
+
},
|
|
126
|
+
"summary": {
|
|
127
|
+
"type": "string",
|
|
128
|
+
"description": "one-sentence statement of the defect."
|
|
129
|
+
},
|
|
130
|
+
"fix": {
|
|
131
|
+
"type": "string",
|
|
132
|
+
"description": "what to change to resolve the finding."
|
|
133
|
+
},
|
|
134
|
+
"task": {
|
|
135
|
+
"type": "integer",
|
|
136
|
+
"minimum": 1,
|
|
137
|
+
"description": "per-task section attribution (grouped review): the task this finding belongs to, one of the group's `tasks`. Absent → the finding is group-level."
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
},
|
|
141
|
+
"description": "[{lens, severity, section|file, line?, summary, fix, task?}] — every review finding; severity blocker → CHANGES_REQUESTED, warn/nit → REVIEW_FIX (收口态 — the engine rolls findings up to status, #278); the optional per-task field carries the grouped review's section attribution."
|
|
142
|
+
},
|
|
143
|
+
"changes": {
|
|
144
|
+
"type": "array",
|
|
145
|
+
"items": {
|
|
146
|
+
"type": "object",
|
|
147
|
+
"required": [
|
|
148
|
+
"file"
|
|
149
|
+
],
|
|
150
|
+
"properties": {
|
|
151
|
+
"file": {
|
|
152
|
+
"type": "string",
|
|
153
|
+
"description": "repo-relative path of a file this round changed."
|
|
154
|
+
},
|
|
155
|
+
"reason": {
|
|
156
|
+
"type": "string",
|
|
157
|
+
"description": "why the file changed (finding id / brief item / fix intent); omitted entries stay attributed by file."
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
},
|
|
161
|
+
"description": "Changed-file attribution ledger (implement/fix rounds declare every file the round touched, each with its reason). The engine reconciles `git diff <base>..HEAD` against it — files off the ledger are booking gaps the execution layer only surfaces (stderr CDD_WARN + a notes record, never a block); the review scope axis judges them as findings."
|
|
162
|
+
},
|
|
163
|
+
"unverifiable": {
|
|
164
|
+
"type": "array",
|
|
165
|
+
"description": "Content-level notes — each entry states one claim the round could not verify (what + why: e.g. {claim, why}). A non-empty list makes the round BLOCKED with failure_category UNVERIFIABLE and a blocker summarizing the entries. Dev-measured acceptance items (plan-constraints §口径) are NOT unverifiable: an evidence-contract accepted-noted round records them in `notes`, never writes unverifiable and never blocks."
|
|
166
|
+
},
|
|
167
|
+
"plan_conflicts": {
|
|
168
|
+
"type": "array",
|
|
169
|
+
"description": "Content-level notes — each entry states one plan conflict discovered during the round. A non-empty list makes the round BLOCKED with failure_category PLAN_CONFLICT and a blocker summarizing the entries."
|
|
170
|
+
},
|
|
171
|
+
"blocker": {
|
|
172
|
+
"type": "string",
|
|
173
|
+
"description": "The round's single real blocker line — states what could not be verified and why, or the concrete reason the round cannot proceed. Real sources only (agent-declared / engine gate reason / failure mechanism / unverifiable summary); never fabricated. Omit when nothing blocks (NOT null) — null is invalid. BLOCKED requires a non-empty blocker or a failure_category (see allOf)."
|
|
174
|
+
},
|
|
175
|
+
"notes": {
|
|
176
|
+
"type": "string",
|
|
177
|
+
"description": "free-form evidence notes (why this fix / why test-evidence was re-recorded / dev-measured acceptance items recorded per §口径 accepted-noted); optional."
|
|
178
|
+
},
|
|
179
|
+
"test_evidence": {
|
|
180
|
+
"type": "object",
|
|
181
|
+
"description": "reference to command outputs (paths), never inline output bodies."
|
|
182
|
+
},
|
|
183
|
+
"recovery": {
|
|
184
|
+
"type": "object",
|
|
185
|
+
"required": [
|
|
186
|
+
"cause"
|
|
187
|
+
],
|
|
188
|
+
"properties": {
|
|
189
|
+
"cause": {
|
|
190
|
+
"type": "string",
|
|
191
|
+
"description": "round-end cause: the failure-category id (EXECUTION_FAILURE / TIMEOUT — the residue-preservation eligibility set) on engine-written death carriers, or the termination sub-cause (stalled/over-budget/signal) on legacy salvage records. The settlement step preserves the residue exactly when this id is in the preserved set."
|
|
192
|
+
},
|
|
193
|
+
"exit_code": {
|
|
194
|
+
"type": "integer",
|
|
195
|
+
"description": "the failed agent's process exit code (1 = run failure, 143 = SIGTERM) — the archived death diagnosis distinguishing exit 1 vs 143; absent on TIMEOUT rounds (the monitor killed the process; there is no exit)."
|
|
196
|
+
},
|
|
197
|
+
"residue_ref": {
|
|
198
|
+
"type": "string",
|
|
199
|
+
"description": "Salvaged-WIP stash commit SHA (index-independent: `stash@{N}` indices shift on every push/drop). Written by the residue settlement step on eligible EXECUTION_FAILURE/TIMEOUT rounds with a dirty tree; the re-dispatch resume pre-flight reads it and `git stash apply`s it. Settlement output ≡ resume input."
|
|
200
|
+
},
|
|
201
|
+
"wip_stat": {
|
|
202
|
+
"type": "object",
|
|
203
|
+
"required": [
|
|
204
|
+
"files",
|
|
205
|
+
"insertions",
|
|
206
|
+
"deletions"
|
|
207
|
+
],
|
|
208
|
+
"properties": {
|
|
209
|
+
"files": {
|
|
210
|
+
"type": "integer"
|
|
211
|
+
},
|
|
212
|
+
"insertions": {
|
|
213
|
+
"type": "integer"
|
|
214
|
+
},
|
|
215
|
+
"deletions": {
|
|
216
|
+
"type": "integer"
|
|
217
|
+
}
|
|
218
|
+
},
|
|
219
|
+
"description": "structured WIP scale (files / +M / -M) at salvage time — the recovery carrier's archivable magnitude beside residue_ref; counts brand-new untracked files too (the normal TDD shape for new tests/modules)."
|
|
220
|
+
},
|
|
221
|
+
"preserved": {
|
|
222
|
+
"type": "boolean",
|
|
223
|
+
"description": "true when the round's residue was stashed into the recovery carrier (residue_ref + wip_stat present); the settlement step's idempotence flag — an already-preserved carrier never double-stashes."
|
|
224
|
+
},
|
|
225
|
+
"stash_message": {
|
|
226
|
+
"type": "string",
|
|
227
|
+
"description": "The standardized stash name `cdd-<op>-<type>-<task>-r<round>-<cause>` (src/artifacts/residue.ts single source) — the legacy stash-list scan matches on it for pre-schema carriers."
|
|
228
|
+
},
|
|
229
|
+
"residue_scope": {
|
|
230
|
+
"type": "string",
|
|
231
|
+
"description": "WIP scope summary (`git diff HEAD --shortstat`, e.g. '2 files changed, 727 insertions(+)') — data-driven input for the resume brief appendix."
|
|
232
|
+
},
|
|
233
|
+
"round": {
|
|
234
|
+
"type": "integer",
|
|
235
|
+
"minimum": 1,
|
|
236
|
+
"description": "the salvaged round number (implement rounds are always round 1)."
|
|
237
|
+
},
|
|
238
|
+
"scope_base": {
|
|
239
|
+
"type": "string",
|
|
240
|
+
"pattern": "^[0-9a-f]{40}$",
|
|
241
|
+
"description": "The task-level scope anchor at salvage time (ledger value priority / fallback dead-round brief TASK_BASE). Resume restores the same anchor — the round-BASE (resume-declared) adoption and the recovered scope stay consistent across round death."
|
|
242
|
+
}
|
|
243
|
+
},
|
|
244
|
+
"additionalProperties": false,
|
|
245
|
+
"description": "Residue recovery carrier — engine-written on EXECUTION_FAILURE/TIMEOUT failure rounds: cause + exit_code ride every death (the archived, replayable diagnosis); residue_ref / wip_stat / preserved appear once the settlement step stashed the dirty-tree WIP. Absent on all other rounds. The re-dispatch's resume pre-flight consumes the stash ref (primary path); carriers written before this field existed fall back to the standardized stash-message scan. Same law as every structured field: the facts live here, the blocker stays human-readable prose."
|
|
246
|
+
}
|
|
247
|
+
},
|
|
248
|
+
"allOf": [
|
|
249
|
+
{
|
|
250
|
+
"if": {
|
|
251
|
+
"properties": {
|
|
252
|
+
"phase": {
|
|
253
|
+
"const": "implement"
|
|
254
|
+
},
|
|
255
|
+
"recovery": {
|
|
256
|
+
"type": "object"
|
|
257
|
+
}
|
|
258
|
+
},
|
|
259
|
+
"required": [
|
|
260
|
+
"phase",
|
|
261
|
+
"recovery"
|
|
262
|
+
]
|
|
263
|
+
},
|
|
264
|
+
"then": {
|
|
265
|
+
"properties": {
|
|
266
|
+
"recovery": {
|
|
267
|
+
"type": "object",
|
|
268
|
+
"required": [
|
|
269
|
+
"residue_ref"
|
|
270
|
+
]
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
},
|
|
275
|
+
{
|
|
276
|
+
"if": {
|
|
277
|
+
"properties": {
|
|
278
|
+
"phase": {
|
|
279
|
+
"enum": [
|
|
280
|
+
"review",
|
|
281
|
+
"branch-review"
|
|
282
|
+
]
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
"required": [
|
|
286
|
+
"phase"
|
|
287
|
+
]
|
|
288
|
+
},
|
|
289
|
+
"then": {
|
|
290
|
+
"required": []
|
|
291
|
+
},
|
|
292
|
+
"else": {
|
|
293
|
+
"required": [
|
|
294
|
+
"status"
|
|
295
|
+
]
|
|
296
|
+
}
|
|
297
|
+
},
|
|
298
|
+
{
|
|
299
|
+
"if": {
|
|
300
|
+
"properties": {
|
|
301
|
+
"status": {
|
|
302
|
+
"const": "BLOCKED"
|
|
303
|
+
}
|
|
304
|
+
},
|
|
305
|
+
"required": [
|
|
306
|
+
"status"
|
|
307
|
+
]
|
|
308
|
+
},
|
|
309
|
+
"then": {
|
|
310
|
+
"anyOf": [
|
|
311
|
+
{
|
|
312
|
+
"required": [
|
|
313
|
+
"blocker"
|
|
314
|
+
],
|
|
315
|
+
"properties": {
|
|
316
|
+
"blocker": {
|
|
317
|
+
"type": "string",
|
|
318
|
+
"minLength": 1
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
},
|
|
322
|
+
{
|
|
323
|
+
"required": [
|
|
324
|
+
"failure_category"
|
|
325
|
+
]
|
|
326
|
+
}
|
|
327
|
+
]
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
],
|
|
331
|
+
"additionalProperties": false
|
|
332
|
+
}
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$version": 3,
|
|
4
|
+
"skeleton": {
|
|
5
|
+
"sections": [
|
|
6
|
+
"Instructions",
|
|
7
|
+
"Handoff",
|
|
8
|
+
"Return",
|
|
9
|
+
"Round context"
|
|
10
|
+
],
|
|
11
|
+
"segments": {
|
|
12
|
+
"shell": [
|
|
13
|
+
"Instructions",
|
|
14
|
+
"Handoff"
|
|
15
|
+
],
|
|
16
|
+
"return": [
|
|
17
|
+
"Return"
|
|
18
|
+
],
|
|
19
|
+
"round-context": [
|
|
20
|
+
"Round context"
|
|
21
|
+
]
|
|
22
|
+
},
|
|
23
|
+
"order": [
|
|
24
|
+
"shell",
|
|
25
|
+
"return",
|
|
26
|
+
"round-context"
|
|
27
|
+
]
|
|
28
|
+
},
|
|
29
|
+
"sections": {
|
|
30
|
+
"shell": [
|
|
31
|
+
"# CDD dispatch — CLI session",
|
|
32
|
+
"",
|
|
33
|
+
"## Instructions",
|
|
34
|
+
"",
|
|
35
|
+
"1. **`## Round context` — the final section — is the only dynamic region of this prompt.** Every per-dispatch value lives there; this shell and `## Return` are the fixed dispatch contract, byte-identical for every round and mode. Wherever this contract names a symbol (`BRIEF`, `HANDOFF_TARGET`, `REVIEW_REFERENCE`, …), resolve the real value from `## Round context`; nothing real rides above it. The `MODE` in `## Round context` selects this round's rules below.",
|
|
36
|
+
"2. **Scope lock (every mode):** consume only this round's inputs listed in `## Round context`. Do **not** read the full plan file. Implement exactly what the brief specifies — no extra features, no tangential refactors, no scope creep beyond the brief's Files/Interfaces/Steps.",
|
|
37
|
+
"3. **`implement`:** read only the task brief at `BRIEF` and the plan constraints at `CONSTRAINTS`. `DISPATCH_UNIT` is this round's group key (the CLI `--tasks` string — the canonical group identity); `BRIEF` is one file holding every `### Task N:` section of the group — implement **ALL sections**, never a subset. `CONFIRMED_SEAMS` listed in the brief → apply them when invoking the implementation approach — no re-negotiation; otherwise propose the test boundaries in the report, then invoke **`mattpocock-skills:tdd`**. This mode does not write a handoff — the engine materializes `tasks-{DISPATCH_UNIT}-implement.json` from your return block four lines + the brief's `TASK_BASE` + `git HEAD` (the engine is the single authority for `commits` and for re-emitting your return block).",
|
|
38
|
+
"4. **`fix`:** read the open findings at `FINDINGS` and the task brief at `BRIEF` (paths only — do not paste review bodies into the prompt). Fix ALL findings — blockers, warns, and nits — and remove fixed findings from the handoff's `findings[]`. `commits.base` = `FIXED_POINT` (this round's `FIX_BASE` — the prior handoff's `commits.head`); `commits.head` = `git rev-parse HEAD` (full 40-char SHA, never `--short`). No fix-scope diff relative to `FIXED_POINT` → no commit (keep `head` unchanged). Implement + handoff in one process; a handoff write failure → return block `status: BLOCKED`; retry = full mode re-run (idempotent).",
|
|
39
|
+
"5. **`review`:** review the axes in `REVIEW_AXES` against the reference in `REVIEW_REFERENCE`. Every finding MUST carry its `lens` label (one of `REVIEW_LENS_GUIDE`); an empty `findings` array = approved. The `returnFormat` named in `## Return` selects the return contract: RETURN_JSON → findings-only JSON on stdout; RETURN_STDOUT_BLOCK → collect findings into the handoff's `findings[]` (do not print them), then the four-line block only.",
|
|
40
|
+
"6. **`docs`:** apply fixes directly to `DOC` per `FINDINGS` (all severities), removing fixed findings; `artifacts` records the doc path and `doc_path` = the exact `DOC` path.",
|
|
41
|
+
"7. **Evidence gate:** before returning, write the test-evidence file under `WORKSPACE` (`tasks-{DISPATCH_UNIT}-test-evidence.json` — the canonical task-family form the engine reads back byte-identically) with at least `command`, `exit_code`, `passed`, and `warnings_count` (include `behavior_change` when applicable). The engine reads it back after you exit: `behavior_change: true` requires `command`, `passed`, and `exit_code` — missing any of the three → the handoff is overridden to `status: BLOCKED` (exit 1); otherwise only a WARN note attaches. Update the implementer report at the path from the brief after verification. Report bodies, test stdout, and diff text live in files only — never in the return.",
|
|
42
|
+
"8. **Commit contract (base/head):** `base` = the brief's `TASK_BASE` (implement) or `FIXED_POINT` (fix — a review's reviewed range). When TDD/verification already produced one or more conventional commits covering this round's scope, set `head` = `git rev-parse HEAD` — do not create duplicate commits; otherwise create **one** conventional commit (`feat:` / `fix:` / `refactor:` / …) with subject aligned to the round — no attribution / co-author / AI-generation trailers — then `head` = `git rev-parse HEAD`. Uncommitted changes at return → `status: BLOCKED`. Only commit changes within this round's scope; out-of-scope uncommitted changes at return → `status: BLOCKED` + `blocker:` listing the out-of-scope paths.",
|
|
43
|
+
"9. **Discipline clauses (single-source; bind every mode):**",
|
|
44
|
+
"- {{> cl:english-comments}}",
|
|
45
|
+
"- {{> cl:eof-newline}}",
|
|
46
|
+
"- {{> cl:no-full-tree-find}}",
|
|
47
|
+
"- {{> cl:bash-stall-limit}}",
|
|
48
|
+
"- {{> cl:plan-freeze}}",
|
|
49
|
+
"- {{> cl:atomic-commit}}",
|
|
50
|
+
"- {{> cl:self-validate}}",
|
|
51
|
+
"- {{> cl:changed-surface}}",
|
|
52
|
+
"",
|
|
53
|
+
"## Handoff",
|
|
54
|
+
"",
|
|
55
|
+
"Write/update the handoff JSON at `HANDOFF_TARGET` (see `## Round context`) per the schema below. The `HANDOFF_WRITE_GATE` entry — `### HANDOFF_WRITE_GATE` in `## Round context` — states this round's write protocol; follow it literally before returning. Work-type rounds (implement/fix) declare `status` (APPROVED once applied, or BLOCKED with the reason in `blocker`); review-family rounds write findings, not status — the engine derives status from findings. `artifacts` points at files, never inline content. Self-validate before returning (`jq .` on the written handoff → `phase`/`artifacts`/`findings` non-null); a non-parseable or schema-violating handoff is rewritten BLOCKED by the engine."
|
|
56
|
+
],
|
|
57
|
+
"return": {
|
|
58
|
+
"RETURN_STDOUT_BLOCK": [
|
|
59
|
+
"## Return",
|
|
60
|
+
"",
|
|
61
|
+
"Return **exactly 4 lines** to stdout — make this block the **final** output; nothing may follow it (stream-json harnesses parse the last block):",
|
|
62
|
+
"",
|
|
63
|
+
"```",
|
|
64
|
+
"status: <APPROVED|BLOCKED>",
|
|
65
|
+
"commits: base=<sha> head=<sha>",
|
|
66
|
+
"artifacts: brief=<path> report=<path> test_evidence=<path>",
|
|
67
|
+
"blocker: <none|one-line>",
|
|
68
|
+
"```",
|
|
69
|
+
"",
|
|
70
|
+
"The `returnFormat` is **RETURN_STDOUT_BLOCK**: review-family rounds (task/branch) collect findings into `HANDOFF_TARGET` `findings[]` (see `## Round context` — do not print them), then output this block as the ONLY stdout content; `implement` rounds return this block directly. Report bodies, test stdout, and diff text live in files only — never in the return. Any non-`APPROVED` status line (e.g. `NEEDS_CONTEXT`) is collapsed by the engine to `BLOCKED` + exit 1."
|
|
71
|
+
],
|
|
72
|
+
"RETURN_JSON": [
|
|
73
|
+
"## Return",
|
|
74
|
+
"",
|
|
75
|
+
"This review's `returnFormat` is **RETURN_JSON** — return findings ONLY as a JSON object:",
|
|
76
|
+
"",
|
|
77
|
+
"`{\"findings\":[{ \"lens\": \"<one of REVIEW_LENS_GUIDE — see ## Round context>\", \"severity\": \"blocker|warn|nit\", \"section\": \"...\", \"line\": 0, \"summary\": \"...\", \"fix\": \"...\" }]}`",
|
|
78
|
+
"",
|
|
79
|
+
"Every finding MUST carry its `lens` label (prevents axis mixing); empty `findings` array = approved; no additional prose."
|
|
80
|
+
],
|
|
81
|
+
"DOCS_FIX": [
|
|
82
|
+
"## Return",
|
|
83
|
+
"",
|
|
84
|
+
"Your return IS the handoff written to `HANDOFF_TARGET` (see `## Round context`) — **the engine reads the file, not your stdout**. Return **no additional prose**; empty `findings` array = all findings fixed. Write/update `HANDOFF_TARGET` per the schema in the shell above BEFORE exiting — leaving it unwritten is BLOCKED (runner exit 1)."
|
|
85
|
+
]
|
|
86
|
+
},
|
|
87
|
+
"round-context": [
|
|
88
|
+
"## Round context",
|
|
89
|
+
"",
|
|
90
|
+
"- `MODE`: {{MODE}}",
|
|
91
|
+
"- `DISPATCH_UNIT`: {{DISPATCH_UNIT}}",
|
|
92
|
+
"- `BRIEF`: {{BRIEF}}",
|
|
93
|
+
"- `CONSTRAINTS`: {{CONSTRAINTS}}",
|
|
94
|
+
"- `FINDINGS`: {{FINDINGS}}",
|
|
95
|
+
"- `FIXED_POINT`: {{FIXED_POINT}}",
|
|
96
|
+
"- `WORKSPACE`: {{WORKSPACE}}",
|
|
97
|
+
"- `WORKSPACE_SLUG`: {{WORKSPACE_SLUG}}",
|
|
98
|
+
"- `REVIEW_TYPE`: {{REVIEW_TYPE}}",
|
|
99
|
+
"- `REVIEW_REFERENCE`: {{REVIEW_REFERENCE}}",
|
|
100
|
+
"- `REVIEW_LENS_GUIDE`: {{REVIEW_LENS_GUIDE}}",
|
|
101
|
+
"- `REVIEW_AXES`: {{REVIEW_AXES}}",
|
|
102
|
+
"- `REVIEW_PLAN_LINE`: {{REVIEW_PLAN_LINE}}",
|
|
103
|
+
"- `DOC`: {{DOC}}",
|
|
104
|
+
"- `HANDOFF_TARGET`: {{HANDOFF_TARGET}}",
|
|
105
|
+
"",
|
|
106
|
+
"### HANDOFF_WRITE_GATE",
|
|
107
|
+
"",
|
|
108
|
+
"{{HANDOFF_WRITE_GATE}}"
|
|
109
|
+
]
|
|
110
|
+
},
|
|
111
|
+
"tokens": [
|
|
112
|
+
{
|
|
113
|
+
"name": "BRIEF",
|
|
114
|
+
"zone": "round-context"
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"name": "CONSTRAINTS",
|
|
118
|
+
"zone": "round-context"
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"name": "DISPATCH_UNIT",
|
|
122
|
+
"zone": "round-context"
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
"name": "DOC",
|
|
126
|
+
"zone": "round-context"
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"name": "FINDINGS",
|
|
130
|
+
"zone": "round-context"
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
"name": "FIXED_POINT",
|
|
134
|
+
"zone": "round-context"
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"name": "HANDOFF_TARGET",
|
|
138
|
+
"zone": "round-context"
|
|
139
|
+
},
|
|
140
|
+
{
|
|
141
|
+
"name": "HANDOFF_WRITE_GATE",
|
|
142
|
+
"zone": "round-context"
|
|
143
|
+
},
|
|
144
|
+
{
|
|
145
|
+
"name": "MODE",
|
|
146
|
+
"zone": "round-context"
|
|
147
|
+
},
|
|
148
|
+
{
|
|
149
|
+
"name": "REVIEW_AXES",
|
|
150
|
+
"zone": "round-context"
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
"name": "REVIEW_LENS_GUIDE",
|
|
154
|
+
"zone": "round-context"
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"name": "REVIEW_PLAN_LINE",
|
|
158
|
+
"zone": "round-context"
|
|
159
|
+
},
|
|
160
|
+
{
|
|
161
|
+
"name": "REVIEW_REFERENCE",
|
|
162
|
+
"zone": "round-context"
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
"name": "REVIEW_TYPE",
|
|
166
|
+
"zone": "round-context"
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
"name": "RETURN_FORMAT",
|
|
170
|
+
"zone": "return"
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
"name": "RETURN_STDOUT_BLOCK",
|
|
174
|
+
"zone": "return"
|
|
175
|
+
},
|
|
176
|
+
{
|
|
177
|
+
"name": "WORKSPACE",
|
|
178
|
+
"zone": "round-context"
|
|
179
|
+
},
|
|
180
|
+
{
|
|
181
|
+
"name": "WORKSPACE_SLUG",
|
|
182
|
+
"zone": "round-context"
|
|
183
|
+
}
|
|
184
|
+
],
|
|
185
|
+
"clauses": {
|
|
186
|
+
"cl:english-comments": "Write code comments and shipped prose in English only — English-primary (no other-language comment blocks, no translated mirrors).",
|
|
187
|
+
"cl:eof-newline": "Every text file must end with exactly one newline (EOF newline): no missing final newline and no trailing blank lines.",
|
|
188
|
+
"cl:no-full-tree-find": "Never run an unbounded full-tree `find` over a large directory and never bare-read a large file — constrain to explicit paths with `maxdepth`/`-path`, or read only the needed range.",
|
|
189
|
+
"cl:bash-stall-limit": "If a Bash command stalls without progress for more than 10 minutes, terminate it and substitute an equivalent, lighter command.",
|
|
190
|
+
"cl:plan-freeze": "Approved plan/spec files are frozen — zero modification authority; any change needed is reported to the orchestrator through findings, never edited in place.",
|
|
191
|
+
"cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers.",
|
|
192
|
+
"cl:self-validate": "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
|
|
193
|
+
"cl:changed-surface": "Changed-surface bookkeeping: implement/fix rounds declare every file they changed in the handoff `changes[]` ledger (file + reason each). The engine reconciles `git diff <base>..HEAD` against it — files off the ledger are surfaced (warn + notes), never blocked; the review scope axis judges them (normal finding → fix loop)."
|
|
194
|
+
},
|
|
195
|
+
"reviews": {
|
|
196
|
+
"task": {
|
|
197
|
+
"lensEnum": [
|
|
198
|
+
"standards",
|
|
199
|
+
"spec"
|
|
200
|
+
],
|
|
201
|
+
"ref": "TASK_BASE..HEAD",
|
|
202
|
+
"axesGuide": "Standards axis (repo coding standards + code-review smell baseline) + Spec axis (task brief / plan requirements) + Scope axis (changed-surface reasonableness): cross-check the handoff's `changes[]` ledger against the actual `git diff <base>..HEAD` fileset — any changed file with no ledger entry and no brief-seam attribution is a candidate finding (severity by your judgment; warn-level booking gaps the engine flagged can surface here as blockers when they expose out-of-brief changes). Single agent, three axes, no parallel sub-agents."
|
|
203
|
+
},
|
|
204
|
+
"branch": {
|
|
205
|
+
"lensEnum": [
|
|
206
|
+
"standards",
|
|
207
|
+
"spec"
|
|
208
|
+
],
|
|
209
|
+
"ref": "BASE..HEAD",
|
|
210
|
+
"axesGuide": "Same three axes as task (branch-wide health: diff BASE..HEAD + plan conformance) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding (severity by your judgment), normal finding → fix loop"
|
|
211
|
+
},
|
|
212
|
+
"spec": {
|
|
213
|
+
"lensEnum": [
|
|
214
|
+
"completeness",
|
|
215
|
+
"consistency",
|
|
216
|
+
"clarity"
|
|
217
|
+
],
|
|
218
|
+
"ref": "doc vs spec",
|
|
219
|
+
"axesGuide": "Follow URC: single-cycle; lens-tag every finding (completeness / consistency / clarity) + Scope axis (changed-surface reasonableness): the doc edits under review must track the reviewed findings — edits beyond them (or beyond the brief seam) are candidate findings"
|
|
220
|
+
},
|
|
221
|
+
"plan": {
|
|
222
|
+
"lensEnum": [
|
|
223
|
+
"completeness",
|
|
224
|
+
"decomposition",
|
|
225
|
+
"buildability"
|
|
226
|
+
],
|
|
227
|
+
"ref": "doc vs spec",
|
|
228
|
+
"axesGuide": "Follow URC: spec coverage (completeness) / task boundaries + interfaces (decomposition) / type consistency + placeholder scan (buildability) + Scope axis (changed-surface reasonableness): the doc edits under review must track the reviewed findings — edits beyond them (or beyond the brief seam) are candidate findings"
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|