@oscaner-skills/cdd-engine 3.1.0 → 4.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.
@@ -3,10 +3,10 @@
3
3
  // judgment face. Every structural judgment of the contract plane is one strategy:
4
4
  // base nine — presence / uniqueness / domain / crosslink / order / continuity /
5
5
  // residue / hollow / selfBounded;
6
- // context — file-existence / sibling-scan / cross-doc-chain /
7
- // section-scoped-domain (the four seam strategies that absorb the
8
- // old doctype classes' contextual judgment — fourTableAudit,
9
- // deviations, Class-A/B, effectiveWaves).
6
+ // context — file-existence / sibling-scan / link-shape / slug-ref /
7
+ // cross-doc-chain / section-scoped-domain (the six seam strategies
8
+ // that absorb the old doctype classes' contextual judgment —
9
+ // fourTableAudit, deviations, the identity chain, effectiveWaves).
10
10
  // Each strategy is one subclass of `abstract Invariant { evaluate(ctx) }`; the
11
11
  // judgment data is always the declared registries + the derived parse face (never
12
12
  // a hand-written structure prose). Judgment dispatch is the coordinator's
@@ -16,7 +16,9 @@ var _a;
16
16
  import { existsSync, readdirSync, readFileSync } from "node:fs";
17
17
  import path from "node:path";
18
18
  import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
19
- import { MarkdownPrimitives } from "./doc.js";
19
+ import { SlugIndex } from "../infra/slug-index.js";
20
+ import { docTypeParsers, MarkdownPrimitives } from "./doc.js";
21
+ import { FrontMatterExtractor } from "./frontmatter.js";
20
22
  // ---------------------------------------------------------------------------
21
23
  // judgment records + the context
22
24
  // ---------------------------------------------------------------------------
@@ -47,8 +49,10 @@ export class NodeFs {
47
49
  try {
48
50
  return readdirSync(p);
49
51
  }
50
- catch {
51
- return [];
52
+ catch (err) {
53
+ if (err.code === "ENOENT")
54
+ return [];
55
+ throw err;
52
56
  }
53
57
  }
54
58
  }
@@ -67,6 +71,23 @@ export class Invariant extends MarkdownPrimitives {
67
71
  finding(ctx, field, message, fix) {
68
72
  return { path: ctx.path, field, message, fix, kind: this.name };
69
73
  }
74
+ /** Whether a value's raw form marks it as a holder placeholder (no existence or
75
+ * domain judgment): the empty value, the two pending forms, the `<…>` link
76
+ * placeholder and the skeleton's `:::fill <slot>` content slot. The ONE
77
+ * placeholder contract every strategy shares — the link-resolution faces skip a
78
+ * placeholder target and the front-matter domain arm skips a placeholder scalar
79
+ * on the keys the skeleton fills (its own §4.2 slot classification decides which,
80
+ * so a truth key's placeholder is still judged). */
81
+ isPlaceholder(target) {
82
+ const trimmed = target.trim();
83
+ if (trimmed === "")
84
+ return true;
85
+ if (trimmed === "Pending" || trimmed === "[Pending]")
86
+ return true;
87
+ if (/^<[^>]+>$/.test(trimmed))
88
+ return true;
89
+ return /^:::fill(?:\s|$)/.test(trimmed);
90
+ }
70
91
  /** The judged doc type's declared registry. */
71
92
  registry(ctx) {
72
93
  return ctx.registries[ctx.docKey];
@@ -136,7 +157,7 @@ export class Invariant extends MarkdownPrimitives {
136
157
  }
137
158
  /** The parsed overall record — when the judged doc is an overall. */
138
159
  overall(ctx) {
139
- return ctx.docKey === "overall-spec" ? ctx.parsed : null;
160
+ return ctx.docKey === "overall" ? ctx.parsed : null;
140
161
  }
141
162
  /** The parsed plan record — when the judged doc is a plan. */
142
163
  plan(ctx) {
@@ -146,15 +167,22 @@ export class Invariant extends MarkdownPrimitives {
146
167
  phaseSpec(ctx) {
147
168
  return ctx.docKey === "phase-spec" ? ctx.parsed : null;
148
169
  }
149
- /** The four-table section heading anchors of the overall (registry-declared). */
170
+ /** The identity index every slug-keyed strategy looks up through — the caller's
171
+ * injected index when present, else one scan over the SAME fs seam every other
172
+ * strategy reads (the judgment stays hermetic: no second, real-filesystem scan).
173
+ * The ONE home of that fallback. */
174
+ indexOf(ctx) {
175
+ return ctx.slugIndex ?? SlugIndex.build(ctx.root, ctx.fs);
176
+ }
177
+ /** The three-table section heading anchors of the overall (registry-declared). */
150
178
  overallTableHeadings(ctx) {
151
179
  const headings = this.overall(ctx);
152
180
  if (headings === null)
153
181
  return [];
154
- const declared = ctx.registries["overall-spec"].elements
182
+ const declared = ctx.registries.overall.elements
155
183
  .filter((element) => element.home === "section" && element.anchor.startsWith("## "))
156
184
  .map((element) => element.anchor);
157
- return declared.filter((anchor) => ["File paths", "Issue inventory", "Phase inventory", "Change history"].some((name) => anchor.includes(name)));
185
+ return declared.filter((anchor) => ["Issue inventory", "Phase inventory", "Change history"].some((name) => anchor.includes(name)));
158
186
  }
159
187
  }
160
188
  // ---------------------------------------------------------------------------
@@ -281,7 +309,7 @@ export class UniquenessInvariant extends Invariant {
281
309
  seenIds.add(block.id);
282
310
  }
283
311
  }
284
- if (ctx.docKey === "overall-spec") {
312
+ if (ctx.docKey === "overall") {
285
313
  const data = this.overall(ctx);
286
314
  if (data !== null) {
287
315
  const seenPhases = new Set();
@@ -329,6 +357,13 @@ export class DomainInvariant extends Invariant {
329
357
  const value = ctx.head.value(element.anchor);
330
358
  if (value === null)
331
359
  continue;
360
+ // The skeleton's own placeholders (`:::fill <slot>` / `<…>`) are holder
361
+ // states, not values — the strict scalar shapes judge a CONCRETE value.
362
+ // The exemption is SCOPED to the keys the skeleton actually fills (§4.2:
363
+ // the link slots and the content slots), so a hand-written placeholder on
364
+ // a truth key (a fixed version / date / status literal) stays a finding.
365
+ if (DomainInvariant.#skeletonFills(ctx, element.anchor) && this.isPlaceholder(value))
366
+ continue;
332
367
  const rawPattern = element.valuePattern;
333
368
  if (rawPattern === undefined)
334
369
  continue;
@@ -351,12 +386,23 @@ export class DomainInvariant extends Invariant {
351
386
  }
352
387
  return findings;
353
388
  }
389
+ /** Whether the skeleton fills the front-matter anchor with a placeholder — the
390
+ * projection's own §4.2 slot classification (the link slots' `<…>` scalar and
391
+ * the content slots' `:::fill`), so the exemption covers exactly the keys that
392
+ * can legally carry a holder form. A key absent from the emission list (a
393
+ * shape-typed optional key) fills nothing and is never exempt. */
394
+ static #skeletonFills(ctx, anchor) {
395
+ const slot = ctx.skeleton.frontmatter.find((entry) => entry.anchor === anchor);
396
+ if (slot === undefined)
397
+ return false;
398
+ return slot.slot === "link" || slot.slot === "content";
399
+ }
354
400
  }
355
401
  /** crosslink — in-document reference resolution against the doc's own identity sets. */
356
402
  export class CrosslinkInvariant extends Invariant {
357
403
  name = "crosslink";
358
404
  evaluate(ctx) {
359
- if (ctx.docKey === "overall-spec")
405
+ if (ctx.docKey === "overall")
360
406
  return this.overallCrosslinks(ctx);
361
407
  if (ctx.docKey === "plan")
362
408
  return this.planCrosslinks(ctx);
@@ -482,7 +528,7 @@ export class OrderInvariant extends Invariant {
482
528
  }
483
529
  /** The document's rank-2 section blocks in document order. */
484
530
  #docSections(ctx) {
485
- if (ctx.docKey === "overall-spec")
531
+ if (ctx.docKey === "overall")
486
532
  return ctx.parsed.sections;
487
533
  if (ctx.docKey === "plan")
488
534
  return ctx.parsed.sections;
@@ -586,7 +632,7 @@ export class HollowInvariant extends Invariant {
586
632
  const findings = [...this.tableHollow(ctx), ...this.taskHollow(ctx), ...this.designHollow(ctx)];
587
633
  return findings;
588
634
  }
589
- /** The overall's four tables: a present table section with zero data rows is hollow. */
635
+ /** The overall's three tables: a present table section with zero data rows is hollow. */
590
636
  tableHollow(ctx) {
591
637
  const data = this.overall(ctx);
592
638
  if (data === null)
@@ -663,7 +709,7 @@ export class SelfBoundedInvariant extends Invariant {
663
709
  * row primitive — the P4.1 T2 isomorphic lineage: the same lineage judgment rides
664
710
  * all doc types). */
665
711
  #historyVersions(ctx) {
666
- if (ctx.docKey === "overall-spec") {
712
+ if (ctx.docKey === "overall") {
667
713
  const data = this.overall(ctx);
668
714
  if (data === null)
669
715
  return [];
@@ -702,11 +748,11 @@ export class SelfBoundedInvariant extends Invariant {
702
748
  }
703
749
  }
704
750
  // ---------------------------------------------------------------------------
705
- // the four context-seam strategies
751
+ // the six context-seam strategies
706
752
  // ---------------------------------------------------------------------------
707
753
  /** The chain-link target shape contract (D2, shape judged at the boundary — the #342
708
754
  * fix): a link target must be a BARE relative path (the repo-root form
709
- * `docs/kairos/specs/…-overall.md` or a doc-relative file name) — never a
755
+ * `docs/kairos/overalls/…-overall.md` or a doc-relative file name) — never a
710
756
  * markdown-link shell (`[label](path)`), a URL or a collation token
711
757
  * (whitespace / parens / angle brackets). The ONE expression of the shape rule:
712
758
  * `of()` yields either the accepted (trimmed) target or the reason the shape is
@@ -732,7 +778,7 @@ export class LinkTargetShape {
732
778
  // URL scheme. The path separators `/` and `:` alone stay legal (a bare
733
779
  // relative path carries both) — only the URL-scheme pairing rejects.
734
780
  if (/[\s()[\]<>]|:\/\//.test(trimmed)) {
735
- return new LinkTargetShape(null, "the value must be a bare relative path (e.g. `docs/kairos/specs/…-overall.md` or `xxx-overall.md`), not a markdown link or URL");
781
+ return new LinkTargetShape(null, "the value must be a bare relative path (e.g. `docs/kairos/overalls/…-overall.md` or `xxx-overall.md`), not a markdown link or URL");
736
782
  }
737
783
  return new LinkTargetShape(trimmed, null);
738
784
  }
@@ -756,10 +802,12 @@ export class FileExistenceInvariant extends Invariant {
756
802
  }
757
803
  return findings;
758
804
  }
759
- /** The chain links of the judged doc type (overall design/plan cells; plan/spec lineage links). */
805
+ /** The chain links of the judged doc type — the overall's Phase-inventory cells.
806
+ * The doc-level chain keys (`program:` · the retired path keys) never appear
807
+ * here: a slug reference is not a path. */
760
808
  chainLinks(ctx) {
761
809
  const links = [];
762
- if (ctx.docKey === "overall-spec") {
810
+ if (ctx.docKey === "overall") {
763
811
  const data = this.overall(ctx);
764
812
  if (data !== null) {
765
813
  for (const phase of data.chain.phases) {
@@ -772,47 +820,24 @@ export class FileExistenceInvariant extends Invariant {
772
820
  }
773
821
  }
774
822
  }
775
- if (ctx.docKey === "plan") {
776
- const data = this.plan(ctx);
777
- if (data !== null) {
778
- if (data.chain.specLink !== null)
779
- links.push({ source: "spec", link: data.chain.specLink });
780
- if (data.chain.parentLink !== null)
781
- links.push({ source: "parent-program", link: data.chain.parentLink });
782
- }
783
- }
784
- if (ctx.docKey === "phase-spec") {
785
- const data = this.phaseSpec(ctx);
786
- if (data !== null && data.chain.parentLink !== null) {
787
- links.push({ source: "parent-program", link: data.chain.parentLink });
788
- }
789
- }
823
+ // A plan carries no chain key (its chain is the same-slug identity document) and
824
+ // the phase-spec's `program:` is a SLUG, not a path — neither feeds the
825
+ // file-existence / sibling-scan / link-shape faces. The phase-spec reference is
826
+ // judged by the `slug-ref` strategy.
790
827
  return links;
791
828
  }
792
- /** Whether a target's raw form marks it as a holder placeholder (no existence judgment). */
793
- isPlaceholder(target) {
794
- const trimmed = target.trim();
795
- if (trimmed === "")
796
- return true;
797
- if (trimmed === "Pending" || trimmed === "[Pending]")
798
- return true;
799
- return /^<[^>]+>$/.test(trimmed);
800
- }
801
829
  /** Whether the target exists — absolute targets directly; repo-root form first, the
802
830
  * doc's own dir as the file-relative fallback. The resolution chain is
803
- * single-sourced in `targetPath` (the ONE home the CLI's plan `spec:` rebase
804
- * delegates to as well — P9 branch-review-1 F8: a future contract change
805
- * cannot silently diverge from the CLI's mirror). */
831
+ * single-sourced in `targetPath` (the ONE home of the link-space reading). */
806
832
  #targetExists(ctx, target) {
807
833
  return ctx.fs.exists(_a.targetPath(ctx.root, ctx.path, target, (p) => ctx.fs.exists(p)));
808
834
  }
809
- /** The ONE chain-link target-resolution chain (the doc-contract's own judgment,
810
- * reused by the CLI's plan `spec:` rebase — F8): an absolute target as
811
- * itself; else the repoRoot-relative reading when it exists; else the doc-dir
812
- * (file-relative) reading. `exists` is the caller's filesystem seam (the
813
- * judgment's `ctx.fs`, the CLI's `fs.existsSync`) — the resolution is the shared
814
- * fact, the read is injected. When neither reading exists the doc-dir path is
815
- * returned (the link-space semantic — the caller owns the truly-missing case). */
835
+ /** The ONE chain-link target-resolution chain: an absolute target as itself; else
836
+ * the repoRoot-relative reading when it exists; else the doc-dir (file-relative)
837
+ * reading. `exists` is the caller's filesystem seam (the judgment's `ctx.fs`) —
838
+ * the resolution is the shared fact, the read is injected. When neither reading
839
+ * exists the doc-dir path is returned (the link-space semantic — the caller owns
840
+ * the truly-missing case). */
816
841
  static targetPath(root, docPath, target, exists) {
817
842
  if (path.isAbsolute(target))
818
843
  return target;
@@ -888,11 +913,46 @@ export class SiblingScanInvariant extends FileExistenceInvariant {
888
913
  ];
889
914
  }
890
915
  }
891
- /** cross-doc-chain — the Class-A/B chain resolves and its lineage tokens belong to the parent. */
916
+ /** slug-ref — a `slug-ref` value names an on-disk identity document by `slug:`
917
+ * (the phase-spec's `program:` → an overall). The value is a SLUG, never a path,
918
+ * so this face judges it by identity lookup alone (zero path resolution, zero
919
+ * filename derivation); the skeleton's placeholder forms ride the shared
920
+ * `isPlaceholder` exemption so a freshly rendered document is never blocked by the
921
+ * hard gate its own skeleton emitted. */
922
+ export class SlugRefInvariant extends Invariant {
923
+ name = "slug-ref";
924
+ evaluate(ctx) {
925
+ const findings = [];
926
+ for (const element of this.elementsOf(ctx)) {
927
+ if (element.refKind !== "slug-ref" || element.home !== "frontmatter")
928
+ continue;
929
+ const value = ctx.head.value(element.anchor);
930
+ if (value === null || this.isPlaceholder(value))
931
+ continue;
932
+ if (this.#resolves(ctx, value))
933
+ continue;
934
+ findings.push(this.finding(ctx, element.anchor, `the ${element.anchor} reference names no on-disk overall document: ${value}`, `name the slug: of an existing overall document (${value} resolves to nothing)`));
935
+ }
936
+ return findings;
937
+ }
938
+ /** Whether the reference resolves — a `slug-ref` value names an on-disk document
939
+ * by its `slug:`, never by a path. The registry declares exactly ONE slug-ref
940
+ * key (`program`), whose target class is the overall, so the lookup is the
941
+ * identity index's overall read. A second slug-ref key would have to carry its
942
+ * target class into this resolution. */
943
+ #resolves(ctx, value) {
944
+ return this.indexOf(ctx).overallOf(value) !== null;
945
+ }
946
+ }
947
+ /** cross-doc-chain — the identity chain resolves and its lineage tokens belong to the
948
+ * program the document names. The chain is expressed in identity keys only: a plan
949
+ * is chained to the identity document sharing its `slug:` (Class-A), and a
950
+ * phase-spec is chained to the overall its `program:` names (the `slug-ref`
951
+ * strategy judges that reference resolves; this strategy judges its lineage). */
892
952
  export class CrossDocChainInvariant extends Invariant {
893
953
  name = "cross-doc-chain";
894
954
  evaluate(ctx) {
895
- if (ctx.docKey === "overall-spec")
955
+ if (ctx.docKey === "overall")
896
956
  return this.overallChain(ctx);
897
957
  if (ctx.docKey === "plan")
898
958
  return this.planChain(ctx);
@@ -913,63 +973,79 @@ export class CrossDocChainInvariant extends Invariant {
913
973
  }
914
974
  return [];
915
975
  }
916
- /** The Class-A/Class-B plan chain: the `spec:`/`parent-program:` head targets + the Class-B lineage. */
976
+ /** The plan chain face (Class-A) — the plan's identity chain is the identity
977
+ * document sharing its `slug:`: a plan with no same-slug identity document has
978
+ * no design spec to dispatch against, and the finding names the `slug` key (the
979
+ * identity fact that is missing its pair). The positive half is any identity
980
+ * document (overall / phase-spec / single-spec) carrying the same slug — a
981
+ * single-spec pair carries no program, so the chain simply ends there. */
917
982
  planChain(ctx) {
918
983
  const data = this.plan(ctx);
919
984
  if (data === null)
920
985
  return [];
921
- const findings = [];
922
- const specLink = data.chain.specLink;
923
- if (specLink === null) {
924
- findings.push(this.finding(ctx, "spec", "the plan carries no spec reference", "add a spec value pointing at the phase design spec"));
925
- }
926
- // The link-label drift judgment retired with the ChainLink label face — the
927
- // spec link is a head scalar now (the `spec:` key), the label is not a fact.
928
- if (data.chain.parentLink === null) {
929
- findings.push(this.finding(ctx, "parent-program", "the plan carries no parent-program reference", "add a parent-program value pointing at the parent overall"));
930
- }
931
- findings.push(...this.classB(ctx, data.chain.parentLink, data.chain.parentTokens));
932
- return findings;
986
+ const slug = ctx.head.slug;
987
+ // A placeholder or missing slug is presence's surface, never this arm's.
988
+ if (slug === null || this.isPlaceholder(slug))
989
+ return [];
990
+ if (this.#identityDocOf(ctx, slug) !== null)
991
+ return [];
992
+ return [
993
+ this.finding(ctx, "slug", `the plan carries no identity document with the same slug: ${slug}`, `add a spec document declaring slug: ${slug} (its doc-type is overall / phase-spec / single-spec)`),
994
+ ];
933
995
  }
934
- /** The Class-B phase-spec chain: the parent-link lineage belongs to the parent overall. */
996
+ /** The phase-spec chain face — the `program:` reference's lineage tokens must
997
+ * belong to the overall it names. The reference's own resolution (the slug
998
+ * naming an on-disk overall) is the `slug-ref` strategy's judgment; this arm
999
+ * only judges the version facts once the target is resolved. */
935
1000
  specChain(ctx) {
936
1001
  const data = this.phaseSpec(ctx);
937
1002
  if (data === null)
938
1003
  return [];
939
1004
  const findings = [];
940
- if (data.chain.parentLink === null) {
941
- findings.push(this.finding(ctx, "parent-program", "the phase-spec carries no parent-program reference", "add a parent-program value pointing at the parent overall"));
942
- }
943
- findings.push(...this.classB(ctx, data.chain.parentLink, data.chain.parentTokens));
944
- return findings;
945
- }
946
- /** Class-B: the parent version tokens must belong to the parent overall's lineage. */
947
- classB(ctx, parentLink, parentTokens) {
948
- const findings = [];
949
- if (parentLink === null || parentTokens.length === 0)
1005
+ const programLink = data.chain.programLink;
1006
+ if (programLink === null)
1007
+ return findings;
1008
+ const program = this.#overallOf(ctx, programLink.target);
1009
+ if (program === null)
950
1010
  return findings;
951
- const parentParsed = ctx.chainDocs?.get(parentLink.target);
952
- if (parentParsed === undefined)
1011
+ const lineage = this.#parentLineage(ctx, program);
1012
+ if (lineage === null)
953
1013
  return findings;
954
- const lineage = this.#parentLineage(parentParsed);
955
- for (const token of parentTokens) {
1014
+ for (const token of data.chain.parentTokens) {
956
1015
  if (!lineage.has(token)) {
957
- findings.push(this.finding(ctx, "parent-program", `the parent-program version token ${token} does not belong to the parent overall's lineage`, `use a version the parent overall declares (its version front-matter or a Change-history row): ${[...lineage].join(", ")}`));
1016
+ findings.push(this.finding(ctx, "program", `the parent-version token ${token} does not belong to the program's lineage: ${programLink.target}`, `use a version the program overall declares (its version front-matter or a Change-history row): ${[...lineage].join(", ")}`));
958
1017
  }
959
1018
  }
960
1019
  return findings;
961
1020
  }
962
- /** The parent overall's lineage: its head `version:` scalar + every
1021
+ /** The identity document carrying the slug, or null — resolved through the one
1022
+ * identity index the board and the pre-flight read (zero second scan). */
1023
+ #identityDocOf(ctx, slug) {
1024
+ return this.indexOf(ctx).identityDoc(slug);
1025
+ }
1026
+ /** The overall document carrying the program slug, or null. */
1027
+ #overallOf(ctx, slug) {
1028
+ return this.indexOf(ctx).overallOf(slug);
1029
+ }
1030
+ /** The program overall's lineage: its head `version:` scalar + every
963
1031
  * Change-history row version (the T6 read point — the header fact rides the
964
- * typed head record, never a body line scan). */
965
- #parentLineage(parent) {
1032
+ * typed head record, never a body line scan). The overall parses through the
1033
+ * SAME row source the judged document went through (split → canonicalize →
1034
+ * parse), so an alias-registered table heading reads identically in both faces.
1035
+ * null when the parent is unreadable: a parent the seam cannot read is never
1036
+ * evidence that a version token is foreign (that absence belongs to the
1037
+ * slug-ref face's resolution). */
1038
+ #parentLineage(ctx, entry) {
1039
+ const content = ctx.fs.read(entry.path);
1040
+ if (content === null)
1041
+ return null;
1042
+ const { head, body } = FrontMatterExtractor.split(content);
1043
+ const lines = body.split("\n").map((line) => ctx.translator.canonicalize(line));
1044
+ const parsed = docTypeParsers.overall.parse(lines, head);
966
1045
  const lineage = new Set();
967
- if (parent.docType !== "overall-spec")
968
- return lineage;
969
- const version = parent.head?.version;
970
- if (version !== null && version !== undefined)
971
- lineage.add(version);
972
- for (const row of parent.tables["Change history"].rows) {
1046
+ if (head.version !== null)
1047
+ lineage.add(head.version);
1048
+ for (const row of parsed.tables["Change history"].rows) {
973
1049
  const match = row[0]?.match(/v\d+\.\d+/);
974
1050
  if (match !== null)
975
1051
  lineage.add(match[0]);
@@ -981,7 +1057,7 @@ export class CrossDocChainInvariant extends Invariant {
981
1057
  export class SectionScopedDomainInvariant extends Invariant {
982
1058
  name = "section-scoped-domain";
983
1059
  evaluate(ctx) {
984
- if (ctx.docKey === "overall-spec")
1060
+ if (ctx.docKey === "overall")
985
1061
  return this.issueScopedRefs(ctx);
986
1062
  if (ctx.docKey === "phase-spec")
987
1063
  return this.designScoping(ctx);
@@ -11,7 +11,7 @@ import { Words } from "../face/words.js";
11
11
  import { declaredRegistries } from "./declare.js";
12
12
  import { docTypeParsers } from "./doc.js";
13
13
  import { FrontMatterExtractor } from "./frontmatter.js";
14
- import { ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, HollowInvariant, LinkShapeInvariant, NodeFs, OrderInvariant, PresenceInvariant, ResidueInvariant, SectionScopedDomainInvariant, SelfBoundedInvariant, SiblingScanInvariant, UniquenessInvariant, } from "./invariants.js";
14
+ import { ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, HollowInvariant, LinkShapeInvariant, NodeFs, OrderInvariant, PresenceInvariant, ResidueInvariant, SectionScopedDomainInvariant, SelfBoundedInvariant, SiblingScanInvariant, SlugRefInvariant, UniquenessInvariant, } from "./invariants.js";
15
15
  import { DOC_KEYS, Projector } from "./project.js";
16
16
  import { Translator } from "./translate.js";
17
17
  /**
@@ -36,7 +36,7 @@ import { Translator } from "./translate.js";
36
36
  */
37
37
  export class Contract {
38
38
  /** The per-doc-key policy sets — the declared composition of the strategy family.
39
- * All thirteen strategies are registry-driven and judge every doc type, so the
39
+ * All fifteen strategies are registry-driven and judge every doc type, so the
40
40
  * per-key sets are the same ordered family; the record keying is what a future
41
41
  * per-type ordering/selection change would carry. */
42
42
  #strategies;
@@ -71,9 +71,11 @@ export class Contract {
71
71
  root: input.root,
72
72
  slices: this.#projector.slices()[input.docKey],
73
73
  shape: this.#projector.shape()[input.docKey],
74
+ skeleton: this.#projector.skeleton()[input.docKey],
74
75
  registries: declaredRegistries,
75
76
  phaseId: input.phaseId,
76
- chainDocs: input.chainDocs,
77
+ translator: this.#translator,
78
+ slugIndex: input.slugIndex,
77
79
  fs: input.fs ?? new NodeFs(),
78
80
  };
79
81
  const findings = [];
@@ -97,6 +99,7 @@ export class Contract {
97
99
  new LinkShapeInvariant(),
98
100
  new FileExistenceInvariant(),
99
101
  new SiblingScanInvariant(),
102
+ new SlugRefInvariant(),
100
103
  new CrossDocChainInvariant(),
101
104
  new SectionScopedDomainInvariant(),
102
105
  ];
@@ -16,9 +16,10 @@
16
16
  // a suspect is always an existing task with a lower id whose edge was simply
17
17
  // not declared (forward references are legal — no contradiction class).
18
18
  //
19
- // The cross-doc label-drift observation (Class-B `parent-program:` label vs
20
- // target basename) retired with the ChainLink label face at the front-matter flip
21
- // (T6) — the chain facts ride the typed head scalars, a link label is not a fact.
19
+ // The cross-doc label-drift observation retired with the ChainLink label face at
20
+ // the front-matter flip (T6) — the chain facts ride the typed head scalars, a link
21
+ // label is not a fact. A plan declares no chain key at all now (its chain is the
22
+ // same-slug identity document), so no plan-side drift observation can exist.
22
23
  //
23
24
  // Every warning is a Warn — a WARN-only observation, never a Finding, never a
24
25
  // BLOCK. Module-level exports are types / the class — zero behavior-carrying
@@ -123,7 +123,7 @@ export class Projector {
123
123
  /** Map a per-registry projector across the four injected registries, keyed by their record identity. */
124
124
  #projectAll(project) {
125
125
  return {
126
- "overall-spec": project(this.#registries["overall-spec"]),
126
+ overall: project(this.#registries.overall),
127
127
  plan: project(this.#registries.plan),
128
128
  "phase-spec": project(this.#registries["phase-spec"]),
129
129
  "single-spec": project(this.#registries["single-spec"]),
@@ -247,7 +247,7 @@ export class Projector {
247
247
  }
248
248
  /** The front-matter emission list — the independent line set §4.2 prescribes:
249
249
  * every frontmatter-home required key plus the type's optional head keys
250
- * (`base` / `depends-on`), in registry order. `parent-version` is the single
250
+ * (`base` / `issues`), in registry order. `parent-version` is the single
251
251
  * explicit exclusion: an optional shape-typed key whose domain admits neither
252
252
  * placeholder form, so absence is the only legal skeleton state (the consumer
253
253
  * fills it when the parent version is known). */
@@ -275,9 +275,10 @@ export class Projector {
275
275
  }
276
276
  /** Classify one required element's slot kind — the placeholder-anchoring
277
277
  * semantics of the element's value (spec §4.1):
278
- * · link — the parent-program / spec-ref link-shaped anchors render
279
- * as placeholder links (`:::fill` never lands on them — a
280
- * fill in a link slot is a guaranteed finding);
278
+ * · link — the front-matter slug-reference anchors (the phase-spec
279
+ * `program:` key) render as placeholder links (`:::fill`
280
+ * never lands on them — a fill in a link slot is a
281
+ * guaranteed finding);
281
282
  * · numeric-heading — the digit-family headings (`N.` / `N.M` / `Task N:`)
282
283
  * whose numbers are true values in the skeleton, never a
283
284
  * literal `N` (a literal `N` punctures the declared
@@ -293,15 +294,14 @@ export class Projector {
293
294
  * fully-anchored enum / graph elements).
294
295
  */
295
296
  #skeletonSlotOf(element) {
296
- // The link-typed anchor slots are the front-matter link keys (`spec` · the
297
- // `parent-program` of plan / phase-spec) — their values render as placeholder
298
- // links (`<…>` targets on the exemption chain), never `:::fill`. The
299
- // enum-typed table cells (a Design-spec cell, a markdown-link
300
- // implementation-plan cell) ride the generator-truth class, never a link
301
- // slot — the home + ref-kind pair keys the class (the frontmatter-home
302
- // anchors are now YAML keys, so the old `\[`-shape probe no longer applies).
303
- if (element.home === "frontmatter" &&
304
- (element.refKind === "parent-program" || element.refKind === "spec-ref"))
297
+ // The link-typed anchor slots are the front-matter slug references (the
298
+ // phase-spec `program:` key) — their values render as placeholder links
299
+ // (`<…>` targets on the exemption chain), never `:::fill`. The enum-typed
300
+ // table cells (a Design-spec cell, a markdown-link implementation-plan cell)
301
+ // ride the generator-truth class, never a link slot — the home + ref-kind pair
302
+ // keys the class (the frontmatter-home anchors are now YAML keys, so the old
303
+ // `\[`-shape probe no longer applies).
304
+ if (element.home === "frontmatter" && element.refKind === "slug-ref")
305
305
  return "link";
306
306
  if ((element.anchor.startsWith("#") || element.anchor === "Task id token") &&
307
307
  element.valuePattern !== undefined &&
@@ -326,7 +326,7 @@ export class Projector {
326
326
  return "scaffold";
327
327
  }
328
328
  // The front-matter content keys (the title plus the other free-text head
329
- // scalars — author · depends-on · base) are the head's fill positions (`:::fill
329
+ // scalars — author · slug · base) are the head's fill positions (`:::fill
330
330
  // <key>` in the emitted front matter); the remaining heading anchors are fixed
331
331
  // structure.
332
332
  if (element.anchor === "title")