@oscaner-skills/cdd-engine 1.0.0 → 2.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 +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -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,185 @@
|
|
|
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
|
+
|
|
28
|
+
/** The context contract — the live argv channel table (the single channel the new
|
|
29
|
+
* tree's command face consumes; the host-marker env closure lives in the harness
|
|
30
|
+
* detect rows, face/host.ts — never duplicated here). */
|
|
31
|
+
export interface ContextContract {
|
|
32
|
+
readonly channels: Readonly<{ argv: Readonly<Record<string, ChannelArgRow>> }>;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** One handoff-family record — the canonical file-name pattern + round policy + the
|
|
36
|
+
* carrier's schema face (the full family row the JSON plane carried — schema /
|
|
37
|
+
* fixFamily / prev are data the typed plane preserves). The v1.9 contract
|
|
38
|
+
* reparametrization: `returnFormat` is deleted (RETURN_STDOUT_BLOCK is the ONE
|
|
39
|
+
* return contract — the per-family field was the JSON/block selector, retired with
|
|
40
|
+
* the divided return faces) and the dead `schema` field is resurrected as the
|
|
41
|
+
* handoff-schema face selector (`work` — implement/fix carrier — vs `findings` —
|
|
42
|
+
* the review carrier, session/handoff-schema.ts). */
|
|
43
|
+
export interface HandoffFamily {
|
|
44
|
+
/** The canonical file name — the `{placeholder}` pattern the ledger fills. */
|
|
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
|
+
/** The carrier schema face (work / findings) — the handoff-schema selector (§3.6:
|
|
51
|
+
* the field resurrected from the dead task/docs discrimination; the docs-fix
|
|
52
|
+
* families (fix.spec / fix.plan) ride the findings face — §3.6's per-mode split:
|
|
53
|
+
* implement/fix → work + evidence · review/docs-fix → findings). */
|
|
54
|
+
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
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The handoff-name space — the workspace segment + the family naming table. */
|
|
64
|
+
export interface HandoffNamespace {
|
|
65
|
+
/** The repo-scoped workspace segment (`.kairos/cdd` — WorkspaceRoot joins it). */
|
|
66
|
+
workspaceRoot: string;
|
|
67
|
+
/** The handoff families keyed by `op.type` — the ledger's naming truth. */
|
|
68
|
+
families: Readonly<Record<string, HandoffFamily>>;
|
|
69
|
+
}
|
|
70
|
+
|
|
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
|
+
/** The engine runtime — the typed engine-config surface (version + channels + names
|
|
81
|
+
* + doc roots). */
|
|
82
|
+
export interface EngineRuntime {
|
|
83
|
+
/** The runtime contract version. */
|
|
84
|
+
$version: number;
|
|
85
|
+
/** The context contract — the live argv channel table. */
|
|
86
|
+
contextContract: ContextContract;
|
|
87
|
+
/** The handoff-name space — workspace + family naming. */
|
|
88
|
+
handoffNamespace: HandoffNamespace;
|
|
89
|
+
/** The doc-tree root segments (the slug → node-tree face's file-system truth). */
|
|
90
|
+
docRoots: DocRoots;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** The handoff family naming table — the canonical per-family file-name patterns
|
|
94
|
+
* keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
|
|
95
|
+
* naming truth, verbatim from the engine-config handoff namespace). The v1.9
|
|
96
|
+
* reparametrization: `returnFormat` is gone (RETURN_STDOUT_BLOCK is the one return
|
|
97
|
+
* contract) and the `schema` faces are the handoff-schema selector (work / findings —
|
|
98
|
+
* §3.6, session/handoff-schema.ts). */
|
|
99
|
+
export const HANDOFF_FAMILIES = {
|
|
100
|
+
"implement.wave": {
|
|
101
|
+
name: "tasks-{tasks}-implement.json",
|
|
102
|
+
round: "fixed",
|
|
103
|
+
schema: "work",
|
|
104
|
+
phase: "implement",
|
|
105
|
+
},
|
|
106
|
+
"review.wave": {
|
|
107
|
+
name: "tasks-{tasks}-review-{round}.json",
|
|
108
|
+
round: "increment",
|
|
109
|
+
schema: "findings",
|
|
110
|
+
phase: "review",
|
|
111
|
+
fixFamily: "fix.wave",
|
|
112
|
+
prev: { round1: "implement.wave", roundR: "fix.wave:R-1" },
|
|
113
|
+
},
|
|
114
|
+
"fix.wave": {
|
|
115
|
+
name: "tasks-{tasks}-fix-{round}.json",
|
|
116
|
+
round: "source",
|
|
117
|
+
schema: "work",
|
|
118
|
+
fixTemplate: "fix",
|
|
119
|
+
phase: "fix",
|
|
120
|
+
prev: { roundR: "review.wave:R" },
|
|
121
|
+
},
|
|
122
|
+
"review.spec": {
|
|
123
|
+
name: "spec-review-{round}.json",
|
|
124
|
+
round: "increment",
|
|
125
|
+
schema: "findings",
|
|
126
|
+
phase: "review",
|
|
127
|
+
fixFamily: "fix.spec",
|
|
128
|
+
},
|
|
129
|
+
"fix.spec": {
|
|
130
|
+
name: "spec-fix-{round}.json",
|
|
131
|
+
round: "source",
|
|
132
|
+
schema: "findings",
|
|
133
|
+
fixTemplate: "docs",
|
|
134
|
+
phase: "fix",
|
|
135
|
+
prev: { roundR: "review.spec:R" },
|
|
136
|
+
},
|
|
137
|
+
"review.plan": {
|
|
138
|
+
name: "plan-review-{round}.json",
|
|
139
|
+
round: "increment",
|
|
140
|
+
schema: "findings",
|
|
141
|
+
phase: "review",
|
|
142
|
+
fixFamily: "fix.plan",
|
|
143
|
+
},
|
|
144
|
+
"fix.plan": {
|
|
145
|
+
name: "plan-fix-{round}.json",
|
|
146
|
+
round: "source",
|
|
147
|
+
schema: "findings",
|
|
148
|
+
fixTemplate: "docs",
|
|
149
|
+
phase: "fix",
|
|
150
|
+
prev: { roundR: "review.plan:R" },
|
|
151
|
+
},
|
|
152
|
+
"review.branch": {
|
|
153
|
+
// find #9 (spec §6.5): the range token leaves the file name — the workspace
|
|
154
|
+
// slug is the plan-slug (the fix face carries --plan) · round accumulates
|
|
155
|
+
// across re-reviews (lineKey pins "branch").
|
|
156
|
+
name: "branch-review-{round}.json",
|
|
157
|
+
round: "increment",
|
|
158
|
+
schema: "findings",
|
|
159
|
+
phase: "branch-review",
|
|
160
|
+
},
|
|
161
|
+
"fix.branch": {
|
|
162
|
+
name: "branch-fix-{round}.json",
|
|
163
|
+
round: "source",
|
|
164
|
+
schema: "work",
|
|
165
|
+
fixTemplate: "fix",
|
|
166
|
+
phase: "fix",
|
|
167
|
+
prev: { roundR: "review.branch:R" },
|
|
168
|
+
},
|
|
169
|
+
} as const satisfies Readonly<Record<string, HandoffFamily>>;
|
|
170
|
+
|
|
171
|
+
/** The engine runtime — the typed engine-config surface, one constant (the argv
|
|
172
|
+
* channel table is the CLI declaration single surface, face/declare.ts §2.4 —
|
|
173
|
+
* referenced here, never re-declared). */
|
|
174
|
+
export const ENGINE_RUNTIME = {
|
|
175
|
+
$version: 1,
|
|
176
|
+
contextContract: { channels: { argv: ARGV_CHANNEL } },
|
|
177
|
+
handoffNamespace: {
|
|
178
|
+
workspaceRoot: ".kairos/cdd",
|
|
179
|
+
families: HANDOFF_FAMILIES,
|
|
180
|
+
},
|
|
181
|
+
docRoots: {
|
|
182
|
+
specs: "docs/kairos/specs",
|
|
183
|
+
plans: "docs/kairos/plans",
|
|
184
|
+
},
|
|
185
|
+
} as const satisfies EngineRuntime;
|
|
@@ -0,0 +1,232 @@
|
|
|
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 { ENGINE_RUNTIME } from "./runtime.ts";
|
|
21
|
+
|
|
22
|
+
/** The tri-state JSON read — the read's three DISTINCT outcomes, discriminated: a
|
|
23
|
+
* `missing` file (never written) and a `malformed` file (present but unparseable)
|
|
24
|
+
* are different facts, so a read-back reconstruct reports each truly — a corrupt
|
|
25
|
+
* draft is never misreported as "not written" (D27 · single-fact honesty). The
|
|
26
|
+
* other-IO-error case (EACCES, EISDIR …) is a present-but-unreadable file and rides
|
|
27
|
+
* the `malformed` side: it is never silently "missing". The lenient face (D39)
|
|
28
|
+
* carries the parser's PRECISE error codes on the `malformed` side for diagnosis
|
|
29
|
+
* (the strict face and the IO-error case leave `errors` absent). */
|
|
30
|
+
export type JsonRead<T> =
|
|
31
|
+
| { kind: "ok"; value: T }
|
|
32
|
+
| { kind: "missing" }
|
|
33
|
+
| { kind: "malformed"; errors?: readonly ParseError[] };
|
|
34
|
+
|
|
35
|
+
/** The repo-scoped workspace base — `<repoRoot>/<workspaceRoot>`. */
|
|
36
|
+
export class WorkspaceRoot {
|
|
37
|
+
readonly repoRoot: string;
|
|
38
|
+
readonly path: string;
|
|
39
|
+
|
|
40
|
+
constructor(repoRoot: string, workspaceRoot: string) {
|
|
41
|
+
this.repoRoot = repoRoot;
|
|
42
|
+
this.path = path.join(repoRoot, workspaceRoot);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Idempotently create the workspace root + self-publish the namespace root's
|
|
46
|
+
* `.gitignore` (a single `*` — everything under `.kairos/` is engine-owned, so
|
|
47
|
+
* the git face ignores the whole namespace wholesale, the `cdd/` workspace and
|
|
48
|
+
* any future sibling alike). The tree-clean gate then reads git's own judgment
|
|
49
|
+
* — `isClean` with zero engine-side exclusion — a consumer repo with no `.kairos`
|
|
50
|
+
* entry in its own `.gitignore` still stays clean across dispatches, because
|
|
51
|
+
* the workspace publishes its keep-out marker at ensure time, before the gate
|
|
52
|
+
* ever reads the tree (the F1 fix: the engine's run artifacts are engine-owned,
|
|
53
|
+
* never "uncommitted user work"). The ignore affects only untracked files — a
|
|
54
|
+
* user who git-tracks the workspace keeps seeing its changes on the gate. */
|
|
55
|
+
ensure(): WorkspaceRoot {
|
|
56
|
+
mkdirSync(this.path, { recursive: true });
|
|
57
|
+
// The namespace root — the workspace root's parent (`.kairos/cdd` → `.kairos`):
|
|
58
|
+
// the keep-out marker sits at the namespace's top, never per-workspace (the
|
|
59
|
+
// consumer-facing convention: ignore the whole `.kairos` namespace at once).
|
|
60
|
+
const namespaceRoot = path.dirname(this.path);
|
|
61
|
+
mkdirSync(namespaceRoot, { recursive: true });
|
|
62
|
+
const ignore = path.join(namespaceRoot, ".gitignore");
|
|
63
|
+
if (!existsSync(ignore)) writeFileSync(ignore, "*\n", "utf8");
|
|
64
|
+
return this;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** One slug's doc-tree paths — the reverse-derived artifact paths of a program or
|
|
69
|
+
* phase slug (each member null when the file does not exist on disk; the file
|
|
70
|
+
* system is the only truth, nothing is synthesized). */
|
|
71
|
+
export interface SlugDocs {
|
|
72
|
+
/** The program's overall spec (`specs/<program>-overall.md`); null when absent. */
|
|
73
|
+
overall: string | null;
|
|
74
|
+
/** The phase's design spec (`specs/<slug>-design.md`); null when absent or the
|
|
75
|
+
* slug is a program slug. */
|
|
76
|
+
spec: string | null;
|
|
77
|
+
/** The phase's plan (`plans/<slug>.md`); null when absent or the slug is a
|
|
78
|
+
* program slug. */
|
|
79
|
+
plan: string | null;
|
|
80
|
+
/** The phase suffix (`-p7`, `-p4.1`, `-p3.2.1` …); null for a program slug. */
|
|
81
|
+
phaseSuffix: string | null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** One dispatch workspace — `<base>/<slug>/`. */
|
|
85
|
+
export class Workspace {
|
|
86
|
+
readonly root: WorkspaceRoot;
|
|
87
|
+
readonly slug: string;
|
|
88
|
+
readonly path: string;
|
|
89
|
+
|
|
90
|
+
constructor(root: WorkspaceRoot, slug: string) {
|
|
91
|
+
this.root = root;
|
|
92
|
+
this.slug = slug;
|
|
93
|
+
this.path = path.join(root.path, slug);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** The doc-file → slug derivation: strip `.md`, then one trailing `-design` or
|
|
97
|
+
* `-plan` suffix (anchored, mutually exclusive — spec and plan converge). */
|
|
98
|
+
static slugFromDoc(doc: string): string {
|
|
99
|
+
const base = path.basename(doc).replace(/\.md$/, "");
|
|
100
|
+
return base.replace(/-(?:design|plan)$/, "");
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** 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). */
|
|
105
|
+
static phaseSuffixOf(slug: string): string | null {
|
|
106
|
+
const match = /(?<program>.+?)(?<suffix>-p\d+(?:\.\d+)*)$/.exec(slug);
|
|
107
|
+
return match?.groups?.suffix ?? null;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** The slug → doc-tree reverse derivation: from a program or phase slug, derive
|
|
111
|
+
* the artifact paths the doc tree should carry, judged by `existsSync` (the
|
|
112
|
+
* file system is the only truth — an absent file is null, never synthesized).
|
|
113
|
+
* A phase slug's overall anchors at the nearest existing `<ancestor>-overall.md`
|
|
114
|
+
* walking up the dotted phase path (`-p7.1` → `-p7` → program root) — no
|
|
115
|
+
* overall-declared table is parsed (the Phase inventory is stale-prone). */
|
|
116
|
+
static docsOfSlug(slug: string, repoRoot: string): SlugDocs {
|
|
117
|
+
const specs = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
|
|
118
|
+
const plans = path.join(repoRoot, ENGINE_RUNTIME.docRoots.plans);
|
|
119
|
+
const suffix = Workspace.phaseSuffixOf(slug);
|
|
120
|
+
if (suffix === null) {
|
|
121
|
+
const overall = path.join(specs, `${slug}-overall.md`);
|
|
122
|
+
return {
|
|
123
|
+
overall: existsSync(overall) ? overall : null,
|
|
124
|
+
spec: null,
|
|
125
|
+
plan: null,
|
|
126
|
+
phaseSuffix: null,
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
const overall = Workspace.#nearestOverall(specs, slug, suffix);
|
|
130
|
+
const spec = path.join(specs, `${slug}-design.md`);
|
|
131
|
+
const plan = path.join(plans, `${slug}.md`);
|
|
132
|
+
return {
|
|
133
|
+
overall,
|
|
134
|
+
spec: existsSync(spec) ? spec : null,
|
|
135
|
+
plan: existsSync(plan) ? plan : null,
|
|
136
|
+
phaseSuffix: suffix,
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** The nearest existing overall anchor walking up the dotted phase path: for a
|
|
141
|
+
* deep suffix (`-p7.1`) the candidates are `<program>-p7`, then the program
|
|
142
|
+
* root; for a single-segment suffix the program root only. Null when no
|
|
143
|
+
* candidate's overall file exists — nothing synthesized. */
|
|
144
|
+
static #nearestOverall(specs: string, slug: string, suffix: string): string | null {
|
|
145
|
+
const stem = slug.slice(0, slug.length - suffix.length);
|
|
146
|
+
const segments = suffix.slice(2).split(".");
|
|
147
|
+
for (let keep = segments.length - 1; keep >= 0; keep--) {
|
|
148
|
+
const candidate =
|
|
149
|
+
keep === 0
|
|
150
|
+
? path.join(specs, `${stem}-overall.md`)
|
|
151
|
+
: path.join(specs, `${stem}-p${segments.slice(0, keep).join(".")}-overall.md`);
|
|
152
|
+
if (existsSync(candidate)) return candidate;
|
|
153
|
+
}
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** Idempotently create the workspace directory. */
|
|
158
|
+
ensure(): Workspace {
|
|
159
|
+
this.root.ensure();
|
|
160
|
+
mkdirSync(this.path, { recursive: true });
|
|
161
|
+
return this;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** A child path inside this workspace. */
|
|
165
|
+
resolve(name: string): string {
|
|
166
|
+
return path.join(this.path, name);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** Read a JSON child — the tri-state face: `{kind:"ok",value}` on a present,
|
|
170
|
+
* parseable file; `{kind:"missing"}` when the path does not exist; `{kind:
|
|
171
|
+
* "malformed"}` when the file is present but its bytes are unparseable (a bad
|
|
172
|
+
* JSON draft) OR unreadable for any other I/O reason (a present-but-broken file is
|
|
173
|
+
* never silently "missing" — the reconstruct reports the true cause). The STRICT
|
|
174
|
+
* read — engine-authored files (`JSON.stringify` output) are always legal JSON, so
|
|
175
|
+
* they never need leniency; a lenient read of a strict file would only mask a real
|
|
176
|
+
* engine bug. */
|
|
177
|
+
readJson<T>(name: string): JsonRead<T> {
|
|
178
|
+
const target = this.resolve(name);
|
|
179
|
+
const text = this.#readText(target);
|
|
180
|
+
if (text.kind !== "ok") return text;
|
|
181
|
+
try {
|
|
182
|
+
return { kind: "ok", value: JSON.parse(text.value) as T };
|
|
183
|
+
} catch {
|
|
184
|
+
return { kind: "malformed" };
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** Read a JSON child LENIENTLY — the sub-agent-authored handoff-draft face (D39).
|
|
189
|
+
* A child LLM writes handoff carriers (`tasks-*-implement.json` …) from prose, and
|
|
190
|
+
* a trailing comma or a stray comment is a routine model slip, not a real defect —
|
|
191
|
+
* the strict `readJson` vetoes the WHOLE implement+review round on one such comma
|
|
192
|
+
* (the W3 {5,11} block: a `notes` array trailing comma, the draft otherwise whole).
|
|
193
|
+
* jsonc-parser with `allowTrailingComma` tolerates ONLY the lenient-dialect surface
|
|
194
|
+
* (trailing commas · comments) and still reports a real break (a missing brace, …)
|
|
195
|
+
* — so a corrupt draft stays fail-loud while a cosmetic slip no longer voids a round.
|
|
196
|
+
* The leniency is scoped to THIS face alone: engine-authored files (including the
|
|
197
|
+
* test-evidence sibling, which the engine/child writes as machine JSON) keep the
|
|
198
|
+
* strict `readJson` — the JSON contract is never widened for engine bytes. */
|
|
199
|
+
readJsonLenient<T>(name: string): JsonRead<T> {
|
|
200
|
+
const target = this.resolve(name);
|
|
201
|
+
const text = this.#readText(target);
|
|
202
|
+
if (text.kind !== "ok") return text;
|
|
203
|
+
const errors: ParseError[] = [];
|
|
204
|
+
const value = parse(text.value, errors, {
|
|
205
|
+
allowTrailingComma: true,
|
|
206
|
+
disallowComments: false,
|
|
207
|
+
}) as T;
|
|
208
|
+
// A real break carries the parser's precise error codes (offset/length/error)
|
|
209
|
+
// for diagnosis; a tolerated slip parses clean (errors empty).
|
|
210
|
+
return errors.length === 0 ? { kind: "ok", value } : { kind: "malformed", errors };
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Read a child's text — the shared tri-state file leg of both JSON reads: a
|
|
214
|
+
* genuinely absent path is `missing`; a present-but-unreadable one (EACCES, EISDIR …)
|
|
215
|
+
* is `malformed` — never silently "missing" (D27 · single-fact honesty). */
|
|
216
|
+
#readText(target: string): { kind: "ok"; value: string } | JsonRead<never> {
|
|
217
|
+
let text: string;
|
|
218
|
+
try {
|
|
219
|
+
text = readFileSync(target, "utf8");
|
|
220
|
+
} catch (raw) {
|
|
221
|
+
const code = (raw as { code?: unknown }).code;
|
|
222
|
+
return code === "ENOENT" ? { kind: "missing" } : { kind: "malformed" };
|
|
223
|
+
}
|
|
224
|
+
return { kind: "ok", value: text };
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** Write a JSON child — mkdir before write. */
|
|
228
|
+
writeJson(name: string, value: unknown): void {
|
|
229
|
+
this.ensure();
|
|
230
|
+
writeFileSync(this.resolve(name), JSON.stringify(value, null, 2), "utf8");
|
|
231
|
+
}
|
|
232
|
+
}
|