@oscaner-skills/cdd-engine 2.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -13,10 +13,9 @@
13
13
  // The element lines are enumerated from the methodology skeleton semantics (the
14
14
  // machine skeleton of each doc type as pinned by the four repo schema JSONs,
15
15
  // read as steady contract data) — freshly declared anchors, never cut from the
16
- // old tree's sources. Counts stand at overall-spec 39 / plan 28 / phase-spec 25 /
17
- // single-spec 13,
18
- // each within the planned 20–40 band (single-spec deliberately below it — the
19
- // lightweight-scaffold charter) and each element carrying all five fields
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
20
19
  // (a completeness contract enforced by the array shape below and by the test
21
20
  // suite, which pins presence/ref-kind domains and per-registry anchor
22
21
  // uniqueness).
@@ -40,7 +39,7 @@ export type RefKind =
40
39
 
41
40
  /** The document surface an element belongs to — where the anchor lives in a conforming document. */
42
41
  export type Home =
43
- | "header"
42
+ | "frontmatter"
44
43
  | "section"
45
44
  | "facet"
46
45
  | "table"
@@ -53,7 +52,7 @@ export type Home =
53
52
 
54
53
  /** One declared element: a structural fact of a doc type's skeleton. */
55
54
  export interface RegistryElement {
56
- /** The machine anchor token the engine keys on — a heading literal, a header marker, or a row/field key. */
55
+ /** The machine anchor token the engine keys on — a heading literal, a YAML front-matter key, or a row/field key. */
57
56
  anchor: string;
58
57
  /** Whether a conforming document must carry the element, may carry it, or carries it only when its condition holds. */
59
58
  presence: Presence;
@@ -98,7 +97,7 @@ const REF_KIND_VALUES = [
98
97
  "task-id",
99
98
  ] as const satisfies readonly RefKind[];
100
99
  const HOME_VALUES = [
101
- "header",
100
+ "frontmatter",
102
101
  "section",
103
102
  "facet",
104
103
  "table",
@@ -109,7 +108,7 @@ const HOME_VALUES = [
109
108
  "design-body",
110
109
  "conditional",
111
110
  ] as const satisfies readonly Home[];
112
- const DOC_TYPE_VALUES = [
111
+ export const DOC_TYPE_VALUES = [
113
112
  "overall-spec",
114
113
  "plan",
115
114
  "phase-spec",
@@ -169,41 +168,49 @@ export class RegistryGuard {
169
168
  // overall-spec — the charter section surface
170
169
  // ---------------------------------------------------------------------------
171
170
  const OVERALL_SPEC_ELEMENTS = [
172
- // Header block (H1 + bullet metadata).
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
173
  {
174
- anchor: "# Title",
174
+ anchor: "title",
175
175
  presence: "required",
176
- valuePattern: "^# \\S.*$",
176
+ valuePattern: "^.+$",
177
177
  refKind: "none",
178
- home: "header",
178
+ home: "frontmatter",
179
179
  },
180
180
  {
181
- anchor: "**Version**",
181
+ anchor: "doc-type",
182
182
  presence: "required",
183
- valuePattern: "^- \\*\\*Version\\*\\*: v\\d+\\.\\d+ · \\d{4}-\\d{2}-\\d{2}$",
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+$",
184
191
  refKind: "version-lineage",
185
- home: "header",
192
+ home: "frontmatter",
186
193
  },
187
194
  {
188
- anchor: "**Status**",
195
+ anchor: "date",
189
196
  presence: "required",
190
- valuePattern: "^- \\*\\*Status\\*\\*: (Draft|Approved|In progress|Complete)$",
197
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
191
198
  refKind: "none",
192
- home: "header",
199
+ home: "frontmatter",
193
200
  },
194
201
  {
195
- anchor: "**Author**",
202
+ anchor: "status",
196
203
  presence: "required",
197
- valuePattern: "^- \\*\\*Author\\*\\*:",
204
+ valuePattern: "^(Draft|Approved|In progress|Complete)$",
198
205
  refKind: "none",
199
- home: "header",
206
+ home: "frontmatter",
200
207
  },
201
208
  {
202
- anchor: "**Constraints**",
209
+ anchor: "author",
203
210
  presence: "required",
204
- valuePattern: "^- \\*\\*Constraints\\*\\*:",
211
+ valuePattern: "^.+$",
205
212
  refKind: "none",
206
- home: "header",
213
+ home: "frontmatter",
207
214
  },
208
215
  // `##`-ranked sections.
209
216
  {
@@ -255,6 +262,23 @@ const OVERALL_SPEC_ELEMENTS = [
255
262
  refKind: "none",
256
263
  home: "section",
257
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
+ },
258
282
  {
259
283
  anchor: "## Maintenance",
260
284
  presence: "required",
@@ -463,48 +487,71 @@ const OVERALL_SPEC_ELEMENTS = [
463
487
  // plan — the task-block + header-field surface
464
488
  // ---------------------------------------------------------------------------
465
489
  const PLAN_ELEMENTS = [
466
- // Header block (H1 + header fields).
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).
467
493
  {
468
- anchor: "# Title",
494
+ anchor: "title",
469
495
  presence: "required",
470
- valuePattern: "^# \\S.*$",
496
+ valuePattern: "^.+$",
471
497
  refKind: "none",
472
- home: "header",
498
+ home: "frontmatter",
473
499
  },
474
500
  {
475
- anchor: "**Spec:**",
501
+ anchor: "doc-type",
476
502
  presence: "required",
477
- valuePattern: "^\\*\\*Spec:\\*\\*\\s+\\[[^\\]]+\\]\\([^)]+\\)$",
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: "^.+$",
478
525
  refKind: "spec-ref",
479
- home: "header",
526
+ home: "frontmatter",
480
527
  },
481
528
  {
482
- anchor: "**Parent program**",
529
+ anchor: "parent-program",
483
530
  presence: "required",
484
- valuePattern: "^- \\*\\*Parent program\\*\\*:? \\[[^\\]]+\\]\\([^)]+\\)",
531
+ valuePattern: "^.+$",
485
532
  refKind: "parent-program",
486
- home: "header",
533
+ home: "frontmatter",
487
534
  },
488
535
  {
489
- anchor: "**Version**",
490
- presence: "required",
491
- valuePattern: "^- \\*\\*Version\\*\\*: v\\d+\\.\\d+ · \\d{4}-\\d{2}-\\d{2}$",
536
+ anchor: "parent-version",
537
+ presence: "optional",
538
+ valuePattern: "^v\\d+\\.\\d+$",
492
539
  refKind: "version-lineage",
493
- home: "header",
540
+ home: "frontmatter",
494
541
  },
495
542
  {
496
- anchor: "**Depends on**",
543
+ anchor: "depends-on",
497
544
  presence: "optional",
498
- valuePattern: "^- \\*\\*Depends on\\*\\*:",
545
+ valuePattern: "^.+$",
499
546
  refKind: "phase-id",
500
- home: "header",
547
+ home: "frontmatter",
501
548
  },
502
549
  {
503
- anchor: "**Base**",
550
+ anchor: "base",
504
551
  presence: "optional",
505
- valuePattern: "^- \\*\\*Base\\*\\*:",
552
+ valuePattern: "^.+$",
506
553
  refKind: "none",
507
- home: "header",
554
+ home: "frontmatter",
508
555
  },
509
556
  // Constraint surface (Form A delta-only).
510
557
  {
@@ -683,55 +730,72 @@ const PLAN_ELEMENTS = [
683
730
  // phase-spec — the skeleton surface
684
731
  // ---------------------------------------------------------------------------
685
732
  const PHASE_SPEC_ELEMENTS = [
686
- // Header five-tuple — `**Version**` strictly required.
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.
687
737
  {
688
- anchor: "# Title",
738
+ anchor: "title",
689
739
  presence: "required",
690
- valuePattern: "^# \\S.*$",
740
+ valuePattern: "^.+$",
691
741
  refKind: "none",
692
- home: "header",
742
+ home: "frontmatter",
693
743
  },
694
744
  {
695
- anchor: "**Version**",
745
+ anchor: "doc-type",
696
746
  presence: "required",
697
- valuePattern: "^- \\*\\*Version\\*\\*: v\\d+\\.\\d+ · \\d{4}-\\d{2}-\\d{2}$",
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+$",
698
755
  refKind: "version-lineage",
699
- home: "header",
756
+ home: "frontmatter",
700
757
  },
701
758
  {
702
- anchor: "**Status**",
759
+ anchor: "date",
703
760
  presence: "required",
704
- valuePattern: "^- \\*\\*Status\\*\\*: (Draft|Approved|Plan pending|Shipped)$",
761
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
705
762
  refKind: "none",
706
- home: "header",
763
+ home: "frontmatter",
707
764
  },
708
765
  {
709
- anchor: "**Author**",
766
+ anchor: "status",
710
767
  presence: "required",
711
- valuePattern: "^- \\*\\*Author\\*\\*:",
768
+ valuePattern: "^(Draft|Approved|Plan pending|Shipped)$",
712
769
  refKind: "none",
713
- home: "header",
770
+ home: "frontmatter",
714
771
  },
715
772
  {
716
- anchor: "**Parent program**",
773
+ anchor: "author",
717
774
  presence: "required",
718
- valuePattern: "^- \\*\\*Parent program\\*\\*:? \\[[^\\]]+\\]\\([^)]+\\)",
719
- refKind: "parent-program",
720
- home: "header",
775
+ valuePattern: "^.+$",
776
+ refKind: "none",
777
+ home: "frontmatter",
721
778
  },
722
779
  {
723
- anchor: "**Depends on**",
780
+ anchor: "parent-program",
724
781
  presence: "required",
725
- valuePattern: "^- \\*\\*Depends on\\*\\*:",
726
- refKind: "none",
727
- home: "header",
782
+ valuePattern: "^.+$",
783
+ refKind: "parent-program",
784
+ home: "frontmatter",
728
785
  },
729
786
  {
730
- anchor: "Depends on ref",
731
- presence: "conditional",
732
- valuePattern: "^P\\d+(\\.\\d+)*",
733
- refKind: "phase-id",
734
- home: "header",
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",
735
799
  },
736
800
  // The double-layer design body.
737
801
  {
@@ -872,47 +936,71 @@ const PHASE_SPEC_ELEMENTS = [
872
936
  // ---------------------------------------------------------------------------
873
937
  // The fourth doc type — the repair/ruling-oriented free-form document (the
874
938
  // 2026-09-28-cdd-review-contract-fix "single-spec" form). Deliberately lighter
875
- // than phase-spec: a header five-tuple (title / version / status / author /
876
- // `- **Depends on**`), four prose body sections and the change-history lineage.
877
- // No `### N.` double-layer outline (the free-form has no numbered design groups),
878
- // no `**Parent program**` requirement (a single-spec has no parent overall — an
879
- // independent program shape). The fixed section sequence runs in document order.
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.
880
945
  const SINGLE_SPEC_ELEMENTS = [
881
- // Header five-tuple — title + the four bullet metadata rows.
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).
882
949
  {
883
- anchor: "# Title",
950
+ anchor: "title",
884
951
  presence: "required",
885
- valuePattern: "^# \\S.*$",
952
+ valuePattern: "^.+$",
886
953
  refKind: "none",
887
- home: "header",
954
+ home: "frontmatter",
888
955
  },
889
956
  {
890
- anchor: "**Version**",
957
+ anchor: "doc-type",
891
958
  presence: "required",
892
- valuePattern: "^- \\*\\*Version\\*\\*: v\\d+\\.\\d+ · \\d{4}-\\d{2}-\\d{2}$",
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+$",
893
967
  refKind: "version-lineage",
894
- home: "header",
968
+ home: "frontmatter",
895
969
  },
896
970
  {
897
- anchor: "**Status**",
971
+ anchor: "date",
898
972
  presence: "required",
899
- valuePattern: "^- \\*\\*Status\\*\\*: (Draft|Approved|In progress|Complete)$",
973
+ valuePattern: "^\\d{4}-\\d{2}-\\d{2}$",
900
974
  refKind: "none",
901
- home: "header",
975
+ home: "frontmatter",
902
976
  },
903
977
  {
904
- anchor: "**Author**",
978
+ anchor: "status",
905
979
  presence: "required",
906
- valuePattern: "^- \\*\\*Author\\*\\*:",
980
+ valuePattern: "^(Draft|Approved|In progress|Complete)$",
907
981
  refKind: "none",
908
- home: "header",
982
+ home: "frontmatter",
909
983
  },
910
984
  {
911
- anchor: "**Depends on**",
985
+ anchor: "author",
912
986
  presence: "required",
913
- valuePattern: "^- \\*\\*Depends on\\*\\*:",
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: "^.+$",
914
1002
  refKind: "none",
915
- home: "header",
1003
+ home: "frontmatter",
916
1004
  },
917
1005
  // The prose body surface — the free-form's four sections in document order.
918
1006
  {