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