@oscaner-skills/cdd-engine 4.11.0 → 4.12.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/dist/contract/doc.js +24 -0
- 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/board-view.js +179 -77
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +23 -13
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/render/brief.js +34 -32
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/ledger.js +35 -5
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +60 -32
- package/dist/session/run.js +44 -41
- package/package.json +1 -1
|
@@ -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
|
};
|
package/dist/session/run.js
CHANGED
|
@@ -18,7 +18,6 @@
|
|
|
18
18
|
// Module-level exports are types / the class / one empty-state data const — zero
|
|
19
19
|
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
20
20
|
import { readFileSync } from "node:fs";
|
|
21
|
-
import { PlanDocType } from "../contract/doc.js";
|
|
22
21
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
23
22
|
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
24
23
|
import { Ledger, RoundViolation, } from "./ledger.js";
|
|
@@ -151,21 +150,20 @@ export class Lifecycle {
|
|
|
151
150
|
/** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
|
|
152
151
|
* keep their existing behavior). */
|
|
153
152
|
#preflight;
|
|
154
|
-
/** The
|
|
155
|
-
* arg
|
|
156
|
-
*
|
|
157
|
-
* (
|
|
158
|
-
*
|
|
159
|
-
|
|
153
|
+
/** The plan read this lifecycle drives (the `next:` implement literal's required
|
|
154
|
+
* `--plan` arg, the branch line's identity document, the brief hash's and the
|
|
155
|
+
* plan snapshot's source, and the pipeline frontier's plan cells). The frontier
|
|
156
|
+
* path is `stationPath()` — the document that read out (its front matter
|
|
157
|
+
* parsed), so a `syntax` plan keeps its face while an `io` failure carries none.
|
|
158
|
+
* REQUIRED: every command preamble holds a value (`undeclared` is a value), so no
|
|
159
|
+
* harness can silently drop the brief hash and the plan snapshot by omission. */
|
|
160
|
+
#plan;
|
|
160
161
|
/** The pipeline frontier's declared identity — the spec line's DECLARED word (the
|
|
161
162
|
* `doc-type:` head key) and its document path. A node with no spec document
|
|
162
163
|
* (`#specPath === null`) keeps this line's own hop assembly: the frontier's rules
|
|
163
164
|
* anchor on an absent identity face, which would print a passed phase's transition. */
|
|
164
165
|
#specType;
|
|
165
166
|
#specPath;
|
|
166
|
-
/** The plan's task graph — the pipeline frontier's guarded plan read, injected by
|
|
167
|
-
* the composition root (the session plane reads no file). */
|
|
168
|
-
#planGraph;
|
|
169
167
|
/** The pipeline frontier — the ONE hop assembly this lifecycle's capsule renders
|
|
170
168
|
* (the same object the board renders). */
|
|
171
169
|
#frontier;
|
|
@@ -183,10 +181,9 @@ export class Lifecycle {
|
|
|
183
181
|
this.#target = opts.target ?? null;
|
|
184
182
|
this.#capsule = opts.capsule ?? null;
|
|
185
183
|
this.#preflight = opts.preflight ?? null;
|
|
186
|
-
this.#
|
|
184
|
+
this.#plan = opts.plan;
|
|
187
185
|
this.#specType = opts.specType ?? null;
|
|
188
186
|
this.#specPath = opts.specPath ?? null;
|
|
189
|
-
this.#planGraph = opts.planGraph ?? null;
|
|
190
187
|
this.#frontier = new PipelineFrontier(this.#ledger);
|
|
191
188
|
this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
|
|
192
189
|
}
|
|
@@ -366,8 +363,9 @@ export class Lifecycle {
|
|
|
366
363
|
// after the terminal branch review reopens the branch-review lead, an unchanged
|
|
367
364
|
// plan keeps the line closed. Same gate, same judgment — only the doc path is
|
|
368
365
|
// the line's plan (the audit target itself carries no doc).
|
|
369
|
-
|
|
370
|
-
|
|
366
|
+
const planPath = this.#plan.stationPath();
|
|
367
|
+
if (target.kind === "branch" && planPath !== null) {
|
|
368
|
+
const verdict = this.#ledger.reviewGate(key, planPath, "branch");
|
|
371
369
|
if (this.#ledger.docReopens(key, "branch", verdict))
|
|
372
370
|
return reviewLead;
|
|
373
371
|
if (verdict.kind === "same" && verdict.pending)
|
|
@@ -577,23 +575,29 @@ export class Lifecycle {
|
|
|
577
575
|
* review or fix round. Null plan path / underivable brief records nothing (present
|
|
578
576
|
* facts only). */
|
|
579
577
|
#recordReviewedWaveBrief(frame) {
|
|
580
|
-
|
|
578
|
+
const planPath = this.#plan.stationPath();
|
|
579
|
+
if (frame.target.kind !== "wave" || planPath === null)
|
|
581
580
|
return;
|
|
582
|
-
this.#ledger.recordReviewedBrief(String(frame.key),
|
|
581
|
+
this.#ledger.recordReviewedBrief(String(frame.key), planPath);
|
|
583
582
|
}
|
|
584
583
|
/** The branch line's reviewed identity (P21 §4.1) — its PLAN document's
|
|
585
584
|
* `doc-revision`, the same ref kind the doc lines bind (no new ref kind, no commit
|
|
586
585
|
* sha). A later plan revision reopens the line; an unchanged plan keeps it closed.
|
|
587
|
-
*
|
|
586
|
+
* The document is re-read at round completion THROUGH the ledger's plan seam (the
|
|
587
|
+
* ONE plan read point), so a fix that edited the plan binds the edited bytes and
|
|
588
|
+
* the write-back never turns a repoRoot-relative path into a cwd-relative syscall.
|
|
589
|
+
* A null plan path records nothing (present facts only). */
|
|
588
590
|
#recordReviewedBranchRevision(frame) {
|
|
589
|
-
|
|
591
|
+
const planPath = this.#plan.stationPath();
|
|
592
|
+
if (planPath === null)
|
|
590
593
|
return;
|
|
591
|
-
this.#
|
|
594
|
+
this.#ledger.recordReviewedPlanRevision(frame.key, planPath, frame.type);
|
|
592
595
|
}
|
|
593
596
|
/** The doc-revision write-back body — read the round's document and bind its
|
|
594
|
-
* current revision to the line row (the ONE read + hash + record path the doc
|
|
595
|
-
* branch
|
|
596
|
-
* nothing — the line keeps the legacy closed face (present facts
|
|
597
|
+
* current revision to the line row (the ONE read + hash + record path the doc
|
|
598
|
+
* leg owns; the branch leg binds the plan read it already judged). An unreadable
|
|
599
|
+
* input records nothing — the line keeps the legacy closed face (present facts
|
|
600
|
+
* only). */
|
|
597
601
|
#recordDocRevisionOf(key, path, identity) {
|
|
598
602
|
try {
|
|
599
603
|
const content = readFileSync(path, "utf8");
|
|
@@ -625,21 +629,16 @@ export class Lifecycle {
|
|
|
625
629
|
this.#recordPlanSnapshot(frame);
|
|
626
630
|
}
|
|
627
631
|
/** Record the closing wave's plan-task snapshot — the plan's CURRENT task-id set
|
|
628
|
-
* read from the plan
|
|
629
|
-
*
|
|
630
|
-
* records nothing: the snapshot is a present fact only, never a
|
|
631
|
-
* (an absent snapshot reads conservatively as "stall" in the wave
|
|
632
|
+
* read from the SAME plan read the brief hashes (the injected `PlanRead`), so the
|
|
633
|
+
* snapshot and the reviewed basis can never describe two different documents. A
|
|
634
|
+
* non-ready plan records nothing: the snapshot is a present fact only, never a
|
|
635
|
+
* fabricated `[]` (an absent snapshot reads conservatively as "stall" in the wave
|
|
636
|
+
* gate). */
|
|
632
637
|
#recordPlanSnapshot(frame) {
|
|
633
|
-
|
|
638
|
+
const doc = this.#plan.doc();
|
|
639
|
+
if (doc === null)
|
|
634
640
|
return;
|
|
635
|
-
|
|
636
|
-
const lines = readFileSync(this.#planPath, "utf8").split("\n");
|
|
637
|
-
const parsed = new PlanDocType("plan").parse(lines);
|
|
638
|
-
this.#ledger.recordPlanTasks(String(frame.key), parsed.taskBlocks.map((block) => block.id));
|
|
639
|
-
}
|
|
640
|
-
catch {
|
|
641
|
-
// unreadable plan — skip the snapshot (present facts only)
|
|
642
|
-
}
|
|
641
|
+
this.#ledger.recordPlanTasks(String(frame.key), doc.taskBlocks.map((block) => block.id));
|
|
643
642
|
}
|
|
644
643
|
/** The handoff-family op of a phase — branch-review rides the review family. */
|
|
645
644
|
#opOf(phase) {
|
|
@@ -707,7 +706,7 @@ export class Lifecycle {
|
|
|
707
706
|
if (frame.target.kind === "plan" || frame.target.kind === "spec")
|
|
708
707
|
return frame.target.doc;
|
|
709
708
|
if (frame.target.kind === "branch")
|
|
710
|
-
return this.#
|
|
709
|
+
return this.#plan.stationPath();
|
|
711
710
|
return null;
|
|
712
711
|
}
|
|
713
712
|
/** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
|
|
@@ -727,8 +726,8 @@ export class Lifecycle {
|
|
|
727
726
|
return {
|
|
728
727
|
specType: this.#specType,
|
|
729
728
|
specPath: this.#specPath,
|
|
730
|
-
planPath: this.#
|
|
731
|
-
|
|
729
|
+
planPath: this.#plan.stationPath(),
|
|
730
|
+
plan: this.#plan,
|
|
732
731
|
};
|
|
733
732
|
}
|
|
734
733
|
/** Whether the branch line has a dispatchable open round — the wave closure's
|
|
@@ -736,7 +735,7 @@ export class Lifecycle {
|
|
|
736
735
|
* shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
|
|
737
736
|
* route combination. */
|
|
738
737
|
#branchLineOpen() {
|
|
739
|
-
return this.#frontier.branchLineOpen(this.#
|
|
738
|
+
return this.#frontier.branchLineOpen(this.#plan.stationPath());
|
|
740
739
|
}
|
|
741
740
|
/** The capsule lines of one step — empty unless a capsule is attached (the non-hard
|
|
742
741
|
* interaction point). A success round carries the handoff carrier path; a failure
|
|
@@ -771,7 +770,11 @@ export class Lifecycle {
|
|
|
771
770
|
#routeTarget(frame) {
|
|
772
771
|
switch (frame.type) {
|
|
773
772
|
case "wave":
|
|
774
|
-
return {
|
|
773
|
+
return {
|
|
774
|
+
type: "wave",
|
|
775
|
+
id: frame.params.tasks ?? "",
|
|
776
|
+
plan: this.#plan.stationPath() ?? undefined,
|
|
777
|
+
};
|
|
775
778
|
case "branch":
|
|
776
779
|
// The branch line's stable id — the workspace plan path carries the
|
|
777
780
|
// fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
|
|
@@ -780,7 +783,7 @@ export class Lifecycle {
|
|
|
780
783
|
return {
|
|
781
784
|
type: "branch",
|
|
782
785
|
id: "branch",
|
|
783
|
-
plan: this.#
|
|
786
|
+
plan: this.#plan.stationPath() ?? undefined,
|
|
784
787
|
};
|
|
785
788
|
case "phase-spec":
|
|
786
789
|
case "overall":
|