@oscaner-skills/cdd-engine 1.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
@@ -0,0 +1,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,42 @@
1
+ // packages/cdd-engine/src-next/infra/config.ts
2
+ // T21 — the config plane becomes a typed accessor facade: the external contract
3
+ // JSONs are gone (the new tree reads zero config files), and every stable fact
4
+ // lives in its single typed home — infra/runtime.ts (engine-config) · face/host.ts
5
+ // (harness contract) · render/templates.ts (template contract). ConfigLoader is the
6
+ // facade over those homes: the consumer surface (engineConfig · harnessContract ·
7
+ // templateContract · handoffNamespace) is unchanged, one no-I/O accessor per face.
8
+ //
9
+ // The previous JSON-plane interfaces (EngineConfig / HarnessContract /
10
+ // TemplateContract / HandoffNamespace) retire here — the typed data modules own the
11
+ // shapes; this module only routes.
12
+
13
+ import { HOST_CONTRACT, type HostContract } from "../face/host.ts";
14
+ import { TEMPLATE_PROMPT, type TemplatePrompt } from "../render/templates.ts";
15
+ import { ENGINE_RUNTIME, type EngineRuntime, type HandoffNamespace } from "./runtime.ts";
16
+
17
+ /**
18
+ * The typed config accessor — the single façade over the typed data planes (zero
19
+ * file reads: every accessor returns the declared constant of its single home).
20
+ * Construction is trivial; the consumer surface matches the retired loader.
21
+ */
22
+ export class ConfigLoader {
23
+ /** The engine-config face — the typed engine runtime (version + channels + names). */
24
+ engineConfig(): EngineRuntime {
25
+ return ENGINE_RUNTIME;
26
+ }
27
+
28
+ /** The harness-contract face — the typed host adaptation contract (hosts + dispatch + refs). */
29
+ harnessContract(): HostContract {
30
+ return HOST_CONTRACT;
31
+ }
32
+
33
+ /** The template-contract face — the typed dispatch-prompt + review criteria. */
34
+ templateContract(): TemplatePrompt {
35
+ return TEMPLATE_PROMPT;
36
+ }
37
+
38
+ /** The handoff-namespace section — the workspace-root + the family naming single source. */
39
+ handoffNamespace(): HandoffNamespace {
40
+ return ENGINE_RUNTIME.handoffNamespace;
41
+ }
42
+ }
@@ -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,39 @@
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
+ }
@@ -0,0 +1,34 @@
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
+ }
@@ -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
+ }
@@ -0,0 +1,132 @@
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;