@oscaner-skills/cdd-engine 1.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
@@ -0,0 +1,302 @@
1
+ // packages/cdd-engine/src-next/face/host.ts
2
+ // T21 — the harness-contract typed surface: the harness-contract JSON's data-plane
3
+ // home as one typed constant module. The new tree reads zero config files — the
4
+ // host-adaptation contract (host detection · dispatch · refs) lives here and is
5
+ // imported, never parsed:
6
+ //
7
+ // · HOSTS — the per-harness rows (cli / invoke / promptForm / output / ship /
8
+ // detect / install). The host-marker closure is single-sourced HERE: the
9
+ // detect rows are the only copy of the marker env keys (the channel audit derives
10
+ // the env whitelist from them — never a second declaration). The promptForm
11
+ // column (§3.5) is the prompt-position semantics data contract — how the
12
+ // skill-ref enters the child prompt (ref-prefixed | plain).
13
+ // · DISPATCH — the dispatch table: the skill-ref each dispatch face resolves
14
+ // to. M1 supersede (P5): the implement slot names the upstream
15
+ // `mattpocock-skills:implement` skill; the fix face carries no skill ref (its
16
+ // fix discipline lives as the FIX_SHELL typed instructions).
17
+ // · REFS — the per-harness slash reference forms (claude/cursor use the
18
+ // `/namespace:skill` form; pi the flat `/skill:<bare>` form — the pi flat
19
+ // namespace has no namespace-qualification syntax).
20
+ // · HostDetect — the module-level host judgment (the detection's single home):
21
+ // the dispatch face's detectHost delegates here; the work face's Capsule wiring
22
+ // reads the same judgment over process.env.
23
+ //
24
+ // P5 lands here: the forbidden parallel-sub-agents prose is deleted from the review
25
+ // dispatch rows (the task/branch rows carry their ref only) and the review
26
+ // criteria — the URC spec/plan axes + the writing-plans self-check + the
27
+ // verification-evidence duty — land in render/templates.ts (the axes guide's
28
+ // typed home). The `mattpocock-skills:implement` ref key is registered here.
29
+ //
30
+ // Module-level exports are types / the declared constant data — zero behavior-
31
+ // carrying bare functions (the plan's zero-bare-function discipline).
32
+
33
+ /** The harness ids the contract adapts. */
34
+ export type HostId = "claude" | "cursor" | "pi";
35
+
36
+ /** One host-detect row — the marker env key (+ the AI_AGENT match semantics). */
37
+ export interface HostDetectSpec {
38
+ /** The marker env key the host detection reads. */
39
+ env: string;
40
+ /** pi-only: the AI_AGENT exact value the detection matches (`=== "value"`). */
41
+ value?: string;
42
+ /** claude-only: the AI_AGENT prefix the detection matches via startsWith. */
43
+ aiAgentPrefix?: string;
44
+ }
45
+
46
+ /** The prompt-position semantics of a harness — HOW the skill-ref enters the child
47
+ * prompt (the §3.5 data contract, resolved by #childPrompt — the from-code-assumed
48
+ * prompt assembly becomes a per-host row). `ref-prefixed`: the slash ref prefixes
49
+ * the single prompt positional; `plain`: the child receives the prompt verbatim
50
+ * (no ref to prefix — the URC-prose rows). */
51
+ export type PromptForm = "ref-prefixed" | "plain";
52
+
53
+ /** One harness's capability facts (T25 — the capabilities per-harness declaration):
54
+ * the tested dispatch faces, one data column per row, zero prose. */
55
+ export interface HostCapabilities {
56
+ /** The parallel sub-agent dispatch face — `true` the measured face (claude),
57
+ * `"pending"` the not-yet-exercised marker (cursor/pi — the per-tested stance,
58
+ * the install `"pending"` pattern). */
59
+ parallel: boolean | "pending";
60
+ }
61
+
62
+ /** One per-harness host row — the adaptation facts the engine + guards consume. */
63
+ export interface HostRow {
64
+ /** The host harness CLI binary. */
65
+ cli: string;
66
+ /** The invoke flags prepended to the dispatch prompt. */
67
+ invoke: string;
68
+ /** The prompt-position semantics — how the skill-ref enters the child prompt. */
69
+ promptForm: PromptForm;
70
+ /** The harness output mode. */
71
+ output: string;
72
+ /** The ship status of the harness face. */
73
+ ship: string;
74
+ /** The detect row — the marker env key(+ semantics). */
75
+ detect: HostDetectSpec;
76
+ /** The per-package install banners (kairos self-install + upstream plugins);
77
+ * `"pending"` is the literal not-yet-known command. */
78
+ install: Readonly<Record<string, readonly string[] | "pending">>;
79
+ /** The capability facts — the tested dispatch-face columns (T25). */
80
+ capabilities: HostCapabilities;
81
+ }
82
+
83
+ /** A review dispatch row — an object-shaped slot naming its ref key (the note face
84
+ * is deleted with the P5 forbidden prose; the review criteria live in the axes
85
+ * guide, render/templates.ts). */
86
+ export interface ReviewDispatchRow {
87
+ /** The ref key the review phase dispatches to. */
88
+ ref: string;
89
+ }
90
+
91
+ /**
92
+ * The dispatch table — the phase/type → skill-ref (or URC prose) resolution.
93
+ * v1.8 closeout: the spec/plan review criteria migrated to the template plane's
94
+ * REVIEWS (render/templates.ts) — the dispatch review rows are the task/branch ref
95
+ * keys only; a spec/plan review resolves no skill ref (the URC prose rides the
96
+ * review prompt's criteria body).
97
+ */
98
+ export interface DispatchTable {
99
+ /** The implement phase's ref key (M1 supersede: mattpocock-skills:implement). */
100
+ implement: string;
101
+ /** The review phase rows — the task/branch ref keys (the spec/plan rows carry no
102
+ * skill ref — the review criteria live in the template plane). */
103
+ review: Readonly<Record<"wave" | "branch", ReviewDispatchRow>>;
104
+ }
105
+
106
+ /** The per-harness slash reference forms of one ref key. */
107
+ export type HostReferenceForm = Readonly<Record<HostId, string>>;
108
+
109
+ /** The full reference table — every `<pkg>:<skill>` cross-skill reference key. */
110
+ export type HostReferenceTable = Readonly<Record<string, HostReferenceForm>>;
111
+
112
+ /** The extended typed harness contract — hosts + dispatch + refs. */
113
+ export interface HostContract {
114
+ hosts: Readonly<Record<HostId, HostRow>>;
115
+ dispatch: DispatchTable;
116
+ refs: HostReferenceTable;
117
+ }
118
+
119
+ /** The per-harness install banners — the kairos self-install + the upstream plugin
120
+ * install commands. The `packages/kairos/README.md` upstream dependency table (and
121
+ * its zh mirror) renders from these rows; the engine-suite gate
122
+ * (face/__tests__/install-rows.guard.test.ts) pins each README row's Claude Code cell
123
+ * to `INSTALL_ROWS[key].join(";")` and the row key set to these keys — a README
124
+ * install-command drift fails there, never silently. */
125
+ export const INSTALL_ROWS = {
126
+ kairos: [
127
+ "claude plugin marketplace add oscaner/skills",
128
+ "claude plugin install kairos@oscaner-skills",
129
+ ],
130
+ superpowers: [
131
+ "claude plugin marketplace add obra/superpowers-marketplace",
132
+ "claude plugin install superpowers@superpowers-marketplace",
133
+ ],
134
+ "mattpocock-skills": [
135
+ "claude plugin marketplace add mattpocock/skills",
136
+ "claude plugin install mattpocock-skills@mattpocock",
137
+ ],
138
+ impeccable: [
139
+ "claude plugin marketplace add pbakaus/impeccable",
140
+ "claude plugin install impeccable@impeccable",
141
+ ],
142
+ } as const;
143
+
144
+ /** The per-harness host rows — claude / cursor / pi adaptation facts. */
145
+ export const HOSTS = {
146
+ claude: {
147
+ promptForm: "ref-prefixed",
148
+ cli: "claude",
149
+ invoke: "-p --output-format text --dangerously-skip-permissions",
150
+ output: "text",
151
+ ship: "full",
152
+ detect: { env: "CLAUDE_CODE_SESSION_ID", aiAgentPrefix: "claude-code" },
153
+ install: INSTALL_ROWS,
154
+ capabilities: { parallel: true },
155
+ },
156
+ cursor: {
157
+ promptForm: "ref-prefixed",
158
+ cli: "cursor-agent",
159
+ invoke: "--print --output-format text --force",
160
+ output: "text",
161
+ ship: "full",
162
+ detect: { env: "CURSOR_TRACE_ID" },
163
+ install: {
164
+ kairos: "pending",
165
+ superpowers: "pending",
166
+ "mattpocock-skills": "pending",
167
+ impeccable: "pending",
168
+ },
169
+ capabilities: { parallel: "pending" },
170
+ },
171
+ pi: {
172
+ promptForm: "ref-prefixed",
173
+ cli: "pi",
174
+ invoke: "-p --mode text",
175
+ output: "text",
176
+ ship: "full",
177
+ detect: { env: "AI_AGENT", value: "pi" },
178
+ install: {
179
+ kairos: ["pi install npm:@oscaner-skills/kairos"],
180
+ superpowers: ["pi install git:github.com/obra/superpowers"],
181
+ "mattpocock-skills": ["pi install git:github.com/mattpocock/skills"],
182
+ impeccable: ["npx impeccable install --providers=pi --scope=global -y"],
183
+ },
184
+ capabilities: { parallel: "pending" },
185
+ },
186
+ } as const satisfies Readonly<Record<HostId, HostRow>>;
187
+
188
+ /** The dispatch table — the phase/type → skill-ref resolution. The implement slot
189
+ * is the M1 supersede (P5): it names the upstream `mattpocock-skills:implement`
190
+ * skill. The fix face carries no skill ref (its fix discipline rides the FIX_SHELL
191
+ * typed instructions). The REVIEW rows are the task/branch ref keys only (the
192
+ * spec/plan rows' URC review criteria migrated to the template plane's REVIEWS at
193
+ * the v1.8 closeout — their single typed home; the parallel-sub-agents note prose
194
+ * is deleted — P5 forbidden text). */
195
+ export const DISPATCH = {
196
+ implement: "mattpocock-skills:implement",
197
+ review: {
198
+ wave: { ref: "mattpocock-skills:code-review" },
199
+ branch: { ref: "mattpocock-skills:code-review" },
200
+ },
201
+ } as const satisfies DispatchTable;
202
+
203
+ /** The reference table — every `<pkg>:<skill>` cross-skill reference key and its
204
+ * per-harness slash form: claude/cursor use `/namespace:skill`, pi the flat
205
+ * `/skill:<bare>` form. The `mattpocock-skills:implement` key is registered here
206
+ * (P5 — the implement dispatch's first-class refs-domain entry). */
207
+ export const REFS = {
208
+ "superpowers:brainstorming": {
209
+ claude: "/superpowers:brainstorming",
210
+ cursor: "/superpowers:brainstorming",
211
+ pi: "/skill:brainstorming",
212
+ },
213
+ "superpowers:writing-plans": {
214
+ claude: "/superpowers:writing-plans",
215
+ cursor: "/superpowers:writing-plans",
216
+ pi: "/skill:writing-plans",
217
+ },
218
+ "superpowers:finishing-a-development-branch": {
219
+ claude: "/superpowers:finishing-a-development-branch",
220
+ cursor: "/superpowers:finishing-a-development-branch",
221
+ pi: "/skill:finishing-a-development-branch",
222
+ },
223
+ "mattpocock-skills:implement": {
224
+ claude: "/mattpocock-skills:implement",
225
+ cursor: "/mattpocock-skills:implement",
226
+ pi: "/skill:implement",
227
+ },
228
+ "mattpocock-skills:code-review": {
229
+ claude: "/mattpocock-skills:code-review",
230
+ cursor: "/mattpocock-skills:code-review",
231
+ pi: "/skill:code-review",
232
+ },
233
+ "mattpocock-skills:grilling": {
234
+ claude: "/mattpocock-skills:grilling",
235
+ cursor: "/mattpocock-skills:grilling",
236
+ pi: "/skill:grilling",
237
+ },
238
+ "kairos:cdd-design": {
239
+ claude: "/kairos:cdd-design",
240
+ cursor: "/kairos:cdd-design",
241
+ pi: "/skill:cdd-design",
242
+ },
243
+ "kairos:cdd-spec-writer": {
244
+ claude: "/kairos:cdd-spec-writer",
245
+ cursor: "/kairos:cdd-spec-writer",
246
+ pi: "/skill:cdd-spec-writer",
247
+ },
248
+ "kairos:cdd-plan": {
249
+ claude: "/kairos:cdd-plan",
250
+ cursor: "/kairos:cdd-plan",
251
+ pi: "/skill:cdd-plan",
252
+ },
253
+ "kairos:cdd-dev": { claude: "/kairos:cdd-dev", cursor: "/kairos:cdd-dev", pi: "/skill:cdd-dev" },
254
+ "kairos:cdd-close": {
255
+ claude: "/kairos:cdd-close",
256
+ cursor: "/kairos:cdd-close",
257
+ pi: "/skill:cdd-close",
258
+ },
259
+ "kairos:cdd-report": {
260
+ claude: "/kairos:cdd-report",
261
+ cursor: "/kairos:cdd-report",
262
+ pi: "/skill:cdd-report",
263
+ },
264
+ } as const satisfies HostReferenceTable;
265
+
266
+ /** The typed harness contract — one constant: hosts + dispatch + refs (the single
267
+ * harness-adaptation truth; zero `_doc`/`$schema` prose). */
268
+ export const HOST_CONTRACT = {
269
+ hosts: HOSTS,
270
+ dispatch: DISPATCH,
271
+ refs: REFS,
272
+ } as const satisfies HostContract;
273
+
274
+ /** HostDetect — the module-level host judgment (the detection's single home). The
275
+ * input is the inline structural env view — no cross-import (the host plane
276
+ * must stay import-clean toward the dispatch face). */
277
+ // biome-ignore lint/complexity/noStaticOnlyClass: the module-level host-detect surface — the zero-bare-function discipline admits no standalone predicate functions.
278
+ export class HostDetect {
279
+ /** detect(env) — the first host detect row that matches, in the pinned order
280
+ * `claude` → `cursor` → `pi` (specific markers first, the generic AI_AGENT
281
+ * last). One row detects by its primary marker (a session env, presence/enum —
282
+ * a UUID CLAUDE_CODE_SESSION_ID is claude by presence) or by the AI_AGENT
283
+ * prefix (AI_AGENT=claude-code-…); no match returns `""`. */
284
+ static detect(env: Record<string, string | undefined>): HostId | "" {
285
+ for (const id of ["claude", "cursor", "pi"] as const) {
286
+ const detect: HostDetectSpec = HOSTS[id].detect;
287
+ if (detect.env !== undefined && detect.env !== "") {
288
+ const marker = env[detect.env];
289
+ if (marker !== undefined && marker.length > 0) {
290
+ if (detect.value !== undefined && marker !== detect.value) continue;
291
+ return id;
292
+ }
293
+ }
294
+ if (detect.aiAgentPrefix !== undefined && detect.aiAgentPrefix.length > 0) {
295
+ const agent = env.AI_AGENT;
296
+ if (agent !== undefined && agent.length > 0 && agent.startsWith(detect.aiAgentPrefix))
297
+ return id;
298
+ }
299
+ }
300
+ return "";
301
+ }
302
+ }