@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
@@ -11,7 +11,7 @@
11
11
  // · process — the subprocess seam (fail-open results);
12
12
  // · workspace — the root/workspace pair + the slug rule + the JSON read/write.
13
13
 
14
- import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
14
+ import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
15
15
  import { tmpdir } from "node:os";
16
16
  import path from "node:path";
17
17
  import { describe, expect, it } from "vitest";
@@ -52,7 +52,7 @@ describe("runtime — the typed engine-config surface (the typed data plane)", (
52
52
  expect(HANDOFF_FAMILIES["review.wave"].name).toBe("tasks-{tasks}-review-{round}.json");
53
53
  // v1.9 — the family `schema` faces select the handoff-schema subset (§3.6: the
54
54
  // field resurrected from the dead task/docs discrimination), and the return-format
55
- // field is gone (RETURN_STDOUT_BLOCK is the ONE return contract). The docs-fix
55
+ // field is gone (RETURN_PROSE is the ONE return contract). The docs-fix
56
56
  // families (fix.spec/fix.plan) ride the findings face — §3.6's per-mode split.
57
57
  expect(HANDOFF_FAMILIES["review.branch"].schema).toBe("findings");
58
58
  expect(HANDOFF_FAMILIES["fix.plan"].schema).toBe("findings");
@@ -108,7 +108,9 @@ describe("config — the typed accessor facade (one no-I/O route per face)", ()
108
108
  // (the review mode's ROLE resolves by REVIEW_TYPE)
109
109
  expect(Object.keys(template.modes)).toEqual(["implement", "fix", "docs-fix"]);
110
110
  expect(Object.keys(template.reviews)).toEqual(["wave", "branch", "spec", "plan"]);
111
- expect(Object.keys(template.return)).toEqual(["RETURN_STDOUT_BLOCK"]);
111
+ // P11 — the return zone is ONE plain-prose block (the two-line stdout contract
112
+ // retired with the introspection that enumerated its formats)
113
+ expect(Object.keys(template.return)).toEqual(["RETURN_PROSE"]);
112
114
  });
113
115
 
114
116
  it("carries the P5 review criteria — the typed dispatch rows + axes guides with zero forbidden prose", () => {
@@ -284,4 +286,48 @@ describe("workspace — the root/workspace pair + the slug rule + JSON roundtrip
284
286
  rmSync(base, { recursive: true, force: true });
285
287
  }
286
288
  });
289
+
290
+ it("writeJson relativizes the declared path fields (doc/plan) to the repoRoot-relative shape (P9 T4 §2.7)", () => {
291
+ const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
292
+ try {
293
+ const workspace = new Workspace(new WorkspaceRoot(base, ".kairos/cdd"), "test-slug");
294
+ const abs = path.join(base, "docs", "kairos", "plans", "p3.md");
295
+ // The persisted shape is repoRoot-relative for the two DECLARED path keys; a
296
+ // prose string that merely looks like a path (the `notes` array) is untouched.
297
+ workspace.writeJson("progress.json", {
298
+ waves: [{ wave: "1", reviewedRevision: { kind: "brief-revision", plan: abs } }],
299
+ notes: [abs],
300
+ });
301
+ const onDisk = JSON.parse(
302
+ readFileSync(path.join(workspace.path, "progress.json"), "utf8"),
303
+ ) as { waves: { reviewedRevision: { plan: string } }[]; notes: string[] };
304
+ expect(onDisk.waves[0]!.reviewedRevision.plan).toBe("docs/kairos/plans/p3.md");
305
+ expect(onDisk.notes).toEqual([abs]);
306
+ } finally {
307
+ rmSync(base, { recursive: true, force: true });
308
+ }
309
+ });
310
+
311
+ it("readJson normalizes a legacy absolute path field on read — the backstop covers un-migrated bytes (P9 T4 §2.11)", () => {
312
+ const base = mkdtempSync(path.join(tmpdir(), "infra-ws-"));
313
+ try {
314
+ const workspace = new Workspace(new WorkspaceRoot(base, ".kairos/cdd"), "test-slug");
315
+ workspace.ensure();
316
+ // A legacy write (absolute plan field) sits on disk; the read normalizes it —
317
+ // the internal value is the canonical relative shape even without migration.
318
+ const abs = path.join(base, "docs", "kairos", "plans", "legacy.md");
319
+ writeFileSync(
320
+ path.join(workspace.path, "progress.json"),
321
+ JSON.stringify({ reviewedRevision: { plan: abs } }),
322
+ "utf8",
323
+ );
324
+ const read = workspace.readJson<{ reviewedRevision: { plan: string } }>("progress.json");
325
+ expect(read.kind).toBe("ok");
326
+ expect(read.kind === "ok" && read.value.reviewedRevision.plan).toBe(
327
+ "docs/kairos/plans/legacy.md",
328
+ );
329
+ } finally {
330
+ rmSync(base, { recursive: true, force: true });
331
+ }
332
+ });
287
333
  });
@@ -0,0 +1,56 @@
1
+ // packages/cdd-engine/src-next/infra/__tests__/root.test.ts
2
+ // T1 — the path value-object pair (design spec §2.2): the ONE basis authority
3
+ // (RepoRoot) + the ONE canonical shape type (RepoPath). The pins judge the pure
4
+ // relativize/resolve pair — zero syscall, zero `process.cwd()` read (the plane
5
+ // is pure string arithmetic over node:path).
6
+
7
+ import path from "node:path";
8
+ import { describe, expect, it } from "vitest";
9
+ import { type RepoPath, RepoRoot } from "../root.ts";
10
+
11
+ /** A fixed absolute root — the value object's injected basis (never a live cwd). */
12
+ const ROOT = path.resolve("/abs/r");
13
+ const root = new RepoRoot(ROOT);
14
+
15
+ describe("RepoRoot — the path-basis value object (the relativize/resolve pair)", () => {
16
+ it("relativizes an in-repo absolute input to the branded repoRoot-relative shape", () => {
17
+ const rel: RepoPath = root.relativize(path.join(ROOT, "docs/kairos/plans/p.md"));
18
+ expect(rel).toBe("docs/kairos/plans/p.md");
19
+ });
20
+
21
+ it("relativizes a caller-relative input against the ROOT (never process.cwd())", () => {
22
+ // A bare relative string resolves against the injected root, not the process
23
+ // cwd — the whole point of the value object holding the basis.
24
+ expect(root.relativize("docs/kairos/plans/p.md")).toBe("docs/kairos/plans/p.md");
25
+ });
26
+
27
+ it("keeps an out-of-repo input in the single relative FORM — `..` segments, never rejected", () => {
28
+ // spec §2.10: the shape is judged, not the location. A repo-external path
29
+ // relativizes to a relative string carrying `..` and does NOT throw.
30
+ const rel = root.relativize(path.resolve(ROOT, "../outside/x.md"));
31
+ expect(rel).toBe("../outside/x.md");
32
+ expect(() => root.relativize("../outside/x.md")).not.toThrow();
33
+ });
34
+
35
+ it("resolve erases a RepoPath back to the absolute syscall string — the round trip is exact", () => {
36
+ const abs = path.join(ROOT, "docs/kairos/plans/p.md");
37
+ expect(root.resolve(root.relativize(abs))).toBe(abs);
38
+ // resolve agrees with path.resolve(root, input) for both input forms.
39
+ expect(root.resolve(root.relativize("docs/x.md"))).toBe(path.resolve(ROOT, "docs/x.md"));
40
+ });
41
+
42
+ it("normalizes the same document's absolute and relative forms to string-equal RepoPaths", () => {
43
+ // The false-drift semantic: one document, two argv spellings → one canonical
44
+ // shape (the same absolute/relative pair relativizes to string-equal
45
+ // `RepoPath`s — an absolute argv and a relative argv for one file must not
46
+ // read as two documents).
47
+ expect(root.relativize(path.join(ROOT, "docs/kairos/plans/p.md"))).toBe(
48
+ root.relativize("docs/kairos/plans/p.md"),
49
+ );
50
+ expect(root.relativize("docs/a.md")).not.toBe(root.relativize("docs/b.md"));
51
+ });
52
+
53
+ it("relativizes the empty input to the empty string (the root against itself)", () => {
54
+ expect(root.relativize("")).toBe("");
55
+ });
56
+ });
@@ -0,0 +1,29 @@
1
+ // packages/cdd-engine/src-next/infra/doc-roots.ts
2
+ // The doc-root leaf (P9 T5 §2.8) — the doc-tree root segments as their OWN
3
+ // dependency-free constant so the CLI declaration surface (face/declare.ts — the
4
+ // help `example` rows) can derive its doc-root literals from the SAME single
5
+ // source the runtime exposes as `ENGINE_RUNTIME.docRoots`, without the module
6
+ // cycle the direct `declare.ts → runtime.ts` import would form (runtime.ts reads
7
+ // ARGV_CHANNEL from declare.ts, so declare.ts must stay import-clean toward it).
8
+ //
9
+ // `ENGINE_RUNTIME.docRoots` IS this object (runtime.ts references it, never
10
+ // re-declares a copy) — the doc-root segments live here once, and every reader
11
+ // (the runtime, the CLI examples, the invariant messages, the board scan) derives
12
+ // from this one value. Module-level export is the declared constant + its type —
13
+ // zero behavior-carrying bare functions.
14
+
15
+ /** The doc-root segments — the slug → doc-tree reverse derivation's root paths
16
+ * (relative to the repo root; the board's scan reads them, never re-declares). */
17
+ export interface DocRoots {
18
+ /** The design-spec directory segment. */
19
+ specs: string;
20
+ /** The plan directory segment. */
21
+ plans: string;
22
+ }
23
+
24
+ /** The doc-tree root segments — the ONE value of the doc-root fact (the runtime's
25
+ * `docRoots` and every derived literal read THIS constant). */
26
+ export const ENGINE_DOC_ROOTS = {
27
+ specs: "docs/kairos/specs",
28
+ plans: "docs/kairos/plans",
29
+ } as const satisfies DocRoots;
@@ -0,0 +1,73 @@
1
+ // packages/cdd-engine/src-next/infra/root.ts
2
+ // T1 — the path value-object pair (design spec §2.2): the ONE authority for the
3
+ // path BASIS (repoRoot) and the ONE type for the canonical path SHAPE
4
+ // (repoRoot-relative).
5
+ //
6
+ // RepoRoot — the value object holding the already-resolved absolute root
7
+ // string (the resolution — `git.topLevel(process.cwd())` — is T2;
8
+ // this plane stays resolution-free so no import cycle forms). Its
9
+ // two methods are the ONLY conversion pair over the path basis:
10
+ // · relativize(input) — the ONE construction entry: any absolute
11
+ // or caller-relative input → the branded, repoRoot-relative
12
+ // `RepoPath` (the user-input read-in point).
13
+ // · resolve(rel) — the ONE erasure point: a `RepoPath` →
14
+ // the absolute `string` fed to `fs` / `git` / `execa` at the
15
+ // syscall boundary.
16
+ //
17
+ // RepoPath — a branded string. The brand lifts the canonical shape to the type
18
+ // level: the absolute state is UNREPRESENTABLE as a `RepoPath`, so a
19
+ // bare `string` can never reach a read/write face (compile-time
20
+ // guard — §2.2's read/write contract). The absolute form is
21
+ // transient at the syscall boundary only: it is produced by
22
+ // `resolve`, never persisted, never compared, never passed across a
23
+ // layer (spec §2.1).
24
+ //
25
+ // The whole plane is pure string arithmetic over `node:path` (zero syscall, zero
26
+ // `process.cwd()` read) — the value object never touches the filesystem.
27
+ //
28
+ // Module-level exports are types / the class — zero behavior-carrying bare
29
+ // functions (the plan's zero-bare-function discipline).
30
+
31
+ import path from "node:path";
32
+
33
+ /** The branded repoRoot-relative path — the canonical shape lifted to the type
34
+ * level. The brand makes the absolute state unrepresentable: only `RepoRoot
35
+ * .relativize` constructs one, and only `RepoRoot.resolve` erases it to the
36
+ * absolute syscall string. */
37
+ export type RepoPath = string & { readonly __repoPath: unique symbol };
38
+
39
+ /** The path-basis value object — the root-basis single source plus the ONE
40
+ * relativize/resolve conversion pair (spec §2.2). Constructed with the
41
+ * ALREADY-resolved absolute root string (resolution is T2 — this plane never
42
+ * reads `process.cwd()`); stateless after construction, so one instance is
43
+ * shared safely. */
44
+ export class RepoRoot {
45
+ /** The absolute root string — the basis every relativize/resolve is taken
46
+ * against. Stored verbatim (never re-resolved: resolution is the caller's —
47
+ * T2 — and a re-resolution here would smuggle a `process.cwd()` read into the
48
+ * pure plane). */
49
+ readonly absolute: string;
50
+
51
+ constructor(absolute: string) {
52
+ this.absolute = absolute;
53
+ }
54
+
55
+ /** The ONE construction entry — normalize any absolute-or-relative input to the
56
+ * branded repoRoot-relative `RepoPath`. An absolute input is taken relative to
57
+ * the root; a caller-relative input is resolved against the root first (so a
58
+ * bare `docs/x.md` is read relative to repoRoot, NEVER to `process.cwd()`).
59
+ * An out-of-repo input (`../outside/x.md`) keeps the single relative FORM — the
60
+ * result carries `..` segments, is NOT rejected and never throws (spec §2.10:
61
+ * the shape is what is judged, not the location). An empty input relativizes to
62
+ * the empty string (root against itself). */
63
+ relativize(input: string): RepoPath {
64
+ return path.relative(this.absolute, path.resolve(this.absolute, input)) as RepoPath;
65
+ }
66
+
67
+ /** The ONE erasure point — a `RepoPath` back to the absolute `string` fed to
68
+ * `fs` / `git` / `execa`. The absolute form exists only here, transient at the
69
+ * syscall boundary. */
70
+ resolve(rel: RepoPath): string {
71
+ return path.resolve(this.absolute, rel);
72
+ }
73
+ }
@@ -24,6 +24,9 @@
24
24
  // carrying bare functions (the plan's zero-bare-function discipline).
25
25
 
26
26
  import { ARGV_CHANNEL, type ChannelArgRow } from "../face/declare.ts";
27
+ import { type DocRoots, ENGINE_DOC_ROOTS } from "./doc-roots.ts";
28
+
29
+ export type { DocRoots } from "./doc-roots.ts";
27
30
 
28
31
  /** The context contract — the live argv channel table (the single channel the new
29
32
  * tree's command face consumes; the host-marker env closure lives in the harness
@@ -32,32 +35,18 @@ export interface ContextContract {
32
35
  readonly channels: Readonly<{ argv: Readonly<Record<string, ChannelArgRow>> }>;
33
36
  }
34
37
 
35
- /** One handoff-family record — the canonical file-name pattern + round policy + the
36
- * carrier's schema face (the full family row the JSON plane carried — schema /
37
- * fixFamily / prev are data the typed plane preserves). The v1.9 contract
38
- * reparametrization: `returnFormat` is deleted (RETURN_STDOUT_BLOCK is the ONE
39
- * return contract — the per-family field was the JSON/block selector, retired with
40
- * the divided return faces) and the dead `schema` field is resurrected as the
41
- * handoff-schema face selector (`work` — implement/fix carrier — vs `findings` —
42
- * the review carrier, session/handoff-schema.ts). */
38
+ /** One handoff-family record — the canonical file-name pattern + the carrier's
39
+ * schema face. Only `name`/`schema` are read (ledger/lifecycle resolve the file
40
+ * name and pick the writable-subset face); the retired round-policy / phase /
41
+ * fix-family / fix-template / prev-derivation fields (zero readers — spec §3.4 ⑯)
42
+ * are deleted, never left as dead declarations. */
43
43
  export interface HandoffFamily {
44
44
  /** The canonical file name — the `{placeholder}` pattern the ledger fills. */
45
45
  name: string;
46
- /** The family's round policy (fixed / increment / source). */
47
- round?: "fixed" | "increment" | "source";
48
- /** The dispatch phase the family carries (implement/review/fix/branch-review). */
49
- phase?: string;
50
46
  /** The carrier schema face (work / findings) — the handoff-schema selector (§3.6:
51
- * the field resurrected from the dead task/docs discrimination; the docs-fix
52
- * families (fix.spec / fix.plan) ride the findings face — §3.6's per-mode split:
53
- * implement/fix → work + evidence · review/docs-fix → findings). */
47
+ * the docs-fix families (fix.spec / fix.plan) ride the findings face — the
48
+ * per-mode split: implement/fix → work + evidence · review/docs-fix → findings). */
54
49
  schema?: "work" | "findings";
55
- /** The fix-round family of a review family. */
56
- fixFamily?: string;
57
- /** The fix-template face of a fix family. */
58
- fixTemplate?: string;
59
- /** The previous-round family derivation of increment/source families. */
60
- prev?: Readonly<Record<string, string>>;
61
50
  }
62
51
 
63
52
  /** The handoff-name space — the workspace segment + the family naming table. */
@@ -68,15 +57,6 @@ export interface HandoffNamespace {
68
57
  families: Readonly<Record<string, HandoffFamily>>;
69
58
  }
70
59
 
71
- /** The doc-root segments — the slug → doc-tree reverse derivation's root paths
72
- * (relative to the repo root; the board's scan reads them, never re-declares). */
73
- export interface DocRoots {
74
- /** The design-spec directory segment. */
75
- specs: string;
76
- /** The plan directory segment. */
77
- plans: string;
78
- }
79
-
80
60
  /** The engine runtime — the typed engine-config surface (version + channels + names
81
61
  * + doc roots). */
82
62
  export interface EngineRuntime {
@@ -93,78 +73,48 @@ export interface EngineRuntime {
93
73
  /** The handoff family naming table — the canonical per-family file-name patterns
94
74
  * keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
95
75
  * naming truth, verbatim from the engine-config handoff namespace). The v1.9
96
- * reparametrization: `returnFormat` is gone (RETURN_STDOUT_BLOCK is the one return
76
+ * reparametrization: `returnFormat` is gone (RETURN_PROSE is the one return
97
77
  * contract) and the `schema` faces are the handoff-schema selector (work / findings —
98
78
  * §3.6, session/handoff-schema.ts). */
99
79
  export const HANDOFF_FAMILIES = {
100
80
  "implement.wave": {
101
81
  name: "tasks-{tasks}-implement.json",
102
- round: "fixed",
103
82
  schema: "work",
104
- phase: "implement",
105
83
  },
106
84
  "review.wave": {
107
85
  name: "tasks-{tasks}-review-{round}.json",
108
- round: "increment",
109
86
  schema: "findings",
110
- phase: "review",
111
- fixFamily: "fix.wave",
112
- prev: { round1: "implement.wave", roundR: "fix.wave:R-1" },
113
87
  },
114
88
  "fix.wave": {
115
89
  name: "tasks-{tasks}-fix-{round}.json",
116
- round: "source",
117
90
  schema: "work",
118
- fixTemplate: "fix",
119
- phase: "fix",
120
- prev: { roundR: "review.wave:R" },
121
91
  },
122
92
  "review.spec": {
123
93
  name: "spec-review-{round}.json",
124
- round: "increment",
125
94
  schema: "findings",
126
- phase: "review",
127
- fixFamily: "fix.spec",
128
95
  },
129
96
  "fix.spec": {
130
97
  name: "spec-fix-{round}.json",
131
- round: "source",
132
98
  schema: "findings",
133
- fixTemplate: "docs",
134
- phase: "fix",
135
- prev: { roundR: "review.spec:R" },
136
99
  },
137
100
  "review.plan": {
138
101
  name: "plan-review-{round}.json",
139
- round: "increment",
140
102
  schema: "findings",
141
- phase: "review",
142
- fixFamily: "fix.plan",
143
103
  },
144
104
  "fix.plan": {
145
105
  name: "plan-fix-{round}.json",
146
- round: "source",
147
106
  schema: "findings",
148
- fixTemplate: "docs",
149
- phase: "fix",
150
- prev: { roundR: "review.plan:R" },
151
107
  },
152
108
  "review.branch": {
153
109
  // find #9 (spec §6.5): the range token leaves the file name — the workspace
154
110
  // slug is the plan-slug (the fix face carries --plan) · round accumulates
155
111
  // across re-reviews (lineKey pins "branch").
156
112
  name: "branch-review-{round}.json",
157
- round: "increment",
158
113
  schema: "findings",
159
- phase: "branch-review",
160
114
  },
161
115
  "fix.branch": {
162
116
  name: "branch-fix-{round}.json",
163
- round: "source",
164
117
  schema: "work",
165
- fixTemplate: "fix",
166
- phase: "fix",
167
- prev: { roundR: "review.branch:R" },
168
118
  },
169
119
  } as const satisfies Readonly<Record<string, HandoffFamily>>;
170
120
 
@@ -178,8 +128,5 @@ export const ENGINE_RUNTIME = {
178
128
  workspaceRoot: ".kairos/cdd",
179
129
  families: HANDOFF_FAMILIES,
180
130
  },
181
- docRoots: {
182
- specs: "docs/kairos/specs",
183
- plans: "docs/kairos/plans",
184
- },
131
+ docRoots: ENGINE_DOC_ROOTS,
185
132
  } as const satisfies EngineRuntime;
@@ -17,6 +17,7 @@
17
17
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
18
18
  import path from "node:path";
19
19
  import { type ParseError, parse } from "jsonc-parser";
20
+ import { RepoRoot } from "./root.ts";
20
21
  import { ENGINE_RUNTIME } from "./runtime.ts";
21
22
 
22
23
  /** The tri-state JSON read — the read's three DISTINCT outcomes, discriminated: a
@@ -32,13 +33,45 @@ export type JsonRead<T> =
32
33
  | { kind: "missing" }
33
34
  | { kind: "malformed"; errors?: readonly ParseError[] };
34
35
 
36
+ /** The slug phase-suffix syntax — the trailing `-p<major>(.<minor>)*` segment
37
+ * (spec §3.2 ⑬). This is the ONE source of the phase-suffix grammar: both the
38
+ * suffix parse (`Workspace.phaseSuffixOf`, the `-p…$` form) and the board's
39
+ * suffix-only match (`BoardView.scanPhases`, the `^p…$` form) compose their
40
+ * patterns from this fragment. (Distinct from the doc-contract design-unit value
41
+ * syntax `P\d+(\.\d+)*-design` — uppercase + `-design` tail — which is another
42
+ * fact, never merged here.) */
43
+ export const PHASE_SUFFIX_CORE = "p\\d+(?:\\.\\d+)*";
44
+
45
+ /** The phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment captured
46
+ * as the named `suffix` group (composed from PHASE_SUFFIX_CORE: the ONE grammar). */
47
+ const PHASE_SUFFIX_TAIL = new RegExp(`(?<program>.+?)(?<suffix>-${PHASE_SUFFIX_CORE})$`);
48
+
49
+ /** The suffix-only match — a bare `<major>(.<minor>)*` phase path (composed from
50
+ * the SAME PHASE_SUFFIX_CORE; the board's scan uses this form). */
51
+ export const PHASE_SUFFIX_BARE = new RegExp(`^${PHASE_SUFFIX_CORE}$`);
52
+
53
+ /** The persisted path-field keys — the JSON fields whose value is a PATH (the
54
+ * progress.json `reviewedRevision.doc` / `.plan` layers · the base.json `plan`
55
+ * field). The read-time normalization (P9 T4 §2.11) relativizes exactly these
56
+ * values, never an arbitrary string (a carrier's `notes` prose is never treated as
57
+ * a path). */
58
+ const PERSISTED_PATH_KEYS: ReadonlySet<string> = new Set(["doc", "plan"]);
59
+
35
60
  /** The repo-scoped workspace base — `<repoRoot>/<workspaceRoot>`. */
36
61
  export class WorkspaceRoot {
37
62
  readonly repoRoot: string;
63
+ /** The repo-basis value object (T1 `RepoRoot`) — constructed ONCE here, at the
64
+ * workspace's own boundary, and shared by every reader that needs the basis
65
+ * (the ledger's write/read normalization, the CLI's capsule/graph render, the
66
+ * board's doc cells): the single repo-basis fact is threaded as the value object,
67
+ * never re-wrapped per call (branch-review-1 F2 — Data Clumps / Primitive
68
+ * Obsession: one basis, one form). */
69
+ readonly basis: RepoRoot;
38
70
  readonly path: string;
39
71
 
40
72
  constructor(repoRoot: string, workspaceRoot: string) {
41
73
  this.repoRoot = repoRoot;
74
+ this.basis = new RepoRoot(repoRoot);
42
75
  this.path = path.join(repoRoot, workspaceRoot);
43
76
  }
44
77
 
@@ -101,9 +134,10 @@ export class Workspace {
101
134
  }
102
135
 
103
136
  /** The slug's phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment
104
- * (null when the slug is a program slug, i.e. carries no phase suffix). */
137
+ * (null when the slug is a program slug, i.e. carries no phase suffix). The
138
+ * grammar is PHASE_SUFFIX_TAIL, composed from the shared PHASE_SUFFIX_CORE. */
105
139
  static phaseSuffixOf(slug: string): string | null {
106
- const match = /(?<program>.+?)(?<suffix>-p\d+(?:\.\d+)*)$/.exec(slug);
140
+ const match = PHASE_SUFFIX_TAIL.exec(slug);
107
141
  return match?.groups?.suffix ?? null;
108
142
  }
109
143
 
@@ -179,7 +213,11 @@ export class Workspace {
179
213
  const text = this.#readText(target);
180
214
  if (text.kind !== "ok") return text;
181
215
  try {
182
- return { kind: "ok", value: JSON.parse(text.value) as T };
216
+ // The read-time path backstop (P9 T4 §2.11): a path field persisted by an
217
+ // older build (an absolute form) is relativized on read, so an un-migrated
218
+ // file still yields the ONE canonical shape downstream. A no-op on
219
+ // already-relative values (relativize is idempotent).
220
+ return { kind: "ok", value: this.#normalizePaths(JSON.parse(text.value)) as T };
183
221
  } catch {
184
222
  return { kind: "malformed" };
185
223
  }
@@ -224,9 +262,61 @@ export class Workspace {
224
262
  return { kind: "ok", value: text };
225
263
  }
226
264
 
227
- /** Write a JSON child — mkdir before write. */
265
+ /** Write a JSON child — mkdir before write. The declared path fields (`doc` /
266
+ * `plan`) are normalized to the canonical repoRoot-relative shape on write (P9
267
+ * T4 §2.7), so every engine-persisted path field lands relative — the read-time
268
+ * backstop then only covers legacy bytes (migration handles history, the read
269
+ * normalizes any straggler). The written bytes carry exactly one trailing `\n`
270
+ * (the repo's EOF rule), so an engine-written file is byte-canonical and the
271
+ * one-time migration leaves it byte-identical (zero churn). */
228
272
  writeJson(name: string, value: unknown): void {
229
273
  this.ensure();
230
- writeFileSync(this.resolve(name), JSON.stringify(value, null, 2), "utf8");
274
+ const normalized = this.#normalizePaths(value);
275
+ writeFileSync(this.resolve(name), `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
276
+ }
277
+
278
+ /** Write a text child — mkdir before write (the text twin of `writeJson`; the
279
+ * engine-rendered brief is the one text artifact the engine authors itself).
280
+ * Returns the resolved path. */
281
+ writeText(name: string, text: string): string {
282
+ this.ensure();
283
+ const target = this.resolve(name);
284
+ writeFileSync(target, text, "utf8");
285
+ return target;
286
+ }
287
+
288
+ /** The workspace's repo-basis value object — the ONE conversion exit the
289
+ * read-time path backstop normalizes through. The basis is the root's OWN
290
+ * value object (`WorkspaceRoot.basis`, built once at the root's boundary) —
291
+ * never re-wrapped here (branch-review-1 F2: one basis, one form). */
292
+ #repoBasis(): RepoRoot {
293
+ return this.root.basis;
294
+ }
295
+
296
+ /** The read-time path backstop (P9 T4 §2.11) — deep-normalize every DECLARED
297
+ * path field (`doc` / `plan` — the `reviewedRevision` two-layer layers + the
298
+ * base artifact's `plan`) to the canonical repoRoot-relative shape, so an
299
+ * un-migrated file (a legacy absolute value) still reads as the ONE shape.
300
+ * Only the declared path keys are touched (never arbitrary prose); the walk is
301
+ * a pure clone (arrays + plain objects), recursing into `waves[]` rows and the
302
+ * reviewed-revision records alike. Relativizing an already-relative value is a
303
+ * no-op (idempotent). */
304
+ #normalizePaths(value: unknown): unknown {
305
+ const root = this.#repoBasis();
306
+ const walk = (node: unknown): unknown => {
307
+ if (Array.isArray(node)) return node.map(walk);
308
+ if (node !== null && typeof node === "object") {
309
+ const out: Record<string, unknown> = {};
310
+ for (const [key, child] of Object.entries(node as Record<string, unknown>)) {
311
+ out[key] =
312
+ PERSISTED_PATH_KEYS.has(key) && typeof child === "string"
313
+ ? root.relativize(child)
314
+ : walk(child);
315
+ }
316
+ return out;
317
+ }
318
+ return node;
319
+ };
320
+ return walk(value);
231
321
  }
232
322
  }