@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,56 +0,0 @@
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
- });
@@ -1,39 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/git.ts
2
- // T12 — GitClient: the new tree's single git seam. It holds exactly the two
3
- // judgments the engine's git face needs — where the repo root is (topLevel) and
4
- // whether the working tree is clean (isClean). Operations are fail-open — a
5
- // non-repo or git error yields null (topLevel) / false (isClean), never a thrown
6
- // exception across the seam.
7
-
8
- import { simpleGit } from "simple-git";
9
-
10
- /** GitClient — the engine's git judgment adapter. Stateless: construction is cheap,
11
- * collaborators that need git are constructor-injected. */
12
- export class GitClient {
13
- #git(cwd: string) {
14
- return simpleGit({ baseDir: cwd });
15
- }
16
-
17
- /** The repo root, mirroring `git rev-parse --show-toplevel`; null outside a repo. */
18
- async topLevel(cwd: string): Promise<string | null> {
19
- try {
20
- return (await this.#git(cwd).revparse(["--show-toplevel"])).trim() || null;
21
- } catch {
22
- return null;
23
- }
24
- }
25
-
26
- /** Whether the working tree is clean — `git status --porcelain` = "" (the
27
- * clean-tree gate reads git's own judgment, zero engine-side exclusion: the
28
- * engine's workspace self-publishes its `.gitignore` (content `*`) at ensure
29
- * time, so its run artifacts never read as uncommitted user work — the gate
30
- * refuses only genuinely dirty USER changes). Fail-open-false (a non-repo
31
- * counts dirty — the CDD flow needs git). */
32
- async isClean(cwd: string): Promise<boolean> {
33
- try {
34
- return (await this.#git(cwd).status()).isClean();
35
- } catch {
36
- return false;
37
- }
38
- }
39
- }
@@ -1,34 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/process.ts
2
- // T12 — ProcessRunner: the new tree's process seam. Subprocess invocations are
3
- // async instance methods over the node:child_process execFile — a fail-open run
4
- // returns a { code, stdout, stderr } result (a missing binary or a non-zero exit
5
- // rides the code, never a thrown exception across the seam).
6
-
7
- import { execFile } from "node:child_process";
8
-
9
- /** The outcome of one process run — fail-open (code signals the failure). */
10
- export interface ProcessResult {
11
- /** The exit code (0 = success; a spawn failure yields a non-zero synthetic code). */
12
- code: number;
13
- /** The process's stdout, verbatim. */
14
- stdout: string;
15
- /** The process's stderr, verbatim. */
16
- stderr: string;
17
- }
18
-
19
- /** ProcessRunner — the subprocess adapter. Stateless and fail-open. */
20
- export class ProcessRunner {
21
- /** Run a command with args in an optional working directory. */
22
- run(command: string, args: readonly string[], cwd?: string): Promise<ProcessResult> {
23
- return new Promise((resolve) => {
24
- execFile(command, [...args], { cwd }, (error, stdout, stderr) => {
25
- if (error === null) {
26
- resolve({ code: 0, stdout, stderr });
27
- return;
28
- }
29
- const code = typeof error.code === "number" ? error.code : 1;
30
- resolve({ code, stdout, stderr });
31
- });
32
- });
33
- }
34
- }
@@ -1,132 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/runtime.ts
2
- // T21 — the engine-config typed surface: the engine-config JSON's data-plane home
3
- // as one typed constant module. The new tree reads zero config files — every
4
- // stable runtime fact lives here (or in its single typed home elsewhere in the
5
- // plane) and is imported, never parsed:
6
- //
7
- // · $version — the runtime contract version (the face's version pin).
8
- // · contextContract — the environment contract's view of the argv channel
9
- // table (the CLI declaration single surface — face/declare.ts §2.4 — is the
10
- // channel's home; the runtime references the same table, never a second list).
11
- // · handoffNamespace — the workspace-root segment + the handoff family naming
12
- // table (the ledger's family resolution reads it).
13
- //
14
- // The JSON plane's dead fields are not carried (the delete-dead-empties iron rule):
15
- // · failureCategories — the new tree keeps no failure-category counter data; the
16
- // ledger's progress key set is the declared code constant (PROGRESS_COUNTER_ZERO).
17
- // · handoffNamespace.slugRule — the slug derivation is code (Workspace.slugFromDoc),
18
- // never a prose data field.
19
- // · contextContract channels.git / derived / transport / timeouts and the env-host
20
- // channel — no live consumer; the host-marker closure is single-sourced by the
21
- // harness detect rows (face/host.ts), never re-declared here.
22
- //
23
- // Module-level exports are types / the declared constant data — zero behavior-
24
- // carrying bare functions (the plan's zero-bare-function discipline).
25
-
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";
30
-
31
- /** The context contract — the live argv channel table (the single channel the new
32
- * tree's command face consumes; the host-marker env closure lives in the harness
33
- * detect rows, face/host.ts — never duplicated here). */
34
- export interface ContextContract {
35
- readonly channels: Readonly<{ argv: Readonly<Record<string, ChannelArgRow>> }>;
36
- }
37
-
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
- export interface HandoffFamily {
44
- /** The canonical file name — the `{placeholder}` pattern the ledger fills. */
45
- name: string;
46
- /** The carrier schema face (work / findings) — the handoff-schema selector (§3.6:
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). */
49
- schema?: "work" | "findings";
50
- }
51
-
52
- /** The handoff-name space — the workspace segment + the family naming table. */
53
- export interface HandoffNamespace {
54
- /** The repo-scoped workspace segment (`.kairos/cdd` — WorkspaceRoot joins it). */
55
- workspaceRoot: string;
56
- /** The handoff families keyed by `op.type` — the ledger's naming truth. */
57
- families: Readonly<Record<string, HandoffFamily>>;
58
- }
59
-
60
- /** The engine runtime — the typed engine-config surface (version + channels + names
61
- * + doc roots). */
62
- export interface EngineRuntime {
63
- /** The runtime contract version. */
64
- $version: number;
65
- /** The context contract — the live argv channel table. */
66
- contextContract: ContextContract;
67
- /** The handoff-name space — workspace + family naming. */
68
- handoffNamespace: HandoffNamespace;
69
- /** The doc-tree root segments (the slug → node-tree face's file-system truth). */
70
- docRoots: DocRoots;
71
- }
72
-
73
- /** The handoff family naming table — the canonical per-family file-name patterns
74
- * keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
75
- * naming truth, verbatim from the engine-config handoff namespace). The v1.9
76
- * reparametrization: `returnFormat` is gone (RETURN_PROSE is the one return
77
- * contract) and the `schema` faces are the handoff-schema selector (work / findings —
78
- * §3.6, session/handoff-schema.ts). */
79
- export const HANDOFF_FAMILIES = {
80
- "implement.wave": {
81
- name: "tasks-{tasks}-implement.json",
82
- schema: "work",
83
- },
84
- "review.wave": {
85
- name: "tasks-{tasks}-review-{round}.json",
86
- schema: "findings",
87
- },
88
- "fix.wave": {
89
- name: "tasks-{tasks}-fix-{round}.json",
90
- schema: "work",
91
- },
92
- "review.spec": {
93
- name: "spec-review-{round}.json",
94
- schema: "findings",
95
- },
96
- "fix.spec": {
97
- name: "spec-fix-{round}.json",
98
- schema: "findings",
99
- },
100
- "review.plan": {
101
- name: "plan-review-{round}.json",
102
- schema: "findings",
103
- },
104
- "fix.plan": {
105
- name: "plan-fix-{round}.json",
106
- schema: "findings",
107
- },
108
- "review.branch": {
109
- // find #9 (spec §6.5): the range token leaves the file name — the workspace
110
- // slug is the plan-slug (the fix face carries --plan) · round accumulates
111
- // across re-reviews (lineKey pins "branch").
112
- name: "branch-review-{round}.json",
113
- schema: "findings",
114
- },
115
- "fix.branch": {
116
- name: "branch-fix-{round}.json",
117
- schema: "work",
118
- },
119
- } as const satisfies Readonly<Record<string, HandoffFamily>>;
120
-
121
- /** The engine runtime — the typed engine-config surface, one constant (the argv
122
- * channel table is the CLI declaration single surface, face/declare.ts §2.4 —
123
- * referenced here, never re-declared). */
124
- export const ENGINE_RUNTIME = {
125
- $version: 1,
126
- contextContract: { channels: { argv: ARGV_CHANNEL } },
127
- handoffNamespace: {
128
- workspaceRoot: ".kairos/cdd",
129
- families: HANDOFF_FAMILIES,
130
- },
131
- docRoots: ENGINE_DOC_ROOTS,
132
- } as const satisfies EngineRuntime;
@@ -1,322 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/workspace.ts
2
- // T12 — the workspace data plane: the WorkspaceRoot + Workspace pair owns every
3
- // on-disk workspace concern of the new tree.
4
- // WorkspaceRoot — the repo-scoped workspace base (`<repoRoot>/<workspaceRoot>`,
5
- // one dispatch family's home; the segment single-sources the engine config's
6
- // handoffNamespace.workspaceRoot and is never a hard-coded literal).
7
- // Workspace — one dispatch workspace (`<base>/<slug>/`): ensure() mkdirs the
8
- // slug dir, readJson/writeJson are the JSON read/write pair (mkdir before
9
- // write; readJson is tri-state — ok / missing / malformed), readJsonLenient is
10
- // the sub-agent-authored draft face (jsonc-parser + trailing-comma/comment
11
- // tolerance — a child-LLM slip never voids a round, a real break still reports
12
- // malformed; D39), resolve() is the
13
- // child-path single fact, slugFromDoc is the doc-file → slug derivation
14
- // (`-design`/`-plan` suffix strip), docsOfSlug is the slug → doc-tree reverse
15
- // derivation (the board's file-system-only truth, phase-suffix parse included).
16
-
17
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
18
- import path from "node:path";
19
- import { type ParseError, parse } from "jsonc-parser";
20
- import { RepoRoot } from "./root.ts";
21
- import { ENGINE_RUNTIME } from "./runtime.ts";
22
-
23
- /** The tri-state JSON read — the read's three DISTINCT outcomes, discriminated: a
24
- * `missing` file (never written) and a `malformed` file (present but unparseable)
25
- * are different facts, so a read-back reconstruct reports each truly — a corrupt
26
- * draft is never misreported as "not written" (D27 · single-fact honesty). The
27
- * other-IO-error case (EACCES, EISDIR …) is a present-but-unreadable file and rides
28
- * the `malformed` side: it is never silently "missing". The lenient face (D39)
29
- * carries the parser's PRECISE error codes on the `malformed` side for diagnosis
30
- * (the strict face and the IO-error case leave `errors` absent). */
31
- export type JsonRead<T> =
32
- | { kind: "ok"; value: T }
33
- | { kind: "missing" }
34
- | { kind: "malformed"; errors?: readonly ParseError[] };
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
-
60
- /** The repo-scoped workspace base — `<repoRoot>/<workspaceRoot>`. */
61
- export class WorkspaceRoot {
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;
70
- readonly path: string;
71
-
72
- constructor(repoRoot: string, workspaceRoot: string) {
73
- this.repoRoot = repoRoot;
74
- this.basis = new RepoRoot(repoRoot);
75
- this.path = path.join(repoRoot, workspaceRoot);
76
- }
77
-
78
- /** Idempotently create the workspace root + self-publish the namespace root's
79
- * `.gitignore` (a single `*` — everything under `.kairos/` is engine-owned, so
80
- * the git face ignores the whole namespace wholesale, the `cdd/` workspace and
81
- * any future sibling alike). The tree-clean gate then reads git's own judgment
82
- * — `isClean` with zero engine-side exclusion — a consumer repo with no `.kairos`
83
- * entry in its own `.gitignore` still stays clean across dispatches, because
84
- * the workspace publishes its keep-out marker at ensure time, before the gate
85
- * ever reads the tree (the F1 fix: the engine's run artifacts are engine-owned,
86
- * never "uncommitted user work"). The ignore affects only untracked files — a
87
- * user who git-tracks the workspace keeps seeing its changes on the gate. */
88
- ensure(): WorkspaceRoot {
89
- mkdirSync(this.path, { recursive: true });
90
- // The namespace root — the workspace root's parent (`.kairos/cdd` → `.kairos`):
91
- // the keep-out marker sits at the namespace's top, never per-workspace (the
92
- // consumer-facing convention: ignore the whole `.kairos` namespace at once).
93
- const namespaceRoot = path.dirname(this.path);
94
- mkdirSync(namespaceRoot, { recursive: true });
95
- const ignore = path.join(namespaceRoot, ".gitignore");
96
- if (!existsSync(ignore)) writeFileSync(ignore, "*\n", "utf8");
97
- return this;
98
- }
99
- }
100
-
101
- /** One slug's doc-tree paths — the reverse-derived artifact paths of a program or
102
- * phase slug (each member null when the file does not exist on disk; the file
103
- * system is the only truth, nothing is synthesized). */
104
- export interface SlugDocs {
105
- /** The program's overall spec (`specs/<program>-overall.md`); null when absent. */
106
- overall: string | null;
107
- /** The phase's design spec (`specs/<slug>-design.md`); null when absent or the
108
- * slug is a program slug. */
109
- spec: string | null;
110
- /** The phase's plan (`plans/<slug>.md`); null when absent or the slug is a
111
- * program slug. */
112
- plan: string | null;
113
- /** The phase suffix (`-p7`, `-p4.1`, `-p3.2.1` …); null for a program slug. */
114
- phaseSuffix: string | null;
115
- }
116
-
117
- /** One dispatch workspace — `<base>/<slug>/`. */
118
- export class Workspace {
119
- readonly root: WorkspaceRoot;
120
- readonly slug: string;
121
- readonly path: string;
122
-
123
- constructor(root: WorkspaceRoot, slug: string) {
124
- this.root = root;
125
- this.slug = slug;
126
- this.path = path.join(root.path, slug);
127
- }
128
-
129
- /** The doc-file → slug derivation: strip `.md`, then one trailing `-design` or
130
- * `-plan` suffix (anchored, mutually exclusive — spec and plan converge). */
131
- static slugFromDoc(doc: string): string {
132
- const base = path.basename(doc).replace(/\.md$/, "");
133
- return base.replace(/-(?:design|plan)$/, "");
134
- }
135
-
136
- /** The slug's phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment
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. */
139
- static phaseSuffixOf(slug: string): string | null {
140
- const match = PHASE_SUFFIX_TAIL.exec(slug);
141
- return match?.groups?.suffix ?? null;
142
- }
143
-
144
- /** The slug → doc-tree reverse derivation: from a program or phase slug, derive
145
- * the artifact paths the doc tree should carry, judged by `existsSync` (the
146
- * file system is the only truth — an absent file is null, never synthesized).
147
- * A phase slug's overall anchors at the nearest existing `<ancestor>-overall.md`
148
- * walking up the dotted phase path (`-p7.1` → `-p7` → program root) — no
149
- * overall-declared table is parsed (the Phase inventory is stale-prone). */
150
- static docsOfSlug(slug: string, repoRoot: string): SlugDocs {
151
- const specs = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
152
- const plans = path.join(repoRoot, ENGINE_RUNTIME.docRoots.plans);
153
- const suffix = Workspace.phaseSuffixOf(slug);
154
- if (suffix === null) {
155
- const overall = path.join(specs, `${slug}-overall.md`);
156
- return {
157
- overall: existsSync(overall) ? overall : null,
158
- spec: null,
159
- plan: null,
160
- phaseSuffix: null,
161
- };
162
- }
163
- const overall = Workspace.#nearestOverall(specs, slug, suffix);
164
- const spec = path.join(specs, `${slug}-design.md`);
165
- const plan = path.join(plans, `${slug}.md`);
166
- return {
167
- overall,
168
- spec: existsSync(spec) ? spec : null,
169
- plan: existsSync(plan) ? plan : null,
170
- phaseSuffix: suffix,
171
- };
172
- }
173
-
174
- /** The nearest existing overall anchor walking up the dotted phase path: for a
175
- * deep suffix (`-p7.1`) the candidates are `<program>-p7`, then the program
176
- * root; for a single-segment suffix the program root only. Null when no
177
- * candidate's overall file exists — nothing synthesized. */
178
- static #nearestOverall(specs: string, slug: string, suffix: string): string | null {
179
- const stem = slug.slice(0, slug.length - suffix.length);
180
- const segments = suffix.slice(2).split(".");
181
- for (let keep = segments.length - 1; keep >= 0; keep--) {
182
- const candidate =
183
- keep === 0
184
- ? path.join(specs, `${stem}-overall.md`)
185
- : path.join(specs, `${stem}-p${segments.slice(0, keep).join(".")}-overall.md`);
186
- if (existsSync(candidate)) return candidate;
187
- }
188
- return null;
189
- }
190
-
191
- /** Idempotently create the workspace directory. */
192
- ensure(): Workspace {
193
- this.root.ensure();
194
- mkdirSync(this.path, { recursive: true });
195
- return this;
196
- }
197
-
198
- /** A child path inside this workspace. */
199
- resolve(name: string): string {
200
- return path.join(this.path, name);
201
- }
202
-
203
- /** Read a JSON child — the tri-state face: `{kind:"ok",value}` on a present,
204
- * parseable file; `{kind:"missing"}` when the path does not exist; `{kind:
205
- * "malformed"}` when the file is present but its bytes are unparseable (a bad
206
- * JSON draft) OR unreadable for any other I/O reason (a present-but-broken file is
207
- * never silently "missing" — the reconstruct reports the true cause). The STRICT
208
- * read — engine-authored files (`JSON.stringify` output) are always legal JSON, so
209
- * they never need leniency; a lenient read of a strict file would only mask a real
210
- * engine bug. */
211
- readJson<T>(name: string): JsonRead<T> {
212
- const target = this.resolve(name);
213
- const text = this.#readText(target);
214
- if (text.kind !== "ok") return text;
215
- try {
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 };
221
- } catch {
222
- return { kind: "malformed" };
223
- }
224
- }
225
-
226
- /** Read a JSON child LENIENTLY — the sub-agent-authored handoff-draft face (D39).
227
- * A child LLM writes handoff carriers (`tasks-*-implement.json` …) from prose, and
228
- * a trailing comma or a stray comment is a routine model slip, not a real defect —
229
- * the strict `readJson` vetoes the WHOLE implement+review round on one such comma
230
- * (the W3 {5,11} block: a `notes` array trailing comma, the draft otherwise whole).
231
- * jsonc-parser with `allowTrailingComma` tolerates ONLY the lenient-dialect surface
232
- * (trailing commas · comments) and still reports a real break (a missing brace, …)
233
- * — so a corrupt draft stays fail-loud while a cosmetic slip no longer voids a round.
234
- * The leniency is scoped to THIS face alone: engine-authored files (including the
235
- * test-evidence sibling, which the engine/child writes as machine JSON) keep the
236
- * strict `readJson` — the JSON contract is never widened for engine bytes. */
237
- readJsonLenient<T>(name: string): JsonRead<T> {
238
- const target = this.resolve(name);
239
- const text = this.#readText(target);
240
- if (text.kind !== "ok") return text;
241
- const errors: ParseError[] = [];
242
- const value = parse(text.value, errors, {
243
- allowTrailingComma: true,
244
- disallowComments: false,
245
- }) as T;
246
- // A real break carries the parser's precise error codes (offset/length/error)
247
- // for diagnosis; a tolerated slip parses clean (errors empty).
248
- return errors.length === 0 ? { kind: "ok", value } : { kind: "malformed", errors };
249
- }
250
-
251
- /** Read a child's text — the shared tri-state file leg of both JSON reads: a
252
- * genuinely absent path is `missing`; a present-but-unreadable one (EACCES, EISDIR …)
253
- * is `malformed` — never silently "missing" (D27 · single-fact honesty). */
254
- #readText(target: string): { kind: "ok"; value: string } | JsonRead<never> {
255
- let text: string;
256
- try {
257
- text = readFileSync(target, "utf8");
258
- } catch (raw) {
259
- const code = (raw as { code?: unknown }).code;
260
- return code === "ENOENT" ? { kind: "missing" } : { kind: "malformed" };
261
- }
262
- return { kind: "ok", value: text };
263
- }
264
-
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). */
272
- writeJson(name: string, value: unknown): void {
273
- this.ensure();
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);
321
- }
322
- }