@oscaner-skills/cdd-engine 2.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 (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,220 @@
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
+ /** The capsule word rows — every word the capsule face emits, one table. */
34
+ export const CAPSULE_WORDS = {
35
+ /** The capsule emit keys in order (a reorder is a red test — the pinned face). */
36
+ keys: ["status", "blocker", "handoff"],
37
+ /** The `·`-separator token of the capsule line. */
38
+ separator: " · ",
39
+ /** The status vocabulary — the five handoff-conclusion values. */
40
+ status: ["APPROVED", "BLOCKED", "CHANGES_REQUESTED", "REVIEW_FIX", "TIMEOUT"],
41
+ /** The route stations — the `: `-suffixed channel anchors. */
42
+ stations: {
43
+ next: "next:",
44
+ blocked: "CDD_BLOCKED:",
45
+ warn: "CDD_WARN:",
46
+ cliMissing: "CDD_CLI_MISSING:",
47
+ },
48
+ /** The route classifier words of the `next:` line. */
49
+ routeWords: {
50
+ done: "done",
51
+ review: "review",
52
+ fix: "fix",
53
+ implement: "implement",
54
+ docType: "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",
55
+ frontmatterParse: "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",
56
+ },
57
+ /** The wave-gate BLOCK wording rows (v1.21) — the highest-arity pre-flight refusal
58
+ * vocabulary, single-sourced (the gate fills the placeholders, never a re-type). */
59
+ waveGate: {
60
+ split: "the requested wave ({requested}) splits/mismatches the derived wave ({open}) — dispatch the full derived wave",
61
+ wrongPhase: "the open wave is at {phase} — run cdd {phase} first",
62
+ },
63
+ /** The pre-flight BLOCK wording rows (P4.1 T1) — the seam's refusal vocabulary,
64
+ * single-sourced (the seam fills the {count} slot, never a re-type). */
65
+ preflight: {
66
+ dirtyTree: "the working tree is dirty — commit or discard your changes, then re-run the same command",
67
+ graph: "the plan graph has {count} edge violation(s) — fix the **DependsOn** edges first",
68
+ docContract: "the target document fails the doc-contract — fix its structural findings first",
69
+ },
70
+ };
71
+ /** The guard-ban vocabulary — the STALE / GATE / shape ban rows the guards assert
72
+ * absent from the live faces (the single-source ban table; the guard scan releases
73
+ * this data source — the retired residue guard's data-row-release stance). */
74
+ export const GUARD_BAN_WORDS = {
75
+ /** The stale retired-mechanism tokens (the migration residue bans). */
76
+ stale: [
77
+ { token: "cursor-agent" },
78
+ { token: "@ts-ignore" },
79
+ { token: "@ts-expect-error" },
80
+ { token: "build.config" },
81
+ { token: "dev:stub" },
82
+ { token: "@typescript/typescript6" },
83
+ { token: "globalSetup" },
84
+ { token: ".mjs" },
85
+ ],
86
+ /** The retired-gate channel tokens. */
87
+ gate: [
88
+ { token: "CDD_GATE" },
89
+ { token: "cdd-gate-core" },
90
+ { token: "gateDecide" },
91
+ ],
92
+ /** The retired engine-shape names the consumer surfaces must not restate. */
93
+ shape: [
94
+ { token: "3-line return block" },
95
+ { token: "4th line counters" },
96
+ { token: "return block" },
97
+ ],
98
+ };
99
+ // ---------------------------------------------------------------------------
100
+ // locale — the word-table locale face (the P7 translation-system data plane)
101
+ // ---------------------------------------------------------------------------
102
+ /** The locale key set — the word table's declared language keys. This is the
103
+ * `langs` projection source: every locale-consuming face derives its language
104
+ * vocabulary from this set (and its aliases from the rows below), never from a
105
+ * hardcoded list — a locale-key change here re-projects the whole plane. */
106
+ export const LOCALE_KEYS = ["en", "zh"];
107
+ /** The issue-body label rows — the human-readable rendering face's locale words, one
108
+ * row per finding type × segment (keyed `${type}.${segment}`). Every label value the
109
+ * issue renderer emits rides these rows — the word table's locale family (the label
110
+ * set is data, never a second rendering table). The finding type × segment matrix is
111
+ * complete (word-table test pins it); the capsule machine words are deliberately
112
+ * absent — the machine face is not a translation surface. */
113
+ export const ISSUE_LABEL_WORDS = {
114
+ "bug.context": { en: "## Context", zh: "## 场景" },
115
+ "bug.problem": { en: "## Problem", zh: "## 问题" },
116
+ "bug.impact": { en: "## Impact", zh: "## 影响" },
117
+ "bug.suggestedFix": { en: "## Suggested fix", zh: "## 建议修复" },
118
+ "enhancement.context": { en: "## Context", zh: "## 场景" },
119
+ "enhancement.problem": { en: "## Gap", zh: "## 差距" },
120
+ "enhancement.impact": { en: "## Impact", zh: "## 影响" },
121
+ "enhancement.suggestedFix": { en: "## Suggested direction", zh: "## 建议方向" },
122
+ "chore.context": { en: "## Context", zh: "## 场景" },
123
+ "chore.problem": { en: "## Gap", zh: "## 差距" },
124
+ "chore.impact": { en: "## Impact", zh: "## 影响" },
125
+ "chore.suggestedFix": { en: "## Suggested direction", zh: "## 建议方向" },
126
+ };
127
+ /** The finding-type vocabulary — the canonical issue-report type set, DERIVED from the
128
+ * issue-label rows' `${type}.${segment}` key prefixes (deduped in row order). This is
129
+ * the ONE source of the accepted finding types: the issue renderer's validation set
130
+ * reads it, and the consumer `cdd-report` SKILL.md's declared `type ∈ {…}` domain is
131
+ * pinned to it by the kairos-suite consistency gate (spec §3.3 ⑥ — never a second
132
+ * hand-written list). */
133
+ export const ISSUE_TYPES = [
134
+ ...new Set(Object.keys(ISSUE_LABEL_WORDS).map((id) => id.split(".")[0])),
135
+ ];
136
+ /** The charter anchor rows — the P7 canonicalize data plane: one row per legacy
137
+ * Chinese charter marker the structure judge matches through the canonicalize view
138
+ * (the doc-arch overall 决策组叶 / 上游先例背书). The family prefix `charter.` sits
139
+ * parallel to the issue-label family — every row flows through localeRows() (the zh
140
+ * knowledge lives ONLY here, never in a code branch or an element-table pattern). */
141
+ export const CHARTER_WORDS = {
142
+ "charter.group-leaf": { en: "group", zh: "组" },
143
+ "charter.upstream-endorsements": { en: "Upstream Endorsements", zh: "上游先例背书" },
144
+ };
145
+ /**
146
+ * Words — the single word table + accessor face. One instance serves every family:
147
+ * the capsule station words (declared steady data), the guard ban words (declared
148
+ * data) and the locale words (the translation/label data — the WordLocaleFace the
149
+ * Translator and the locale consumers read). The capsule reads its whole vocabulary
150
+ * through this class — the second table is excluded by construction.
151
+ */
152
+ export class Words {
153
+ // -------------------------------------------------------------------------
154
+ // capsule — the station-word family
155
+ // -------------------------------------------------------------------------
156
+ /** The capsule emit keys in order — status · blocker · handoff (the pinned byte
157
+ * order the capsule renders by). */
158
+ capsuleKeys() {
159
+ return CAPSULE_WORDS.keys;
160
+ }
161
+ /** The `·`-separator token of the capsule line. */
162
+ capsuleSeparator() {
163
+ return CAPSULE_WORDS.separator;
164
+ }
165
+ /** The status vocabulary — the five handoff-conclusion values. */
166
+ statusVocab() {
167
+ return CAPSULE_WORDS.status;
168
+ }
169
+ /** One route station by its semantic kind (`next:` / `CDD_BLOCKED:` / …). */
170
+ station(kind) {
171
+ return CAPSULE_WORDS.stations[kind];
172
+ }
173
+ /** One route classifier word (`done` / `review` / `fix` / `implement`). */
174
+ routeWord(kind) {
175
+ return CAPSULE_WORDS.routeWords[kind];
176
+ }
177
+ /** The wave-gate BLOCK wording rows — the vocabulary the WaveGate verdicts render
178
+ * (single source: the gate fills the placeholders from these rows, never re-types). */
179
+ waveGateWords() {
180
+ return CAPSULE_WORDS.waveGate;
181
+ }
182
+ /** The pre-flight BLOCK wording rows — the seam's refusal vocabulary (single
183
+ * source: the seam fills the placeholders from these rows, never re-types). */
184
+ preflightWords() {
185
+ return CAPSULE_WORDS.preflight;
186
+ }
187
+ // -------------------------------------------------------------------------
188
+ // locale — the word-table locale face (the langs projection + the label rows)
189
+ // -------------------------------------------------------------------------
190
+ /** The locale key set — the word table's declared languages (the `langs`
191
+ * projection every locale-consuming face derives its vocabulary from). */
192
+ localeKeys() {
193
+ return LOCALE_KEYS;
194
+ }
195
+ /** Every locale row of the word table, flat (the Translator's row index source —
196
+ * the single translation data, zero second table: the issue-label rows + the
197
+ * charter anchor rows). */
198
+ localeRows() {
199
+ return [...Object.values(ISSUE_LABEL_WORDS), ...Object.values(CHARTER_WORDS)];
200
+ }
201
+ /** One locale row by its word id (`${type}.${segment}` or a charter row id);
202
+ * null for an unknown id. */
203
+ localeRow(id) {
204
+ const row = ISSUE_LABEL_WORDS[id] ??
205
+ CHARTER_WORDS[id];
206
+ return row ?? null;
207
+ }
208
+ // -------------------------------------------------------------------------
209
+ // guard — the ban-word family
210
+ // -------------------------------------------------------------------------
211
+ /** The guard ban rows of one family — the STALE / GATE / shape ban words. */
212
+ guardBanWords(family) {
213
+ return GUARD_BAN_WORDS[family];
214
+ }
215
+ /** The full guard ban token set — every banned word, flat (the single-source
216
+ * scan set the guards consume). */
217
+ guardBanTokens() {
218
+ return Object.values(GUARD_BAN_WORDS).flatMap((family) => family.map((row) => row.token));
219
+ }
220
+ }
@@ -9,34 +9,29 @@
9
9
  // The previous JSON-plane interfaces (EngineConfig / HarnessContract /
10
10
  // TemplateContract / HandoffNamespace) retire here — the typed data modules own the
11
11
  // shapes; this module only routes.
12
-
13
- import { HOST_CONTRACT, type HostContract } from "../face/host.ts";
14
- import { TEMPLATE_PROMPT, type TemplatePrompt } from "../render/templates.ts";
15
- import { ENGINE_RUNTIME, type EngineRuntime, type HandoffNamespace } from "./runtime.ts";
16
-
12
+ import { HOST_CONTRACT } from "../face/host.js";
13
+ import { TEMPLATE_PROMPT } from "../render/templates.js";
14
+ import { ENGINE_RUNTIME } from "./runtime.js";
17
15
  /**
18
16
  * The typed config accessor — the single façade over the typed data planes (zero
19
17
  * file reads: every accessor returns the declared constant of its single home).
20
18
  * Construction is trivial; the consumer surface matches the retired loader.
21
19
  */
22
20
  export class ConfigLoader {
23
- /** The engine-config face — the typed engine runtime (version + channels + names). */
24
- engineConfig(): EngineRuntime {
25
- return ENGINE_RUNTIME;
26
- }
27
-
28
- /** The harness-contract face — the typed host adaptation contract (hosts + dispatch + refs). */
29
- harnessContract(): HostContract {
30
- return HOST_CONTRACT;
31
- }
32
-
33
- /** The template-contract face — the typed dispatch-prompt + review criteria. */
34
- templateContract(): TemplatePrompt {
35
- return TEMPLATE_PROMPT;
36
- }
37
-
38
- /** The handoff-namespace section — the workspace-root + the family naming single source. */
39
- handoffNamespace(): HandoffNamespace {
40
- return ENGINE_RUNTIME.handoffNamespace;
41
- }
21
+ /** The engine-config face — the typed engine runtime (version + channels + names). */
22
+ engineConfig() {
23
+ return ENGINE_RUNTIME;
24
+ }
25
+ /** The harness-contract face — the typed host adaptation contract (hosts + dispatch + refs). */
26
+ harnessContract() {
27
+ return HOST_CONTRACT;
28
+ }
29
+ /** The template-contract face — the typed dispatch-prompt + review criteria. */
30
+ templateContract() {
31
+ return TEMPLATE_PROMPT;
32
+ }
33
+ /** The handoff-namespace section — the workspace-root + the family naming single source. */
34
+ handoffNamespace() {
35
+ return ENGINE_RUNTIME.handoffNamespace;
36
+ }
42
37
  }
@@ -0,0 +1,19 @@
1
+ // packages/cdd-engine/src-next/infra/doc-roots.ts
2
+ // The doc-root leaf (P9 T5 §2.8) — the doc-tree root segments as their OWN
3
+ // dependency-free constant so the CLI declaration surface (face/declare.ts — the
4
+ // help `example` rows) can derive its doc-root literals from the SAME single
5
+ // source the runtime exposes as `ENGINE_RUNTIME.docRoots`, without the module
6
+ // cycle the direct `declare.ts → runtime.ts` import would form (runtime.ts reads
7
+ // ARGV_CHANNEL from declare.ts, so declare.ts must stay import-clean toward it).
8
+ //
9
+ // `ENGINE_RUNTIME.docRoots` IS this object (runtime.ts references it, never
10
+ // re-declares a copy) — the doc-root segments live here once, and every reader
11
+ // (the runtime, the CLI examples, the invariant messages, the board scan) derives
12
+ // from this one value. Module-level export is the declared constant + its type —
13
+ // zero behavior-carrying bare functions.
14
+ /** The doc-tree root segments — the ONE value of the doc-root fact (the runtime's
15
+ * `docRoots` and every derived literal read THIS constant). */
16
+ export const ENGINE_DOC_ROOTS = {
17
+ specs: "docs/kairos/specs",
18
+ plans: "docs/kairos/plans",
19
+ };
@@ -0,0 +1,37 @@
1
+ // packages/cdd-engine/src-next/infra/git.ts
2
+ // T12 — GitClient: the new tree's single git seam. It holds exactly the two
3
+ // judgments the engine's git face needs — where the repo root is (topLevel) and
4
+ // whether the working tree is clean (isClean). Operations are fail-open — a
5
+ // non-repo or git error yields null (topLevel) / false (isClean), never a thrown
6
+ // exception across the seam.
7
+ import { simpleGit } from "simple-git";
8
+ /** GitClient — the engine's git judgment adapter. Stateless: construction is cheap,
9
+ * collaborators that need git are constructor-injected. */
10
+ export class GitClient {
11
+ #git(cwd) {
12
+ return simpleGit({ baseDir: cwd });
13
+ }
14
+ /** The repo root, mirroring `git rev-parse --show-toplevel`; null outside a repo. */
15
+ async topLevel(cwd) {
16
+ try {
17
+ return (await this.#git(cwd).revparse(["--show-toplevel"])).trim() || null;
18
+ }
19
+ catch {
20
+ return null;
21
+ }
22
+ }
23
+ /** Whether the working tree is clean — `git status --porcelain` = "" (the
24
+ * clean-tree gate reads git's own judgment, zero engine-side exclusion: the
25
+ * engine's workspace self-publishes its `.gitignore` (content `*`) at ensure
26
+ * time, so its run artifacts never read as uncommitted user work — the gate
27
+ * refuses only genuinely dirty USER changes). Fail-open-false (a non-repo
28
+ * counts dirty — the CDD flow needs git). */
29
+ async isClean(cwd) {
30
+ try {
31
+ return (await this.#git(cwd).status()).isClean();
32
+ }
33
+ catch {
34
+ return false;
35
+ }
36
+ }
37
+ }
@@ -0,0 +1,22 @@
1
+ // packages/cdd-engine/src-next/infra/process.ts
2
+ // T12 — ProcessRunner: the new tree's process seam. Subprocess invocations are
3
+ // async instance methods over the node:child_process execFile — a fail-open run
4
+ // returns a { code, stdout, stderr } result (a missing binary or a non-zero exit
5
+ // rides the code, never a thrown exception across the seam).
6
+ import { execFile } from "node:child_process";
7
+ /** ProcessRunner — the subprocess adapter. Stateless and fail-open. */
8
+ export class ProcessRunner {
9
+ /** Run a command with args in an optional working directory. */
10
+ run(command, args, cwd) {
11
+ return new Promise((resolve) => {
12
+ execFile(command, [...args], { cwd }, (error, stdout, stderr) => {
13
+ if (error === null) {
14
+ resolve({ code: 0, stdout, stderr });
15
+ return;
16
+ }
17
+ const code = typeof error.code === "number" ? error.code : 1;
18
+ resolve({ code, stdout, stderr });
19
+ });
20
+ });
21
+ }
22
+ }
@@ -0,0 +1,62 @@
1
+ // packages/cdd-engine/src-next/infra/root.ts
2
+ // T1 — the path value-object pair (design spec §2.2): the ONE authority for the
3
+ // path BASIS (repoRoot) and the ONE type for the canonical path SHAPE
4
+ // (repoRoot-relative).
5
+ //
6
+ // RepoRoot — the value object holding the already-resolved absolute root
7
+ // string (the resolution — `git.topLevel(process.cwd())` — is T2;
8
+ // this plane stays resolution-free so no import cycle forms). Its
9
+ // two methods are the ONLY conversion pair over the path basis:
10
+ // · relativize(input) — the ONE construction entry: any absolute
11
+ // or caller-relative input → the branded, repoRoot-relative
12
+ // `RepoPath` (the user-input read-in point).
13
+ // · resolve(rel) — the ONE erasure point: a `RepoPath` →
14
+ // the absolute `string` fed to `fs` / `git` / `execa` at the
15
+ // syscall boundary.
16
+ //
17
+ // RepoPath — a branded string. The brand lifts the canonical shape to the type
18
+ // level: the absolute state is UNREPRESENTABLE as a `RepoPath`, so a
19
+ // bare `string` can never reach a read/write face (compile-time
20
+ // guard — §2.2's read/write contract). The absolute form is
21
+ // transient at the syscall boundary only: it is produced by
22
+ // `resolve`, never persisted, never compared, never passed across a
23
+ // layer (spec §2.1).
24
+ //
25
+ // The whole plane is pure string arithmetic over `node:path` (zero syscall, zero
26
+ // `process.cwd()` read) — the value object never touches the filesystem.
27
+ //
28
+ // Module-level exports are types / the class — zero behavior-carrying bare
29
+ // functions (the plan's zero-bare-function discipline).
30
+ import path from "node:path";
31
+ /** The path-basis value object — the root-basis single source plus the ONE
32
+ * relativize/resolve conversion pair (spec §2.2). Constructed with the
33
+ * ALREADY-resolved absolute root string (resolution is T2 — this plane never
34
+ * reads `process.cwd()`); stateless after construction, so one instance is
35
+ * shared safely. */
36
+ export class RepoRoot {
37
+ /** The absolute root string — the basis every relativize/resolve is taken
38
+ * against. Stored verbatim (never re-resolved: resolution is the caller's —
39
+ * T2 — and a re-resolution here would smuggle a `process.cwd()` read into the
40
+ * pure plane). */
41
+ absolute;
42
+ constructor(absolute) {
43
+ this.absolute = absolute;
44
+ }
45
+ /** The ONE construction entry — normalize any absolute-or-relative input to the
46
+ * branded repoRoot-relative `RepoPath`. An absolute input is taken relative to
47
+ * the root; a caller-relative input is resolved against the root first (so a
48
+ * bare `docs/x.md` is read relative to repoRoot, NEVER to `process.cwd()`).
49
+ * An out-of-repo input (`../outside/x.md`) keeps the single relative FORM — the
50
+ * result carries `..` segments, is NOT rejected and never throws (spec §2.10:
51
+ * the shape is what is judged, not the location). An empty input relativizes to
52
+ * the empty string (root against itself). */
53
+ relativize(input) {
54
+ return path.relative(this.absolute, path.resolve(this.absolute, input));
55
+ }
56
+ /** The ONE erasure point — a `RepoPath` back to the absolute `string` fed to
57
+ * `fs` / `git` / `execa`. The absolute form exists only here, transient at the
58
+ * syscall boundary. */
59
+ resolve(rel) {
60
+ return path.resolve(this.absolute, rel);
61
+ }
62
+ }
@@ -0,0 +1,85 @@
1
+ // packages/cdd-engine/src-next/infra/runtime.ts
2
+ // T21 — the engine-config typed surface: the engine-config JSON's data-plane home
3
+ // as one typed constant module. The new tree reads zero config files — every
4
+ // stable runtime fact lives here (or in its single typed home elsewhere in the
5
+ // plane) and is imported, never parsed:
6
+ //
7
+ // · $version — the runtime contract version (the face's version pin).
8
+ // · contextContract — the environment contract's view of the argv channel
9
+ // table (the CLI declaration single surface — face/declare.ts §2.4 — is the
10
+ // channel's home; the runtime references the same table, never a second list).
11
+ // · handoffNamespace — the workspace-root segment + the handoff family naming
12
+ // table (the ledger's family resolution reads it).
13
+ //
14
+ // The JSON plane's dead fields are not carried (the delete-dead-empties iron rule):
15
+ // · failureCategories — the new tree keeps no failure-category counter data; the
16
+ // ledger's progress key set is the declared code constant (PROGRESS_COUNTER_ZERO).
17
+ // · handoffNamespace.slugRule — the slug derivation is code (Workspace.slugFromDoc),
18
+ // never a prose data field.
19
+ // · contextContract channels.git / derived / transport / timeouts and the env-host
20
+ // channel — no live consumer; the host-marker closure is single-sourced by the
21
+ // harness detect rows (face/host.ts), never re-declared here.
22
+ //
23
+ // Module-level exports are types / the declared constant data — zero behavior-
24
+ // carrying bare functions (the plan's zero-bare-function discipline).
25
+ import { ARGV_CHANNEL } from "../face/declare.js";
26
+ import { ENGINE_DOC_ROOTS } from "./doc-roots.js";
27
+ /** The handoff family naming table — the canonical per-family file-name patterns
28
+ * keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
29
+ * naming truth, verbatim from the engine-config handoff namespace). The v1.9
30
+ * reparametrization: `returnFormat` is gone (RETURN_PROSE is the one return
31
+ * contract) and the `schema` faces are the handoff-schema selector (work / findings —
32
+ * §3.6, session/handoff-schema.ts). */
33
+ export const HANDOFF_FAMILIES = {
34
+ "implement.wave": {
35
+ name: "tasks-{tasks}-implement.json",
36
+ schema: "work",
37
+ },
38
+ "review.wave": {
39
+ name: "tasks-{tasks}-review-{round}.json",
40
+ schema: "findings",
41
+ },
42
+ "fix.wave": {
43
+ name: "tasks-{tasks}-fix-{round}.json",
44
+ schema: "work",
45
+ },
46
+ "review.spec": {
47
+ name: "spec-review-{round}.json",
48
+ schema: "findings",
49
+ },
50
+ "fix.spec": {
51
+ name: "spec-fix-{round}.json",
52
+ schema: "findings",
53
+ },
54
+ "review.plan": {
55
+ name: "plan-review-{round}.json",
56
+ schema: "findings",
57
+ },
58
+ "fix.plan": {
59
+ name: "plan-fix-{round}.json",
60
+ schema: "findings",
61
+ },
62
+ "review.branch": {
63
+ // find #9 (spec §6.5): the range token leaves the file name — the workspace
64
+ // slug is the plan-slug (the fix face carries --plan) · round accumulates
65
+ // across re-reviews (lineKey pins "branch").
66
+ name: "branch-review-{round}.json",
67
+ schema: "findings",
68
+ },
69
+ "fix.branch": {
70
+ name: "branch-fix-{round}.json",
71
+ schema: "work",
72
+ },
73
+ };
74
+ /** The engine runtime — the typed engine-config surface, one constant (the argv
75
+ * channel table is the CLI declaration single surface, face/declare.ts §2.4 —
76
+ * referenced here, never re-declared). */
77
+ export const ENGINE_RUNTIME = {
78
+ $version: 1,
79
+ contextContract: { channels: { argv: ARGV_CHANNEL } },
80
+ handoffNamespace: {
81
+ workspaceRoot: ".kairos/cdd",
82
+ families: HANDOFF_FAMILIES,
83
+ },
84
+ docRoots: ENGINE_DOC_ROOTS,
85
+ };