@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.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/package.json +4 -3
- package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
- package/src-next/__tests__/floor.guard.test.ts +69 -0
- package/src-next/__tests__/issue-body.guard.test.ts +66 -0
- package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
- package/src-next/__tests__/smoke.integration.test.ts +60 -77
- package/src-next/__tests__/support/strip-comments.ts +99 -0
- package/src-next/__tests__/zero-dep.test.ts +6 -46
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
- package/src-next/contract/__tests__/declare.test.ts +251 -12
- package/src-next/contract/__tests__/doc.test.ts +214 -45
- package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
- package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
- package/src-next/contract/__tests__/judge.test.ts +410 -172
- package/src-next/contract/__tests__/lint.test.ts +49 -39
- package/src-next/contract/__tests__/project.test.ts +60 -19
- package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
- package/src-next/contract/declare.ts +179 -91
- package/src-next/contract/doc.ts +227 -164
- package/src-next/contract/frontmatter.ts +233 -0
- package/src-next/contract/home-extractors.ts +397 -0
- package/src-next/contract/invariants.ts +214 -69
- package/src-next/contract/judge.ts +28 -19
- package/src-next/contract/lint.ts +5 -41
- package/src-next/contract/project.ts +103 -43
- package/src-next/contract/skill-anatomy.ts +39 -11
- package/src-next/face/__tests__/board-view.test.ts +318 -115
- package/src-next/face/__tests__/capsule.test.ts +49 -25
- package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
- package/src-next/face/__tests__/cli.test.ts +1091 -837
- package/src-next/face/__tests__/face.test.ts +5 -5
- package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
- package/src-next/face/__tests__/preview.test.ts +374 -0
- package/src-next/face/__tests__/projection.test.ts +5 -3
- package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
- package/src-next/face/__tests__/termination.test.ts +650 -0
- package/src-next/face/artifacts.ts +90 -37
- package/src-next/face/board-view.ts +128 -138
- package/src-next/face/capsule.ts +30 -16
- package/src-next/face/cli.ts +306 -97
- package/src-next/face/declare.ts +15 -18
- package/src-next/face/gate.ts +19 -18
- package/src-next/face/host.ts +6 -30
- package/src-next/face/lifecycle.ts +213 -188
- package/src-next/face/preview.ts +151 -0
- package/src-next/face/projection.ts +4 -1
- package/src-next/face/route-render.ts +39 -14
- package/src-next/face/termination.ts +573 -0
- package/src-next/face/words.ts +20 -2
- package/src-next/infra/__tests__/infra.test.ts +49 -3
- package/src-next/infra/__tests__/root.test.ts +56 -0
- package/src-next/infra/doc-roots.ts +29 -0
- package/src-next/infra/root.ts +73 -0
- package/src-next/infra/runtime.ts +12 -65
- package/src-next/infra/workspace.ts +95 -5
- package/src-next/render/__tests__/render.test.ts +92 -41
- package/src-next/render/__tests__/skeleton.test.ts +282 -64
- package/src-next/render/issue-body.ts +5 -2
- package/src-next/render/skeleton.ts +155 -90
- package/src-next/render/templates.ts +51 -56
- package/src-next/session/__tests__/graph.test.ts +11 -4
- package/src-next/session/__tests__/ledger.test.ts +3 -2
- package/src-next/session/__tests__/next.test.ts +100 -8
- package/src-next/session/__tests__/preflight.test.ts +79 -25
- package/src-next/session/__tests__/round-naming.test.ts +142 -0
- package/src-next/session/__tests__/run.test.ts +140 -128
- package/src-next/session/__tests__/wave.test.ts +11 -4
- package/src-next/session/ledger.ts +96 -24
- package/src-next/session/next.ts +116 -15
- package/src-next/session/preflight.ts +41 -10
- package/src-next/session/round-naming.ts +84 -0
- package/src-next/session/run.ts +24 -20
- package/templates/report/issue-body.json +0 -46
- 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 (
|
|
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
|
-
|
|
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 +
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
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
|
|
52
|
-
*
|
|
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 (
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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
|
}
|