@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,314 +0,0 @@
1
- // packages/cdd-engine/src-next/face/words.ts
2
- // T10 — the single word table (design spec §1.2: one table, one derivation chain).
3
- // The five-way lexicon split of the old tree (words content → contract-lexicon.json
4
- // → schema shape → word-table accessor → guard-lexicon) converges into ONE word
5
- // table with three families served by one class:
6
- //
7
- // capsule — the capsule-station words: the capsule keys (status · blocker ·
8
- // handoff, the pinned emit order), the `next:` route station + the stderr
9
- // stations, the status vocabulary and the route classifier words. Every
10
- // byte the capsule emits rides this family — a reorder is a red test.
11
- // guard — the guard-ban words: the retired-vocabulary ban rows (STALE / GATE /
12
- // shape) the guards assert absent from the live faces. This is the ban
13
- // table's data-source face — the guard scan releases these rows as its
14
- // own data, so the words can live in the shipped table (the
15
- // data-row-release stance of the retired residue guard).
16
- // locale — the locale face (T19, the P7 translation system): each row carries
17
- // `{ en: canonical, zh?: Chinese alias }`, the locale key set is the `langs`
18
- // projection source (locale-consuming faces derive from it, never a
19
- // hardcoded list), and the issue-label rows are the human-readable
20
- // rendering face's locale words. The Translator (contract/translate.ts)
21
- // speaks the whole plane from this face — the word table is the single
22
- // translation data (a new word is a new data row, never a code branch).
23
- //
24
- // The vocabulary is English-primary and death-stable: v1 keeps the same word face
25
- // the consumers already read (status · blocker · handoff · next:) — a steady state,
26
- // never a compatibility shim. The capsule class reads ALL its words through this
27
- // instance (constructor injection) — the guaranteed "one table, zero second table".
28
- // The capsule machine face (status · next: · CDD_BLOCKED:) is never a locale row —
29
- // the machine surface stays English-constant, never localizeable.
30
- //
31
- // Module-level exports are types / the declared word data / the class — zero
32
- // behavior-carrying bare functions (the plan's zero-bare-function discipline).
33
-
34
- import type { LocalizedWord, WordLocaleFace } from "../contract/translate.ts";
35
-
36
- // ---------------------------------------------------------------------------
37
- // capsule — the station-word family (the declared steady word face)
38
- // ---------------------------------------------------------------------------
39
-
40
- /** The capsule emit keys — the pinned `status · blocker · handoff` order. */
41
- export type CapsuleKey = "status" | "blocker" | "handoff";
42
-
43
- /** The route station kinds — the addressed channels of the command surface. */
44
- export type StationKind = "next" | "blocked" | "warn" | "cliMissing";
45
-
46
- /** The route classifier words — the station vocabulary the `next:` line renders
47
- * (v1.20: the `none` word is retired — closure is `done`, never "no suggestion";
48
- * v1.25: `implement` — the dispatch-ready `next:` literal's verb for a ready wave;
49
- * `docType` — the missing-declaration BLOCK wording the capsule's unified next face
50
- * renders over the CDD_BLOCKED station, spec §12 · D34). */
51
- export type RouteWordKind =
52
- | "done"
53
- | "review"
54
- | "fix"
55
- | "implement"
56
- | "docType"
57
- | "frontmatterParse";
58
-
59
- /** The wave-gate BLOCK wording rows — the vocabulary the WaveGate verdicts render
60
- * (the v1.21 word-table pin: the gate's prompt wording rides the word table, never a CLI literal).
61
- * Each row is a placeholder template verbatim-filled by the wave gate; the braces
62
- * ({requested}/{open}/{phase}) are the fill slots, part of the row. (v1.28 — the
63
- * heterogeneous row retired: the wave-unitary ledger holds one row per wave, so a
64
- * mixed-phase anomaly is structurally impossible.) */
65
- export interface WaveGateWords {
66
- /** The split/subset BLOCK — a `--tasks` set that splits or mismatches the derived wave. */
67
- split: string;
68
- /** The wrong-phase BLOCK — the open wave is at a phase different from the requested verb. */
69
- wrongPhase: string;
70
- }
71
-
72
- /** The pre-flight BLOCK wording rows — the lifecycle pre-flight seam's refusal
73
- * vocabulary (P4.1 T1 — the word-table pin: the seam's CDD_BLOCKED wording rides
74
- * the table, never a CLI restate). The braces are fill slots ({count}); the
75
- * wave-gate rows above stay the wave gate's own surface. */
76
- export interface PreflightWords {
77
- /** The dirty-tree BLOCK — a dirty working tree refuses every work dispatch. */
78
- dirtyTree: string;
79
- /** The graph BLOCK — the plan's DependsOn graph fails to validate. */
80
- graph: string;
81
- /** The doc-contract BLOCK — the target doc fails the structural contract. */
82
- docContract: string;
83
- }
84
-
85
- /** The capsule word rows — every word the capsule face emits, one table. */
86
- export const CAPSULE_WORDS = {
87
- /** The capsule emit keys in order (a reorder is a red test — the pinned face). */
88
- keys: ["status", "blocker", "handoff"] as const satisfies readonly CapsuleKey[],
89
- /** The `·`-separator token of the capsule line. */
90
- separator: " · ",
91
- /** The status vocabulary — the five handoff-conclusion values. */
92
- status: ["APPROVED", "BLOCKED", "CHANGES_REQUESTED", "REVIEW_FIX", "TIMEOUT"] as const,
93
- /** The route stations — the `: `-suffixed channel anchors. */
94
- stations: {
95
- next: "next:",
96
- blocked: "CDD_BLOCKED:",
97
- warn: "CDD_WARN:",
98
- cliMissing: "CDD_CLI_MISSING:",
99
- } as const,
100
- /** The route classifier words of the `next:` line. */
101
- routeWords: {
102
- done: "done",
103
- review: "review",
104
- fix: "fix",
105
- implement: "implement",
106
- docType:
107
- "the doc declares no `doc-type:` key — add `doc-type: <overall-spec|phase-spec|single-spec|plan>` to the doc's front-matter (spec §12 · D34) and re-run",
108
- frontmatterParse:
109
- "the doc's front-matter is not valid YAML: {reason} on line {line}, column {column} (`{source}`) — quote values that start with `[` or `{` (a YAML flow-sequence start) and re-run",
110
- } as const,
111
- /** The wave-gate BLOCK wording rows (v1.21) — the highest-arity pre-flight refusal
112
- * vocabulary, single-sourced (the gate fills the placeholders, never a re-type). */
113
- waveGate: {
114
- split:
115
- "the requested wave ({requested}) splits/mismatches the derived wave ({open}) — dispatch the full derived wave",
116
- wrongPhase: "the open wave is at {phase} — run cdd {phase} first",
117
- } as const satisfies WaveGateWords,
118
- /** The pre-flight BLOCK wording rows (P4.1 T1) — the seam's refusal vocabulary,
119
- * single-sourced (the seam fills the {count} slot, never a re-type). */
120
- preflight: {
121
- dirtyTree:
122
- "the working tree is dirty — commit or discard your changes, then re-run the same command",
123
- graph: "the plan graph has {count} edge violation(s) — fix the **DependsOn** edges first",
124
- docContract: "the target document fails the doc-contract — fix its structural findings first",
125
- } as const satisfies PreflightWords,
126
- } as const;
127
-
128
- // ---------------------------------------------------------------------------
129
- // guard — the ban-word family (the retired-vocabulary ban rows, self-declared)
130
- // ---------------------------------------------------------------------------
131
-
132
- /** The guard-ban row shape — one banned token of the guard-vocabulary families. */
133
- export interface GuardBanWord {
134
- /** The banned token the live faces must not carry. */
135
- token: string;
136
- }
137
-
138
- /** The guard-ban vocabulary — the STALE / GATE / shape ban rows the guards assert
139
- * absent from the live faces (the single-source ban table; the guard scan releases
140
- * this data source — the retired residue guard's data-row-release stance). */
141
- export const GUARD_BAN_WORDS = {
142
- /** The stale retired-mechanism tokens (the migration residue bans). */
143
- stale: [
144
- { token: "cursor-agent" },
145
- { token: "@ts-ignore" },
146
- { token: "@ts-expect-error" },
147
- { token: "build.config" },
148
- { token: "dev:stub" },
149
- { token: "@typescript/typescript6" },
150
- { token: "globalSetup" },
151
- { token: ".mjs" },
152
- ] as const satisfies readonly GuardBanWord[],
153
- /** The retired-gate channel tokens. */
154
- gate: [
155
- { token: "CDD_GATE" },
156
- { token: "cdd-gate-core" },
157
- { token: "gateDecide" },
158
- ] as const satisfies readonly GuardBanWord[],
159
- /** The retired engine-shape names the consumer surfaces must not restate. */
160
- shape: [
161
- { token: "3-line return block" },
162
- { token: "4th line counters" },
163
- { token: "return block" },
164
- ] as const satisfies readonly GuardBanWord[],
165
- } as const;
166
-
167
- /** The guard-ban family keys (stale / gate / shape). */
168
- export type GuardFamily = keyof typeof GUARD_BAN_WORDS;
169
-
170
- // ---------------------------------------------------------------------------
171
- // locale — the word-table locale face (the P7 translation-system data plane)
172
- // ---------------------------------------------------------------------------
173
-
174
- /** The locale key set — the word table's declared language keys. This is the
175
- * `langs` projection source: every locale-consuming face derives its language
176
- * vocabulary from this set (and its aliases from the rows below), never from a
177
- * hardcoded list — a locale-key change here re-projects the whole plane. */
178
- export const LOCALE_KEYS = ["en", "zh"] as const;
179
-
180
- /** One locale word row id — the issue-label family's word-id shape (`${type}.${segment}`). */
181
- export type LocaleWordId = `${string}.${string}`;
182
-
183
- /** The issue-body label rows — the human-readable rendering face's locale words, one
184
- * row per finding type × segment (keyed `${type}.${segment}`). Every label value the
185
- * issue renderer emits rides these rows — the word table's locale family (the label
186
- * set is data, never a second rendering table). The finding type × segment matrix is
187
- * complete (word-table test pins it); the capsule machine words are deliberately
188
- * absent — the machine face is not a translation surface. */
189
- export const ISSUE_LABEL_WORDS = {
190
- "bug.context": { en: "## Context", zh: "## 场景" },
191
- "bug.problem": { en: "## Problem", zh: "## 问题" },
192
- "bug.impact": { en: "## Impact", zh: "## 影响" },
193
- "bug.suggestedFix": { en: "## Suggested fix", zh: "## 建议修复" },
194
- "enhancement.context": { en: "## Context", zh: "## 场景" },
195
- "enhancement.problem": { en: "## Gap", zh: "## 差距" },
196
- "enhancement.impact": { en: "## Impact", zh: "## 影响" },
197
- "enhancement.suggestedFix": { en: "## Suggested direction", zh: "## 建议方向" },
198
- "chore.context": { en: "## Context", zh: "## 场景" },
199
- "chore.problem": { en: "## Gap", zh: "## 差距" },
200
- "chore.impact": { en: "## Impact", zh: "## 影响" },
201
- "chore.suggestedFix": { en: "## Suggested direction", zh: "## 建议方向" },
202
- } as const satisfies Readonly<Record<LocaleWordId, LocalizedWord>>;
203
-
204
- /** The finding-type vocabulary — the canonical issue-report type set, DERIVED from the
205
- * issue-label rows' `${type}.${segment}` key prefixes (deduped in row order). This is
206
- * the ONE source of the accepted finding types: the issue renderer's validation set
207
- * reads it, and the consumer `cdd-report` SKILL.md's declared `type ∈ {…}` domain is
208
- * pinned to it by the kairos-suite consistency gate (spec §3.3 ⑥ — never a second
209
- * hand-written list). */
210
- export const ISSUE_TYPES: readonly string[] = [
211
- ...new Set(Object.keys(ISSUE_LABEL_WORDS).map((id) => id.split(".")[0]!)),
212
- ];
213
-
214
- /** The charter anchor rows — the P7 canonicalize data plane: one row per legacy
215
- * Chinese charter marker the structure judge matches through the canonicalize view
216
- * (the doc-arch overall 决策组叶 / 上游先例背书). The family prefix `charter.` sits
217
- * parallel to the issue-label family — every row flows through localeRows() (the zh
218
- * knowledge lives ONLY here, never in a code branch or an element-table pattern). */
219
- export const CHARTER_WORDS = {
220
- "charter.group-leaf": { en: "group", zh: "组" },
221
- "charter.upstream-endorsements": { en: "Upstream Endorsements", zh: "上游先例背书" },
222
- } as const satisfies Readonly<Record<LocaleWordId, LocalizedWord>>;
223
-
224
- /**
225
- * Words — the single word table + accessor face. One instance serves every family:
226
- * the capsule station words (declared steady data), the guard ban words (declared
227
- * data) and the locale words (the translation/label data — the WordLocaleFace the
228
- * Translator and the locale consumers read). The capsule reads its whole vocabulary
229
- * through this class — the second table is excluded by construction.
230
- */
231
- export class Words implements WordLocaleFace {
232
- // -------------------------------------------------------------------------
233
- // capsule — the station-word family
234
- // -------------------------------------------------------------------------
235
-
236
- /** The capsule emit keys in order — status · blocker · handoff (the pinned byte
237
- * order the capsule renders by). */
238
- capsuleKeys(): readonly CapsuleKey[] {
239
- return CAPSULE_WORDS.keys;
240
- }
241
-
242
- /** The `·`-separator token of the capsule line. */
243
- capsuleSeparator(): string {
244
- return CAPSULE_WORDS.separator;
245
- }
246
-
247
- /** The status vocabulary — the five handoff-conclusion values. */
248
- statusVocab(): readonly string[] {
249
- return CAPSULE_WORDS.status;
250
- }
251
-
252
- /** One route station by its semantic kind (`next:` / `CDD_BLOCKED:` / …). */
253
- station(kind: StationKind): string {
254
- return CAPSULE_WORDS.stations[kind];
255
- }
256
-
257
- /** One route classifier word (`done` / `review` / `fix` / `implement`). */
258
- routeWord(kind: RouteWordKind): string {
259
- return CAPSULE_WORDS.routeWords[kind];
260
- }
261
-
262
- /** The wave-gate BLOCK wording rows — the vocabulary the WaveGate verdicts render
263
- * (single source: the gate fills the placeholders from these rows, never re-types). */
264
- waveGateWords(): WaveGateWords {
265
- return CAPSULE_WORDS.waveGate;
266
- }
267
-
268
- /** The pre-flight BLOCK wording rows — the seam's refusal vocabulary (single
269
- * source: the seam fills the placeholders from these rows, never re-types). */
270
- preflightWords(): PreflightWords {
271
- return CAPSULE_WORDS.preflight;
272
- }
273
-
274
- // -------------------------------------------------------------------------
275
- // locale — the word-table locale face (the langs projection + the label rows)
276
- // -------------------------------------------------------------------------
277
-
278
- /** The locale key set — the word table's declared languages (the `langs`
279
- * projection every locale-consuming face derives its vocabulary from). */
280
- localeKeys(): readonly string[] {
281
- return LOCALE_KEYS;
282
- }
283
-
284
- /** Every locale row of the word table, flat (the Translator's row index source —
285
- * the single translation data, zero second table: the issue-label rows + the
286
- * charter anchor rows). */
287
- localeRows(): readonly LocalizedWord[] {
288
- return [...Object.values(ISSUE_LABEL_WORDS), ...Object.values(CHARTER_WORDS)];
289
- }
290
-
291
- /** One locale row by its word id (`${type}.${segment}` or a charter row id);
292
- * null for an unknown id. */
293
- localeRow(id: string): LocalizedWord | null {
294
- const row =
295
- (ISSUE_LABEL_WORDS as Readonly<Record<string, LocalizedWord>>)[id] ??
296
- (CHARTER_WORDS as Readonly<Record<string, LocalizedWord>>)[id];
297
- return row ?? null;
298
- }
299
-
300
- // -------------------------------------------------------------------------
301
- // guard — the ban-word family
302
- // -------------------------------------------------------------------------
303
-
304
- /** The guard ban rows of one family — the STALE / GATE / shape ban words. */
305
- guardBanWords(family: GuardFamily): readonly GuardBanWord[] {
306
- return GUARD_BAN_WORDS[family];
307
- }
308
-
309
- /** The full guard ban token set — every banned word, flat (the single-source
310
- * scan set the guards consume). */
311
- guardBanTokens(): readonly string[] {
312
- return Object.values(GUARD_BAN_WORDS).flatMap((family) => family.map((row) => row.token));
313
- }
314
- }
@@ -1,333 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/__tests__/infra.test.ts
2
- // T12 infra suite + T21 typed-plane migration + T2 declaration convergence:
3
- // · runtime — the typed engine-config surface (version + the handoff namespace:
4
- // workspace-root segment + the family naming table — the argv channel table's
5
- // home is the CLI declaration single surface, face/declare.ts §2.4), single-source
6
- // asserts (the data lives in the typed modules — zero config-home reads);
7
- // · config — the ConfigLoader typed accessor facade (the consumer surface the
8
- // retired loader kept: engineConfig / harnessContract / templateContract /
9
- // handoffNamespace — now the typed planes' single home);
10
- // · git — the single git seam over a real temp repo;
11
- // · process — the subprocess seam (fail-open results);
12
- // · workspace — the root/workspace pair + the slug rule + the JSON read/write.
13
-
14
- import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
15
- import { tmpdir } from "node:os";
16
- import path from "node:path";
17
- import { describe, expect, it } from "vitest";
18
- import { ARGV_CHANNEL } from "../../face/declare.ts";
19
- import { DISPATCH, HOSTS, REFS } from "../../face/host.ts";
20
- import { REVIEWS, TEMPLATE_PROMPT } from "../../render/templates.ts";
21
- import { ConfigLoader } from "../config.ts";
22
- import { GitClient } from "../git.ts";
23
- import { ProcessRunner } from "../process.ts";
24
- import { ENGINE_RUNTIME, HANDOFF_FAMILIES } from "../runtime.ts";
25
- import { Workspace, WorkspaceRoot } from "../workspace.ts";
26
-
27
- describe("runtime — the typed engine-config surface (the typed data plane)", () => {
28
- it("carries the engine runtime facts — version, the argv channel, the handoff namespace", () => {
29
- expect(ENGINE_RUNTIME.$version).toBeGreaterThanOrEqual(1);
30
- expect(ENGINE_RUNTIME.handoffNamespace.workspaceRoot).toBe(".kairos/cdd");
31
- // The CLI channel table — the flag/type/enum single source (tasks / type enum),
32
- // single-homed at the CLI declaration surface (face/declare.ts §2.4 — moved
33
- // from this plane by the T2 declaration convergence), with the flag-level
34
- // `help` row the commander Options face reads (Task 4).
35
- expect(ARGV_CHANNEL.tasks).toEqual({
36
- flag: "--tasks",
37
- type: "int-list",
38
- help: "the task ids of the wave group (comma-separated)",
39
- });
40
- expect(ARGV_CHANNEL.type.values).toEqual(["wave", "branch", "spec", "plan"]);
41
- expect(ARGV_CHANNEL.help).toEqual({
42
- flag: "--help",
43
- alias: "-h",
44
- type: "bool",
45
- scope: "program",
46
- help: "show this help",
47
- });
48
- });
49
-
50
- it("carries the handoff family naming table — every op.type the ledger resolves", () => {
51
- expect(HANDOFF_FAMILIES["implement.wave"].name).toBe("tasks-{tasks}-implement.json");
52
- expect(HANDOFF_FAMILIES["review.wave"].name).toBe("tasks-{tasks}-review-{round}.json");
53
- // v1.9 — the family `schema` faces select the handoff-schema subset (§3.6: the
54
- // field resurrected from the dead task/docs discrimination), and the return-format
55
- // field is gone (RETURN_PROSE is the ONE return contract). The docs-fix
56
- // families (fix.spec/fix.plan) ride the findings face — §3.6's per-mode split.
57
- expect(HANDOFF_FAMILIES["review.branch"].schema).toBe("findings");
58
- expect(HANDOFF_FAMILIES["fix.plan"].schema).toBe("findings");
59
- expect(HANDOFF_FAMILIES["implement.wave"].schema).toBe("work");
60
- expect(HANDOFF_FAMILIES["fix.wave"].schema).toBe("work");
61
- for (const key of [
62
- "implement.wave",
63
- "review.wave",
64
- "fix.wave",
65
- "review.spec",
66
- "fix.spec",
67
- "review.plan",
68
- "fix.plan",
69
- "review.branch",
70
- "fix.branch",
71
- ] as const satisfies readonly (keyof typeof HANDOFF_FAMILIES)[]) {
72
- expect(HANDOFF_FAMILIES[key], key).toBeDefined();
73
- }
74
- // the return-format field is deleted with the divided return faces (the type-level
75
- // assertion — a re-added field would fail the compile)
76
- });
77
-
78
- it("declares the single-source channel/marker facts with zero duplication (host markers in host.ts only)", () => {
79
- // The host-marker closure derives from the harness detect rows (face/host.ts) —
80
- // the argv channel lives at the CLI declaration surface (face/declare.ts §2.4)
81
- // and carries no host marker; the marker env keys appear in no channel row
82
- // (single source, no second declaration).
83
- const argvText = JSON.stringify(ARGV_CHANNEL);
84
- for (const marker of ["CLAUDE_CODE_SESSION_ID", "CURSOR_TRACE_ID", "AI_AGENT"]) {
85
- expect(argvText, marker).not.toContain(marker);
86
- }
87
- });
88
- });
89
-
90
- describe("config — the typed accessor facade (one no-I/O route per face)", () => {
91
- it("routes the engine-config face — the handoff namespace + version", () => {
92
- const loader = new ConfigLoader();
93
- expect(loader.handoffNamespace().workspaceRoot).toBe(".kairos/cdd");
94
- expect(loader.engineConfig().$version).toBeGreaterThanOrEqual(1);
95
- });
96
-
97
- it("routes the harness + template faces — the typed host contract + dispatch prompt", () => {
98
- const loader = new ConfigLoader();
99
- expect(loader.harnessContract().hosts.claude.detect.env).toBe("CLAUDE_CODE_SESSION_ID");
100
- expect(loader.harnessContract().hosts.claude.promptForm).toBe("ref-prefixed");
101
- expect(loader.harnessContract().dispatch.implement).toBe("mattpocock-skills:implement");
102
- expect(loader.harnessContract().refs["mattpocock-skills:code-review"].pi).toBe(
103
- "/skill:code-review",
104
- );
105
- const template = loader.templateContract();
106
- // v1.8 — the mode dispatch table (implement/fix/review/docs-fix) + the single return contract
107
- // (RETURN_JSON / DOCS_FIX retired) — the work-mode rows + the four review variants
108
- // (the review mode's ROLE resolves by REVIEW_TYPE)
109
- expect(Object.keys(template.modes)).toEqual(["implement", "fix", "docs-fix"]);
110
- expect(Object.keys(template.reviews)).toEqual(["wave", "branch", "spec", "plan"]);
111
- // P11 — the return zone is ONE plain-prose block (the two-line stdout contract
112
- // retired with the introspection that enumerated its formats)
113
- expect(Object.keys(template.return)).toEqual(["RETURN_PROSE"]);
114
- });
115
-
116
- it("carries the P5 review criteria — the typed dispatch rows + axes guides with zero forbidden prose", () => {
117
- // The task/branch dispatch rows name their ref only (the parallel-sub-agents note is deleted).
118
- expect(DISPATCH.review.wave).toEqual({ ref: "mattpocock-skills:code-review" });
119
- expect(DISPATCH.review.branch).toEqual({ ref: "mattpocock-skills:code-review" });
120
- // The spec/plan URC criteria migrated to the template plane's REVIEWS (v1.8
121
- // closeout) — their single typed home: the three axes + the writing-plans
122
- // self-check + the verification-evidence duty, plus the per-type lens.
123
- expect(REVIEWS.spec.axesGuide).toContain("completeness/consistency/clarity");
124
- expect(REVIEWS.spec.axesGuide).toContain("writing-plans self-check");
125
- expect(REVIEWS.spec.axesGuide).toContain("verification evidence");
126
- expect(REVIEWS.plan.axesGuide).toContain("completeness/decomposition/buildability");
127
- expect(REVIEWS.spec.lensEnum).toEqual(["completeness", "consistency", "clarity"]);
128
- expect(REVIEWS.plan.lensEnum).toEqual(["completeness", "decomposition", "buildability"]);
129
- // The review prompts fold the criteria/lens into their fixed prefix — the
130
- // INPUT_CRITERIA/INPUT_LENS round-context tokens are gone (§3.7).
131
- expect(TEMPLATE_PROMPT.reviews.spec.shell.join("\n")).toContain("Follow URC");
132
- expect(TEMPLATE_PROMPT.tokens.map((t) => t.name)).not.toContain("INPUT_CRITERIA");
133
- // The implement slot is the M1 supersede — mattpocock-skills:implement, registered in refs.
134
- expect(DISPATCH.implement).toBe("mattpocock-skills:implement");
135
- expect(REFS["mattpocock-skills:implement"].claude).toBe("/mattpocock-skills:implement");
136
- expect(REFS["mattpocock-skills:implement"].pi).toBe("/skill:implement");
137
- // The forbidden prose is gone from every review surface.
138
- const reviewText = JSON.stringify({ ...DISPATCH.review, ...REVIEWS });
139
- expect(reviewText).not.toContain("parallel sub-agents");
140
- // The axes guides carry the verification-evidence duty.
141
- expect(REVIEWS.wave.axesGuide).toContain("dual evidence");
142
- expect(REVIEWS.branch.axesGuide).toContain("dual evidence");
143
- expect(TEMPLATE_PROMPT.modes.implement.shell.join("\n")).toContain(
144
- "mattpocock-skills:implement",
145
- );
146
- // Zero $schema/_doc prose in the typed planes.
147
- expect(JSON.stringify(ENGINE_RUNTIME)).not.toContain("$schema");
148
- expect(JSON.stringify(ENGINE_RUNTIME)).not.toContain('"_doc"');
149
- expect(JSON.stringify(HOSTS)).not.toContain("$schema");
150
- });
151
- });
152
-
153
- describe("git — the single git seam over a real temp repo", () => {
154
- it("walks init → dirty → clean over one repo (fail-open)", async () => {
155
- const dir = mkdtempSync(path.join(tmpdir(), "infra-git-"));
156
- try {
157
- const proc = new ProcessRunner();
158
- await proc.run("git", ["init", "-b", "main", dir]);
159
- await proc.run("git", ["config", "user.email", "tester@example.dev"], dir);
160
- await proc.run("git", ["config", "user.name", "Tester"], dir);
161
- const git = new GitClient();
162
- expect(await git.topLevel(dir)).toBe(realpathSync(dir));
163
- writeFileSync(path.join(dir, "a.txt"), "a\n");
164
- expect(await git.isClean(dir)).toBe(false);
165
- await proc.run("git", ["add", "-A"], dir);
166
- await proc.run("git", ["commit", "-m", "feat: initial"], dir);
167
- expect(await git.isClean(dir)).toBe(true);
168
- } finally {
169
- rmSync(dir, { recursive: true, force: true });
170
- }
171
- });
172
-
173
- it("fails open outside a git repo (no exception crosses the seam)", async () => {
174
- const dir = mkdtempSync(path.join(tmpdir(), "infra-nogit-"));
175
- try {
176
- const git = new GitClient();
177
- expect(await git.topLevel(dir)).toBeNull();
178
- expect(await git.isClean(dir)).toBe(false); // no repo counts dirty
179
- } finally {
180
- rmSync(dir, { recursive: true, force: true });
181
- }
182
- });
183
-
184
- it("exposes exactly the two judgment seams — topLevel + isClean, the commit seams retired (§2.1)", () => {
185
- // The GitClient is the engine's git JUDGMENT adapter: repo-root location
186
- // (topLevel) + working-tree cleanliness (isClean). The retired commit seams
187
- // (revParseHead / addAll / commit / log) must not survive on the prototype —
188
- // the engine checks no commit identity, it judges the live tree.
189
- const methods = Object.getOwnPropertyNames(GitClient.prototype).filter(
190
- (name) => name !== "constructor",
191
- );
192
- expect(methods.sort()).toEqual(["isClean", "topLevel"]);
193
- });
194
- });
195
-
196
- describe("process — the subprocess seam", () => {
197
- it("captures a successful run's stdout", async () => {
198
- const result = await new ProcessRunner().run("node", ["-e", "console.log('hello')"]);
199
- expect(result.code).toBe(0);
200
- expect(result.stdout).toContain("hello");
201
- });
202
-
203
- it("rides a synthetic code for a non-zero exit and a missing binary (fail-open)", async () => {
204
- const proc = new ProcessRunner();
205
- const failing = await proc.run("node", ["-e", "process.exit(3)"]);
206
- expect(failing.code).toBe(3);
207
- const missing = await proc.run("definitely-not-a-binary-xyz", []);
208
- expect(missing.code).not.toBe(0);
209
- });
210
- });
211
-
212
- describe("workspace — the root/workspace pair + the slug rule + JSON roundtrip", () => {
213
- it("derives paths and roundtrips JSON reads/writes under the slug dir", () => {
214
- const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
215
- try {
216
- const root = new WorkspaceRoot(base, ".kairos/cdd");
217
- const workspace = new Workspace(root, "test-slug");
218
- expect(workspace.path).toBe(path.join(base, ".kairos", "cdd", "test-slug"));
219
- workspace.writeJson("probe.json", { a: 1 });
220
- expect(workspace.readJson<{ a: number }>("probe.json")).toEqual({
221
- kind: "ok",
222
- value: { a: 1 },
223
- });
224
- expect(workspace.readJson("missing.json")).toEqual({ kind: "missing" });
225
- expect(workspace.resolve("probe.json")).toBe(path.join(workspace.path, "probe.json"));
226
- } finally {
227
- rmSync(base, { recursive: true, force: true });
228
- }
229
- });
230
-
231
- it("readJson is tri-state — a present-but-unparseable file reads `malformed`, never `missing` (D27)", () => {
232
- const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
233
- try {
234
- const root = new WorkspaceRoot(base, ".kairos/cdd");
235
- const workspace = new Workspace(root, "test-slug");
236
- workspace.ensure();
237
- writeFileSync(path.join(workspace.path, "bad.json"), "{ not json", "utf8");
238
- // the true cause is reported: a corrupt file is a distinct fact from an absent one
239
- expect(workspace.readJson("bad.json")).toEqual({ kind: "malformed" });
240
- expect(workspace.readJson("absent.json")).toEqual({ kind: "missing" });
241
- } finally {
242
- rmSync(base, { recursive: true, force: true });
243
- }
244
- });
245
-
246
- it("derives the slug from a doc file name — single-layer -design/-plan strip", () => {
247
- expect(Workspace.slugFromDoc("2026-10-02-x-p3-design.md")).toBe("2026-10-02-x-p3");
248
- expect(Workspace.slugFromDoc("2026-10-02-x-p3-plan.md")).toBe("2026-10-02-x-p3");
249
- expect(Workspace.slugFromDoc("2026-10-02-x-overall.md")).toBe("2026-10-02-x-overall");
250
- expect(Workspace.slugFromDoc("notes.md")).toBe("notes");
251
- });
252
-
253
- it("readJsonLenient tolerates the sub-agent draft dialect — trailing comma / comments (D39)", () => {
254
- const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
255
- try {
256
- const root = new WorkspaceRoot(base, ".kairos/cdd");
257
- const workspace = new Workspace(root, "test-slug");
258
- workspace.ensure();
259
- // The W3 {5,11} block shape — a trailing comma in the draft's notes array: the
260
- // lenient read passes it, the strict read vetoes it (the two faces are isolated).
261
- const trailing = '{\n "status": "APPROVED",\n "notes": [\n "a",\n "b",\n ]\n}\n';
262
- writeFileSync(path.join(workspace.path, "draft.json"), trailing, "utf8");
263
- expect(workspace.readJsonLenient("draft.json")).toEqual({
264
- kind: "ok",
265
- value: { status: "APPROVED", notes: ["a", "b"] },
266
- });
267
- expect(workspace.readJson("draft.json")).toEqual({ kind: "malformed" });
268
-
269
- // A comment is the same dialect slip — tolerated leniently, vetoed strictly.
270
- writeFileSync(path.join(workspace.path, "commented.json"), '{ // note\n "a": 1\n}', "utf8");
271
- expect(workspace.readJsonLenient("commented.json")).toEqual({ kind: "ok", value: { a: 1 } });
272
- expect(workspace.readJson("commented.json")).toEqual({ kind: "malformed" });
273
-
274
- // A REAL break stays fail-loud on both faces — leniency never swallows corruption.
275
- // The lenient face ALSO carries the parser's precise error codes (D39) for
276
- // diagnosis; the strict face reports its bare malformed outcome.
277
- writeFileSync(path.join(workspace.path, "broken.json"), '{ "a": 1 ', "utf8");
278
- const broken = workspace.readJsonLenient("broken.json");
279
- expect(broken.kind).toBe("malformed");
280
- expect(broken.kind === "malformed" && (broken.errors?.length ?? 0) > 0).toBe(true);
281
- expect(workspace.readJson("broken.json")).toEqual({ kind: "malformed" });
282
-
283
- // The tri-state legs hold on the lenient face too.
284
- expect(workspace.readJsonLenient("absent.json")).toEqual({ kind: "missing" });
285
- } finally {
286
- rmSync(base, { recursive: true, force: true });
287
- }
288
- });
289
-
290
- it("writeJson relativizes the declared path fields (doc/plan) to the repoRoot-relative shape (P9 T4 §2.7)", () => {
291
- const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
292
- try {
293
- const workspace = new Workspace(new WorkspaceRoot(base, ".kairos/cdd"), "test-slug");
294
- const abs = path.join(base, "docs", "kairos", "plans", "p3.md");
295
- // The persisted shape is repoRoot-relative for the two DECLARED path keys; a
296
- // prose string that merely looks like a path (the `notes` array) is untouched.
297
- workspace.writeJson("progress.json", {
298
- waves: [{ wave: "1", reviewedRevision: { kind: "brief-revision", plan: abs } }],
299
- notes: [abs],
300
- });
301
- const onDisk = JSON.parse(
302
- readFileSync(path.join(workspace.path, "progress.json"), "utf8"),
303
- ) as { waves: { reviewedRevision: { plan: string } }[]; notes: string[] };
304
- expect(onDisk.waves[0]!.reviewedRevision.plan).toBe("docs/kairos/plans/p3.md");
305
- expect(onDisk.notes).toEqual([abs]);
306
- } finally {
307
- rmSync(base, { recursive: true, force: true });
308
- }
309
- });
310
-
311
- it("readJson normalizes a legacy absolute path field on read — the backstop covers un-migrated bytes (P9 T4 §2.11)", () => {
312
- const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
313
- try {
314
- const workspace = new Workspace(new WorkspaceRoot(base, ".kairos/cdd"), "test-slug");
315
- workspace.ensure();
316
- // A legacy write (absolute plan field) sits on disk; the read normalizes it —
317
- // the internal value is the canonical relative shape even without migration.
318
- const abs = path.join(base, "docs", "kairos", "plans", "legacy.md");
319
- writeFileSync(
320
- path.join(workspace.path, "progress.json"),
321
- JSON.stringify({ reviewedRevision: { plan: abs } }),
322
- "utf8",
323
- );
324
- const read = workspace.readJson<{ reviewedRevision: { plan: string } }>("progress.json");
325
- expect(read.kind).toBe("ok");
326
- expect(read.kind === "ok" && read.value.reviewedRevision.plan).toBe(
327
- "docs/kairos/plans/legacy.md",
328
- );
329
- } finally {
330
- rmSync(base, { recursive: true, force: true });
331
- }
332
- });
333
- });