@oscaner-skills/cdd-engine 4.11.0 → 4.13.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 +22 -0
- package/README.zh-CN.md +22 -0
- package/dist/contract/doc.js +24 -0
- package/dist/contract/invariants.js +11 -6
- package/dist/contract/judge.js +45 -4
- package/dist/contract/project.js +12 -1
- package/dist/contract/task-block-grammar.js +3 -1
- package/dist/face/artifacts.js +13 -4
- package/dist/face/board-view.js +475 -105
- package/dist/face/cli.js +336 -110
- package/dist/face/declare.js +10 -6
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +142 -115
- package/dist/face/preview.js +9 -0
- package/dist/face/route-render.js +23 -7
- package/dist/face/words.js +97 -0
- package/dist/infra/carrier-seal.js +47 -24
- package/dist/infra/plan-source.js +461 -0
- package/dist/infra/slug-index.js +58 -27
- package/dist/infra/workspace.js +19 -1
- package/dist/render/brief.js +34 -32
- package/dist/render/templates.js +11 -2
- package/dist/session/artifact-reads.js +108 -0
- package/dist/session/carrier-rulings.js +98 -45
- package/dist/session/dispatch-authority.js +3 -4
- package/dist/session/inflight.js +5 -2
- package/dist/session/ledger.js +203 -241
- package/dist/session/next.js +62 -15
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +60 -32
- package/dist/session/round-artifacts.js +635 -0
- package/dist/session/round-naming.js +16 -81
- package/dist/session/run.js +57 -53
- package/package.json +1 -1
package/dist/session/next.js
CHANGED
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
// Module-level exports are types / constants / the class — zero behavior-carrying
|
|
37
37
|
// bare functions (the plan's zero-bare-function discipline).
|
|
38
38
|
var _a;
|
|
39
|
+
import path from "node:path";
|
|
39
40
|
/** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
|
|
40
41
|
* defers the next hop to user adjudication (soft by nature: a default suggestion,
|
|
41
42
|
* never a hard stop — the user / the plan write authority override it). */
|
|
@@ -133,17 +134,20 @@ export const NEXT_HOP_REASON = {
|
|
|
133
134
|
};
|
|
134
135
|
/** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
|
|
135
136
|
export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
|
|
136
|
-
/** The fix
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
*
|
|
143
|
-
* `
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
|
|
137
|
+
/** The value slot of the fix readback sentence — the rendered sidecar path the route
|
|
138
|
+
* carries (`Route.rulings`). The sentence is FIXED bytes and the path is a VALUE, so
|
|
139
|
+
* the render face fills a slot instead of deriving a name (§2.10 · §2.6's "the render
|
|
140
|
+
* plane holds no name rule"). */
|
|
141
|
+
export const FIX_READBACK_SLOT = "<rendered sidecar path>";
|
|
142
|
+
/** The fix-route readback suffix — appended to the fix findings path on the route's
|
|
143
|
+
* `next:` render, with the sidecar path filled into `FIX_READBACK_SLOT`:
|
|
144
|
+
* `(confirm the reviews handoff · if a finding needs a ruling, record it at
|
|
145
|
+
* <rendered sidecar path>)`. A RESULT sentence, never a naming rule: the old wording
|
|
146
|
+
* taught the `.json` → `.rulings.json` transformation, which is the very second
|
|
147
|
+
* expression this phase retires (§2.8 · issue ④). The path arrives from the route (the
|
|
148
|
+
* router renders it from the CARRIER's identity), so no reader of this constant derives
|
|
149
|
+
* a name from it. A carrier with no round identity renders no suffix at all. */
|
|
150
|
+
export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record it at <rendered sidecar path>)";
|
|
147
151
|
/** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
|
|
148
152
|
* produces no `next:` line on any op. Exported as the ONE failure-status set: the
|
|
149
153
|
* skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
|
|
@@ -155,6 +159,21 @@ export const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
|
|
|
155
159
|
* no hidden state: every judgment reads the execution state + the round carrier.
|
|
156
160
|
*/
|
|
157
161
|
export class NextStepRouter {
|
|
162
|
+
/** The artifact matrix this router holds — the composition root's single instance,
|
|
163
|
+
* handed down so the readback face renders the SAME name the dispatch gate judges
|
|
164
|
+
* (the router itself derives no name). `null` — a hermetic caller — means the fix
|
|
165
|
+
* hop carries no `rulings` value: a router without a matrix cannot render a name and
|
|
166
|
+
* must not invent one. */
|
|
167
|
+
#artifacts;
|
|
168
|
+
/** `artifacts` is the composition root's matrix, OPTIONAL here — unlike
|
|
169
|
+
* `CliLifecycle#artifacts`, which is required because a wiring bug there would read as
|
|
170
|
+
* a legal `absent` carrier. A hermetic caller passing `null` loses exactly one
|
|
171
|
+
* decorative cell (the fix hop's read-back hint, omitted whole — never printed empty),
|
|
172
|
+
* and no judgment becomes a visible `absent` through it. Production passes the single
|
|
173
|
+
* instance. */
|
|
174
|
+
constructor(artifacts) {
|
|
175
|
+
this.#artifacts = artifacts ?? null;
|
|
176
|
+
}
|
|
158
177
|
/** next(state, ref) — the C5 derivation: the next-hop Route, or null when the round
|
|
159
178
|
* produces no next line (the BLOCKED/TIMEOUT failure-mode face). */
|
|
160
179
|
next(state, ref) {
|
|
@@ -171,7 +190,7 @@ export class NextStepRouter {
|
|
|
171
190
|
// what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
|
|
172
191
|
// ready batch decides whether the next wave continues or the run is exhausted.
|
|
173
192
|
if (ref.findings.length > 0)
|
|
174
|
-
return
|
|
193
|
+
return this.#fixRoute(ref);
|
|
175
194
|
return this.#close(state);
|
|
176
195
|
case "fix": {
|
|
177
196
|
// C5-1: the fix face is the re-review / closure decision point. The soft cap
|
|
@@ -191,11 +210,39 @@ export class NextStepRouter {
|
|
|
191
210
|
case "branch-review":
|
|
192
211
|
// The branch terminal face — findings route the fix; zero findings close the line
|
|
193
212
|
// through the same unified closure terminal.
|
|
194
|
-
return ref.findings.length > 0
|
|
195
|
-
? { kind: "fix", reviews: ref.reviewsPath }
|
|
196
|
-
: this.#close(state);
|
|
213
|
+
return ref.findings.length > 0 ? this.#fixRoute(ref) : this.#close(state);
|
|
197
214
|
}
|
|
198
215
|
}
|
|
216
|
+
/** The one-way fix hop — the carrier the fix reads plus the ruling sidecar's RESOLVED
|
|
217
|
+
* path beside it. The path's name comes from the CARRIER's identity
|
|
218
|
+
* (`attribute(basename(carrier))` with `op` fixed to `review`), never from this fix
|
|
219
|
+
* round's `(line, op)` and never from a tail replacement on the handoff's own
|
|
220
|
+
* spelling: `plan-review-1-a1.json` renders `plan-review-1.c1.rulings.json`. A carrier
|
|
221
|
+
* the matrix cannot place (a P34-era legacy spelling) leaves the value absent, and the
|
|
222
|
+
* render face then omits the readback sentence whole. */
|
|
223
|
+
#fixRoute(ref) {
|
|
224
|
+
const reviews = ref.reviewsPath;
|
|
225
|
+
const rulings = this.#rulingsOf(reviews);
|
|
226
|
+
return {
|
|
227
|
+
kind: "fix",
|
|
228
|
+
...(reviews === undefined ? {} : { reviews }),
|
|
229
|
+
...(rulings === null ? {} : { rulings }),
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
/** The sidecar path beside one carrier — the matrix's `rulings` render of the carrier's
|
|
233
|
+
* own round identity, resolved in the carrier's OWN directory (the same coordinate the
|
|
234
|
+
* dispatch gate prints as `derived:`). The identity itself comes from the matrix's ONE
|
|
235
|
+
* entry (`ArtifactRegistry#reviewedIdentityOf`), so the `op: "review"` construction
|
|
236
|
+
* this router used to spell has one home. Null when the router holds no matrix or the
|
|
237
|
+
* name attributes to no round identity. */
|
|
238
|
+
#rulingsOf(carrier) {
|
|
239
|
+
if (this.#artifacts === null || carrier === undefined)
|
|
240
|
+
return null;
|
|
241
|
+
const identity = this.#artifacts.reviewedIdentityOf(carrier);
|
|
242
|
+
if (identity === null)
|
|
243
|
+
return null;
|
|
244
|
+
return path.join(path.dirname(carrier), this.#artifacts.render(identity, "rulings"));
|
|
245
|
+
}
|
|
199
246
|
/** The unified closure terminal (v1.20) — the single way a review/fix closure renders
|
|
200
247
|
* its next hop: the ready batch decides `next-wave` vs `done` (a closing review with
|
|
201
248
|
* another wave ready continues the run; an exhausted run reports `done`). */
|
package/dist/session/pipeline.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
//
|
|
13
13
|
// Constructed with the node's `Ledger` (the `Ledger` / `Lifecycle` shape: one read
|
|
14
14
|
// face injected, no global state). The plan is never read here — the guarded plan
|
|
15
|
-
// read stays on the board side and rides in as `
|
|
15
|
+
// read stays on the board side and rides in as `plan`, so this module holds
|
|
16
16
|
// zero file-system read and no second plan parse.
|
|
17
17
|
//
|
|
18
18
|
// The four rules over the ONE `PIPELINE_FACES` order:
|
|
@@ -172,7 +172,7 @@ export class PipelineFrontier {
|
|
|
172
172
|
* alone would fall into rule 2 and render the wave face's own exit
|
|
173
173
|
* (`PIPELINE_NEXT.wave`), a worse literal than the one being removed. */
|
|
174
174
|
#waveState(input) {
|
|
175
|
-
const graph = input.
|
|
175
|
+
const graph = input.plan.graph();
|
|
176
176
|
const waveKey = graph === null ? null : this.#waveKeyOf(graph);
|
|
177
177
|
const entered = graph !== null && this.#wavesEntered(graph);
|
|
178
178
|
return {
|
|
@@ -3,15 +3,21 @@
|
|
|
3
3
|
// converge into ONE single-entry gate a work command consults before ANY child
|
|
4
4
|
// dispatch — the clean-tree hard gate (tree-clean → BLOCKED with the commit/discard
|
|
5
5
|
// guidance, the skill-side claim `engine entry gate: dirty → BLOCKED` finally made
|
|
6
|
-
// real), then the in-flight gate, the plan
|
|
7
|
-
// §3
|
|
8
|
-
//
|
|
9
|
-
//
|
|
10
|
-
//
|
|
6
|
+
// real), then the in-flight gate, the plan read's own structure refusal (the
|
|
7
|
+
// un-gated plan-carrier leg, P35 §2.3), the graph validate, the plan/ledger
|
|
8
|
+
// structure gate (`plan-ledger`, P21 §3.1/§6.4) and the doc-side gate
|
|
9
|
+
// (Contract.validate over the target doc). The dispatch's own phase — the wave
|
|
10
|
+
// face's gate and the doc/branch line's — is NOT judged here: it belongs to the ONE
|
|
11
|
+
// dispatch authority (`session/dispatch-authority.ts`, P27 §2), the seam's single
|
|
12
|
+
// consumer.
|
|
11
13
|
//
|
|
12
14
|
// Gate order (the design's pinned sequence, judgeable on every verdict):
|
|
13
|
-
// tree-clean → in-flight → graph → plan-ledger →
|
|
15
|
+
// tree-clean → in-flight → plan-carrier → graph → plan-ledger →
|
|
14
16
|
// (spec/plan faces) Contract.validate → dispatch
|
|
17
|
+
// The plan-carrier leg is the readable plan's OWN refusal (P35 §2.3): an UN-GATED
|
|
18
|
+
// judgment over `ctx.plan` — not a row of the doc-shape block — so the wave face
|
|
19
|
+
// (no doc target, `ctx.doc === null`) is judged too. It speaks the existing
|
|
20
|
+
// `doc-contract` gate id and reason token, so no token joins the table.
|
|
15
21
|
// The evidence/read-back gates stay at the dispatch child face (the seam never
|
|
16
22
|
// touches the round's produced artifacts — non-pre-flight by design).
|
|
17
23
|
//
|
|
@@ -25,7 +31,6 @@
|
|
|
25
31
|
//
|
|
26
32
|
// Module-level exports are types / the class — zero behavior-carrying bare
|
|
27
33
|
// functions (the plan's zero-bare-function discipline).
|
|
28
|
-
import { PlanDocType } from "../contract/doc.js";
|
|
29
34
|
import { FrontMatterExtractor } from "../contract/frontmatter.js";
|
|
30
35
|
import { LedgerTaskSetRule, NodeFs } from "../contract/invariants.js";
|
|
31
36
|
import { Contract } from "../contract/judge.js";
|
|
@@ -55,9 +60,9 @@ export class PreFlight {
|
|
|
55
60
|
this.#words = opts.words;
|
|
56
61
|
this.#fs = opts.fs ?? new NodeFs();
|
|
57
62
|
}
|
|
58
|
-
/** vet(ctx) — the single seam call: tree-clean → in-flight →
|
|
59
|
-
* → doc-contract. The first refused gate owns the verdict; the gates
|
|
60
|
-
* precede it (the judgeable order). */
|
|
63
|
+
/** vet(ctx) — the single seam call: tree-clean → in-flight → plan-carrier → graph
|
|
64
|
+
* → plan-ledger → doc-contract. The first refused gate owns the verdict; the gates
|
|
65
|
+
* that ran precede it (the judgeable order). */
|
|
61
66
|
async vet(ctx) {
|
|
62
67
|
const gates = [];
|
|
63
68
|
const checked = [];
|
|
@@ -89,24 +94,47 @@ export class PreFlight {
|
|
|
89
94
|
holding: inFlight,
|
|
90
95
|
}, gates, checked, this.#docOutcomeOf(ctx), { kind: "no-ledger-facts" });
|
|
91
96
|
}
|
|
92
|
-
// 3.
|
|
97
|
+
// 3. plan-carrier — the plan READ's own structure judgment (P35 §2.3): every face
|
|
98
|
+
// that carries a plan read (wave / plan / branch) asks the value whether the
|
|
99
|
+
// document it read may be dispatched. The source is `ctx.plan`, never `ctx.doc`
|
|
100
|
+
// — the wave face reaches this point with no doc target at all. The `io` cause
|
|
101
|
+
// never asks this leg: the scene stops at the usage seam before any workspace
|
|
102
|
+
// key exists, so only `syntax` and the `spec-absent` orphan arrive here.
|
|
103
|
+
if (ctx.type === "wave" || ctx.type === "plan" || ctx.type === "branch") {
|
|
104
|
+
const refusal = ctx.plan.refusal(this.#words);
|
|
105
|
+
if (refusal !== null) {
|
|
106
|
+
// The plan face's own gate set already holds `doc-contract`, so its refusal
|
|
107
|
+
// accounts for the gate it PLANNED to run; the wave / branch faces never
|
|
108
|
+
// planned it and must not claim they did.
|
|
109
|
+
if (ctx.type === "plan") {
|
|
110
|
+
gates.push("doc-contract");
|
|
111
|
+
checked.push("doc-contract");
|
|
112
|
+
}
|
|
113
|
+
return this.#refusal({ ok: false, gate: refusal.gate, reason: refusal.reason, message: refusal.message }, gates, checked, this.#docOutcomeOf(ctx), { kind: "no-ledger-facts" });
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
// 4. graph — the wave/plan faces' structural gate, on a READY plan only: a
|
|
117
|
+
// non-ready read never enters the gate plan, so the row is neither pushed nor
|
|
118
|
+
// reported (`checked`'s byte set stays the healthy one).
|
|
93
119
|
let graph = null;
|
|
94
|
-
if ((ctx.type === "wave" || ctx.type === "plan") && ctx.
|
|
120
|
+
if ((ctx.type === "wave" || ctx.type === "plan") && ctx.plan.kind === "ready") {
|
|
95
121
|
gates.push("graph");
|
|
96
122
|
checked.push("graph");
|
|
97
|
-
graph =
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
123
|
+
graph = ctx.plan.graph();
|
|
124
|
+
if (graph !== null) {
|
|
125
|
+
const issues = graph.validate();
|
|
126
|
+
if (issues.length > 0) {
|
|
127
|
+
return this.#refusal({
|
|
128
|
+
ok: false,
|
|
129
|
+
gate: "graph",
|
|
130
|
+
reason: "graph",
|
|
131
|
+
message: this.#words.preflightWords().graph.replace("{count}", String(issues.length)),
|
|
132
|
+
details: issues.map((issue) => `${issue.kind}@T${issue.task}: ${issue.message}`),
|
|
133
|
+
}, gates, checked, this.#docOutcomeOf(ctx), { kind: "no-ledger-facts" });
|
|
134
|
+
}
|
|
107
135
|
}
|
|
108
136
|
}
|
|
109
|
-
//
|
|
137
|
+
// 5. plan-ledger — the ledger-scope rules (P21 §3.1/§6.4). Plan / wave / branch
|
|
110
138
|
// dispatches run it; the doc-scope rules never do (two scopes, two entries).
|
|
111
139
|
// A missing fact bundle is NOT a refusal: the rows render `skipped`.
|
|
112
140
|
let ledgerOutcome = { kind: "no-ledger-facts" };
|
|
@@ -133,7 +161,7 @@ export class PreFlight {
|
|
|
133
161
|
}
|
|
134
162
|
}
|
|
135
163
|
}
|
|
136
|
-
//
|
|
164
|
+
// 6. doc-contract — the doc shapes' structural gate (the doc-scope rules).
|
|
137
165
|
// The four document shapes (`phase-spec` · `overall` · `plan` · `single-spec`)
|
|
138
166
|
// are judged by the SAME gate: the document's declared `doc-type:` picks the
|
|
139
167
|
// contract, never the command's `--type` spelling.
|
|
@@ -308,16 +336,16 @@ export class PreFlight {
|
|
|
308
336
|
}
|
|
309
337
|
return rows;
|
|
310
338
|
}
|
|
311
|
-
/** The ledger fact bundle of one dispatch — built from the ledger, the plan
|
|
312
|
-
* and the plan's topological layers. Null when either fact source is absent
|
|
313
|
-
*
|
|
339
|
+
/** The ledger fact bundle of one dispatch — built from the ledger, the plan read
|
|
340
|
+
* and the plan's topological layers. Null when either fact source is absent (the
|
|
341
|
+
* gate then renders `skipped (no ledger facts)`). */
|
|
314
342
|
#ledgerFactsOf(ctx, graph) {
|
|
315
343
|
const ledger = ctx.ledger;
|
|
316
|
-
|
|
344
|
+
const doc = ctx.plan.doc();
|
|
345
|
+
if (ledger === null || doc === null)
|
|
317
346
|
return null;
|
|
318
|
-
const
|
|
319
|
-
const
|
|
320
|
-
const layers = (graph ?? new TaskGraph(parsed)).batches();
|
|
347
|
+
const planTasks = doc.taskBlocks.map((block) => block.id);
|
|
348
|
+
const layers = (graph ?? ctx.plan.graph() ?? new TaskGraph(doc)).batches();
|
|
321
349
|
const data = ledger.readProgress();
|
|
322
350
|
const recorded = this.#recordedTasksOf(data);
|
|
323
351
|
const closed = ledger.closedWaves();
|
|
@@ -384,7 +412,7 @@ export class PreFlight {
|
|
|
384
412
|
return {
|
|
385
413
|
docKey: "plan",
|
|
386
414
|
path: ctx.doc?.path ?? "",
|
|
387
|
-
content: ctx.
|
|
415
|
+
content: ctx.plan.text() ?? "",
|
|
388
416
|
root: ctx.repoRoot,
|
|
389
417
|
fs: this.#fs,
|
|
390
418
|
};
|