@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (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 +149 -0
  15. package/dist/face/cli.js +893 -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 +702 -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 +504 -0
  25. package/dist/face/words.js +258 -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 +453 -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
@@ -0,0 +1,371 @@
1
+ // packages/cdd-engine/src-next/contract/project.ts
2
+ // T3 — the projection face: the six derived surfaces (shape / schema / slices /
3
+ // tokens / reference / skeleton) are projected from the declared registries
4
+ // (declare.ts) through one shared derivation chain.
5
+ //
6
+ // Every surface is pure derivation from the registries injected at construction —
7
+ // zero hand-written shape prose, zero duplicated data. The chain: each registry
8
+ // row is projected onto a derived identity (anchor · presence · ref-kind · home ·
9
+ // value pattern), and the six projection methods each select the face their
10
+ // consumers need:
11
+ // · shape — the section skeleton: registry rows grouped by home surface
12
+ // in first-occurrence order (the interpreter's structure walk);
13
+ // · schema — a JSON Schema per doc type (properties keyed by anchor, the
14
+ // required set from the required-presence elements, property
15
+ // descriptions carrying presence · home · ref-kind);
16
+ // · slices — the parse face: every element's anchor-literal slice plus the
17
+ // declared value pattern compiled for line/cell matching.
18
+ // Frontmatter-home elements are exempt from both compilations —
19
+ // their anchor is a YAML key, looked up directly against the
20
+ // parsed front-matter, never scanned line-by-line (§3.3);
21
+ // · tokens — the flat anchor lexicon, one token per registered element;
22
+ // · reference — the per-element reference vocabulary (ref-kind + value
23
+ // pattern), one entry per registered element;
24
+ // · skeleton — the doc-skeleton face (spec §4.1/§4.2): every required
25
+ // element classified into its placeholder-anchoring slot kind
26
+ // (content / link / numeric-heading / generator-truth /
27
+ // table-header / table-row / scaffold) in shape-group order,
28
+ // plus the independent front-matter emission list (the head's
29
+ // required + optional keys) — the skeleton the
30
+ // `cdd schema get <type> --output skeleton` render face (D19)
31
+ // assembles.
32
+ //
33
+ // The module's whole behavior surface is the Projector class (the zero-bare-
34
+ // function discipline: module-level exports are types / the class — the projection
35
+ // helpers and the escape primitive are private members). The schema/shape bytes are
36
+ // pinned from the new tree's first version by the test suite (byte snapshots) —
37
+ // both serializations are insertion-order deterministic, so the pinned bytes are
38
+ // stable across runs.
39
+ var _a;
40
+ import { DOC_TYPE_VALUES } from "./declare.js";
41
+ /** The four doc-type record keys in canonical order — the runtime companion of
42
+ * `DocKey`, re-exported from the declaration root (declare.ts `DOC_TYPE_VALUES`).
43
+ * The judge's policy composition and the board's declaration domain read THIS
44
+ * tuple; a value drift is impossible (one array). */
45
+ export const DOC_KEYS = DOC_TYPE_VALUES;
46
+ /**
47
+ * The projection carrier — the registered registries' single derivation surface.
48
+ * Constructed on the declared registries (the domain's `declaredRegistries`),
49
+ * its seven methods project the six faces (shape / schema / slices / tokens /
50
+ * reference / skeleton) and their composed record. Every surface is pure
51
+ * derivation from the injected registries; construction is cheap and the
52
+ * instance is stateless after construction, so sharing one instance across the
53
+ * consumers (the parsers, the contract, the lint, the graph) composes safely.
54
+ */
55
+ export class Projector {
56
+ /** The declared registries every projection derives from — the construction input. */
57
+ #registries;
58
+ constructor(registries) {
59
+ this.#registries = registries;
60
+ }
61
+ /** Derive all four doc types' section-skeleton faces. */
62
+ shape() {
63
+ return this.#projectAll((registry) => this.#projectDocShape(registry));
64
+ }
65
+ /** Derive all four doc types' JSON Schema faces. */
66
+ schema() {
67
+ return this.#projectAll((registry) => this.#projectDocSchema(registry));
68
+ }
69
+ /** Derive all four doc types' parse-regex faces. */
70
+ slices() {
71
+ return this.#projectAll((registry) => this.#projectDocSlices(registry));
72
+ }
73
+ /** Derive all four doc types' anchor lexicons. */
74
+ tokens() {
75
+ return this.#projectAll((registry) => this.#projectDocTokens(registry));
76
+ }
77
+ /** Derive all four doc types' reference vocabularies. */
78
+ reference() {
79
+ return this.#projectAll((registry) => this.#projectDocReference(registry));
80
+ }
81
+ /** Derive all four doc types' doc-skeleton faces (body slots + the front-matter
82
+ * emission list). */
83
+ skeleton() {
84
+ return this.#projectAll((registry) => this.#projectDocSkeleton(registry));
85
+ }
86
+ /** The composed projection face — all six derived surfaces over the injected registries. */
87
+ registries() {
88
+ return {
89
+ shape: this.shape(),
90
+ schema: this.schema(),
91
+ slices: this.slices(),
92
+ tokens: this.tokens(),
93
+ reference: this.reference(),
94
+ skeleton: this.skeleton(),
95
+ };
96
+ }
97
+ /**
98
+ * Escape a literal so it can be embedded verbatim in a RegExp — the
99
+ * anchor-literal → parse-regex derivation the slices face is built on. Every
100
+ * declared anchor escapes to a pattern that matches the anchor itself (the
101
+ * "each slice parses its anchor" checkable).
102
+ */
103
+ static #escapeRegExp(text) {
104
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
105
+ }
106
+ // -------------------------------------------------------------------------
107
+ // shared derivation chain — the chain root every projection selects from
108
+ // -------------------------------------------------------------------------
109
+ /** Project one registry row onto the derived identity (refKind materialized to its "none" default). */
110
+ #deriveElement(element) {
111
+ return {
112
+ anchor: element.anchor,
113
+ presence: element.presence,
114
+ refKind: element.refKind ?? "none",
115
+ home: element.home,
116
+ valuePattern: element.valuePattern,
117
+ };
118
+ }
119
+ /** Derive the whole registry rows of one doc type. */
120
+ #deriveRegistry(registry) {
121
+ return registry.elements.map((element) => this.#deriveElement(element));
122
+ }
123
+ /** Map a per-registry projector across the four injected registries, keyed by their record identity. */
124
+ #projectAll(project) {
125
+ return {
126
+ "overall-spec": project(this.#registries["overall-spec"]),
127
+ plan: project(this.#registries.plan),
128
+ "phase-spec": project(this.#registries["phase-spec"]),
129
+ "single-spec": project(this.#registries["single-spec"]),
130
+ };
131
+ }
132
+ // -------------------------------------------------------------------------
133
+ // the per-face projectors
134
+ // -------------------------------------------------------------------------
135
+ /** Project one registry onto its section-structure face (one shape element per registered element). */
136
+ #projectDocShape(registry) {
137
+ const groups = [];
138
+ const groupSlotOf = new Map();
139
+ for (const element of this.#deriveRegistry(registry)) {
140
+ let slot = groupSlotOf.get(element.home);
141
+ if (slot === undefined) {
142
+ slot = groups.length;
143
+ groupSlotOf.set(element.home, slot);
144
+ groups.push({ home: element.home, elements: [] });
145
+ }
146
+ groups[slot].elements.push({
147
+ anchor: element.anchor,
148
+ presence: element.presence,
149
+ refKind: element.refKind,
150
+ });
151
+ }
152
+ return { docType: registry.docType, structure: groups };
153
+ }
154
+ /** Project one registry onto its JSON Schema face. */
155
+ #projectDocSchema(registry) {
156
+ const elements = this.#deriveRegistry(registry);
157
+ const properties = {};
158
+ const required = [];
159
+ for (const element of elements) {
160
+ if (element.valuePattern !== undefined) {
161
+ properties[element.anchor] = {
162
+ type: "string",
163
+ pattern: element.valuePattern,
164
+ description: `presence: ${element.presence} · home: ${element.home} · ref: ${element.refKind}`,
165
+ };
166
+ }
167
+ if (element.presence === "required")
168
+ required.push(element.anchor);
169
+ }
170
+ return {
171
+ docType: registry.docType,
172
+ $schema: "https://json-schema.org/draft/2020-12/schema",
173
+ title: `${registry.docType} document structure`,
174
+ description: `Derived JSON Schema — ${elements.length} declared elements · ${required.length} required`,
175
+ type: "object",
176
+ properties,
177
+ required,
178
+ };
179
+ }
180
+ /** Project one registry onto its parse-regex face. */
181
+ #projectDocSlices(registry) {
182
+ const slices = [];
183
+ for (const element of this.#deriveRegistry(registry)) {
184
+ // Frontmatter-home elements anchor on YAML keys — a key is looked up
185
+ // directly against the parsed front-matter, so both RegExp compilations
186
+ // (anchor + value) stop on the header leg (§3.3).
187
+ const header = element.home === "frontmatter";
188
+ slices.push({
189
+ anchor: element.anchor,
190
+ presence: element.presence,
191
+ home: element.home,
192
+ anchorPattern: header ? undefined : new RegExp(_a.#escapeRegExp(element.anchor)),
193
+ valuePattern: element.valuePattern === undefined || header
194
+ ? undefined
195
+ : new RegExp(element.valuePattern),
196
+ });
197
+ }
198
+ return { docType: registry.docType, slices };
199
+ }
200
+ /** Project one registry onto its anchor-lexicon face. */
201
+ #projectDocTokens(registry) {
202
+ return {
203
+ docType: registry.docType,
204
+ tokens: this.#deriveRegistry(registry).map((element) => ({
205
+ anchor: element.anchor,
206
+ presence: element.presence,
207
+ home: element.home,
208
+ refKind: element.refKind,
209
+ })),
210
+ };
211
+ }
212
+ /** Project one registry onto its reference-vocabulary face. */
213
+ #projectDocReference(registry) {
214
+ return {
215
+ docType: registry.docType,
216
+ entries: this.#deriveRegistry(registry).map((element) => ({
217
+ anchor: element.anchor,
218
+ refKind: element.refKind,
219
+ valuePattern: element.valuePattern,
220
+ })),
221
+ };
222
+ }
223
+ // -------------------------------------------------------------------------
224
+ // the skeleton face — the doc-skeleton projection (spec §4.1/§4.2)
225
+ // -------------------------------------------------------------------------
226
+ /** Project one registry onto its doc-skeleton face — the required elements'
227
+ * slots in the shape's home-group order (the shape walk is the ordering
228
+ * source: group sequence + within-group registry order, never a second order
229
+ * declaration). Optional/conditional elements generate no slot — the zero
230
+ * conditional-residue contract mirrored at the skeleton surface. The
231
+ * front-matter emission list is projected independently of the slot channel
232
+ * (§4.2: required head keys + the type's optional head keys; `parent-version`
233
+ * is the one explicit exclusion — its `v<n>.<m>` domain admits no placeholder
234
+ * form). */
235
+ #projectDocSkeleton(registry) {
236
+ const byAnchor = new Map(this.#deriveRegistry(registry).map((element) => [element.anchor, element]));
237
+ const slots = [];
238
+ for (const group of this.#projectDocShape(registry).structure) {
239
+ for (const element of group.elements) {
240
+ const derived = byAnchor.get(element.anchor);
241
+ if (derived.presence !== "required")
242
+ continue;
243
+ slots.push(this.#skeletonSlot(derived));
244
+ }
245
+ }
246
+ return { docType: registry.docType, slots, frontmatter: this.#frontmatterSlots(registry) };
247
+ }
248
+ /** The front-matter emission list — the independent line set §4.2 prescribes:
249
+ * every frontmatter-home required key plus the type's optional head keys
250
+ * (`base` / `depends-on`), in registry order. `parent-version` is the single
251
+ * explicit exclusion: an optional shape-typed key whose domain admits neither
252
+ * placeholder form, so absence is the only legal skeleton state (the consumer
253
+ * fills it when the parent version is known). */
254
+ #frontmatterSlots(registry) {
255
+ const out = [];
256
+ for (const element of this.#deriveRegistry(registry)) {
257
+ if (element.home !== "frontmatter")
258
+ continue;
259
+ if (element.anchor === "parent-version")
260
+ continue;
261
+ out.push(this.#skeletonSlot(element));
262
+ }
263
+ return out;
264
+ }
265
+ /** Project one derived element onto its skeleton slot row. */
266
+ #skeletonSlot(element) {
267
+ return {
268
+ anchor: element.anchor,
269
+ presence: element.presence,
270
+ home: element.home,
271
+ slot: this.#skeletonSlotOf(element),
272
+ valuePattern: element.valuePattern,
273
+ refKind: element.refKind,
274
+ };
275
+ }
276
+ /** Classify one required element's slot kind — the placeholder-anchoring
277
+ * semantics of the element's value (spec §4.1):
278
+ * · link — the parent-program / spec-ref link-shaped anchors render
279
+ * as placeholder links (`:::fill` never lands on them — a
280
+ * fill in a link slot is a guaranteed finding);
281
+ * · numeric-heading — the digit-family headings (`N.` / `N.M` / `Task N:`)
282
+ * whose numbers are true values in the skeleton, never a
283
+ * literal `N` (a literal `N` punctures the declared
284
+ * digit-shaped value pattern);
285
+ * · generator-truth — a pattern-typed value row: a fully-anchored enum domain
286
+ * (the first legal literal — `status: Draft`) or a
287
+ * graph row (hard edge / legend conforming lines);
288
+ * · table-header / table-row / scaffold — the table column headers, the data
289
+ * rows and the fixed scaffold rows (the version line, the
290
+ * table version/date tokens, the fixed structure headings);
291
+ * · content — the remaining free-text value positions — the ONLY
292
+ * `:::fill` landing class (pure content slots carry zero
293
+ * fully-anchored enum / graph elements).
294
+ */
295
+ #skeletonSlotOf(element) {
296
+ // The link-typed anchor slots are the front-matter link keys (`spec` · the
297
+ // `parent-program` of plan / phase-spec) — their values render as placeholder
298
+ // links (`<…>` targets on the exemption chain), never `:::fill`. The
299
+ // enum-typed table cells (a Design-spec cell, a markdown-link
300
+ // implementation-plan cell) ride the generator-truth class, never a link
301
+ // slot — the home + ref-kind pair keys the class (the frontmatter-home
302
+ // anchors are now YAML keys, so the old `\[`-shape probe no longer applies).
303
+ if (element.home === "frontmatter" &&
304
+ (element.refKind === "parent-program" || element.refKind === "spec-ref"))
305
+ return "link";
306
+ if ((element.anchor.startsWith("#") || element.anchor === "Task id token") &&
307
+ element.valuePattern !== undefined &&
308
+ /\\d/.test(element.valuePattern))
309
+ return "numeric-heading";
310
+ // The front-matter version and date rows are fixed scaffold — the same class
311
+ // as the table version/date tokens.
312
+ if (element.anchor === "version" || element.anchor === "date")
313
+ return "scaffold";
314
+ if (element.home === "graph" || _a.#isEnumPattern(element.valuePattern))
315
+ return "generator-truth";
316
+ if (element.home === "table") {
317
+ if (element.anchor.endsWith(" columns"))
318
+ return "table-header";
319
+ if (element.anchor.endsWith(" row"))
320
+ return "table-row";
321
+ // The dependency cell is a free-text cell value (`:::fill` — a P->P shape to
322
+ // fill, not a structural token) — every other table token (version / date /
323
+ // phase id) is fixed scaffold.
324
+ if (element.anchor === "Dependency cell")
325
+ return "content";
326
+ return "scaffold";
327
+ }
328
+ // The front-matter content keys (the title plus the other free-text head
329
+ // scalars — author · depends-on · base) are the head's fill positions (`:::fill
330
+ // <key>` in the emitted front matter); the remaining heading anchors are fixed
331
+ // structure.
332
+ if (element.anchor === "title")
333
+ return "content";
334
+ if (element.anchor.startsWith("#"))
335
+ return "scaffold";
336
+ return "content";
337
+ }
338
+ /** Whether a declared value pattern is a point-enum form — a bare pipe inside an
339
+ * alternative group (escapes stripped first: the declared patterns escape their
340
+ * literal metacharacters — `\|` = a table bar, `\[` = a literal bracket — while
341
+ * the enum alternatives ride BARE pipes inside unescaped group parens; parens
342
+ * inside the character classes are skipped). The strip leaves the character
343
+ * classes partially intact — the scan tracks class brackets so a `)` inside
344
+ * `[^)]` never closes the group. The first legal literal is the generator truth. */
345
+ static #isEnumPattern(valuePattern) {
346
+ if (valuePattern === undefined)
347
+ return false;
348
+ const unescaped = valuePattern.replace(/\\./g, "");
349
+ let depth = 0;
350
+ let inClass = false;
351
+ for (const char of unescaped) {
352
+ if (inClass) {
353
+ if (char === "]")
354
+ inClass = false;
355
+ continue;
356
+ }
357
+ if (char === "[") {
358
+ inClass = true;
359
+ continue;
360
+ }
361
+ if (char === "(")
362
+ depth += 1;
363
+ else if (char === ")")
364
+ depth -= 1;
365
+ else if (char === "|" && depth > 0)
366
+ return true;
367
+ }
368
+ return false;
369
+ }
370
+ }
371
+ _a = Projector;
@@ -0,0 +1,156 @@
1
+ // packages/cdd-engine/src-next/contract/skill-anatomy.ts
2
+ // T14 — the skill-anatomy contract typed export: skill-anatomy.json's content
3
+ // relocates into this typed constant module (the engine contract plane). The old
4
+ // JSON home is retired — the guard (scripts) consumes THIS export, never a JSON path.
5
+ //
6
+ // The contract: the node-anchored skill (SKILL.md) document structure — the
7
+ // section-heading registry (a STRICT allowlist), the `## Flow Digraph` mermaid
8
+ // section (mermaid-only), the `### `node`` node-definition grammar, the per-node
9
+ // four-element contract, the `## Invariants` / `## Failure Modes` tables, the
10
+ // BLOCKED terminal convention, the growth boundary (15 nodes / 17 edges — a
11
+ // crossing's rationale registers in this contract's registry), and the
12
+ // consumer-surface purity rule (SKILL.md carries zero growth/refactor narrative
13
+ // headings). Every fact the guard asserts is data here — the guard never restates
14
+ // a heading, pattern or limit.
15
+ //
16
+ // Module-level exports are type definitions + the declared contract constant —
17
+ // zero behavior-carrying bare functions (the plan's zero-bare-function discipline).
18
+ /** The section-heading registry — the strict `## `/`### ` allowlist (public +
19
+ * conditional sections + the node-name heading grammar). */
20
+ const SECTION_REGISTRY = {
21
+ public: ["flowDigraph", "nodeDefinitions", "invariants", "failureModes"],
22
+ conditional: [],
23
+ sections: {
24
+ flowDigraph: { heading: "## Flow Digraph" },
25
+ nodeDefinitions: { heading: "## Node Definitions" },
26
+ invariants: { heading: "## Invariants" },
27
+ failureModes: { heading: "## Failure Modes" },
28
+ },
29
+ headingKinds: { nodeName: { pattern: "^### `[^`]+`$" } },
30
+ };
31
+ /** The six-skill roster — the P4 closed set: exactly these members ship, the 9th
32
+ * seat is vacant (a directory scan may carry zero more, zero missing); the family
33
+ * facts drive the digraph-shape assertions (consistency over the five chains). */
34
+ const SKILL_ROSTER = {
35
+ "cdd-design": { role: "orchestrator", family: "onepass" },
36
+ "cdd-spec-writer": { role: "spec-writer", family: "loop" },
37
+ "cdd-plan": { role: "orchestrator", family: "loop" },
38
+ "cdd-dev": { role: "executor", family: "loop" },
39
+ "cdd-close": { role: "orchestrator", family: "close" },
40
+ "cdd-report": { role: "utility", family: "onepass" },
41
+ };
42
+ /** The skill-anatomy contract — one typed constant: the structure facts + the
43
+ * diagnostic wording the checks quote (single source, never a guard literal). */
44
+ export const SKILL_ANATOMY = {
45
+ sectionRegistry: SECTION_REGISTRY,
46
+ digraph: {
47
+ sectionHeading: "## Flow Digraph",
48
+ mermaidOnly: true,
49
+ mermaidFence: "```mermaid",
50
+ nodeTypes: {
51
+ operator: { pattern: "^\\w+\\[.*\\]$" },
52
+ decision: { pattern: "^\\w+\\{.*\\}$" },
53
+ terminal: { pattern: "^\\w+\\(\\(.*\\)\\)$" },
54
+ },
55
+ terminalStates: { blocked: "BLOCKED", approved: "APPROVED" },
56
+ // The five-chain unified skeleton — one shared hub across the loop family; the
57
+ // hub carries the two-edge pipeline shape (the closure routes through the engine's
58
+ // next face, D33 — no closure exit, no handoff-* terminal). The close/onepass
59
+ // families are the explicit no-self-loop exceptions.
60
+ loopHubNode: { name: "NEXT-LOOP" },
61
+ // The v1.20 restored loop conditions — the pinned word face of the NEXT-LOOP hub's
62
+ // two out-edges (the digraph's static branch truth, one table with the runtime
63
+ // `next:` instance: `until next is terminal` self-loop · the `no next` failure
64
+ // face. Each label must be one of these — the guard asserts it).
65
+ nextLoopConditions: ["until next is terminal", "no next"],
66
+ },
67
+ nodeDefinitions: {
68
+ sectionHeading: "## Node Definitions",
69
+ headingKind: { pattern: "^### `[^`]+`$" },
70
+ extensionRule: "prose sections map one-to-one to graph nodes",
71
+ },
72
+ nodeElements: {
73
+ do: { pattern: "^- \\*\\*Do\\*\\*:" },
74
+ read: { pattern: "^- \\*\\*Read\\*\\*:" },
75
+ exit: { pattern: "^- \\*\\*Exit\\*\\*:" },
76
+ fail: { pattern: "^- \\*\\*Fail\\*\\*:" },
77
+ },
78
+ invariants: { table: { rowPattern: "^\\|\\s*[A-Z]+\\d+\\s*\\|" } },
79
+ failureModes: { table: { rowPattern: "^\\|[^\\n]+\\|$" } },
80
+ blockedTerminal: {
81
+ stateToken: "BLOCKED",
82
+ requires: ["blocking reason", "recovery action", "no silent fallback"],
83
+ },
84
+ growthBoundary: {
85
+ nodeLimit: 15,
86
+ edgeLimit: 17,
87
+ // The registered-growth rationale registry — a digraph crossing the boundary is
88
+ // admitted here (never narrated inside the consumer SKILL.md). No crossing is
89
+ // registered: every live digraph stays inside the node/edge limits.
90
+ registry: {
91
+ crossings: {},
92
+ },
93
+ },
94
+ consumerPurity: {
95
+ forbiddenNarrativeHeads: ["## Flow size note", "## Full Flow Refactor Rationale"],
96
+ zeroTraceRule: "zero trace in the consumer skill",
97
+ },
98
+ // The author-entry bootstrap surface (§10 · the D29-regression pin) — the
99
+ // content-authoring entry nodes' skeleton bootstrap literals. D29 strips the
100
+ // INTERNAL structure mirror (slot names / `:::fill` restatements), never the
101
+ // entry node's bootstrap command (its own exception); this pins the literals so
102
+ // a shape-keyed strip cannot silently remove them again.
103
+ authorBootstrap: {
104
+ entries: [
105
+ { skill: "cdd-spec-writer", node: "author-spec" },
106
+ { skill: "cdd-plan", node: "author-plan" },
107
+ ],
108
+ skeletonCommandPattern: "schema get \\S+ --output skeleton",
109
+ },
110
+ // The frontmatter-validity rule (spec §4 · D42) — every shipped SKILL.md's YAML
111
+ // frontmatter block must parse under a REAL parser; a bare `: ` in an unquoted
112
+ // scalar breaks the block and the harness silently drops the skill.
113
+ frontmatter: {
114
+ fence: "---",
115
+ rule: "every SKILL.md frontmatter block must parse under a real YAML parser — an unquoted `: ` in a scalar makes the block unparseable and the harness silently drops the skill (D42)",
116
+ },
117
+ skills: { registry: SKILL_ROSTER },
118
+ // The check-facing diagnostic wording — the prose the anatomy assertions quote
119
+ // when a structure rule fires (the contract's self-describing face).
120
+ wording: {
121
+ registryRule: "the section-heading registry is a STRICT allowlist — a registry-external heading is a BLOCK because an undefined section is uncertainty on the consumer's real entry surface",
122
+ headingKindRule: "every live `### ` heading is a backticked node-name heading (a node-definitions entry) — any other `### ` form is registry-external → BLOCK",
123
+ digraphContentRule: "the Flow Digraph section carries EXACTLY ONE mermaid block and ZERO trailing prose — a flow intro line below the mermaid is redundant narration, forbidden on the consumer surface",
124
+ nodeElementRule: "the per-node four-element contract — every node definition's prose carries Do / Read / Exit / Fail; a node missing any of the four elements is structurally incomplete",
125
+ nodeDefinitionRule: "every digraph operator node has a definition heading and every definition heading names a digraph operator node (bidirectional completeness) — orphans and dangling nodes fail",
126
+ growthRule: "crossing the growth boundary requires a rationale registered in this contract's growth registry — NEVER inside the consumer-shipped SKILL.md (consumer-surface purity)",
127
+ purityRule: "SKILL.md is an instruction document — growth/refactor narrative headings are forbidden in ANY form; the rationale surface lives here, the consumer skill carries zero trace",
128
+ closedSetRule: "the kairos skills are a CLOSED six-set registered in this contract's roster — the directory scan must carry exactly these members (9th seat vacant): an extra member is a new skill entering without registration, a missing member is a retired skill leaving without a plan entry",
129
+ loopShapeRule: "the five-chain unified skeleton — every loop-family skill digraph carries the shared NEXT-LOOP hub; the hub carries TWO out-edges (the `until next is terminal` self-loop · the `no next` BLOCKED face) and NO handoff-* terminal — its closure routes through the engine's next face (the dissolved handoff, D33) (digraph↔Node Definitions↔text-reference consistency, shared node names must never drift)",
130
+ enderShapeRule: "the explicit no-self-loop exceptions — cdd-close ends at the finish semantic gate + terminal, cdd-report is a one-shot toolchain, cdd-design is a forked-routing one-pass flow; a NEXT-LOOP self-loop in any of them is a shape violation",
131
+ edgeConditionRule: "decision edges carry explicit condition labels — the NEXT-LOOP hub's out-edges ARE the pinned loop conditions (`until next is terminal` → self-loop · `no next` → BLOCKED) and every edge out of a decision node is condition-labeled; an unlabeled decision edge, a bare NEXT-LOOP self-loop, or a NEXT-LOOP out-edge count/condition that deviates from the pinned shape is a shape violation (the edge-zero-state-label rule retired v1.20)",
132
+ routeFactRule: "next: is consumed as a dispatch-ready literal (the literal IS the dispatch, no kind→command mapping layer); a full cdd command string never follows the next: token on a line; BLOCKED/TIMEOUT carry no next line and are not consumed as next steps",
133
+ },
134
+ // The engine-lexicon pinned condition words (the v1.20 word-table pin) — the phrase
135
+ // set the digraph's loop/closure decision edges may carry: the NEXT-LOOP phrases +
136
+ // the decision status words (the word table's status vocabulary minus the failure
137
+ // statuses) + the Route decision words (the `next:` lexical domain). This declared
138
+ // value is PINNED by the engine-suite derivation gate
139
+ // (contract/__tests__/edge-conditions.guard.test.ts) — it must equal the derivation
140
+ // from the engine word table / Route lexicon (`CAPSULE_WORDS.status` minus
141
+ // `FAILED_STATUS`, `ROUTE_DECISION_WORDS`, `nextLoopConditions`); a drifted engine
142
+ // word fails that gate, never a silent second list. The kairos-suite edge assertion
143
+ // consumes this set as its label allowlist.
144
+ edgeConditionWords: [
145
+ "until next is terminal",
146
+ "no next",
147
+ "APPROVED",
148
+ "CHANGES_REQUESTED",
149
+ "REVIEW_FIX",
150
+ "done",
151
+ "next-wave",
152
+ "review",
153
+ "fix",
154
+ "soft-cap",
155
+ ],
156
+ };
@@ -0,0 +1,85 @@
1
+ // packages/cdd-engine/src-next/contract/translate.ts
2
+ // T19 — the single bidirectional translation layer (the P7 translation system core):
3
+ // the words' locale face (each row `{ en: canonical, zh?: Chinese alias }`) is served
4
+ // by the word table (face/words.ts — the word table's locale family), and ONE
5
+ // translator class speaks for the whole plane:
6
+ //
7
+ // canonicalize(line) — the recognition face: every registered Chinese alias span in
8
+ // the line maps to its canonical English row (the longest registered alias wins
9
+ // at each position — non-overlapping spans; unregistered text passes through
10
+ // unchanged). The doc-parse / judge recognition channel the legacy Chinese
11
+ // markers used to need — recognition rides this layer, never a second
12
+ // hand-written map. The single recognition face: the retired single-token
13
+ // normalize folds in — a single-token judgement is canonicalize over that
14
+ // token's line.
15
+ // localize(token, locale) — the rendering face: the canonical token → the requested
16
+ // locale's output word (the en locale renders the canonical itself — identity),
17
+ // the human-readable rendering faces' locale-normalized output.
18
+ //
19
+ // The layer is word-table driven with ZERO switch (a new word is declared as data,
20
+ // never as a code branch — the lookups are maps over the injected row data). The
21
+ // capsule machine face (status · next: · CDD_BLOCKED:) is deliberately NOT in the
22
+ // locale rows — the machine surface is English-constant and never localizable.
23
+ // Module-level exports are types / the class — zero behavior-carrying bare functions.
24
+ /**
25
+ * Translator — the single bidirectional translation layer. canonicalize() recognizes
26
+ * an input line — every registered Chinese alias span maps to its canonical English
27
+ * form, unregistered text passes through (identity); localize() renders a canonical
28
+ * token at a requested locale. Both ride the injected word-table locale face — zero
29
+ * switch: a new word is a new data row, never a new code branch (the word table is
30
+ * the single-source translation data).
31
+ */
32
+ export class Translator {
33
+ /** The bilingual row index — canonical token → its row (the localize/identity path). */
34
+ #byToken;
35
+ /** The alias index — non-en alias → its canonical token (the canonicalize path). */
36
+ #byAlias;
37
+ /** The alias keys, longest first — the canonicalize scan order (the longest
38
+ * registered alias binds at each position; a same-length tie keeps insertion
39
+ * order). Built once — the scan never re-sorts. */
40
+ #aliasesByLength;
41
+ constructor(face) {
42
+ const byToken = new Map();
43
+ const byAlias = new Map();
44
+ for (const row of face.localeRows()) {
45
+ byToken.set(row.en, row);
46
+ if (row.zh !== undefined)
47
+ byAlias.set(row.zh, row.en);
48
+ }
49
+ this.#byToken = byToken;
50
+ this.#byAlias = byAlias;
51
+ this.#aliasesByLength = [...byAlias.keys()].sort((a, b) => b.length - a.length);
52
+ }
53
+ /** canonicalize(line) — the bidirectional recognition face: every registered
54
+ * Chinese alias span in the line maps to its canonical English row (the longest
55
+ * registered alias wins at each position — non-overlapping spans; unregistered
56
+ * text, an already-canonical line, and an empty line pass through unchanged). The
57
+ * single recognition face — a single-token judgement is canonicalize over that
58
+ * token's line (the retired single-token normalize). Pure: the caller owns any
59
+ * write-back — this method never rewrites the source document. */
60
+ canonicalize(line) {
61
+ let out = "";
62
+ let i = 0;
63
+ while (i < line.length) {
64
+ const alias = this.#aliasesByLength.find((candidate) => line.startsWith(candidate, i));
65
+ if (alias === undefined) {
66
+ out += line[i];
67
+ i += 1;
68
+ }
69
+ else {
70
+ out += this.#byAlias.get(alias);
71
+ i += alias.length;
72
+ }
73
+ }
74
+ return out;
75
+ }
76
+ /** localize(token, locale) — the rendering face: the canonical token → the requested
77
+ * locale's output word (en renders the canonical itself — identity); an unknown
78
+ * token, an unknown locale, or a row without the locale's column is null. */
79
+ localize(token, locale) {
80
+ const row = this.#byToken.get(token);
81
+ if (row === undefined)
82
+ return null;
83
+ return row[locale] ?? null;
84
+ }
85
+ }