@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,998 @@
1
+ // packages/cdd-engine/src-next/contract/declare.ts
2
+ // T2 — the element-registry declaration (the design spec's single-declaration root).
3
+ //
4
+ // Each doc type (overall-spec / plan / phase-spec / single-spec) carries one typed
5
+ // element registry:
6
+ // flat declared data, one row per element — anchor token · presence · value
7
+ // pattern · ref kind · home surface. The registry is simultaneously the
8
+ // interpreter's judgment data (judge.ts consumes the anchors/domains) and the
9
+ // projection surfaces' derivation source (project.ts derives shape / schema /
10
+ // slices / tokens / reference from it) — no hand-written duplicate exists
11
+ // anywhere in the new tree.
12
+ //
13
+ // The element lines are enumerated from the methodology skeleton semantics (the
14
+ // machine skeleton of each doc type as pinned by the four repo schema JSONs,
15
+ // read as steady contract data) — freshly declared anchors, never cut from the
16
+ // old tree's sources. Counts stand at overall-spec 42 / plan 31 / phase-spec 27 /
17
+ // single-spec 16, each within the post-frontmatter band (single-spec below 20 —
18
+ // the lightweight-scaffold charter) and each element carrying all five fields
19
+ // (a completeness contract enforced by the array shape below and by the test
20
+ // suite, which pins presence/ref-kind domains and per-registry anchor
21
+ // uniqueness).
22
+ // The legal value vocabularies — the single declared source the guards check
23
+ // against. Each is pinned to its narrow union, so a domain drift fails the
24
+ // compile.
25
+ const PRESENCE_VALUES = [
26
+ "required",
27
+ "optional",
28
+ "conditional",
29
+ ];
30
+ const REF_KIND_VALUES = [
31
+ "none",
32
+ "version-lineage",
33
+ "markdown-link",
34
+ "phase-id",
35
+ "issue-ref",
36
+ "spec-ref",
37
+ "parent-program",
38
+ "task-id",
39
+ ];
40
+ const HOME_VALUES = [
41
+ "frontmatter",
42
+ "section",
43
+ "facet",
44
+ "table",
45
+ "graph",
46
+ "task-block",
47
+ "task-field",
48
+ "task-step",
49
+ "design-body",
50
+ "conditional",
51
+ ];
52
+ export const DOC_TYPE_VALUES = [
53
+ "overall-spec",
54
+ "plan",
55
+ "phase-spec",
56
+ "single-spec",
57
+ ];
58
+ /**
59
+ * The registry guards — the runtime contract that narrows an unknown candidate
60
+ * to a registry element or a full element registry. A static predicate class
61
+ * (zero instance state): every guard reads its legal vocabulary from the
62
+ * declared constants above, so a domain drift fails the guard tests.
63
+ */
64
+ // biome-ignore lint/complexity/noStaticOnlyClass: the plan-mandated static guard surface — the zero-bare-function discipline admits no standalone predicate functions.
65
+ export class RegistryGuard {
66
+ /** Narrow a candidate to a well-formed registry element: anchor token, presence,
67
+ * value pattern, ref kind and home all inside their legal domains. */
68
+ static isElement(value) {
69
+ if (typeof value !== "object" || value === null)
70
+ return false;
71
+ const candidate = value;
72
+ if (typeof candidate.anchor !== "string" || candidate.anchor.length === 0)
73
+ return false;
74
+ if (typeof candidate.presence !== "string" ||
75
+ !PRESENCE_VALUES.includes(candidate.presence))
76
+ return false;
77
+ if (candidate.valuePattern !== undefined && typeof candidate.valuePattern !== "string")
78
+ return false;
79
+ if (candidate.refKind !== undefined &&
80
+ (typeof candidate.refKind !== "string" ||
81
+ !REF_KIND_VALUES.includes(candidate.refKind)))
82
+ return false;
83
+ if (typeof candidate.home !== "string" ||
84
+ !HOME_VALUES.includes(candidate.home))
85
+ return false;
86
+ return true;
87
+ }
88
+ /** Narrow a candidate to a full element registry (doc type + all elements well-formed). */
89
+ static isRegistry(value) {
90
+ if (typeof value !== "object" || value === null)
91
+ return false;
92
+ const candidate = value;
93
+ if (typeof candidate.docType !== "string" ||
94
+ !DOC_TYPE_VALUES.includes(candidate.docType))
95
+ return false;
96
+ if (!Array.isArray(candidate.elements))
97
+ return false;
98
+ return candidate.elements.every((element) => RegistryGuard.isElement(element));
99
+ }
100
+ }
101
+ // ---------------------------------------------------------------------------
102
+ // overall-spec — the charter section surface
103
+ // ---------------------------------------------------------------------------
104
+ const OVERALL_SPEC_ELEMENTS = [
105
+ // Header block — YAML front-matter keys (a frontmatter-home anchor IS the
106
+ // front-matter key name; the value patterns are scalar shapes, §2.3).
107
+ {
108
+ anchor: "title",
109
+ presence: "required",
110
+ valuePattern: "^.+$",
111
+ refKind: "none",
112
+ home: "frontmatter",
113
+ },
114
+ {
115
+ anchor: "doc-type",
116
+ presence: "required",
117
+ valuePattern: `^(${DOC_TYPE_VALUES.join("|")})$`,
118
+ refKind: "none",
119
+ home: "frontmatter",
120
+ },
121
+ {
122
+ anchor: "version",
123
+ presence: "required",
124
+ valuePattern: "^v\\d+\\.\\d+$",
125
+ refKind: "version-lineage",
126
+ home: "frontmatter",
127
+ },
128
+ {
129
+ anchor: "date",
130
+ presence: "required",
131
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
132
+ refKind: "none",
133
+ home: "frontmatter",
134
+ },
135
+ {
136
+ anchor: "status",
137
+ presence: "required",
138
+ valuePattern: "^(Draft|Approved|In progress|Complete)$",
139
+ refKind: "none",
140
+ home: "frontmatter",
141
+ },
142
+ {
143
+ anchor: "author",
144
+ presence: "required",
145
+ valuePattern: "^.+$",
146
+ refKind: "none",
147
+ home: "frontmatter",
148
+ },
149
+ // `##`-ranked sections.
150
+ {
151
+ anchor: "## Document scope",
152
+ presence: "required",
153
+ valuePattern: "^## Document scope$",
154
+ refKind: "none",
155
+ home: "section",
156
+ },
157
+ {
158
+ anchor: "## File paths",
159
+ presence: "required",
160
+ valuePattern: "^## File paths$",
161
+ refKind: "none",
162
+ home: "section",
163
+ },
164
+ {
165
+ anchor: "## Program charter",
166
+ presence: "required",
167
+ valuePattern: "^## Program charter$",
168
+ refKind: "none",
169
+ home: "section",
170
+ },
171
+ {
172
+ anchor: "## Issue inventory",
173
+ presence: "required",
174
+ valuePattern: "^## Issue inventory$",
175
+ refKind: "none",
176
+ home: "section",
177
+ },
178
+ {
179
+ anchor: "## Phase inventory",
180
+ presence: "required",
181
+ valuePattern: "^## Phase inventory$",
182
+ refKind: "none",
183
+ home: "section",
184
+ },
185
+ {
186
+ anchor: "## Dependency graph",
187
+ presence: "required",
188
+ valuePattern: "^## Dependency graph( \\(ASCII\\))?$",
189
+ refKind: "none",
190
+ home: "section",
191
+ },
192
+ {
193
+ anchor: "## Boundary rules",
194
+ presence: "required",
195
+ valuePattern: "^## Boundary rules$",
196
+ refKind: "none",
197
+ home: "section",
198
+ },
199
+ // The constraint surface (Form A delta-only) — the retired overall Constraints
200
+ // header bullet normalised to the body section + its delta bullet (the body
201
+ // anchor must be declared before the skeleton composes it, §2.4).
202
+ {
203
+ anchor: "## Constraints",
204
+ presence: "required",
205
+ valuePattern: "^## Constraints$",
206
+ refKind: "none",
207
+ home: "section",
208
+ },
209
+ {
210
+ anchor: "Constraint delta bullet",
211
+ presence: "required",
212
+ valuePattern: "^- ",
213
+ refKind: "none",
214
+ home: "section",
215
+ },
216
+ {
217
+ anchor: "## Maintenance",
218
+ presence: "required",
219
+ valuePattern: "^## Maintenance$",
220
+ refKind: "none",
221
+ home: "section",
222
+ },
223
+ {
224
+ anchor: "## Change history",
225
+ presence: "required",
226
+ valuePattern: "^## Change history$",
227
+ refKind: "none",
228
+ home: "section",
229
+ },
230
+ // Charter facets (`###`/`####` leaves under the charter). The legacy Chinese
231
+ // markers (the doc-arch decision-group leaves M/F/R/B/E, the doc-arch
232
+ // upstream-endorsements facet) match through the judge's canonicalize row-source
233
+ // seam (contract/judge.ts) — the value patterns below are English canonicals,
234
+ // never a second hand-written zh pattern.
235
+ {
236
+ anchor: "### Goal",
237
+ presence: "required",
238
+ valuePattern: "^### Goal",
239
+ refKind: "none",
240
+ home: "facet",
241
+ },
242
+ {
243
+ anchor: "### Non-goals",
244
+ presence: "required",
245
+ valuePattern: "^### Non-goals",
246
+ refKind: "none",
247
+ home: "facet",
248
+ },
249
+ {
250
+ anchor: "### Cross-cutting",
251
+ presence: "required",
252
+ valuePattern: "^### Cross-cutting",
253
+ refKind: "none",
254
+ home: "facet",
255
+ },
256
+ {
257
+ anchor: "#### [MFRBEN] group",
258
+ presence: "optional",
259
+ valuePattern: "^#### [MFRBEN] group",
260
+ refKind: "none",
261
+ home: "facet",
262
+ },
263
+ {
264
+ anchor: "#### Upstream Endorsements",
265
+ presence: "optional",
266
+ valuePattern: "^#### Upstream Endorsements$",
267
+ refKind: "none",
268
+ home: "facet",
269
+ },
270
+ // Issue inventory — the anchor-registration domain.
271
+ {
272
+ anchor: "Issue inventory columns",
273
+ presence: "required",
274
+ valuePattern: "^\\| Phase \\| Issue \\(ref\\) \\| Title summary \\|$",
275
+ refKind: "none",
276
+ home: "table",
277
+ },
278
+ {
279
+ anchor: "Issue row",
280
+ presence: "required",
281
+ valuePattern: "^\\|\\s*P\\d+(\\.\\d+)*\\s*\\|",
282
+ refKind: "issue-ref",
283
+ home: "table",
284
+ },
285
+ {
286
+ anchor: "Issue ref cell",
287
+ presence: "required",
288
+ valuePattern: "^(none|#\\d+|\\[#\\d+\\]|#\\d+#issuecomment-\\d+|([^)]*)|\\([^)]*\\))$",
289
+ refKind: "issue-ref",
290
+ home: "table",
291
+ },
292
+ {
293
+ anchor: "issuecomment anchor",
294
+ presence: "conditional",
295
+ valuePattern: "^#\\d+#issuecomment-\\d+$",
296
+ refKind: "issue-ref",
297
+ home: "table",
298
+ },
299
+ // Phase inventory row ledger.
300
+ {
301
+ anchor: "Phase inventory columns",
302
+ presence: "required",
303
+ valuePattern: "^\\| # \\| Phase \\| Scope \\| Design spec \\| Implementation plan \\| Acceptance criteria \\| Dependency \\|$",
304
+ refKind: "none",
305
+ home: "table",
306
+ },
307
+ {
308
+ anchor: "Phase row",
309
+ presence: "required",
310
+ valuePattern: "^\\|\\s*P\\d+(\\.\\d+)*\\s*\\|",
311
+ refKind: "phase-id",
312
+ home: "table",
313
+ },
314
+ {
315
+ anchor: "Phase id token",
316
+ presence: "required",
317
+ valuePattern: "^P\\d+(\\.\\d+)*$",
318
+ refKind: "phase-id",
319
+ home: "table",
320
+ },
321
+ {
322
+ anchor: "Implementation plan cell",
323
+ presence: "required",
324
+ valuePattern: "^(Pending|\\[Pending\\]|In-flight|\\[In-flight\\]|Done|\\[[^\\]]+\\]\\([^)]+\\))$",
325
+ refKind: "markdown-link",
326
+ home: "table",
327
+ },
328
+ {
329
+ anchor: "Design spec cell",
330
+ presence: "required",
331
+ valuePattern: "^(\\[[^\\]]+\\]\\([^)]+\\)|P\\d+(\\.\\d+)*-design|Done|\\[Pending\\])$",
332
+ refKind: "spec-ref",
333
+ home: "table",
334
+ },
335
+ {
336
+ anchor: "Dependency cell",
337
+ presence: "required",
338
+ valuePattern: "^P\\d+(\\.\\d+)*\\s*->",
339
+ refKind: "phase-id",
340
+ home: "table",
341
+ },
342
+ // Dependency graph edges + legend.
343
+ {
344
+ anchor: "Hard edge",
345
+ presence: "required",
346
+ valuePattern: "^P\\d+(\\.\\d+)*\\s*->\\s*P\\d+(\\.\\d+)*",
347
+ refKind: "phase-id",
348
+ home: "graph",
349
+ },
350
+ {
351
+ anchor: "Soft edge",
352
+ presence: "optional",
353
+ valuePattern: "^P\\d+(\\.\\d+)*\\s*->\\s*\\(?\\s*soft\\s*\\)?",
354
+ refKind: "phase-id",
355
+ home: "graph",
356
+ },
357
+ {
358
+ anchor: "Graph legend",
359
+ presence: "required",
360
+ valuePattern: "^(?:- )?`?->\\s*(?:\\(soft\\))?\\s*`? = hard block|^(?:- )?`?->\\s*\\(soft\\)\\s*`? = suggestion only",
361
+ refKind: "none",
362
+ home: "graph",
363
+ },
364
+ // File paths artifact table.
365
+ {
366
+ anchor: "File path row",
367
+ presence: "required",
368
+ valuePattern: "^\\| [^|]+ \\| `[^`]+` \\|$",
369
+ refKind: "none",
370
+ home: "table",
371
+ },
372
+ // Change history — the version-lineage surface.
373
+ {
374
+ anchor: "Change history row",
375
+ presence: "required",
376
+ valuePattern: "^\\|\\s*v\\d+\\.\\d+\\s*\\|",
377
+ refKind: "version-lineage",
378
+ home: "table",
379
+ },
380
+ {
381
+ anchor: "Version token",
382
+ presence: "required",
383
+ valuePattern: "^v\\d+\\.\\d+$",
384
+ refKind: "version-lineage",
385
+ home: "table",
386
+ },
387
+ {
388
+ anchor: "Change history date",
389
+ presence: "required",
390
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
391
+ refKind: "none",
392
+ home: "table",
393
+ },
394
+ {
395
+ anchor: "Backfill clause",
396
+ presence: "conditional",
397
+ valuePattern: "(Pending|\\[Pending\\])\\s*(→|->)\\s*\\S+",
398
+ refKind: "version-lineage",
399
+ home: "table",
400
+ },
401
+ {
402
+ anchor: "Design claim token",
403
+ presence: "conditional",
404
+ valuePattern: "^P\\d+(\\.\\d+)*-design$",
405
+ refKind: "spec-ref",
406
+ home: "table",
407
+ },
408
+ {
409
+ anchor: "Phase range ref",
410
+ presence: "optional",
411
+ valuePattern: "^P\\d+(\\.\\d+)*\\s*[-–—]\\s*P\\d+(\\.\\d+)*$",
412
+ refKind: "phase-id",
413
+ home: "table",
414
+ },
415
+ ];
416
+ // ---------------------------------------------------------------------------
417
+ // plan — the task-block + header-field surface
418
+ // ---------------------------------------------------------------------------
419
+ const PLAN_ELEMENTS = [
420
+ // Header block — YAML front-matter keys (the frontmatter-home anchor IS the
421
+ // front-matter key name). Plan deliberately omits `status` / `author` — no
422
+ // plan head carries either row (the per-type presence contract of §2.3).
423
+ {
424
+ anchor: "title",
425
+ presence: "required",
426
+ valuePattern: "^.+$",
427
+ refKind: "none",
428
+ home: "frontmatter",
429
+ },
430
+ {
431
+ anchor: "doc-type",
432
+ presence: "required",
433
+ valuePattern: `^(${DOC_TYPE_VALUES.join("|")})$`,
434
+ refKind: "none",
435
+ home: "frontmatter",
436
+ },
437
+ {
438
+ anchor: "version",
439
+ presence: "required",
440
+ valuePattern: "^v\\d+\\.\\d+$",
441
+ refKind: "version-lineage",
442
+ home: "frontmatter",
443
+ },
444
+ {
445
+ anchor: "date",
446
+ presence: "required",
447
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
448
+ refKind: "none",
449
+ home: "frontmatter",
450
+ },
451
+ {
452
+ anchor: "spec",
453
+ presence: "required",
454
+ valuePattern: "^.+$",
455
+ refKind: "spec-ref",
456
+ home: "frontmatter",
457
+ },
458
+ {
459
+ anchor: "parent-program",
460
+ presence: "required",
461
+ valuePattern: "^.+$",
462
+ refKind: "parent-program",
463
+ home: "frontmatter",
464
+ },
465
+ {
466
+ anchor: "parent-version",
467
+ presence: "optional",
468
+ valuePattern: "^v\\d+\\.\\d+$",
469
+ refKind: "version-lineage",
470
+ home: "frontmatter",
471
+ },
472
+ {
473
+ anchor: "depends-on",
474
+ presence: "optional",
475
+ valuePattern: "^.+$",
476
+ refKind: "phase-id",
477
+ home: "frontmatter",
478
+ },
479
+ {
480
+ anchor: "base",
481
+ presence: "optional",
482
+ valuePattern: "^.+$",
483
+ refKind: "none",
484
+ home: "frontmatter",
485
+ },
486
+ // Constraint surface (Form A delta-only).
487
+ {
488
+ anchor: "## Constraints",
489
+ presence: "required",
490
+ valuePattern: "^## Constraints$",
491
+ refKind: "none",
492
+ home: "section",
493
+ },
494
+ {
495
+ anchor: "Constraint delta bullet",
496
+ presence: "required",
497
+ valuePattern: "^- ",
498
+ refKind: "none",
499
+ home: "section",
500
+ },
501
+ {
502
+ anchor: "Constraint delta sub-heading",
503
+ presence: "optional",
504
+ valuePattern: "^### ",
505
+ refKind: "none",
506
+ home: "section",
507
+ },
508
+ // Task blocks — the `### Task N:` heading and its number identity. The heading
509
+ // shape accepts the TITLED form (`### Task N: <title>` — the tree-wide canonical
510
+ // form; the parse face anchors on `^### Task (\d+):`); the bare heading is one
511
+ // instance of the same pattern, never a second form.
512
+ {
513
+ anchor: "### Task N:",
514
+ presence: "required",
515
+ valuePattern: "^### Task \\d+:( .*)?$",
516
+ refKind: "none",
517
+ home: "task-block",
518
+ },
519
+ {
520
+ anchor: "Task id token",
521
+ presence: "required",
522
+ valuePattern: "^\\d+$",
523
+ refKind: "task-id",
524
+ home: "task-block",
525
+ },
526
+ // Task block fields.
527
+ {
528
+ anchor: "**Objective**",
529
+ presence: "required",
530
+ valuePattern: "^- \\*\\*Objective\\*\\*:",
531
+ refKind: "none",
532
+ home: "task-field",
533
+ },
534
+ {
535
+ anchor: "**Files**",
536
+ presence: "required",
537
+ valuePattern: "^- \\*\\*Files\\*\\*:",
538
+ refKind: "none",
539
+ home: "task-field",
540
+ },
541
+ {
542
+ anchor: "File path token",
543
+ presence: "required",
544
+ valuePattern: "^[\\w./-]+",
545
+ refKind: "none",
546
+ home: "task-field",
547
+ },
548
+ {
549
+ anchor: "**Consumes**",
550
+ presence: "required",
551
+ valuePattern: "^- \\*\\*Consumes\\*\\*:",
552
+ refKind: "none",
553
+ home: "task-field",
554
+ },
555
+ {
556
+ anchor: "**Produces**",
557
+ presence: "required",
558
+ valuePattern: "^- \\*\\*Produces\\*\\*:",
559
+ refKind: "none",
560
+ home: "task-field",
561
+ },
562
+ {
563
+ anchor: "**Steps**",
564
+ presence: "required",
565
+ valuePattern: "^- \\*\\*Steps\\*\\*:",
566
+ refKind: "none",
567
+ home: "task-field",
568
+ },
569
+ // Step leaves — execution steps and their verifiable outcomes.
570
+ {
571
+ anchor: "Step action",
572
+ presence: "required",
573
+ valuePattern: "^- ",
574
+ refKind: "none",
575
+ home: "task-step",
576
+ },
577
+ {
578
+ anchor: "Step checkable",
579
+ presence: "required",
580
+ valuePattern: "—\\s*checkable:\\s*\\S",
581
+ refKind: "none",
582
+ home: "task-step",
583
+ },
584
+ {
585
+ anchor: "**Acceptance**",
586
+ presence: "required",
587
+ valuePattern: "^- \\*\\*Acceptance\\*\\*:",
588
+ refKind: "none",
589
+ home: "task-field",
590
+ },
591
+ // The single directed edge — declares which other tasks this one depends on
592
+ // (any existing task id; forward references are legal — the anti-dependency gate
593
+ // retired, T24; the value prefix carries the list, §3.8).
594
+ {
595
+ anchor: "**DependsOn**",
596
+ presence: "required",
597
+ valuePattern: "^- \\*\\*DependsOn\\*\\*:",
598
+ refKind: "none",
599
+ home: "task-field",
600
+ },
601
+ {
602
+ anchor: "DependsOn none",
603
+ presence: "optional",
604
+ valuePattern: "^(none|\\s*)$",
605
+ refKind: "none",
606
+ home: "task-field",
607
+ },
608
+ {
609
+ anchor: "DependsOn id",
610
+ presence: "optional",
611
+ valuePattern: "^[1-9]\\d*$",
612
+ refKind: "task-id",
613
+ home: "task-field",
614
+ },
615
+ // Reference-lint token — prose mentions of a task id (a WARN-only observation
616
+ // surface; the crosslink invariant does NOT consume this element — the
617
+ // reference-lint pass is its only consumer).
618
+ {
619
+ anchor: "Task prose reference",
620
+ presence: "optional",
621
+ valuePattern: "\\b(?:Task|T)\\s*([1-9]\\d*)\\b(?!\\.\\d)",
622
+ refKind: "task-id",
623
+ home: "task-field",
624
+ },
625
+ // Change history — the version-lineage surface (P4.1 T2 · overall-isomorphic): the
626
+ // section heading + the row/version/date cells. Presence is required on the
627
+ // heading (since P4.1 every plan carries a Change-history table); the row cells are
628
+ // domain-judged on the table rows.
629
+ {
630
+ anchor: "## Change history",
631
+ presence: "required",
632
+ valuePattern: "^## Change history$",
633
+ refKind: "none",
634
+ home: "section",
635
+ },
636
+ {
637
+ anchor: "Change history row",
638
+ presence: "required",
639
+ valuePattern: "^\\|\\s*v\\d+\\.\\d+\\s*\\|",
640
+ refKind: "version-lineage",
641
+ home: "table",
642
+ },
643
+ {
644
+ anchor: "Version token",
645
+ presence: "required",
646
+ valuePattern: "^v\\d+\\.\\d+$",
647
+ refKind: "version-lineage",
648
+ home: "table",
649
+ },
650
+ {
651
+ anchor: "Change history date",
652
+ presence: "required",
653
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
654
+ refKind: "none",
655
+ home: "table",
656
+ },
657
+ ];
658
+ // ---------------------------------------------------------------------------
659
+ // phase-spec — the skeleton surface
660
+ // ---------------------------------------------------------------------------
661
+ const PHASE_SPEC_ELEMENTS = [
662
+ // Header block — YAML front-matter keys (the frontmatter-home anchor IS the
663
+ // key name). The old line-scan phase-id fallback is retired — its anchor never
664
+ // appeared in any document literal and it had zero consumers; the phase-id
665
+ // reference class rides the plan `depends-on` row.
666
+ {
667
+ anchor: "title",
668
+ presence: "required",
669
+ valuePattern: "^.+$",
670
+ refKind: "none",
671
+ home: "frontmatter",
672
+ },
673
+ {
674
+ anchor: "doc-type",
675
+ presence: "required",
676
+ valuePattern: `^(${DOC_TYPE_VALUES.join("|")})$`,
677
+ refKind: "none",
678
+ home: "frontmatter",
679
+ },
680
+ {
681
+ anchor: "version",
682
+ presence: "required",
683
+ valuePattern: "^v\\d+\\.\\d+$",
684
+ refKind: "version-lineage",
685
+ home: "frontmatter",
686
+ },
687
+ {
688
+ anchor: "date",
689
+ presence: "required",
690
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
691
+ refKind: "none",
692
+ home: "frontmatter",
693
+ },
694
+ {
695
+ anchor: "status",
696
+ presence: "required",
697
+ valuePattern: "^(Draft|Approved|Plan pending|Shipped)$",
698
+ refKind: "none",
699
+ home: "frontmatter",
700
+ },
701
+ {
702
+ anchor: "author",
703
+ presence: "required",
704
+ valuePattern: "^.+$",
705
+ refKind: "none",
706
+ home: "frontmatter",
707
+ },
708
+ {
709
+ anchor: "parent-program",
710
+ presence: "required",
711
+ valuePattern: "^.+$",
712
+ refKind: "parent-program",
713
+ home: "frontmatter",
714
+ },
715
+ {
716
+ anchor: "parent-version",
717
+ presence: "optional",
718
+ valuePattern: "^v\\d+\\.\\d+$",
719
+ refKind: "version-lineage",
720
+ home: "frontmatter",
721
+ },
722
+ {
723
+ anchor: "depends-on",
724
+ presence: "required",
725
+ valuePattern: "^.+$",
726
+ refKind: "none",
727
+ home: "frontmatter",
728
+ },
729
+ // The double-layer design body.
730
+ {
731
+ anchor: "## Design",
732
+ presence: "required",
733
+ valuePattern: "^## Design$",
734
+ refKind: "none",
735
+ home: "design-body",
736
+ },
737
+ {
738
+ anchor: "### N. group heading",
739
+ presence: "required",
740
+ valuePattern: "^### \\d+\\. ",
741
+ refKind: "none",
742
+ home: "design-body",
743
+ },
744
+ {
745
+ anchor: "#### N.M item heading",
746
+ presence: "required",
747
+ valuePattern: "^#### \\d+\\.\\d+ ",
748
+ refKind: "none",
749
+ home: "design-body",
750
+ },
751
+ {
752
+ anchor: "### Acceptance criteria",
753
+ presence: "required",
754
+ valuePattern: "^### Acceptance criteria$",
755
+ refKind: "none",
756
+ home: "design-body",
757
+ },
758
+ {
759
+ anchor: "Acceptance entry",
760
+ presence: "required",
761
+ valuePattern: "^- `",
762
+ refKind: "none",
763
+ home: "design-body",
764
+ },
765
+ // The inheritance-point constraint surface (delta-only).
766
+ {
767
+ anchor: "## Constraints",
768
+ presence: "required",
769
+ valuePattern: "^## Constraints$",
770
+ refKind: "none",
771
+ home: "section",
772
+ },
773
+ {
774
+ anchor: "Constraint delta bullet",
775
+ presence: "required",
776
+ valuePattern: "^- ",
777
+ refKind: "none",
778
+ home: "section",
779
+ },
780
+ // Conditional sections — written only when their condition holds, zero residue otherwise.
781
+ {
782
+ anchor: "## Deviations",
783
+ presence: "conditional",
784
+ valuePattern: "^## Deviations$",
785
+ refKind: "none",
786
+ home: "conditional",
787
+ },
788
+ {
789
+ anchor: "Deviations columns",
790
+ presence: "conditional",
791
+ valuePattern: "^\\| Overall assumption \\| Phase decision \\| Overall updated\\? \\|$",
792
+ refKind: "none",
793
+ home: "conditional",
794
+ },
795
+ {
796
+ anchor: "Deviations row",
797
+ presence: "conditional",
798
+ valuePattern: "^\\|\\s*[^|]+\\s*\\|\\s*[^|]+\\s*\\|\\s*(Yes|No)\\b",
799
+ refKind: "none",
800
+ home: "conditional",
801
+ },
802
+ {
803
+ anchor: "Overall updated answer",
804
+ presence: "conditional",
805
+ valuePattern: "^Yes",
806
+ refKind: "none",
807
+ home: "conditional",
808
+ },
809
+ {
810
+ anchor: "## Incremental warning",
811
+ presence: "conditional",
812
+ valuePattern: "^## Incremental warning$",
813
+ refKind: "none",
814
+ home: "conditional",
815
+ },
816
+ {
817
+ anchor: "## Notes for downstream",
818
+ presence: "conditional",
819
+ valuePattern: "^## Notes for downstream$",
820
+ refKind: "none",
821
+ home: "conditional",
822
+ },
823
+ {
824
+ anchor: "## Review record",
825
+ presence: "conditional",
826
+ valuePattern: "^## Review record$",
827
+ refKind: "none",
828
+ home: "conditional",
829
+ },
830
+ // Change history — the version-lineage surface (P4.1 T2 · overall-isomorphic): the
831
+ // section heading + the row/version/date cells. Presence is required on the
832
+ // heading (since P4.1 every phase-spec carries a Change-history table).
833
+ {
834
+ anchor: "## Change history",
835
+ presence: "required",
836
+ valuePattern: "^## Change history$",
837
+ refKind: "none",
838
+ home: "section",
839
+ },
840
+ {
841
+ anchor: "Change history row",
842
+ presence: "required",
843
+ valuePattern: "^\\|\\s*v\\d+\\.\\d+\\s*\\|",
844
+ refKind: "version-lineage",
845
+ home: "table",
846
+ },
847
+ {
848
+ anchor: "Version token",
849
+ presence: "required",
850
+ valuePattern: "^v\\d+\\.\\d+$",
851
+ refKind: "version-lineage",
852
+ home: "table",
853
+ },
854
+ {
855
+ anchor: "Change history date",
856
+ presence: "required",
857
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
858
+ refKind: "none",
859
+ home: "table",
860
+ },
861
+ ];
862
+ // ---------------------------------------------------------------------------
863
+ // single-spec — the lightweight free-form scaffold (P6 T2 · spec §2.1)
864
+ // ---------------------------------------------------------------------------
865
+ // The fourth doc type — the repair/ruling-oriented free-form document (the
866
+ // 2026-09-28-cdd-review-contract-fix "single-spec" form). Deliberately lighter
867
+ // than phase-spec: a front-matter key set (title / doc-type / version / date /
868
+ // status / author / depends-on / issues), four prose body sections and the
869
+ // change-history lineage. No `### N.` double-layer outline (the free-form has no
870
+ // numbered design groups), no parent-program key (a single-spec has no parent
871
+ // overall — an independent program shape). The fixed section sequence runs in
872
+ // document order.
873
+ const SINGLE_SPEC_ELEMENTS = [
874
+ // Header block — YAML front-matter keys (the frontmatter-home anchor IS the
875
+ // key name). The repaired/ruling carrier keeps the issue pointer as an
876
+ // optional `issues` scalar (single-spec only, §2.3).
877
+ {
878
+ anchor: "title",
879
+ presence: "required",
880
+ valuePattern: "^.+$",
881
+ refKind: "none",
882
+ home: "frontmatter",
883
+ },
884
+ {
885
+ anchor: "doc-type",
886
+ presence: "required",
887
+ valuePattern: `^(${DOC_TYPE_VALUES.join("|")})$`,
888
+ refKind: "none",
889
+ home: "frontmatter",
890
+ },
891
+ {
892
+ anchor: "version",
893
+ presence: "required",
894
+ valuePattern: "^v\\d+\\.\\d+$",
895
+ refKind: "version-lineage",
896
+ home: "frontmatter",
897
+ },
898
+ {
899
+ anchor: "date",
900
+ presence: "required",
901
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
902
+ refKind: "none",
903
+ home: "frontmatter",
904
+ },
905
+ {
906
+ anchor: "status",
907
+ presence: "required",
908
+ valuePattern: "^(Draft|Approved|In progress|Complete)$",
909
+ refKind: "none",
910
+ home: "frontmatter",
911
+ },
912
+ {
913
+ anchor: "author",
914
+ presence: "required",
915
+ valuePattern: "^.+$",
916
+ refKind: "none",
917
+ home: "frontmatter",
918
+ },
919
+ {
920
+ anchor: "depends-on",
921
+ presence: "required",
922
+ valuePattern: "^.+$",
923
+ refKind: "none",
924
+ home: "frontmatter",
925
+ },
926
+ {
927
+ anchor: "issues",
928
+ presence: "optional",
929
+ valuePattern: "^.+$",
930
+ refKind: "none",
931
+ home: "frontmatter",
932
+ },
933
+ // The prose body surface — the free-form's four sections in document order.
934
+ {
935
+ anchor: "## Background & root cause",
936
+ presence: "required",
937
+ valuePattern: "^## Background & root cause$",
938
+ refKind: "none",
939
+ home: "section",
940
+ },
941
+ {
942
+ anchor: "## Design decisions",
943
+ presence: "required",
944
+ valuePattern: "^## Design decisions$",
945
+ refKind: "none",
946
+ home: "section",
947
+ },
948
+ {
949
+ anchor: "## Acceptance",
950
+ presence: "required",
951
+ valuePattern: "^## Acceptance$",
952
+ refKind: "none",
953
+ home: "section",
954
+ },
955
+ {
956
+ anchor: "## Constraints",
957
+ presence: "required",
958
+ valuePattern: "^## Constraints$",
959
+ refKind: "none",
960
+ home: "section",
961
+ },
962
+ // Change history — the version-lineage surface (same shape as the other types).
963
+ {
964
+ anchor: "## Change history",
965
+ presence: "required",
966
+ valuePattern: "^## Change history$",
967
+ refKind: "none",
968
+ home: "section",
969
+ },
970
+ {
971
+ anchor: "Change history row",
972
+ presence: "required",
973
+ valuePattern: "^\\|\\s*v\\d+\\.\\d+\\s*\\|",
974
+ refKind: "version-lineage",
975
+ home: "table",
976
+ },
977
+ {
978
+ anchor: "Version token",
979
+ presence: "required",
980
+ valuePattern: "^v\\d+\\.\\d+$",
981
+ refKind: "version-lineage",
982
+ home: "table",
983
+ },
984
+ {
985
+ anchor: "Change history date",
986
+ presence: "required",
987
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
988
+ refKind: "none",
989
+ home: "table",
990
+ },
991
+ ];
992
+ /** The four declared registries — the judge's judgment data and the projection surfaces' derivation source. */
993
+ export const declaredRegistries = {
994
+ "overall-spec": { docType: "overall-spec", elements: OVERALL_SPEC_ELEMENTS },
995
+ plan: { docType: "plan", elements: PLAN_ELEMENTS },
996
+ "phase-spec": { docType: "phase-spec", elements: PHASE_SPEC_ELEMENTS },
997
+ "single-spec": { docType: "single-spec", elements: SINGLE_SPEC_ELEMENTS },
998
+ };