@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.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +149 -0
- package/dist/face/cli.js +893 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +702 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +504 -0
- package/dist/face/words.js +258 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +453 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/face/declare.ts
|
|
2
|
+
// §2.4 — the CLI declaration single surface: the argv channel table, the seven-command
|
|
3
|
+
// declarations, every CLI face type and the conditional-required group table cohere
|
|
4
|
+
// in ONE file (the user ruling 2026-10-11: the declaration was scattered across
|
|
5
|
+
// runtime/registry/argv → one surface). The migration converges:
|
|
6
|
+
//
|
|
7
|
+
// · ARGV_CHANNEL / ChannelValueType / ChannelArgRow — from infra/runtime.ts (the
|
|
8
|
+
// engine-config face keeps only the version + the handoff-namespace facts).
|
|
9
|
+
// · CliVerb / CliLeafName / CliValueOverride / CliArgSpec / CliLeafSpec /
|
|
10
|
+
// CliCommandSpec / CLI_COMMANDS — from face/registry.ts (the registry file is
|
|
11
|
+
// deleted; the rows drop the `usage` field — the usage semantics merge into the
|
|
12
|
+
// projection's .description(), and the six-line usage corpus retires here).
|
|
13
|
+
// · REQUIRED_GROUPS — from face/validate.ts (the preAction data face; the
|
|
14
|
+
// retired validator component retires — the value-domain semantics move to the
|
|
15
|
+
// builder's parseArg method family).
|
|
16
|
+
// · SCHEMA_TYPE_KEYS — from face/argv.ts (the schema <type> vocabulary; consumed
|
|
17
|
+
// by the builder's #parseTypeKey — the argv.ts parse channel died at T6).
|
|
18
|
+
//
|
|
19
|
+
// Module-level exports are types / declared constant data — zero behavior-carrying
|
|
20
|
+
// bare functions (the plan's zero-bare-function discipline); the projection
|
|
21
|
+
// algorithm lives in the single CommandTreeBuilder class (face/projection.ts).
|
|
22
|
+
import { InvalidArgumentError } from "commander";
|
|
23
|
+
import { ENGINE_DOC_ROOTS } from "../infra/doc-roots.js";
|
|
24
|
+
/** The argv channel table — the CLI flag/type/enum single source (the engine-config
|
|
25
|
+
* argv channel verbatim: flag spellings, value types and enum domains ride these
|
|
26
|
+
* rows, and the command declarations + the channel audit read them from here). The
|
|
27
|
+
* `help` rows are the flag-level descriptions of the commander Options face (one
|
|
28
|
+
* text per key, shared by every command that declares it). */
|
|
29
|
+
export const ARGV_CHANNEL = {
|
|
30
|
+
plan: { flag: "--plan", type: "path", help: "the CDD plan document path" },
|
|
31
|
+
spec: { flag: "--spec", type: "path", help: "the design-spec document path" },
|
|
32
|
+
reviews: {
|
|
33
|
+
flag: "--reviews",
|
|
34
|
+
type: "path",
|
|
35
|
+
help: "the source review handoff JSON path",
|
|
36
|
+
},
|
|
37
|
+
tasks: {
|
|
38
|
+
flag: "--tasks",
|
|
39
|
+
type: "int-list",
|
|
40
|
+
help: "the task ids of the wave group (comma-separated)",
|
|
41
|
+
},
|
|
42
|
+
type: {
|
|
43
|
+
flag: "--type",
|
|
44
|
+
type: "enum",
|
|
45
|
+
values: ["wave", "branch", "spec", "plan"],
|
|
46
|
+
help: "the target face of the round",
|
|
47
|
+
},
|
|
48
|
+
base: { flag: "--base", type: "string", help: "the base artifact branch name" },
|
|
49
|
+
round: { flag: "--round", type: "int", help: "the review/fix round number" },
|
|
50
|
+
source: {
|
|
51
|
+
flag: "--source",
|
|
52
|
+
type: "enum",
|
|
53
|
+
values: ["plan-field", "branch-upstream", "conversation-context", "user-confirmed"],
|
|
54
|
+
help: "the base artifact's source channel",
|
|
55
|
+
},
|
|
56
|
+
force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
|
|
57
|
+
dryRun: {
|
|
58
|
+
flag: "--dry-run",
|
|
59
|
+
type: "bool",
|
|
60
|
+
scope: "program",
|
|
61
|
+
help: "preview the next dispatch step and its expected artifacts — zero repo writes, no round consumed (implement/review/fix only)",
|
|
62
|
+
},
|
|
63
|
+
help: {
|
|
64
|
+
flag: "--help",
|
|
65
|
+
alias: "-h",
|
|
66
|
+
type: "bool",
|
|
67
|
+
scope: "program",
|
|
68
|
+
help: "show this help",
|
|
69
|
+
},
|
|
70
|
+
output: {
|
|
71
|
+
flag: "--output",
|
|
72
|
+
type: "enum",
|
|
73
|
+
values: ["json", "skeleton"],
|
|
74
|
+
help: "the schema render face — json (the derived declaration, default) or skeleton (the scaffold written into <target>)",
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
/** The value-domain shapes — the parsed raw's check + normalization per shaped
|
|
78
|
+
* channel type: the parseArg family's single executor source (§4.1). Each rule
|
|
79
|
+
* validates the raw against the row's declared domain and returns the normalized
|
|
80
|
+
* value; a non-conforming raw throws commander.InvalidArgumentError with the
|
|
81
|
+
* pinned error bytes (the value-domain error messages are a pinned surface —
|
|
82
|
+
* zero byte drift across the retired method family). The enum rule reads the
|
|
83
|
+
* row's declared `values`; the int-list normalization rewrites the consumed
|
|
84
|
+
* shape, never the run face's own normalization. Data rows, never bare
|
|
85
|
+
* functions — one executor reads them (face/projection.ts #parseArgOf). */
|
|
86
|
+
export const VALUE_SHAPES = {
|
|
87
|
+
enum: {
|
|
88
|
+
parse(raw, row) {
|
|
89
|
+
if (!(row.values ?? []).includes(raw)) {
|
|
90
|
+
throw new InvalidArgumentError(`must be one of ${(row.values ?? []).join(" | ")}`);
|
|
91
|
+
}
|
|
92
|
+
return raw;
|
|
93
|
+
},
|
|
94
|
+
},
|
|
95
|
+
"int-list": {
|
|
96
|
+
parse(raw) {
|
|
97
|
+
const parts = raw.split(",").map((part) => part.trim());
|
|
98
|
+
const invalid = parts.find((part) => !/^\d+$/.test(part));
|
|
99
|
+
if (invalid !== undefined) {
|
|
100
|
+
throw new InvalidArgumentError(`--tasks <n|n,n,…> — must be comma-separated integers: ${invalid}`);
|
|
101
|
+
}
|
|
102
|
+
return [...new Set(parts.map(Number))].sort((a, b) => a - b).join(",");
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
int: {
|
|
106
|
+
parse(raw) {
|
|
107
|
+
if (!/^\d+$/.test(raw)) {
|
|
108
|
+
throw new InvalidArgumentError("must be an integer");
|
|
109
|
+
}
|
|
110
|
+
return raw;
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
};
|
|
114
|
+
/** The seven subcommand declarations — implement, review, fix (the lifecycle work
|
|
115
|
+
* commands) plus the pure base / schema / issue artifact commands and the board
|
|
116
|
+
* observability command. */
|
|
117
|
+
export const CLI_COMMANDS = [
|
|
118
|
+
{
|
|
119
|
+
name: "implement",
|
|
120
|
+
description: "run the task implement phase",
|
|
121
|
+
example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
|
|
122
|
+
keys: [
|
|
123
|
+
{ key: "tasks", required: true },
|
|
124
|
+
{ key: "plan", required: true },
|
|
125
|
+
],
|
|
126
|
+
},
|
|
127
|
+
{
|
|
128
|
+
name: "review",
|
|
129
|
+
description: "run a review — task | branch | spec | plan",
|
|
130
|
+
example: `cdd review --type spec --spec ${ENGINE_DOC_ROOTS.specs}/p3-design.md`,
|
|
131
|
+
keys: [
|
|
132
|
+
{ key: "type", required: true },
|
|
133
|
+
{ key: "tasks" },
|
|
134
|
+
{ key: "plan" },
|
|
135
|
+
{ key: "spec" },
|
|
136
|
+
{ key: "round" },
|
|
137
|
+
],
|
|
138
|
+
},
|
|
139
|
+
{
|
|
140
|
+
name: "fix",
|
|
141
|
+
description: "fix review findings — task | branch | spec | plan",
|
|
142
|
+
example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
|
|
143
|
+
keys: [
|
|
144
|
+
{ key: "type", required: true },
|
|
145
|
+
{ key: "tasks" },
|
|
146
|
+
{ key: "reviews" },
|
|
147
|
+
{ key: "spec" },
|
|
148
|
+
{ key: "plan" },
|
|
149
|
+
],
|
|
150
|
+
},
|
|
151
|
+
{
|
|
152
|
+
name: "base",
|
|
153
|
+
description: "read/write base.json (single CDD --plan target)",
|
|
154
|
+
example: `cdd base set --plan ${ENGINE_DOC_ROOTS.plans}/p3.md --base develop --source plan-field`,
|
|
155
|
+
keys: [],
|
|
156
|
+
leaves: [
|
|
157
|
+
{
|
|
158
|
+
name: "set",
|
|
159
|
+
description: "write the base artifact",
|
|
160
|
+
keys: [
|
|
161
|
+
{ key: "plan", required: true },
|
|
162
|
+
{ key: "base", required: true, valueType: "branch" },
|
|
163
|
+
{ key: "source", required: true },
|
|
164
|
+
{ key: "force" },
|
|
165
|
+
],
|
|
166
|
+
},
|
|
167
|
+
{
|
|
168
|
+
name: "get",
|
|
169
|
+
description: "read the base artifact",
|
|
170
|
+
keys: [{ key: "plan", required: true }],
|
|
171
|
+
},
|
|
172
|
+
],
|
|
173
|
+
},
|
|
174
|
+
{
|
|
175
|
+
name: "schema",
|
|
176
|
+
description: "read canonical doc-structure schemas (discovery, zero enforcement)",
|
|
177
|
+
example: "cdd schema get phase-spec",
|
|
178
|
+
keys: [{ key: "plan" }],
|
|
179
|
+
leaves: [
|
|
180
|
+
{
|
|
181
|
+
name: "get",
|
|
182
|
+
description: "print the derived doc-structure schema for <type> (the --output json face, default) or render the derived doc skeleton into <target> (the --output skeleton face)",
|
|
183
|
+
keys: [{ key: "plan" }, { key: "output" }],
|
|
184
|
+
positionals: [{ key: "type", required: true }, { key: "target" }],
|
|
185
|
+
},
|
|
186
|
+
],
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
name: "issue",
|
|
190
|
+
description: "aggregate issue-body rendering (cdd issue render, zero enforcement)",
|
|
191
|
+
example: "cdd issue render < findings.json",
|
|
192
|
+
keys: [],
|
|
193
|
+
leaves: [
|
|
194
|
+
{
|
|
195
|
+
name: "render",
|
|
196
|
+
description: "render the aggregate issue body (stdin findings JSON → stdout)",
|
|
197
|
+
keys: [],
|
|
198
|
+
},
|
|
199
|
+
],
|
|
200
|
+
},
|
|
201
|
+
{
|
|
202
|
+
name: "board",
|
|
203
|
+
description: "render the slug progress board (overall/spec/plan/wave/branch)",
|
|
204
|
+
example: "cdd board 2026-10-10-engine-doc-tooling-p7",
|
|
205
|
+
keys: [],
|
|
206
|
+
positionals: [{ key: "slug", required: true }],
|
|
207
|
+
},
|
|
208
|
+
];
|
|
209
|
+
/** The schema `<type>` vocabulary — the get leaf's ONE table (spec §5.3): the
|
|
210
|
+
* primary DocKey spellings (overall-spec | plan | phase-spec | single-spec) plus
|
|
211
|
+
* the legacy `phaseSpec` alias row normalized to the kebab key. One normalizing
|
|
212
|
+
* vocabulary, never a second hand-written list — the builder's #parseTypeKey
|
|
213
|
+
* validates through it. */
|
|
214
|
+
export const SCHEMA_TYPE_KEYS = {
|
|
215
|
+
"overall-spec": "overall-spec",
|
|
216
|
+
plan: "plan",
|
|
217
|
+
"phase-spec": "phase-spec",
|
|
218
|
+
"single-spec": "single-spec",
|
|
219
|
+
phaseSpec: "phase-spec",
|
|
220
|
+
};
|
|
221
|
+
/** The conditional required group per work verb + target type — the preAction hook's
|
|
222
|
+
* data face (spec §4.2): review `{plan}` / `{spec}` / `{plan}` · fix `{plan}` /
|
|
223
|
+
* `{spec}` / `{findings, plan}` — every branch face carries the `--plan` workspace
|
|
224
|
+
* identity (the branch line holds no commit ref: the review judges the live tree,
|
|
225
|
+
* the scope anchor BASE_BRANCH is engine-injected at dispatch). Keyed by declared
|
|
226
|
+
* flag spelling; non-exclusive — a round declaring both `--plan` and `--spec`
|
|
227
|
+
* stays accepted (no mutual-exclusion rejection). */
|
|
228
|
+
export const REQUIRED_GROUPS = {
|
|
229
|
+
review: {
|
|
230
|
+
wave: ["--plan"],
|
|
231
|
+
spec: ["--spec"],
|
|
232
|
+
plan: ["--plan"],
|
|
233
|
+
branch: ["--plan"],
|
|
234
|
+
},
|
|
235
|
+
fix: {
|
|
236
|
+
wave: ["--plan"],
|
|
237
|
+
spec: ["--spec"],
|
|
238
|
+
plan: ["--plan"],
|
|
239
|
+
branch: ["--reviews", "--plan"],
|
|
240
|
+
},
|
|
241
|
+
};
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/face/gate.ts
|
|
2
|
+
// T8 — the split contract's gate face (§6.2: face/gate.ts — the target/line gate
|
|
3
|
+
// family). The work commands' readiness gates — the single-target line's phase
|
|
4
|
+
// derivation (#lineGate/#linePhase/#lineKey/#lineParams/#lineRoundRoute/#lineFixRoute),
|
|
5
|
+
// the doc line's revision-aware BLOCK + pending-fix faces (#docLineBlock/
|
|
6
|
+
// #pendingFixBlock/#docContent/#docVersionOf) and the group/line helpers
|
|
7
|
+
// (#tasksOf/#renderBrief/#refFromHandoff). The method bodies are the pre-split Cli
|
|
8
|
+
// members moved verbatim — behavior bytes identical; the root Cli holds the gate
|
|
9
|
+
// instance and composes through it via its .action thin shells (zero bare functions).
|
|
10
|
+
import { readFileSync } from "node:fs";
|
|
11
|
+
import { FrontMatterExtractor } from "../contract/frontmatter.js";
|
|
12
|
+
import { BriefRenderer } from "../render/brief.js";
|
|
13
|
+
import { RoundNaming } from "../session/round-naming.js";
|
|
14
|
+
/**
|
|
15
|
+
* CliGate — the target/line gate family (the split contract's gate face): the
|
|
16
|
+
* readiness judgments the work commands consult before dispatching a round. The
|
|
17
|
+
* instance's methods take the per-invocation scene; the gate holds only the stable
|
|
18
|
+
* collaborators it needs (the brief renderer). The verdict-bearing methods return
|
|
19
|
+
* their ruling + message — the root renders, never re-judges.
|
|
20
|
+
*/
|
|
21
|
+
export class CliGate {
|
|
22
|
+
#brief;
|
|
23
|
+
constructor(opts = {}) {
|
|
24
|
+
this.#brief = opts.brief ?? new BriefRenderer();
|
|
25
|
+
}
|
|
26
|
+
/** The single-target line's current open phase plus the doc-line verdict the gate
|
|
27
|
+
* judged — the {phase, verdict} pair IS the gate's ruling: the revision-aware
|
|
28
|
+
* BLOCK renders only the "same" verdict the gate returned, the pending-fix note
|
|
29
|
+
* only the derived pending face, never a recomputed one. The task face holds no
|
|
30
|
+
* separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
|
|
31
|
+
* task-face phase authority — the wave gate is the single phase authority. A
|
|
32
|
+
* doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
|
|
33
|
+
* doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
|
|
34
|
+
* dispatches): a moved doc opens the review lead whatever the round/route state
|
|
35
|
+
* says (fix after · backfill after · user-decision after are the SAME case — the
|
|
36
|
+
* stuck "next round is fix after an aborted fix" never freezes a revised doc),
|
|
37
|
+
* an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
|
|
38
|
+
* from the latest review's non-APPROVED conclusion opens only the fix phase,
|
|
39
|
+
* while the no-pending face falls back to the legacy rounds/routes judgment: a
|
|
40
|
+
* completed-fix line reopens the review lead through its fix round's C5-1 route
|
|
41
|
+
* (the lifecycle's own fall-through — an open gate and a dispatchable frame
|
|
42
|
+
* agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
|
|
43
|
+
* (no identity on record / an unreadable doc) keeps the legacy round/route
|
|
44
|
+
* judgment + the generic closed message (only present facts land). */
|
|
45
|
+
lineGate(scene) {
|
|
46
|
+
if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
|
|
47
|
+
const key = this.#lineKey(scene);
|
|
48
|
+
if (key === null)
|
|
49
|
+
return { phase: null, verdict: null, reviewed: null };
|
|
50
|
+
const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
|
|
51
|
+
if (verdict.kind === "open") {
|
|
52
|
+
return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
|
|
53
|
+
}
|
|
54
|
+
if (verdict.kind === "same") {
|
|
55
|
+
if (verdict.pending) {
|
|
56
|
+
return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
|
|
57
|
+
}
|
|
58
|
+
// same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
|
|
59
|
+
// own fall-through): a completed-fix line reopens the review lead through its
|
|
60
|
+
// fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
|
|
61
|
+
const open = this.#linePhase(scene);
|
|
62
|
+
return open !== null
|
|
63
|
+
? { phase: open, verdict: null, reviewed: null }
|
|
64
|
+
: { phase: null, verdict: "same", reviewed: verdict.reviewed };
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
const open = this.#linePhase(scene);
|
|
68
|
+
return { phase: open, verdict: null, reviewed: null };
|
|
69
|
+
}
|
|
70
|
+
/** The doc line's revision-aware BLOCK message (T7/T8) — the unchanged-approved
|
|
71
|
+
* face: "{plan|spec} already reviewed at vX.Y (doc-hash …) — target revision
|
|
72
|
+
* unchanged; amend body/version to open a new review". Renders ONLY on the
|
|
73
|
+
* gate's "same" verdict — the approved identity the gate judged, whose reviewed
|
|
74
|
+
* ref the message names: the block consumes the verdict's identity, never a
|
|
75
|
+
* second ledger lookup (the face's judgment read points converge to the
|
|
76
|
+
* method family). Null off that face or with no identity ("target revision
|
|
77
|
+
* unchanged" is a present fact only there). */
|
|
78
|
+
docLineBlock(scene, reviewed) {
|
|
79
|
+
if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
|
|
80
|
+
return null;
|
|
81
|
+
const version = this.#docVersionOf(this.#docContent(scene.target.doc));
|
|
82
|
+
return `${scene.type} already reviewed at ${version ?? "the current version"} (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — target revision unchanged; amend body/version to open a new review`;
|
|
83
|
+
}
|
|
84
|
+
/** The doc line's derived pending-fix note (T8) — the unchanged + non-APPROVED
|
|
85
|
+
* face: "the pending fix applies to the unchanged doc (doc-hash …) — run cdd
|
|
86
|
+
* fix first". Renders ONLY for the gate's "pending-fix" verdict — the derived
|
|
87
|
+
* fix-awaited face (a same-doc re-review stays refused until its fix lands,
|
|
88
|
+
* Review Convergence anti-spin); the message names the reviewed identity the
|
|
89
|
+
* gate judged. */
|
|
90
|
+
pendingFixBlock(scene, reviewed) {
|
|
91
|
+
if (reviewed === null || (scene.target?.kind !== "plan" && scene.target?.kind !== "spec"))
|
|
92
|
+
return null;
|
|
93
|
+
return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
|
|
94
|
+
}
|
|
95
|
+
/** The requested group ints — the normalized tasks value split. */
|
|
96
|
+
tasksOf(parsed) {
|
|
97
|
+
return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
|
|
98
|
+
}
|
|
99
|
+
/** Render the task group brief into the workspace (the implement dispatch's input)
|
|
100
|
+
* — the brief mirrors the current plan (its task sections + the `## Constraints`
|
|
101
|
+
* section, re-extracted at every dispatch). */
|
|
102
|
+
renderBrief(scene, parsed) {
|
|
103
|
+
const tasks = this.tasksOf(parsed);
|
|
104
|
+
const content = this.#brief.render(scene.planText, tasks);
|
|
105
|
+
// The real run's workspace is built by the single write point (`Cli#runWork`'s
|
|
106
|
+
// ensure, P11 · §4.2) BEFORE this render; the write still rides the workspace's
|
|
107
|
+
// own text-write face (the `writeJson` mkdir-before-write pattern), never a
|
|
108
|
+
// second explicit `ensure()` — no bare `writeFileSync` into a possibly absent dir.
|
|
109
|
+
const name = new RoundNaming(scene.workspace).briefName(parsed.args.tasks ?? "");
|
|
110
|
+
return scene.workspace.writeText(name, content);
|
|
111
|
+
}
|
|
112
|
+
/** The single-target line's current open phase — fix-awaits / re-review / closure
|
|
113
|
+
* read from the ledger's SINGLE line-phase judge (`Ledger#linePhase`, D40 — the
|
|
114
|
+
* retired gate twin): the gate and the lifecycle's frame frontier now read ONE
|
|
115
|
+
* source, never a second walk. */
|
|
116
|
+
#linePhase(scene) {
|
|
117
|
+
const key = this.#lineKey(scene);
|
|
118
|
+
if (key === null)
|
|
119
|
+
return null;
|
|
120
|
+
return scene.ledger.linePhase(key, scene.face.type);
|
|
121
|
+
}
|
|
122
|
+
/** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
|
|
123
|
+
* §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
|
|
124
|
+
* its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
|
|
125
|
+
* string must not fork the same line into two ledger rows, resetting its round),
|
|
126
|
+
* the lifecycle's own key derivation (run.ts #lineKey). */
|
|
127
|
+
#lineKey(scene) {
|
|
128
|
+
if (scene.target?.kind === "branch")
|
|
129
|
+
return "branch";
|
|
130
|
+
if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
|
|
131
|
+
return scene.face.type;
|
|
132
|
+
return null;
|
|
133
|
+
}
|
|
134
|
+
/** The doc's live content — readable doc else null. This helper backs the face's
|
|
135
|
+
* one remaining doc read site, the revision-aware BLOCK's version token — a read
|
|
136
|
+
* fired only when the BLOCK message actually renders (the version is raw doc
|
|
137
|
+
* grammar — zero parse dependence: the revision hash is a raw-content digest).
|
|
138
|
+
* The gate's own doc read lives in the ledger (Ledger#docLineVerdict — one read
|
|
139
|
+
* per reviewGate, the shared comparison). A BLOCK render is a run-failure prose
|
|
140
|
+
* channel — never a usage face — so the read is guarded here (null on unreadable),
|
|
141
|
+
* not routed through the artifacts readText's usage error. */
|
|
142
|
+
#docContent(doc) {
|
|
143
|
+
try {
|
|
144
|
+
return readFileSync(doc, "utf8");
|
|
145
|
+
}
|
|
146
|
+
catch {
|
|
147
|
+
return null;
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
/** The doc's `v<major>.<minor>` version token — the front-matter `version:`
|
|
151
|
+
* scalar (the T6 read point: the header version facts ride the typed head
|
|
152
|
+
* record — the fence split + `yaml` engine, never a line scan). */
|
|
153
|
+
#docVersionOf(content) {
|
|
154
|
+
if (content === null)
|
|
155
|
+
return null;
|
|
156
|
+
return FrontMatterExtractor.split(content).head.version;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/face/graph-view.ts
|
|
2
|
+
// The wave-board display (the board face). The engine
|
|
3
|
+
// OWNS the layout: the derived waves (TaskGraph.batches) ARE the display's rows —
|
|
4
|
+
// one wave band per row, the band's tasks inline, the incoming source bands noted.
|
|
5
|
+
// Deterministic, always in wave order, zero third-party layout — the engine renders
|
|
6
|
+
// the node placement and the labels itself, so the board honors the wave order and
|
|
7
|
+
// survives the full plan scale.
|
|
8
|
+
//
|
|
9
|
+
// Two consumers share the report: the pre-flight refusal's blocked-dispatch hint and
|
|
10
|
+
// the board.
|
|
11
|
+
//
|
|
12
|
+
// Module-level exports are the class + the shared progress-marker vocabulary (the
|
|
13
|
+
// glyph set + the legend tails) — zero behavior-carrying bare functions.
|
|
14
|
+
/** The progress-marker glyph set — the ONE display vocabulary both the wave board
|
|
15
|
+
* (per-task markers) and the slug board (wave-level markers) render: ✔ done ·
|
|
16
|
+
* ▶ current · ○ pending. Single-sourced here so the two faces share one home,
|
|
17
|
+
* never a second declaration kept aligned by convention. */
|
|
18
|
+
export const PROGRESS_MARKERS = { done: "✔", current: "▶", pending: "○" };
|
|
19
|
+
/** The progress-marker legend tail lines — one per face scope, the scope word
|
|
20
|
+
* (`current` vs `current wave`) the ONE deliberate difference between the two
|
|
21
|
+
* boards (the graph's tasks sit inside a wave; the slug board's wave-less scopes
|
|
22
|
+
* carry no wave). The glyphs ride PROGRESS_MARKERS so the vocabulary has exactly
|
|
23
|
+
* one home. */
|
|
24
|
+
export const PROGRESS_LEGEND = {
|
|
25
|
+
board: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current · ${PROGRESS_MARKERS.pending} pending`,
|
|
26
|
+
graph: `progress: ${PROGRESS_MARKERS.done} done · ${PROGRESS_MARKERS.current} current wave · ${PROGRESS_MARKERS.pending} pending`,
|
|
27
|
+
};
|
|
28
|
+
/** GraphView — the wave-board display: one deterministic row per derived wave, the
|
|
29
|
+
* band's tasks inline with progress markers, the incoming source bands noted.
|
|
30
|
+
* v1.20 — the in-wave marker mix: the done set rides `closedWaves()` (the report's
|
|
31
|
+
* done projection, never "any ledger row"), and a current-wave task that is already
|
|
32
|
+
* done shows ✔, never a swallowed whole-row ▶. */
|
|
33
|
+
export class GraphView {
|
|
34
|
+
/** render(report, title) → the wave-board + the legend (the plan read and the
|
|
35
|
+
* pre-flight display call the same face). */
|
|
36
|
+
render(report, title) {
|
|
37
|
+
const done = new Set(report.done);
|
|
38
|
+
const currentIndex = report.waves.findIndex((wave) => wave.some((id) => !done.has(id)));
|
|
39
|
+
const markers = new Map();
|
|
40
|
+
for (const [index, wave] of report.waves.entries()) {
|
|
41
|
+
for (const id of wave) {
|
|
42
|
+
// The per-task marker, done first: a completed task shows ✔ even inside the
|
|
43
|
+
// current wave (the mix), a not-done current-wave task shows ▶, the rest ○.
|
|
44
|
+
markers.set(id, done.has(id)
|
|
45
|
+
? PROGRESS_MARKERS.done
|
|
46
|
+
: index === currentIndex
|
|
47
|
+
? PROGRESS_MARKERS.current
|
|
48
|
+
: PROGRESS_MARKERS.pending);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
const rows = report.waves
|
|
52
|
+
.map((wave, index) => {
|
|
53
|
+
const tasks = wave
|
|
54
|
+
.map((id) => `T${id}${markers.get(id) ?? PROGRESS_MARKERS.pending}`)
|
|
55
|
+
.join(" · ");
|
|
56
|
+
// find #6 (user 2026-10-09: "W1 fits the agent mindset better"): the board label = the
|
|
57
|
+
// derived wave index + 1 (W1 · W2 · …) with no zero-padding — the plan's
|
|
58
|
+
// execution-order labels reference this derived label verbatim (display
|
|
59
|
+
// layer only; the wave derivation itself is unchanged).
|
|
60
|
+
const line = ` W${index + 1} ${tasks}`;
|
|
61
|
+
return index === currentIndex ? `${line} ← in-flight` : line;
|
|
62
|
+
})
|
|
63
|
+
.join("\n");
|
|
64
|
+
return `${title}\n\nwave board:\n${rows}\n\n${PROGRESS_LEGEND.graph}`;
|
|
65
|
+
}
|
|
66
|
+
}
|