@oscaner-skills/cdd-engine 1.0.0 → 2.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/README.md +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,650 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/render/templates.ts
|
|
2
|
+
// T21 — the template-contract typed surface: the template-contract JSON's data-plane
|
|
3
|
+
// home PLUS the TemplateAssembler (one module, one renderer). The dispatch prompt
|
|
4
|
+
// data (the per-mode shell frames · the review variants · the return-format block ·
|
|
5
|
+
// the round-context subsets · the token registry · the clause partials) and the
|
|
6
|
+
// review criteria (the four-type axes guides — P4, extended to spec/plan by the
|
|
7
|
+
// v1.8 review-closeout) are typed constant data here, imported never parsed:
|
|
8
|
+
//
|
|
9
|
+
// · TEMPLATE_PROMPT — the rendering data plane the assembler consumes; this
|
|
10
|
+
// module renders over it (the JSON's $schema/_doc prose plane is gone).
|
|
11
|
+
// · REVIEWS — the four-type review criteria (task/branch axes guides + the
|
|
12
|
+
// spec/plan URC prose, migrated from the dispatch table — their single typed
|
|
13
|
+
// home, P4). P5 lands here: the "no parallel sub-agents" phrase is deleted.
|
|
14
|
+
//
|
|
15
|
+
// T15 v1.8 (the mode dispatch table — §3.5) restructures the prompt from "one all-mode
|
|
16
|
+
// manual + dynamic zone" to the per-mode dispatch table:
|
|
17
|
+
// · MODE_PROMPTS — one row per work-mode (implement / fix / docs-fix — the ROLE
|
|
18
|
+
// vocabulary; the spec/plan fix faces ride the docs-fix row): the mode's FIXED
|
|
19
|
+
// prefix (its instruction shell + the injected writable-subset schema at the
|
|
20
|
+
// shell's tail — byte-identical for every dispatch of the mode, so the prompt-
|
|
21
|
+
// cache prefix groups by mode) + the mode's REDUCED round-context subset.
|
|
22
|
+
// · REVIEW_VARIANTS — the review mode's four per-type rows (task/branch/spec/plan):
|
|
23
|
+
// the criteria + lens text are FIXED PREFIX content (folded into each variant's
|
|
24
|
+
// shell — they are per-type constants, so they never ride the dynamic tail; the
|
|
25
|
+
// INPUT_CRITERIA / INPUT_LENS round-context tokens are gone) and each variant's
|
|
26
|
+
// fixed prefix is byte-stable — a review dispatch's cache prefix groups by type.
|
|
27
|
+
// · the normalized token vocabulary (§3.5): INPUT_* (read-side) / OUTPUT_* (write-
|
|
28
|
+
// side) / WORKSPACE_* (environment) / BASE_BRANCH (the branch review's scope
|
|
29
|
+
// anchor) / ROLE (the nominative identity) / WAVE (the wave-unitary unit).
|
|
30
|
+
// Round-context keys are the mode's consumption set — a key the shell never
|
|
31
|
+
// names is not declared (the fix round carries no INPUT_ RULES).
|
|
32
|
+
//
|
|
33
|
+
// T15 v1.9 (the handoff contract-surface rework — §3.6) lands the schema injection
|
|
34
|
+
// in the same plane: the `## Handoff schema` section at every shell's tail carries
|
|
35
|
+
// the {{HANDOFF_SCHEMA}} slot (projection ① of session/handoff-schema.ts — the same
|
|
36
|
+
// declared objects the engine validates the draft against, projection ②). The
|
|
37
|
+
// handoff-format prose is gone; RETURN_STDOUT_BLOCK is the ONE return contract.
|
|
38
|
+
//
|
|
39
|
+
// T15 v1.10/1.11 (the review-closeout batch — §3.7) refines the shell composition:
|
|
40
|
+
// the work-mode tail is the shared EVIDENCE_ITEM cell (implement/fix carry it;
|
|
41
|
+
// docs-fix carries no evidence file — zero per-mode duplication), and the review
|
|
42
|
+
// variants fold the criteria/lens in.
|
|
43
|
+
//
|
|
44
|
+
// P5 (M1) supersede: the implement mode's dispatch wording names the upstream
|
|
45
|
+
// `mattpocock-skills:implement` skill (the ref the dispatch row now resolves to),
|
|
46
|
+
// never the retired tdd alias.
|
|
47
|
+
//
|
|
48
|
+
// Module-level exports are types / the declared constant data / the class — zero
|
|
49
|
+
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
50
|
+
|
|
51
|
+
import type { TargetType } from "../session/faces.ts";
|
|
52
|
+
|
|
53
|
+
/** The per-dispatch slot values — one entry per declared template token. */
|
|
54
|
+
export interface TemplateValues {
|
|
55
|
+
readonly [name: string]: string;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** One token declaration — a round-context/return zone slot the dispatch fills. */
|
|
59
|
+
export interface TemplateToken {
|
|
60
|
+
/** The token name — the `{{NAME}}` slot spelling. */
|
|
61
|
+
name: string;
|
|
62
|
+
/** The zone the token belongs to (shell / return / round-context). */
|
|
63
|
+
zone: string;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** One per-return-format block — the `## Return` zone's declared variants. */
|
|
67
|
+
export interface ReturnZone {
|
|
68
|
+
[format: string]: readonly string[];
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** The work-modes of the dispatch table — the ROLE values (fix's spec/plan face is
|
|
72
|
+
* the docs-fix mode; review covers task/branch/spec/plan + branch-review). */
|
|
73
|
+
export type WorkMode = "implement" | "fix" | "review" | "docs-fix";
|
|
74
|
+
|
|
75
|
+
/** The work-mode rows of the dispatch table — every ROLE except review (the review
|
|
76
|
+
* mode's rows are the four per-type REVIEW_VARIANTS). */
|
|
77
|
+
export type WorkModeRowKey = Exclude<WorkMode, "review">;
|
|
78
|
+
|
|
79
|
+
/** The four review types — the review mode's per-type prefix variants (the criteria
|
|
80
|
+
* and lens are per-type constants, so each variant's fixed prefix is byte-stable). */
|
|
81
|
+
|
|
82
|
+
/** One dispatch-table row — a mode's fixed prefix + its reduced dynamic tail. */
|
|
83
|
+
export interface ModePromptRow {
|
|
84
|
+
/** The work-mode identity (the ROLE vocabulary). */
|
|
85
|
+
mode: WorkMode;
|
|
86
|
+
/** The mode's FIXED prefix — its instruction shell + the `## Handoff schema`
|
|
87
|
+
* section (with the {{HANDOFF_SCHEMA}} slot at the tail — the injected
|
|
88
|
+
* writable-subset fence): byte-identical for every dispatch of the mode. */
|
|
89
|
+
shell: readonly string[];
|
|
90
|
+
/** The mode's REDUCED round-context subset — the only dynamic region; a key
|
|
91
|
+
* whose value is empty is not emitted (empty-valued keys are dropped). */
|
|
92
|
+
roundContext: readonly string[];
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The template prompt data plane — the work-mode rows + the review-per-type rows +
|
|
96
|
+
* the single return contract + the token registry + the clause partials. */
|
|
97
|
+
export interface TemplatePrompt {
|
|
98
|
+
$version: number;
|
|
99
|
+
/** The work-mode rows — one per non-review ROLE (§3.5; the review rows live in
|
|
100
|
+
* `reviews` — their ROLE value is "review" and REVIEW_TYPE selects the row). */
|
|
101
|
+
modes: Readonly<Record<WorkModeRowKey, ModePromptRow>>;
|
|
102
|
+
/** The review mode's per-type rows — each variant's fixed prefix carries its
|
|
103
|
+
* criteria + lens (folded in, never tokens). */
|
|
104
|
+
reviews: Readonly<Record<TargetType, ModePromptRow>>;
|
|
105
|
+
/** The `## Return` zone — the single block contract (v1.9). */
|
|
106
|
+
return: ReturnZone;
|
|
107
|
+
/** The token registry — the union across every mode's round context + the shell's
|
|
108
|
+
* schema slot (the gate's declared list). */
|
|
109
|
+
tokens: readonly TemplateToken[];
|
|
110
|
+
clauses: Readonly<Record<string, string>>;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** One review guide row — the criteria of one review type (its lens vocabulary +
|
|
114
|
+
* the axes/URC prose — the review prompt's fixed criteria body). */
|
|
115
|
+
export interface ReviewGuideRow {
|
|
116
|
+
/** The lens vocabulary — the finding lens labels the review may carry. */
|
|
117
|
+
lensEnum: readonly string[];
|
|
118
|
+
/** The axes/URC guide prose — the criteria body (the task/branch four axes +
|
|
119
|
+
* verification-evidence duty; the spec/plan URC rows). */
|
|
120
|
+
axesGuide: string;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** The review criteria — the four per-type guides (P4 typed data; the spec/plan
|
|
124
|
+
* URC prose migrated from the dispatch table at v1.8 closeout). */
|
|
125
|
+
export type ReviewGuides = Readonly<Record<TargetType, ReviewGuideRow>>;
|
|
126
|
+
|
|
127
|
+
/** The nominal fixed-frame cells shared by every shell (byte-identical words — the
|
|
128
|
+
* fixed prefix is read on every dispatch, so every word costs child context). */
|
|
129
|
+
const FRAME_ITEMS: readonly string[] = [
|
|
130
|
+
"**Fixed contract:** everything above `## Round context` is this mode's fixed text — byte-identical per dispatch. `## Round context` is the only dynamic region; resolve every symbol from it — nothing real rides above.",
|
|
131
|
+
"**Scope lock:** use only this round's inputs in `## Round context`. No full plan reads. No extra features, no tangential refactors, no scope creep.",
|
|
132
|
+
];
|
|
133
|
+
|
|
134
|
+
/** The shared work-mode tail cell — the evidence gate (implement/fix carry it;
|
|
135
|
+
* docs-fix carries no evidence file — zero per-mode duplication, §3.7). The
|
|
136
|
+
* evidence file's concrete name rides the injected schema's preamble (per-family
|
|
137
|
+
* prefix), never this fixed text. */
|
|
138
|
+
const EVIDENCE_ITEM =
|
|
139
|
+
"**Evidence gate:** write the test-evidence file at the prescribed `OUTPUT_EVIDENCE` path per the `test-evidence` schema in `## Handoff schema` — `command`/`exit_code`/`passed`/`warnings_count` + `typecheck` (`command`/`exit_code`/`passed`); `behavior_change` when applicable. Update the round's report after verification. Missing or schema-violating evidence → the engine rewrites the draft to `status: BLOCKED`. Reports, test output, diffs: files only, never the return.";
|
|
140
|
+
|
|
141
|
+
/** The discipline-clause cells shared by every shell (the `{{> cl:…}}` partials
|
|
142
|
+
* resolve from the single clause container — the same bytes, one per shell). */
|
|
143
|
+
const LICENSE_ITEMS: readonly string[] = [
|
|
144
|
+
"",
|
|
145
|
+
"**Discipline clauses:**",
|
|
146
|
+
"- {{> cl:english-comments}}",
|
|
147
|
+
"- {{> cl:eof-newline}}",
|
|
148
|
+
"- {{> cl:no-full-tree-find}}",
|
|
149
|
+
"- {{> cl:bash-stall-limit}}",
|
|
150
|
+
"- {{> cl:plan-freeze}}",
|
|
151
|
+
"- {{> cl:atomic-commit}}",
|
|
152
|
+
"- {{> cl:self-validate}}",
|
|
153
|
+
];
|
|
154
|
+
|
|
155
|
+
/** The `## Handoff schema` section — the injected writable-subset fence at every
|
|
156
|
+
* shell's tail (the {{HANDOFF_SCHEMA}} slot; the face's sets differ per mode, so
|
|
157
|
+
* the section's bytes are fixed per mode — §3.5 prefix-cache grouping). */
|
|
158
|
+
const SCHEMA_SECTION: readonly string[] = ["", "## Handoff schema", "", "{{HANDOFF_SCHEMA}}"];
|
|
159
|
+
|
|
160
|
+
/** The implement row's fixed prefix — header + instructions + the shared work tail. */
|
|
161
|
+
const IMPLEMENT_SHELL: readonly string[] = [
|
|
162
|
+
"# CDD dispatch — implement round",
|
|
163
|
+
"",
|
|
164
|
+
"## Instructions",
|
|
165
|
+
"",
|
|
166
|
+
...FRAME_ITEMS,
|
|
167
|
+
"**implement:** read `INPUT_WAVE_BRIEF` (the complete plan mirror — every `### Task N:` of the wave + the plan's `## Constraints` section, fresh-extracted at dispatch). `WAVE` = this round's wave (the task list); implement ALL tasks of the wave, never a subset. `CONFIRMED_SEAMS` in the brief → apply as-is; else propose test boundaries in the report, then invoke **`mattpocock-skills:implement`**. Write the handoff draft at `OUTPUT_HANDOFF` per `## Handoff schema` BEFORE the return block: `status` (APPROVED once applied, else BLOCKED + `failure_category`) and `artifacts` (the prescribed `OUTPUT_REPORT`/`OUTPUT_EVIDENCE` paths from the round context — the `{family}-{key}-` canonical names, zero free naming).",
|
|
168
|
+
EVIDENCE_ITEM,
|
|
169
|
+
...LICENSE_ITEMS,
|
|
170
|
+
...SCHEMA_SECTION,
|
|
171
|
+
];
|
|
172
|
+
|
|
173
|
+
/** The fix row's fixed prefix — header + instructions + the shared work tail. */
|
|
174
|
+
const FIX_TYPED_INSTRUCTIONS: readonly string[] = [
|
|
175
|
+
"**Verify-then-apply:** verify each finding against the codebase's actual state before changing anything — apply a finding only when it is technically sound; a finding that does not hold up stays open with a note (never blind adoption). Apply findings one at a time and test each one before moving on.",
|
|
176
|
+
"**Conditional TDD:** when a finding requires a behavior change and the change has no test coverage, write or adjust the tests first and drive the change red→green — the discipline applies conditionally, never as a blanket demand on every finding.",
|
|
177
|
+
];
|
|
178
|
+
|
|
179
|
+
/** The fix row's fixed prefix — header + instructions + the shared work tail. */
|
|
180
|
+
const FIX_SHELL: readonly string[] = [
|
|
181
|
+
"# CDD dispatch — fix round",
|
|
182
|
+
"",
|
|
183
|
+
"## Instructions",
|
|
184
|
+
"",
|
|
185
|
+
...FRAME_ITEMS,
|
|
186
|
+
...FIX_TYPED_INSTRUCTIONS,
|
|
187
|
+
"**fix:** read `INPUT_FINDINGS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_DOC` on the branch/doc lines — the plan document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_FINDINGS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
|
|
188
|
+
EVIDENCE_ITEM,
|
|
189
|
+
...LICENSE_ITEMS,
|
|
190
|
+
// T5 (v0.3) — The work face's ONE strict-schema sentence: every top-level draft
|
|
191
|
+
// field comes from the `## Handoff schema` declared properties (the fields'
|
|
192
|
+
// single source is the injected fence below — never a second enumeration in the
|
|
193
|
+
// shell prose; a fix child that mirrors the source review carrier's top-level
|
|
194
|
+
// shape trips the engine's read-back BLOCK, so the sentence names the schema as
|
|
195
|
+
// the field source explicitly).
|
|
196
|
+
"**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — the declaration is the field source, zero extra keys.",
|
|
197
|
+
...SCHEMA_SECTION,
|
|
198
|
+
];
|
|
199
|
+
|
|
200
|
+
/** The docs-fix row's fixed prefix — header + instructions (no evidence — the
|
|
201
|
+
* docs-fix face writes no evidence file). */
|
|
202
|
+
const DOCS_FIX_SHELL: readonly string[] = [
|
|
203
|
+
"# CDD dispatch — docs-fix round",
|
|
204
|
+
"",
|
|
205
|
+
"## Instructions",
|
|
206
|
+
"",
|
|
207
|
+
...FRAME_ITEMS,
|
|
208
|
+
"**docs-fix:** apply `INPUT_FINDINGS` (all severities) directly to `INPUT_DOC`, removing fixed findings; record the path in `artifacts.doc`; empty `findings` = all fixed. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema`; the engine derives the conclusion from the residual findings; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
|
|
209
|
+
...LICENSE_ITEMS,
|
|
210
|
+
// T5 (v0.3) — The findings face's ONE strict-schema sentence: same schema-first
|
|
211
|
+
// directive as the work shell, naming the required `findings` (carried over from
|
|
212
|
+
// the source review carrier verbatim — the required key is told how to fill, so
|
|
213
|
+
// the sentence never contradicts the findings carrier's own required gate; the
|
|
214
|
+
// work shell's field list is never copied here, and no field enumeration rides
|
|
215
|
+
// the findings shell's prose either).
|
|
216
|
+
"**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — `findings` (required) rides over from `INPUT_FINDINGS` verbatim, unmodified; the declaration is the field source, zero extra keys.",
|
|
217
|
+
...SCHEMA_SECTION,
|
|
218
|
+
];
|
|
219
|
+
|
|
220
|
+
/** The review variants' shared instruction text — the review's mode rule (the
|
|
221
|
+
* criteria body + the lens vocabulary ride per-type fixed items below). */
|
|
222
|
+
const REVIEW_ITEM =
|
|
223
|
+
"**review:** review the criteria below against the reference face named in the round context. Wave reviews judge `INPUT_WAVE_BRIEF` (the complete plan mirror); the branch/spec/plan reviews judge `INPUT_DOC`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status.";
|
|
224
|
+
|
|
225
|
+
/** The review mode's shared reduced tail — the only dynamic region of every review
|
|
226
|
+
* variant (the criteria/lens are fixed-prefix per type, never here). Each review
|
|
227
|
+
* type carries its own referent (wave → `INPUT_WAVE_BRIEF`; branch/spec/plan →
|
|
228
|
+
* `INPUT_DOC`); the branch review additionally carries `BASE_BRANCH` (the scope
|
|
229
|
+
* anchor). Empty slots are dropped by the assembler. */
|
|
230
|
+
const REVIEW_CONTEXT: readonly string[] = [
|
|
231
|
+
"## Round context",
|
|
232
|
+
"",
|
|
233
|
+
"- `ROLE`: {{ROLE}}",
|
|
234
|
+
"- `WAVE`: {{WAVE}}",
|
|
235
|
+
"- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
|
|
236
|
+
"- `INPUT_DOC`: {{INPUT_DOC}}",
|
|
237
|
+
"- `BASE_BRANCH`: {{BASE_BRANCH}}",
|
|
238
|
+
"- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
|
|
239
|
+
"- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
|
|
240
|
+
"- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
|
|
241
|
+
"- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
|
|
242
|
+
];
|
|
243
|
+
|
|
244
|
+
/** The work-mode dispatch rows — implement / fix / docs-fix (§3.5; the review rows
|
|
245
|
+
* are REVIEW_VARIANTS). */
|
|
246
|
+
const MODE_PROMPTS: Readonly<Record<WorkModeRowKey, ModePromptRow>> = {
|
|
247
|
+
implement: {
|
|
248
|
+
mode: "implement",
|
|
249
|
+
shell: IMPLEMENT_SHELL,
|
|
250
|
+
roundContext: [
|
|
251
|
+
"## Round context",
|
|
252
|
+
"",
|
|
253
|
+
"- `ROLE`: {{ROLE}}",
|
|
254
|
+
"- `WAVE`: {{WAVE}}",
|
|
255
|
+
"- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
|
|
256
|
+
// find #4 + #5 — the plan's ## Constraints rides the wave brief mirror;
|
|
257
|
+
// the OUTPUT_* write paths are prescribed (the {family}-{key}- canonical names)
|
|
258
|
+
"- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
|
|
259
|
+
"- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
|
|
260
|
+
"- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
|
|
261
|
+
"- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
|
|
262
|
+
"- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
|
|
263
|
+
],
|
|
264
|
+
},
|
|
265
|
+
fix: {
|
|
266
|
+
mode: "fix",
|
|
267
|
+
shell: FIX_SHELL,
|
|
268
|
+
roundContext: [
|
|
269
|
+
"## Round context",
|
|
270
|
+
"",
|
|
271
|
+
"- `ROLE`: {{ROLE}}",
|
|
272
|
+
"- `WAVE`: {{WAVE}}",
|
|
273
|
+
"- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
|
|
274
|
+
"- `INPUT_DOC`: {{INPUT_DOC}}",
|
|
275
|
+
"- `INPUT_FINDINGS`: {{INPUT_FINDINGS}}",
|
|
276
|
+
"- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
|
|
277
|
+
"- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
|
|
278
|
+
"- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
|
|
279
|
+
"- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
|
|
280
|
+
"- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
|
|
281
|
+
],
|
|
282
|
+
},
|
|
283
|
+
"docs-fix": {
|
|
284
|
+
mode: "docs-fix",
|
|
285
|
+
shell: DOCS_FIX_SHELL,
|
|
286
|
+
roundContext: [
|
|
287
|
+
"## Round context",
|
|
288
|
+
"",
|
|
289
|
+
"- `ROLE`: {{ROLE}}",
|
|
290
|
+
"- `WAVE`: {{WAVE}}",
|
|
291
|
+
"- `INPUT_DOC`: {{INPUT_DOC}}",
|
|
292
|
+
"- `INPUT_FINDINGS`: {{INPUT_FINDINGS}}",
|
|
293
|
+
"- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
|
|
294
|
+
"- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
|
|
295
|
+
"- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
|
|
296
|
+
"- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
|
|
297
|
+
],
|
|
298
|
+
},
|
|
299
|
+
};
|
|
300
|
+
|
|
301
|
+
/** The four-type review criteria — the review prompts' fixed criteria body (P4; the
|
|
302
|
+
* spec/plan URC rows migrated from the dispatch table at the v1.8 closeout — their
|
|
303
|
+
* single typed home). */
|
|
304
|
+
export const REVIEWS = {
|
|
305
|
+
wave: {
|
|
306
|
+
lensEnum: ["standards", "spec", "buildability"],
|
|
307
|
+
axesGuide:
|
|
308
|
+
"Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run `git diff origin/<BASE_BRANCH>..HEAD` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (`**Files:**` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. Single agent, four axes.",
|
|
309
|
+
},
|
|
310
|
+
branch: {
|
|
311
|
+
lensEnum: ["standards", "spec", "buildability"],
|
|
312
|
+
axesGuide:
|
|
313
|
+
"Same four axes as task (branch-wide health: run `git diff origin/<BASE_BRANCH>..HEAD` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + 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.",
|
|
314
|
+
},
|
|
315
|
+
spec: {
|
|
316
|
+
lensEnum: ["completeness", "consistency", "clarity"],
|
|
317
|
+
axesGuide:
|
|
318
|
+
"Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding",
|
|
319
|
+
},
|
|
320
|
+
plan: {
|
|
321
|
+
lensEnum: ["completeness", "decomposition", "buildability"],
|
|
322
|
+
axesGuide:
|
|
323
|
+
"Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding",
|
|
324
|
+
},
|
|
325
|
+
} as const satisfies ReviewGuides;
|
|
326
|
+
|
|
327
|
+
/** The per-type facts the review variants compose at module-const time (the lens
|
|
328
|
+
* vocabularies + the criteria bodies — single data references, never restates). */
|
|
329
|
+
const REVIEWS_WAVE_LENS = REVIEWS.wave.lensEnum.join(" | ");
|
|
330
|
+
const REVIEWS_BRANCH_LENS = REVIEWS.branch.lensEnum.join(" | ");
|
|
331
|
+
const REVIEWS_SPEC_LENS = REVIEWS.spec.lensEnum.join(" | ");
|
|
332
|
+
const REVIEWS_PLAN_LENS = REVIEWS.plan.lensEnum.join(" | ");
|
|
333
|
+
const REVIEW_WAVE_AXES = REVIEWS.wave.axesGuide;
|
|
334
|
+
const REVIEW_BRANCH_AXES = REVIEWS.branch.axesGuide;
|
|
335
|
+
const REVIEW_SPEC_URC = REVIEWS.spec.axesGuide;
|
|
336
|
+
const REVIEW_PLAN_URC = REVIEWS.plan.axesGuide;
|
|
337
|
+
|
|
338
|
+
/** The review mode's four per-type rows (§3.7) — each variant's fixed prefix folds
|
|
339
|
+
* its criteria + lens INLINE (the `INPUT_CRITERIA`/`INPUT_LENS` round-context
|
|
340
|
+
* tokens are gone), and shares the REVIEW_CONTEXT dynamic tail. */
|
|
341
|
+
const REVIEW_VARIANTS: Readonly<Record<TargetType, ModePromptRow>> = {
|
|
342
|
+
wave: {
|
|
343
|
+
mode: "review",
|
|
344
|
+
shell: [
|
|
345
|
+
"# CDD dispatch — review round",
|
|
346
|
+
"",
|
|
347
|
+
"## Instructions",
|
|
348
|
+
"",
|
|
349
|
+
...FRAME_ITEMS,
|
|
350
|
+
REVIEW_ITEM,
|
|
351
|
+
`**Lens labels:** one of \`${REVIEWS_WAVE_LENS}\` — every finding MUST carry its \`lens\`.`,
|
|
352
|
+
`**Criteria — wave:** ${REVIEW_WAVE_AXES}`,
|
|
353
|
+
...LICENSE_ITEMS,
|
|
354
|
+
...SCHEMA_SECTION,
|
|
355
|
+
],
|
|
356
|
+
roundContext: REVIEW_CONTEXT,
|
|
357
|
+
},
|
|
358
|
+
branch: {
|
|
359
|
+
mode: "review",
|
|
360
|
+
shell: [
|
|
361
|
+
"# CDD dispatch — review round",
|
|
362
|
+
"",
|
|
363
|
+
"## Instructions",
|
|
364
|
+
"",
|
|
365
|
+
...FRAME_ITEMS,
|
|
366
|
+
REVIEW_ITEM,
|
|
367
|
+
`**Lens labels:** one of \`${REVIEWS_BRANCH_LENS}\` — every finding MUST carry its \`lens\`.`,
|
|
368
|
+
`**Criteria — branch:** ${REVIEW_BRANCH_AXES}`,
|
|
369
|
+
...LICENSE_ITEMS,
|
|
370
|
+
...SCHEMA_SECTION,
|
|
371
|
+
],
|
|
372
|
+
roundContext: REVIEW_CONTEXT,
|
|
373
|
+
},
|
|
374
|
+
spec: {
|
|
375
|
+
mode: "review",
|
|
376
|
+
shell: [
|
|
377
|
+
"# CDD dispatch — review round",
|
|
378
|
+
"",
|
|
379
|
+
"## Instructions",
|
|
380
|
+
"",
|
|
381
|
+
...FRAME_ITEMS,
|
|
382
|
+
REVIEW_ITEM,
|
|
383
|
+
`**Lens labels:** one of \`${REVIEWS_SPEC_LENS}\` — every finding MUST carry its \`lens\`.`,
|
|
384
|
+
`**Criteria — spec:** ${REVIEW_SPEC_URC}`,
|
|
385
|
+
...LICENSE_ITEMS,
|
|
386
|
+
...SCHEMA_SECTION,
|
|
387
|
+
],
|
|
388
|
+
roundContext: REVIEW_CONTEXT,
|
|
389
|
+
},
|
|
390
|
+
plan: {
|
|
391
|
+
mode: "review",
|
|
392
|
+
shell: [
|
|
393
|
+
"# CDD dispatch — review round",
|
|
394
|
+
"",
|
|
395
|
+
"## Instructions",
|
|
396
|
+
"",
|
|
397
|
+
...FRAME_ITEMS,
|
|
398
|
+
REVIEW_ITEM,
|
|
399
|
+
`**Lens labels:** one of \`${REVIEWS_PLAN_LENS}\` — every finding MUST carry its \`lens\`.`,
|
|
400
|
+
`**Criteria — plan:** ${REVIEW_PLAN_URC}`,
|
|
401
|
+
...LICENSE_ITEMS,
|
|
402
|
+
...SCHEMA_SECTION,
|
|
403
|
+
],
|
|
404
|
+
roundContext: REVIEW_CONTEXT,
|
|
405
|
+
},
|
|
406
|
+
};
|
|
407
|
+
|
|
408
|
+
/** The `## Return` zone — the single block contract (v1.9: the child's content
|
|
409
|
+
* lives in the draft file, the block is the pointer every mode returns). */
|
|
410
|
+
const RETURN_ZONE: ReturnZone = {
|
|
411
|
+
RETURN_STDOUT_BLOCK: [
|
|
412
|
+
"## Return",
|
|
413
|
+
"",
|
|
414
|
+
"Output exactly 2 lines — this block is the FINAL output; nothing may follow it:",
|
|
415
|
+
"",
|
|
416
|
+
"```",
|
|
417
|
+
"status: <APPROVED|BLOCKED>",
|
|
418
|
+
"artifacts: report=<path> test_evidence=<path>",
|
|
419
|
+
"```",
|
|
420
|
+
"",
|
|
421
|
+
"RETURN_STDOUT_BLOCK (one contract): the handoff content (findings/notes/evidence) lives in the draft at `OUTPUT_HANDOFF` — this block is the pointer. Review/docs-fix rounds state `status: APPROVED` (their conclusion derives from the draft's findings); work rounds state the concluding status. Never emit the 3rd `counters:` / 4th `next:` lines (the engine appends them). Any non-`APPROVED` status (e.g. `NEEDS_CONTEXT`) → collapsed to `BLOCKED` + exit 1.",
|
|
422
|
+
"",
|
|
423
|
+
"The `artifacts:` line's paths are the round context's prescribed `OUTPUT_REPORT`/`OUTPUT_EVIDENCE` values — copy them verbatim (zero free naming; a declared path deviating from the canonical name is corrected to it and flagged on the carrier's notes).",
|
|
424
|
+
],
|
|
425
|
+
};
|
|
426
|
+
|
|
427
|
+
/** The token registry — the union across every mode's round context + the shell's
|
|
428
|
+
* schema slot (the v1.8 normalized vocabulary; the assembly face supplies every
|
|
429
|
+
* declared slot, empty where the mode does not consume it — the round-context
|
|
430
|
+
* renderer drops the empty-valued lines). REVIEW_TYPE is the review-mode row
|
|
431
|
+
* selector (supplied but never rendered). */
|
|
432
|
+
const TOKENS: readonly TemplateToken[] = [
|
|
433
|
+
{ name: "BASE_BRANCH", zone: "round-context" },
|
|
434
|
+
{ name: "HANDOFF_SCHEMA", zone: "shell" },
|
|
435
|
+
{ name: "INPUT_DOC", zone: "round-context" },
|
|
436
|
+
{ name: "INPUT_FINDINGS", zone: "round-context" },
|
|
437
|
+
{ name: "INPUT_WAVE_BRIEF", zone: "round-context" },
|
|
438
|
+
// find #5 — the prescribed artifact write paths (the {family}-{key}-{artifact}
|
|
439
|
+
// single naming; the brief is a pure read input with no write slot).
|
|
440
|
+
{ name: "OUTPUT_REPORT", zone: "round-context" },
|
|
441
|
+
{ name: "OUTPUT_EVIDENCE", zone: "round-context" },
|
|
442
|
+
{ name: "OUTPUT_HANDOFF", zone: "round-context" },
|
|
443
|
+
{ name: "REVIEW_TYPE", zone: "round-context" },
|
|
444
|
+
{ name: "ROLE", zone: "round-context" },
|
|
445
|
+
{ name: "WAVE", zone: "round-context" },
|
|
446
|
+
{ name: "WORKSPACE_DIR", zone: "round-context" },
|
|
447
|
+
{ name: "WORKSPACE_ID", zone: "round-context" },
|
|
448
|
+
];
|
|
449
|
+
|
|
450
|
+
/** The clause partials — the `{{> cl:…}}` forms of the discipline clauses. */
|
|
451
|
+
export const CLAUSES = {
|
|
452
|
+
"cl:english-comments":
|
|
453
|
+
"Write code comments and shipped prose in English only — English-primary (no other-language comment blocks, no translated mirrors).",
|
|
454
|
+
"cl:eof-newline":
|
|
455
|
+
"Every text file must end with exactly one newline (EOF newline): no missing final newline and no trailing blank lines.",
|
|
456
|
+
"cl:no-full-tree-find":
|
|
457
|
+
"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.",
|
|
458
|
+
"cl:bash-stall-limit":
|
|
459
|
+
"If a Bash command stalls without progress for more than 10 minutes, terminate it and substitute an equivalent, lighter command.",
|
|
460
|
+
"cl:plan-freeze":
|
|
461
|
+
"Approved plan/spec files are frozen — zero modification authority; any change needed is reported to the orchestrator through findings, never edited in place.",
|
|
462
|
+
"cl:atomic-commit":
|
|
463
|
+
"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.",
|
|
464
|
+
"cl:self-validate":
|
|
465
|
+
"Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
|
|
466
|
+
} as const;
|
|
467
|
+
|
|
468
|
+
/** The dispatch-prompt data plane — the typed template-contract surface. $version 7
|
|
469
|
+
* is the single-reference-face shape: one doc anchor per line (INPUT_DOC /
|
|
470
|
+
* INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the two-line return
|
|
471
|
+
* contract, and the per-type review criterion shells. */
|
|
472
|
+
export const TEMPLATE_PROMPT = {
|
|
473
|
+
$version: 7,
|
|
474
|
+
modes: MODE_PROMPTS,
|
|
475
|
+
reviews: REVIEW_VARIANTS,
|
|
476
|
+
return: RETURN_ZONE,
|
|
477
|
+
tokens: TOKENS,
|
|
478
|
+
clauses: CLAUSES,
|
|
479
|
+
} as const satisfies TemplatePrompt;
|
|
480
|
+
|
|
481
|
+
/** The ROLE vocabulary — the four work-modes of the dispatch table (§3.5). */
|
|
482
|
+
export const WORK_MODES: readonly WorkMode[] = ["implement", "fix", "review", "docs-fix"];
|
|
483
|
+
|
|
484
|
+
/**
|
|
485
|
+
* The template assembler — the ONE renderer over the typed template-prompt data
|
|
486
|
+
* plane. Construction reads the typed contract (the module's declared data —
|
|
487
|
+
* no file reads, no second copy). render(values) selects the row by the ROLE value
|
|
488
|
+
* (the review mode by ROLE + REVIEW_TYPE) — the row's fixed prefix + the single
|
|
489
|
+
* return contract + its reduced round context (empty-value keys not emitted).
|
|
490
|
+
*/
|
|
491
|
+
export class TemplateAssembler {
|
|
492
|
+
readonly #contract: TemplatePrompt;
|
|
493
|
+
|
|
494
|
+
constructor() {
|
|
495
|
+
this.#contract = TEMPLATE_PROMPT;
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/** The return formats the contract declares — the single block contract (v1.9:
|
|
499
|
+
* one format; every pre-v1.9 return variant is retired). */
|
|
500
|
+
returnFormats(): readonly string[] {
|
|
501
|
+
return Object.keys(this.#contract.return);
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
/** The tokens the contract declares (the union across every mode — all zones). */
|
|
505
|
+
declaredTokens(): readonly string[] {
|
|
506
|
+
return this.#contract.tokens.map((token) => token.name);
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
/** The work-modes of the dispatch table — the ROLE vocabulary. */
|
|
510
|
+
workModes(): readonly WorkMode[] {
|
|
511
|
+
return WORK_MODES;
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
/** Assemble the full dispatch template for a role with the slot values — the
|
|
515
|
+
* row's fixed prefix + the single return contract + its reduced round context
|
|
516
|
+
* (empty-value keys omitted). */
|
|
517
|
+
render(values: TemplateValues): string {
|
|
518
|
+
this.#gate(values);
|
|
519
|
+
const row = this.#rowOf(values);
|
|
520
|
+
const zones: Record<string, string> = {
|
|
521
|
+
shell: this.#joinLines(row.shell),
|
|
522
|
+
return: this.#joinLines(this.#contract.return.RETURN_STDOUT_BLOCK),
|
|
523
|
+
"round-context": this.#contextLines(row, values),
|
|
524
|
+
};
|
|
525
|
+
return this.#fill([zones.shell, zones.return, zones["round-context"]].join("\n\n"), values);
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
#joinLines(lines: readonly string[]): string {
|
|
529
|
+
return lines.join("\n");
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/** The row of a ROLE — the review mode's per-type variant (selected by the
|
|
533
|
+
* REVIEW_TYPE discriminant), the work modes from the modes table. */
|
|
534
|
+
#rowOf(values: TemplateValues): ModePromptRow {
|
|
535
|
+
if (values.ROLE === "review") {
|
|
536
|
+
const row = this.#contract.reviews[values.REVIEW_TYPE as TargetType];
|
|
537
|
+
if (row === undefined) {
|
|
538
|
+
throw new Error(
|
|
539
|
+
`template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`,
|
|
540
|
+
);
|
|
541
|
+
}
|
|
542
|
+
return row;
|
|
543
|
+
}
|
|
544
|
+
const row = this.#contract.modes[values.ROLE as WorkModeRowKey];
|
|
545
|
+
if (row === undefined) {
|
|
546
|
+
throw new Error(
|
|
547
|
+
`template work-mode not declared: ${values.ROLE === undefined ? "(missing ROLE)" : values.ROLE}`,
|
|
548
|
+
);
|
|
549
|
+
}
|
|
550
|
+
return row;
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
/** The reduced round-context section — the row's subset, a key whose value is
|
|
554
|
+
* empty omitted (only present facts land in the dynamic region). */
|
|
555
|
+
#contextLines(row: ModePromptRow, values: TemplateValues): string {
|
|
556
|
+
const lines: string[] = [];
|
|
557
|
+
for (const line of row.roundContext) {
|
|
558
|
+
const slot = line.match(/\{\{([A-Z0-9_]+)\}\}/)?.[1];
|
|
559
|
+
if (slot !== undefined && values[slot] === "") continue;
|
|
560
|
+
lines.push(line);
|
|
561
|
+
}
|
|
562
|
+
return lines.join("\n");
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
/** The hard gates — a known ROLE (+ its REVIEW_TYPE for reviews), every declared
|
|
566
|
+
* token supplied (empty allowed — a mode's non-consumed slots are legitimately
|
|
567
|
+
* empty and merely not emitted), no undeclared values, the single return
|
|
568
|
+
* contract declared, and every round-context name the mode's shell prose
|
|
569
|
+
* references carried by that mode's layout (shell↔layout consistency). */
|
|
570
|
+
#gate(values: TemplateValues): void {
|
|
571
|
+
const role = values.ROLE;
|
|
572
|
+
const row =
|
|
573
|
+
role === undefined
|
|
574
|
+
? undefined
|
|
575
|
+
: role === "review"
|
|
576
|
+
? this.#reviewRow(values)
|
|
577
|
+
: this.#workRow(role);
|
|
578
|
+
if (row === undefined) {
|
|
579
|
+
const message =
|
|
580
|
+
role === "review"
|
|
581
|
+
? `template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`
|
|
582
|
+
: `template work-mode not declared: ${role === undefined ? "(missing ROLE)" : role}`;
|
|
583
|
+
throw new Error(message);
|
|
584
|
+
}
|
|
585
|
+
for (const token of this.#contract.tokens) {
|
|
586
|
+
if (values[token.name] === undefined) {
|
|
587
|
+
throw new Error(`template token ${token.name} (${token.zone}) has no value`);
|
|
588
|
+
}
|
|
589
|
+
}
|
|
590
|
+
for (const name of Object.keys(values)) {
|
|
591
|
+
if (!this.#contract.tokens.some((token) => token.name === name)) {
|
|
592
|
+
throw new Error(`template value provided for undeclared token ${name}`);
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
this.#assertShellLayout(row);
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
/** The shell↔layout consistency assertion (§3.6): every round-context name the
|
|
599
|
+
* mode's shell prose references (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) must be
|
|
600
|
+
* carried by that mode's round-context layout ∪ the shared return tail — a shell
|
|
601
|
+
* claiming a slot its layout never carries is a construction error. This closes
|
|
602
|
+
* the "claimed but not carried" blind spot the token gates cannot see (the shell
|
|
603
|
+
* prose is not `{{slot}}`-templated). */
|
|
604
|
+
#assertShellLayout(row: ModePromptRow): void {
|
|
605
|
+
const naming = /\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g;
|
|
606
|
+
const namesOf = (text: string): string[] => text.match(naming) ?? [];
|
|
607
|
+
const allowed = new Set<string>([
|
|
608
|
+
...row.roundContext.flatMap((line) => namesOf(line)),
|
|
609
|
+
...namesOf(this.#joinLines(this.#contract.return.RETURN_STDOUT_BLOCK)),
|
|
610
|
+
]);
|
|
611
|
+
for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
|
|
612
|
+
if (!allowed.has(name)) {
|
|
613
|
+
throw new Error(
|
|
614
|
+
`template mode ${row.mode} shell references ${name} not carried by its round context`,
|
|
615
|
+
);
|
|
616
|
+
}
|
|
617
|
+
}
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
/** The review variant of a REVIEW_TYPE (verified in the gate). */
|
|
621
|
+
#reviewRow(values: TemplateValues): ModePromptRow | undefined {
|
|
622
|
+
return this.#contract.reviews[values.REVIEW_TYPE as TargetType];
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
/** The work-mode row of a ROLE (verified in the gate). */
|
|
626
|
+
#workRow(role: string): ModePromptRow | undefined {
|
|
627
|
+
return this.#contract.modes[role as WorkModeRowKey];
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/** Slot resolution — the `{{> cl:…}}` clause partials resolve from the contract's
|
|
631
|
+
* clauses container, the `{{TOKEN}}` slots from the values; any unresolved form
|
|
632
|
+
* (a clause absent from the container, a slot with no value) is a hard error. */
|
|
633
|
+
#fill(text: string, values: TemplateValues): string {
|
|
634
|
+
return text
|
|
635
|
+
.replace(/\{\{> cl:([A-Za-z0-9-]+)\}\}/g, (_match, name: string) => {
|
|
636
|
+
const clause = this.#contract.clauses[`cl:${name}`];
|
|
637
|
+
if (clause === undefined) {
|
|
638
|
+
throw new Error(`template clause cl:${name} not declared`);
|
|
639
|
+
}
|
|
640
|
+
return clause;
|
|
641
|
+
})
|
|
642
|
+
.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_match, name: string) => {
|
|
643
|
+
const value = values[name];
|
|
644
|
+
if (value === undefined) {
|
|
645
|
+
throw new Error(`template slot not resolved: ${name}`);
|
|
646
|
+
}
|
|
647
|
+
return value;
|
|
648
|
+
});
|
|
649
|
+
}
|
|
650
|
+
}
|