@oscaner-skills/cdd-engine 2.0.0 → 3.0.1
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/{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 +141 -0
- package/dist/face/cli.js +891 -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 +603 -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 +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/dist/infra/doc-roots.js +19 -0
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/dist/infra/root.js +62 -0
- 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 +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +8 -7
- package/templates/report/issue-body.json +0 -46
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/smoke.integration.test.ts +0 -202
- package/src-next/__tests__/zero-dep.test.ts +0 -134
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
- package/src-next/contract/__tests__/declare.test.ts +0 -242
- package/src-next/contract/__tests__/doc.test.ts +0 -358
- package/src-next/contract/__tests__/judge.test.ts +0 -873
- package/src-next/contract/__tests__/lint.test.ts +0 -314
- package/src-next/contract/__tests__/project.test.ts +0 -419
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -983
- package/src-next/contract/doc.ts +0 -753
- package/src-next/contract/invariants.ts +0 -1268
- package/src-next/contract/judge.ts +0 -142
- package/src-next/contract/lint.ts +0 -275
- package/src-next/contract/project.ts +0 -596
- package/src-next/contract/skill-anatomy.ts +0 -273
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -948
- package/src-next/face/__tests__/capsule.test.ts +0 -276
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
- package/src-next/face/__tests__/cli.test.ts +0 -4643
- 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__/negation.ts +0 -6
- package/src-next/face/__tests__/projection.test.ts +0 -301
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -195
- package/src-next/face/board-view.ts +0 -662
- package/src-next/face/capsule.ts +0 -149
- package/src-next/face/cli.ts +0 -819
- package/src-next/face/declare.ts +0 -326
- package/src-next/face/gate.ts +0 -170
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -326
- package/src-next/face/lifecycle.ts +0 -700
- package/src-next/face/projection.ts +0 -282
- package/src-next/face/route-render.ts +0 -160
- package/src-next/face/words.ts +0 -296
- package/src-next/infra/__tests__/infra.test.ts +0 -287
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -185
- package/src-next/infra/workspace.ts +0 -232
- package/src-next/render/__tests__/render.test.ts +0 -499
- package/src-next/render/__tests__/skeleton.test.ts +0 -466
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -159
- package/src-next/render/skeleton.ts +0 -437
- package/src-next/render/templates.ts +0 -650
- package/src-next/session/__tests__/graph.test.ts +0 -270
- 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 -744
- package/src-next/session/__tests__/next.test.ts +0 -368
- package/src-next/session/__tests__/preflight.test.ts +0 -491
- package/src-next/session/__tests__/run.test.ts +0 -1014
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -469
- 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 -1004
- package/src-next/session/next.ts +0 -192
- package/src-next/session/preflight.ts +0 -240
- package/src-next/session/run.ts +0 -606
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
package/src-next/session/next.ts
DELETED
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/session/next.ts
|
|
2
|
-
// T7 — NextStepRouter single point (design spec §3.2): the ONLY `next:` generation
|
|
3
|
-
// face of the new tree. The C5 decision table (the spec's pinned semantics, v1.20:
|
|
4
|
-
// the closure single-verdict — close() is the one closure point every review/fix
|
|
5
|
-
// approval shares):
|
|
6
|
-
// review zero findings → close(state) — the ready batch decides next-wave | done
|
|
7
|
-
// review findings → fix (one-way — a review never previews what a fix will do)
|
|
8
|
-
// fix blocker>0 → a re-review hop (the live tree, no commit identity)
|
|
9
|
-
// fix blocker==0 → close(state) — the warn/nit-only / clean closure (#278,
|
|
10
|
-
// no APPROVED-mandated re-review)
|
|
11
|
-
// fix soft cap → the "BLOCKED: review-cycle-cap" suggestion (user adjudicates)
|
|
12
|
-
// BLOCKED/TIMEOUT → null (no next line — the CDD_BLOCKED channel owns the face)
|
|
13
|
-
//
|
|
14
|
-
// close(state) — the v1.20 unified closure terminal: every closure point (a review
|
|
15
|
-
// with zero findings / a fix whose source blockers cleared) renders the SAME route
|
|
16
|
-
// family — `next-wave` when another wave is ready, `done` when the run is exhausted.
|
|
17
|
-
// The `none` word is RETIRED (closure is `done`, never "no suggestion"), and a
|
|
18
|
-
// completed non-failed round producing null is now a hard error on the dispatch face
|
|
19
|
-
// (no next line = abnormal) — never a silent approved-without-next.
|
|
20
|
-
//
|
|
21
|
-
// The table judges the round carrier (ledger.ts — the fix round's own findings are
|
|
22
|
-
// the source review's input, C5-1) against the execution state (state.ts — the
|
|
23
|
-
// ready batch decides next-wave vs done). The Route output carries the structured
|
|
24
|
-
// facts the capsule face renders into the `next:` line — including the fix-route
|
|
25
|
-
// readback copy, authored here once as FIX_READBACK_SUFFIX (the declared wording
|
|
26
|
-
// the capsule renders verbatim, never a literal restate).
|
|
27
|
-
//
|
|
28
|
-
// D40 — ONE "next step" concept: the face-INTERNAL C5 hop and the face-TO-face
|
|
29
|
-
// handoff are the SAME `Route` union (a `handoff` kind carries the pipeline entry),
|
|
30
|
-
// so a consumer never consults a second table. `NextStepRouter.resolve` is the ONE
|
|
31
|
-
// "one line → next" resolver: an active C5 hop passes through, a drained line yields
|
|
32
|
-
// the face-to-face handoff. Both the board (its per-line walk) and the capsule
|
|
33
|
-
// (the round's own line) call it — single resolver, single renderer.
|
|
34
|
-
//
|
|
35
|
-
// Module-level exports are types / constants / the class — zero behavior-carrying
|
|
36
|
-
// bare functions (the plan's zero-bare-function discipline).
|
|
37
|
-
|
|
38
|
-
import type { Round } from "./ledger.ts";
|
|
39
|
-
import type { ExecutionState } from "./state.ts";
|
|
40
|
-
|
|
41
|
-
/** The next-hop suggestion — the decision table's output (null = no next line). The
|
|
42
|
-
* ONE "next step" concept (D40): the face-internal C5 hops AND the face-to-face
|
|
43
|
-
* handoff are the same union, so a consumer never consults a second table. */
|
|
44
|
-
export type Route =
|
|
45
|
-
/** closure — the run is exhausted (`next: done`, the v1.20 terminal word). */
|
|
46
|
-
| { kind: "done" }
|
|
47
|
-
/** closure — another wave is ready: the next dispatch wave's task ids. */
|
|
48
|
-
| { kind: "next-wave"; tasks: string }
|
|
49
|
-
/** a review hop — a review judges the live tree, carrying no commit identity. */
|
|
50
|
-
| { kind: "review" }
|
|
51
|
-
/** the one-way fix hop — findingsPath = the review handoff the fix reads (`--findings`). */
|
|
52
|
-
| { kind: "fix"; findings?: string }
|
|
53
|
-
/** the review-cycle soft cap — the suggestion defers to user adjudication. */
|
|
54
|
-
| { kind: "soft-cap"; message: string }
|
|
55
|
-
/** the face-to-face handoff (D40) — the line's C5 frontier exhausted, so the next
|
|
56
|
-
* step is the next pipeline face's entry (`PIPELINE_NEXT[doc-class]`): the face
|
|
57
|
-
* to face transition is ONE Route kind, never a second table a consumer reads. */
|
|
58
|
-
| { kind: "handoff"; entry: PipelineEntry };
|
|
59
|
-
|
|
60
|
-
/** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
|
|
61
|
-
* defers the next hop to user adjudication (soft by nature: a default suggestion,
|
|
62
|
-
* never a hard stop — the user / Plan Sole Writer override it). */
|
|
63
|
-
export const REVIEW_CYCLE_CAP = 10;
|
|
64
|
-
|
|
65
|
-
// ---------------------------------------------------------------------------
|
|
66
|
-
// the face indirection line — the pipeline's face-to-face `done` routing table (D33)
|
|
67
|
-
// ---------------------------------------------------------------------------
|
|
68
|
-
|
|
69
|
-
/** The doc-class keys of the unified next face — one row per pipeline seam a face
|
|
70
|
-
* `done` can land on (the capsule's doc-class lookup reads them). */
|
|
71
|
-
export type PipelineKey = "phase-spec" | "overall-spec" | "plan" | "wave" | "branch";
|
|
72
|
-
|
|
73
|
-
/** One pipeline-next row — the skill ref to dispatch (`ref`), a literal command
|
|
74
|
-
* (`literal`, the wave→branch transition — the wiring literal with its `<plan>`
|
|
75
|
-
* slot), or the pipeline terminal (`done`). */
|
|
76
|
-
export type PipelineEntry =
|
|
77
|
-
| { kind: "ref"; ref: string }
|
|
78
|
-
| { kind: "literal"; literal: string }
|
|
79
|
-
| { kind: "done" };
|
|
80
|
-
|
|
81
|
-
/** The pipeline next table — the ONE face-indirection source (D33 · single-addressed
|
|
82
|
-
* at session/next.ts):
|
|
83
|
-
* the doc-class key → the next pipeline entrypoint. The skill refs ride REFS
|
|
84
|
-
* (face/host.ts) resolved per host at the render — never a hard-coded plugin
|
|
85
|
-
* spelling; the wave literal's `<plan>` slot is filled by the capsule with the
|
|
86
|
-
* frame's plan fact. */
|
|
87
|
-
export const PIPELINE_NEXT: Readonly<Record<PipelineKey, PipelineEntry>> = {
|
|
88
|
-
"phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
|
|
89
|
-
"overall-spec": { kind: "done" },
|
|
90
|
-
plan: { kind: "ref", ref: "kairos:cdd-dev" },
|
|
91
|
-
wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
|
|
92
|
-
branch: { kind: "ref", ref: "kairos:cdd-close" },
|
|
93
|
-
};
|
|
94
|
-
|
|
95
|
-
/** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
|
|
96
|
-
export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
|
|
97
|
-
|
|
98
|
-
/** The fix-route readback suffix — appended verbatim to the fix findings path on the
|
|
99
|
-
* route's `next:` render (`(confirm the findings · if a finding needs a ruling,
|
|
100
|
-
* record the ruling in the findings file)`), a pure wording prompt: the
|
|
101
|
-
* anti-blind-fix mechanical guard is the ledger round / C5-1, the suffix only
|
|
102
|
-
* reminds the orchestrator to confirm the captured findings and, when a finding
|
|
103
|
-
* needs a user ruling, record that ruling back into the findings file the fix
|
|
104
|
-
* round consumes. `annotate` names the carrier action alone — distinct from
|
|
105
|
-
* `backfill` (a durable fact landed into its owning doc), which stays the
|
|
106
|
-
* ruling's destination when it asserts a project-level fact. */
|
|
107
|
-
export const FIX_READBACK_SUFFIX =
|
|
108
|
-
"(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
|
|
109
|
-
|
|
110
|
-
/** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
|
|
111
|
-
* produces no `next:` line on any op. */
|
|
112
|
-
const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
|
|
113
|
-
|
|
114
|
-
/**
|
|
115
|
-
* NextStepRouter — the C5 decision table as one instance method. The router keeps
|
|
116
|
-
* no hidden state: every judgment reads the execution state + the round carrier.
|
|
117
|
-
*/
|
|
118
|
-
export class NextStepRouter {
|
|
119
|
-
/** next(state, ref) — the C5 derivation: the next-hop Route, or null when the round
|
|
120
|
-
* produces no next line (the BLOCKED/TIMEOUT failure-mode face). */
|
|
121
|
-
next(state: ExecutionState, ref: Round): Route | null {
|
|
122
|
-
// The failure face first — a BLOCKED/TIMEOUT round never gets a next suggestion.
|
|
123
|
-
if (ref.status !== undefined && FAILED_STATUS.has(ref.status)) return null;
|
|
124
|
-
|
|
125
|
-
switch (ref.phase) {
|
|
126
|
-
case "implement":
|
|
127
|
-
// The implement round completes → the group's review is the next hop. A
|
|
128
|
-
// review judges the live tree, so the hop carries no commit identity.
|
|
129
|
-
return { kind: "review" };
|
|
130
|
-
case "review":
|
|
131
|
-
// One-way: any findings (any severity) → the fix round — a review never previews
|
|
132
|
-
// what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
|
|
133
|
-
// ready batch decides whether the next wave continues or the run is exhausted.
|
|
134
|
-
if (ref.findings.length > 0) return { kind: "fix", findings: ref.findingsPath };
|
|
135
|
-
return this.#close(state);
|
|
136
|
-
case "fix": {
|
|
137
|
-
// C5-1: the fix face is the re-review / closure decision point. The soft cap
|
|
138
|
-
// outranks the blocker row — a capped run defers to the user, never auto-loops.
|
|
139
|
-
if (ref.consecutiveS1 >= REVIEW_CYCLE_CAP) {
|
|
140
|
-
return { kind: "soft-cap", message: SOFT_CAP_SUGGESTION };
|
|
141
|
-
}
|
|
142
|
-
if (this.#blockerCount(ref) > 0) {
|
|
143
|
-
// Blockers remain in the input findings → the fix delta is re-reviewed. A
|
|
144
|
-
// review judges the live tree, so the hop carries no commit identity.
|
|
145
|
-
return { kind: "review" };
|
|
146
|
-
}
|
|
147
|
-
// No blockers → the unified closure: the ready batch decides next-wave | done
|
|
148
|
-
// (a warn/nit-only fix closes — the #278 REVIEW_FIX state, no re-review preview).
|
|
149
|
-
return this.#close(state);
|
|
150
|
-
}
|
|
151
|
-
case "branch-review":
|
|
152
|
-
// The branch terminal face — findings route the fix; zero findings close the line
|
|
153
|
-
// through the same unified closure terminal.
|
|
154
|
-
return ref.findings.length > 0
|
|
155
|
-
? { kind: "fix", findings: ref.findingsPath }
|
|
156
|
-
: this.#close(state);
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
|
|
160
|
-
/** The unified closure terminal (v1.20) — the single way a review/fix closure renders
|
|
161
|
-
* its next hop: the ready batch decides `next-wave` vs `done` (a closing review with
|
|
162
|
-
* another wave ready continues the run; an exhausted run reports `done`). */
|
|
163
|
-
#close(state: ExecutionState): Route {
|
|
164
|
-
const ready = state.readyBatch();
|
|
165
|
-
return ready.length > 0 ? { kind: "next-wave", tasks: ready.join(",") } : { kind: "done" };
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
/** The blocker count of the round's findings — the C5-1 severity count. */
|
|
169
|
-
#blockerCount(ref: Round): number {
|
|
170
|
-
return ref.findings.filter((finding) => finding.severity === "blocker").length;
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
/** The face-to-face handoff route for a pipeline doc-class (D40) — the next-face
|
|
174
|
-
* entry (`PIPELINE_NEXT[key]`). One of the two ways the ONE "next step" concept
|
|
175
|
-
* is produced (the C5 hop is the other), so a consumer never consults a second
|
|
176
|
-
* table. */
|
|
177
|
-
static handoff(key: PipelineKey): Route {
|
|
178
|
-
return { kind: "handoff", entry: PIPELINE_NEXT[key] };
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
/** Resolve a line's next step (D40) — the single "one line → next" point shared by
|
|
182
|
-
* the board (its per-line walk) and the capsule (the round's own line). An ACTIVE
|
|
183
|
-
* C5 hop (`review` / `fix` / `implement` / `next-wave` / `soft-cap`) passes through
|
|
184
|
-
* as the line's next step; a drained or not-yet-started line (the C5 `done` / no
|
|
185
|
-
* active round) yields the face-to-face handoff carrying the pipeline entry. A null
|
|
186
|
-
* doc-class (no face seam — the overall line / a bare terminal) rerenders the bare
|
|
187
|
-
* `done` word. Pure — the callers hold their own line facts. */
|
|
188
|
-
static resolve(active: Route | null, key: PipelineKey | null): Route {
|
|
189
|
-
if (active !== null && active.kind !== "done") return active;
|
|
190
|
-
return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
|
|
191
|
-
}
|
|
192
|
-
}
|
|
@@ -1,240 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/session/preflight.ts
|
|
2
|
-
// P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the dispatch gates
|
|
3
|
-
// converge into ONE single-entry gate a work command consults before ANY child
|
|
4
|
-
// dispatch — the clean-tree hard gate (tree-clean → BLOCKED with the commit/discard
|
|
5
|
-
// guidance, the skill-side claim `engine entry gate: dirty → BLOCKED` finally made
|
|
6
|
-
// real), then the wave-side gates (graph validate + the three-verb WaveGate)
|
|
7
|
-
// and the doc-side gate (Contract.validate over the target doc).
|
|
8
|
-
//
|
|
9
|
-
// Gate order (the design's pinned sequence, judgeable on every verdict):
|
|
10
|
-
// tree-clean → (wave/plan faces) graph validate → (wave face) WaveGate.vet →
|
|
11
|
-
// (spec/plan faces) Contract.validate → dispatch
|
|
12
|
-
// The evidence/read-back gates stay at the dispatch child face (the seam never
|
|
13
|
-
// touches the round's produced artifacts — non-pre-flight by design).
|
|
14
|
-
//
|
|
15
|
-
// The verdict is the single BLOCK carrier: `gate` names the refusing gate, `reason`
|
|
16
|
-
// the named refusal row, `message` the CDD_BLOCKED wording (pinned rows), `details`
|
|
17
|
-
// the named issue/finding lines the renderer prints, `order` the gates that ran
|
|
18
|
-
// (the CLI never re-implements a gate — the seam owns the whole sequence). BLOCK
|
|
19
|
-
// wording rides the word table (the capsule station + the preflight rows), never a
|
|
20
|
-
// CLI restate.
|
|
21
|
-
//
|
|
22
|
-
// Module-level exports are types / the class — zero behavior-carrying bare
|
|
23
|
-
// functions (the plan's zero-bare-function discipline).
|
|
24
|
-
|
|
25
|
-
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
26
|
-
import { PlanDocType } from "../contract/doc.ts";
|
|
27
|
-
import type { DocFs } from "../contract/invariants.ts";
|
|
28
|
-
import type { Contract } from "../contract/judge.ts";
|
|
29
|
-
import type { DocKey } from "../contract/project.ts";
|
|
30
|
-
import type { Words } from "../face/words.ts";
|
|
31
|
-
import type { GitClient } from "../infra/git.ts";
|
|
32
|
-
import type { TargetType } from "./faces.ts";
|
|
33
|
-
import { TaskGraph } from "./graph.ts";
|
|
34
|
-
import type { Ledger } from "./ledger.ts";
|
|
35
|
-
import { WaveGate } from "./wave.ts";
|
|
36
|
-
|
|
37
|
-
/** The named gates the seam composes — the run evidence + the blocking gate label. */
|
|
38
|
-
export type PreFlightGateName = "tree-clean" | "graph" | "wave" | "doc-contract";
|
|
39
|
-
|
|
40
|
-
/** The named refusal rows — the BLOCK reason the CDD_BLOCKED wording fills. */
|
|
41
|
-
export type PreFlightReason = "dirty-tree" | "graph" | "split" | "wrong-phase" | "doc-contract";
|
|
42
|
-
|
|
43
|
-
/** One pre-flight verdict — the single BLOCK carrier of the dispatch gates. */
|
|
44
|
-
export interface PreFlightVerdict {
|
|
45
|
-
/** Whether the dispatch is approved (the gates passed). */
|
|
46
|
-
ok: boolean;
|
|
47
|
-
/** The refusing gate (absent when ok — no gate blocked). */
|
|
48
|
-
gate?: PreFlightGateName;
|
|
49
|
-
/** The named refusal row (absent when ok). */
|
|
50
|
-
reason?: PreFlightReason;
|
|
51
|
-
/** The rendered BLOCK wording — the CDD_BLOCKED channel carries it (word-table
|
|
52
|
-
* rows + the WaveGate verdict's own filled rows). */
|
|
53
|
-
message?: string;
|
|
54
|
-
/** The named issue/finding lines the renderer prints under the message. */
|
|
55
|
-
details?: readonly string[];
|
|
56
|
-
/** The gates that ran, in order — the judgeable order (tree-clean → graph →
|
|
57
|
-
* wave → doc-contract, per the face's applicable set). */
|
|
58
|
-
order: readonly PreFlightGateName[];
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
/** The doc-contract target of a spec/plan dispatch. */
|
|
62
|
-
export interface PreFlightDoc {
|
|
63
|
-
/** The target doc type's registry key — read from the doc's `- **Doc type**:`
|
|
64
|
-
* header declaration (spec §12 · D34; both the spec and the plan faces key by
|
|
65
|
-
* the declaration, zero command-type carve-out).
|
|
66
|
-
* null when a present doc carries no declaration — the seam BLOCKs (zero
|
|
67
|
-
* filename-suffix fallback, one declaration reading face `BoardView.readDocType`). */
|
|
68
|
-
docKey: DocKey | null;
|
|
69
|
-
/** The target doc's path (the lifecycle's audit path). */
|
|
70
|
-
path: string;
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
/** One dispatch's pre-flight inputs — the facts the seam judges. */
|
|
74
|
-
export interface PreFlightContext {
|
|
75
|
-
/** The requested dispatch verb (the three work verbs — the WaveGate's verb). */
|
|
76
|
-
verb: "implement" | "review" | "fix";
|
|
77
|
-
/** The dispatch's target type (wave / branch / spec / plan). */
|
|
78
|
-
type: TargetType;
|
|
79
|
-
/** The repo root the tree-clean gate reads. */
|
|
80
|
-
repoRoot: string;
|
|
81
|
-
/** The plan text (the wave/plan faces' graph gate input; null otherwise). */
|
|
82
|
-
planText: string | null;
|
|
83
|
-
/** The requested `--tasks` group (the wave face's WaveGate input). */
|
|
84
|
-
tasks: ReadonlySet<number> | null;
|
|
85
|
-
/** The session ledger (the wave face's WaveGate input). */
|
|
86
|
-
ledger: Ledger | null;
|
|
87
|
-
/** The doc-contract target of a spec/plan dispatch (null on the other faces). */
|
|
88
|
-
doc: PreFlightDoc | null;
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
/**
|
|
92
|
-
* PreFlight — the single pre-flight seam of the work dispatch. One `vet` call runs
|
|
93
|
-
* the whole gate sequence in the pinned order and returns the verdict the CLI
|
|
94
|
-
* renders (or approves): the seam owns the gates, the CLI only orchestrates the
|
|
95
|
-
* call + the render — zero second implementation on the CLI face.
|
|
96
|
-
*/
|
|
97
|
-
export class PreFlight {
|
|
98
|
-
/** The git seam the tree-clean gate reads. */
|
|
99
|
-
readonly #git: GitClient;
|
|
100
|
-
/** The doc-contract coordinator the doc faces judge through. */
|
|
101
|
-
readonly #contract: Contract;
|
|
102
|
-
/** The three-verb unified wave gate the wave face consults. */
|
|
103
|
-
readonly #waveGate: WaveGate;
|
|
104
|
-
/** The word table the BLOCK wording rides. */
|
|
105
|
-
readonly #words: Words;
|
|
106
|
-
/** The filesystem seam the doc-contract gate reads (defaults to node:fs). */
|
|
107
|
-
readonly #fs: DocFs;
|
|
108
|
-
|
|
109
|
-
constructor(opts: {
|
|
110
|
-
git: GitClient;
|
|
111
|
-
contract: Contract;
|
|
112
|
-
words: Words;
|
|
113
|
-
waveGate?: WaveGate;
|
|
114
|
-
fs?: DocFs;
|
|
115
|
-
}) {
|
|
116
|
-
this.#git = opts.git;
|
|
117
|
-
this.#contract = opts.contract;
|
|
118
|
-
this.#words = opts.words;
|
|
119
|
-
this.#waveGate = opts.waveGate ?? new WaveGate();
|
|
120
|
-
this.#fs = opts.fs ?? new NodeFs();
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
/** vet(ctx) — the single seam call: tree-clean → graph → wave → doc-contract.
|
|
124
|
-
* The first refused gate owns the verdict; the gates that ran precede it (the
|
|
125
|
-
* judgeable order). */
|
|
126
|
-
async vet(ctx: PreFlightContext): Promise<PreFlightVerdict> {
|
|
127
|
-
const gates: PreFlightGateName[] = [];
|
|
128
|
-
// 1. tree-clean — the hard gate all three verbs share: a dirty working tree
|
|
129
|
-
// BLOCKs BEFORE any other judgment (review's baseline = the committed state). isClean is
|
|
130
|
-
// fail-open-false (a non-repo counts dirty — the CDD flow needs git).
|
|
131
|
-
gates.push("tree-clean");
|
|
132
|
-
if (!(await this.#git.isClean(ctx.repoRoot))) {
|
|
133
|
-
return {
|
|
134
|
-
ok: false,
|
|
135
|
-
gate: "tree-clean",
|
|
136
|
-
reason: "dirty-tree",
|
|
137
|
-
message: this.#words.preflightWords().dirtyTree,
|
|
138
|
-
order: gates,
|
|
139
|
-
};
|
|
140
|
-
}
|
|
141
|
-
// 2. graph — the wave/plan faces' structural gate: the plan's DependsOn
|
|
142
|
-
// graph must validate (missing-edge / missing-id / self-loop / cycle) before
|
|
143
|
-
// the dispatch reads it. The task-loss class dies here, never silently.
|
|
144
|
-
let graph: TaskGraph | null = null;
|
|
145
|
-
if ((ctx.type === "wave" || ctx.type === "plan") && ctx.planText !== null) {
|
|
146
|
-
gates.push("graph");
|
|
147
|
-
graph = new TaskGraph(new PlanDocType("plan").parse(ctx.planText.split("\n")));
|
|
148
|
-
const issues = graph.validate();
|
|
149
|
-
if (issues.length > 0) {
|
|
150
|
-
return {
|
|
151
|
-
ok: false,
|
|
152
|
-
gate: "graph",
|
|
153
|
-
reason: "graph",
|
|
154
|
-
message: this.#words.preflightWords().graph.replace("{count}", String(issues.length)),
|
|
155
|
-
details: issues.map((issue) => `${issue.kind}@T${issue.task}: ${issue.message}`),
|
|
156
|
-
order: gates,
|
|
157
|
-
};
|
|
158
|
-
}
|
|
159
|
-
}
|
|
160
|
-
// 3. wave — the three-verb unified wave gate (the task face's phase authority):
|
|
161
|
-
// the requested `--tasks` must be EXACTLY the derived open wave at the verb's
|
|
162
|
-
// phase. The refusal wording rides the wave-gate word-table rows.
|
|
163
|
-
if (ctx.type === "wave" && graph !== null && ctx.ledger !== null && ctx.tasks !== null) {
|
|
164
|
-
gates.push("wave");
|
|
165
|
-
const verdict = this.#waveGate.vet(ctx.tasks, ctx.verb, graph, ctx.ledger, this.#words);
|
|
166
|
-
if (!verdict.ok) {
|
|
167
|
-
return {
|
|
168
|
-
ok: false,
|
|
169
|
-
gate: "wave",
|
|
170
|
-
reason: verdict.reason,
|
|
171
|
-
message: verdict.message ?? "",
|
|
172
|
-
order: gates,
|
|
173
|
-
};
|
|
174
|
-
}
|
|
175
|
-
}
|
|
176
|
-
// 4. doc-contract — the doc faces' structural gate: the target doc must pass
|
|
177
|
-
// Contract.validate (the interpreter's single judgment entry) before its
|
|
178
|
-
// review/fix round dispatches. An unreadable doc carries no judgment (no
|
|
179
|
-
// fabricated findings from an absent surface). A PRESENT doc carrying no
|
|
180
|
-
// `- **Doc type**:` declaration BLOCKs (spec §12 · D34: the declared type is
|
|
181
|
-
// the one reading face, zero filename-suffix fallback).
|
|
182
|
-
if (ctx.type === "spec" || ctx.type === "plan") {
|
|
183
|
-
gates.push("doc-contract");
|
|
184
|
-
const doc = ctx.doc;
|
|
185
|
-
const content = doc === null ? null : this.#fs.read(doc.path);
|
|
186
|
-
if (content !== null && doc !== null) {
|
|
187
|
-
if (doc.docKey === null) {
|
|
188
|
-
return {
|
|
189
|
-
ok: false,
|
|
190
|
-
gate: "doc-contract",
|
|
191
|
-
reason: "doc-contract",
|
|
192
|
-
message: this.#words.routeWord("docType"),
|
|
193
|
-
order: gates,
|
|
194
|
-
};
|
|
195
|
-
}
|
|
196
|
-
const findings = this.#contract.validate({
|
|
197
|
-
docKey: doc.docKey,
|
|
198
|
-
path: doc.path,
|
|
199
|
-
content,
|
|
200
|
-
root: ctx.repoRoot,
|
|
201
|
-
fs: this.#fs,
|
|
202
|
-
});
|
|
203
|
-
if (findings.length > 0) {
|
|
204
|
-
return {
|
|
205
|
-
ok: false,
|
|
206
|
-
gate: "doc-contract",
|
|
207
|
-
reason: "doc-contract",
|
|
208
|
-
message: this.#words.preflightWords().docContract,
|
|
209
|
-
details: findings.map(
|
|
210
|
-
(finding) => `${finding.kind}@${finding.field}: ${finding.message}`,
|
|
211
|
-
),
|
|
212
|
-
order: gates,
|
|
213
|
-
};
|
|
214
|
-
}
|
|
215
|
-
}
|
|
216
|
-
}
|
|
217
|
-
return { ok: true, order: gates };
|
|
218
|
-
}
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
/** The node:fs default — the production seam for the doc-contract's file reads. */
|
|
222
|
-
class NodeFs implements DocFs {
|
|
223
|
-
read(p: string): string | null {
|
|
224
|
-
try {
|
|
225
|
-
return readFileSync(p, "utf8");
|
|
226
|
-
} catch {
|
|
227
|
-
return null;
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
exists(p: string): boolean {
|
|
231
|
-
return existsSync(p);
|
|
232
|
-
}
|
|
233
|
-
list(p: string): readonly string[] {
|
|
234
|
-
try {
|
|
235
|
-
return readdirSync(p);
|
|
236
|
-
} catch {
|
|
237
|
-
return [];
|
|
238
|
-
}
|
|
239
|
-
}
|
|
240
|
-
}
|