@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.
@@ -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/ledger structure gate (`plan-ledger`, P21
7
- // §3.1/§6.4), the graph validate and the doc-side gate (Contract.validate over the
8
- // target doc). The dispatch's own phase — the wave face's gate and the doc/branch
9
- // line's — is NOT judged here: it belongs to the ONE dispatch authority
10
- // (`session/dispatch-authority.ts`, P27 §2), the seam's single consumer.
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 → graph → plan-ledger
59
- * → doc-contract. The first refused gate owns the verdict; the gates that ran
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. graph — the wave/plan faces' structural gate.
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.planText !== null) {
120
+ if ((ctx.type === "wave" || ctx.type === "plan") && ctx.plan.kind === "ready") {
95
121
  gates.push("graph");
96
122
  checked.push("graph");
97
- graph = new TaskGraph(new PlanDocType("plan").parse(ctx.planText.split("\n")));
98
- const issues = graph.validate();
99
- if (issues.length > 0) {
100
- return this.#refusal({
101
- ok: false,
102
- gate: "graph",
103
- reason: "graph",
104
- message: this.#words.preflightWords().graph.replace("{count}", String(issues.length)),
105
- details: issues.map((issue) => `${issue.kind}@T${issue.task}: ${issue.message}`),
106
- }, gates, checked, this.#docOutcomeOf(ctx), { kind: "no-ledger-facts" });
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
- // 4. plan-ledger — the ledger-scope rules (P21 §3.1/§6.4). Plan / wave / branch
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
- // 5. doc-contract — the doc shapes' structural gate (the doc-scope rules).
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 text
312
- * and the plan's topological layers. Null when either fact source is absent
313
- * (the gate then renders `skipped (no ledger facts)`). */
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
- if (ledger === null || ctx.planText === null)
344
+ const doc = ctx.plan.doc();
345
+ if (ledger === null || doc === null)
317
346
  return null;
318
- const parsed = new PlanDocType("plan").parse(ctx.planText.split("\n"));
319
- const planTasks = parsed.taskBlocks.map((block) => block.id);
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.planText ?? "",
415
+ content: ctx.plan.text() ?? "",
388
416
  root: ctx.repoRoot,
389
417
  fs: this.#fs,
390
418
  };
@@ -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 workspace plan path — the `next:` implement literal's required `--plan`
155
- * arg (P4.1 T4 — the task face's implement-consuming fact), and the plan cell of
156
- * the pipeline frontier's input. A `--spec` round fills it from the document index
157
- * (the same-slug plan the argv does not name); the plan / branch lines carry their
158
- * argv value. */
159
- #planPath;
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.#planPath = opts.planPath ?? null;
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
- if (target.kind === "branch" && this.#planPath !== null) {
370
- const verdict = this.#ledger.reviewGate(key, this.#planPath, "branch");
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
- if (frame.target.kind !== "wave" || this.#planPath === null)
578
+ const planPath = this.#plan.stationPath();
579
+ if (frame.target.kind !== "wave" || planPath === null)
581
580
  return;
582
- this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
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
- * An unreadable plan / a null plan path records nothing (present facts only). */
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
- if (this.#planPath === null)
591
+ const planPath = this.#plan.stationPath();
592
+ if (planPath === null)
590
593
  return;
591
- this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
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 and
595
- * branch legs share; each passes its own path source). An unreadable input records
596
- * nothing — the line keeps the legacy closed face (present facts only). */
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 document (`#planPath`, the same source the brief renders
629
- * from) through the contract parse face. An unreadable plan or a null plan path
630
- * records nothing: the snapshot is a present fact only, never a fabricated `[]`
631
- * (an absent snapshot reads conservatively as "stall" in the wave gate). */
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
- if (this.#planPath === null)
638
+ const doc = this.#plan.doc();
639
+ if (doc === null)
634
640
  return;
635
- try {
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.#planPath;
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.#planPath,
731
- planGraph: this.#planGraph,
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.#planPath);
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 { type: "wave", id: frame.params.tasks ?? "", plan: this.#planPath ?? undefined };
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.#planPath ?? undefined,
786
+ plan: this.#plan.stationPath() ?? undefined,
784
787
  };
785
788
  case "phase-spec":
786
789
  case "overall":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.11.0",
3
+ "version": "4.12.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {