@oscaner-skills/cdd-engine 4.10.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.
@@ -18,13 +18,13 @@
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";
25
24
  import { NextStepRouter } from "./next.js";
26
25
  import { PipelineFrontier } from "./pipeline.js";
27
26
  import { ReviewedIdentity } from "./reviewed-identity.js";
27
+ import { RoundNaming } from "./round-naming.js";
28
28
  /** The empty run state — a target line with no task frontier (branch/spec/plan):
29
29
  * the frontier query faces are always empty (a single-target line never continues
30
30
  * a batch) and markDone is a no-op. */
@@ -150,21 +150,20 @@ export class Lifecycle {
150
150
  /** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
151
151
  * keep their existing behavior). */
152
152
  #preflight;
153
- /** The workspace plan path — the `next:` implement literal's required `--plan`
154
- * arg (P4.1 T4 — the task face's implement-consuming fact), and the plan cell of
155
- * the pipeline frontier's input. A `--spec` round fills it from the document index
156
- * (the same-slug plan the argv does not name); the plan / branch lines carry their
157
- * argv value. */
158
- #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;
159
161
  /** The pipeline frontier's declared identity — the spec line's DECLARED word (the
160
162
  * `doc-type:` head key) and its document path. A node with no spec document
161
163
  * (`#specPath === null`) keeps this line's own hop assembly: the frontier's rules
162
164
  * anchor on an absent identity face, which would print a passed phase's transition. */
163
165
  #specType;
164
166
  #specPath;
165
- /** The plan's task graph — the pipeline frontier's guarded plan read, injected by
166
- * the composition root (the session plane reads no file). */
167
- #planGraph;
168
167
  /** The pipeline frontier — the ONE hop assembly this lifecycle's capsule renders
169
168
  * (the same object the board renders). */
170
169
  #frontier;
@@ -182,10 +181,9 @@ export class Lifecycle {
182
181
  this.#target = opts.target ?? null;
183
182
  this.#capsule = opts.capsule ?? null;
184
183
  this.#preflight = opts.preflight ?? null;
185
- this.#planPath = opts.planPath ?? null;
184
+ this.#plan = opts.plan;
186
185
  this.#specType = opts.specType ?? null;
187
186
  this.#specPath = opts.specPath ?? null;
188
- this.#planGraph = opts.planGraph ?? null;
189
187
  this.#frontier = new PipelineFrontier(this.#ledger);
190
188
  this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
191
189
  }
@@ -301,7 +299,7 @@ export class Lifecycle {
301
299
  phase,
302
300
  round,
303
301
  target,
304
- params: this.#paramsOf({ type: "wave", phase, target, round }),
302
+ params: this.#paramsOf({ type: "wave", phase, target, round, attempt }),
305
303
  key,
306
304
  attempt,
307
305
  };
@@ -338,7 +336,7 @@ export class Lifecycle {
338
336
  phase,
339
337
  round,
340
338
  target,
341
- params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
339
+ params: this.#paramsOf({ type: this.#face.type, phase, target, round, attempt }),
342
340
  key,
343
341
  attempt,
344
342
  };
@@ -365,8 +363,9 @@ export class Lifecycle {
365
363
  // after the terminal branch review reopens the branch-review lead, an unchanged
366
364
  // plan keeps the line closed. Same gate, same judgment — only the doc path is
367
365
  // the line's plan (the audit target itself carries no doc).
368
- if (target.kind === "branch" && this.#planPath !== null) {
369
- 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");
370
369
  if (this.#ledger.docReopens(key, "branch", verdict))
371
370
  return reviewLead;
372
371
  if (verdict.kind === "same" && verdict.pending)
@@ -407,25 +406,22 @@ export class Lifecycle {
407
406
  // -------------------------------------------------------------------------
408
407
  // the frame → handoff params shaping
409
408
  // -------------------------------------------------------------------------
410
- /** The handoff params one frame fills — the type's placeholders from the target
411
- * and round. The round rides the increment families (review / fix / branch-review
412
- * — the family name carries it); the fixed implement family stays round-less. */
409
+ /** The handoff params one frame fills — the type's placeholders from the target,
410
+ * the round and the attempt. EVERY family carries its cycle now (P34 T1: the
411
+ * implement family included, so its draft and final are two names), and every
412
+ * family carries the attempt the naming face renders as `-a{n}`. */
413
413
  #paramsOf(frame) {
414
414
  switch (frame.type) {
415
415
  case "wave": {
416
416
  const waveTarget = frame.target;
417
- const params = { tasks: waveTarget.tasks.join(",") };
418
- if (frame.phase !== "implement")
419
- params.round = frame.round;
420
- return params;
417
+ return { tasks: waveTarget.tasks.join(","), round: frame.round, attempt: frame.attempt };
421
418
  }
422
419
  case "branch":
423
- return { round: frame.round };
424
420
  case "phase-spec":
425
421
  case "overall":
426
422
  case "plan":
427
423
  case "single-spec":
428
- return { round: frame.round };
424
+ return { round: frame.round, attempt: frame.attempt };
429
425
  }
430
426
  }
431
427
  // -------------------------------------------------------------------------
@@ -437,19 +433,17 @@ export class Lifecycle {
437
433
  * outcome carrying no verdict) — the engine-built fallback from the outcome fields.
438
434
  * Either way it lands as the FINAL carrier beside the child's draft, never over it
439
435
  * (P31 §2.3: the draft keeps the child's bytes, the final carries the engine's
440
- * materialization, and the record names both paths). A production round that wrote
441
- * no carrier is booked with `carrierPath: null` and no file at either name: the
442
- * completion criterion owns the absence (§3.3), and a re-dispatch's draft read must
443
- * see the child's own draft, never an engine synthesis of it. A failure round
444
- * WITHOUT a carrier leaves the child's draft untouched (no-overwrite on failure) but
445
- * is STILL recorded — every dispatched round lands; "completed" is the record's
446
- * verdict, never a membership test. Returns the in-register round count (the task
436
+ * materialization, and the ledger DERIVES the record's path from its own identity —
437
+ * the record remembers the digest, never a path). A production round that wrote no
438
+ * carrier leaves no file at either name: the completion criterion owns the absence
439
+ * (§3.3), and a re-dispatch's draft read must see the child's own draft, never an
440
+ * engine synthesis of it. A failure round WITHOUT a carrier leaves the child's
441
+ * draft untouched (no-overwrite on failure) but is STILL recorded — every dispatched
442
+ * round lands; "completed" is the record's verdict, never a membership test. Returns the in-register round count (the task
447
443
  * done-marking rides the step's C5 route — #markTerminal, after #routeNext). */
448
444
  #bookkeep(frame, outcome) {
449
445
  const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
450
- let carrierPath = null;
451
446
  let carrierDigest = null;
452
- let draftPath = null;
453
447
  if (outcome.carrier !== undefined || (outcome.verdict === undefined && !blocked)) {
454
448
  const op = this.#opOf(frame.phase);
455
449
  // T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
@@ -472,13 +466,12 @@ export class Lifecycle {
472
466
  // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
473
467
  if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
474
468
  carrier.status = outcome.status;
475
- // P31 §2.2/§2.3 — the persist hands the FINAL carrier path, the draft path it
476
- // landed beside and the payload digest, so the round record can name both
477
- // artifacts and replay the comparison on every later read of this carrier.
469
+ // P31 §2.2/§2.3 — the persist seals the round's two names and hands back the
470
+ // payload digest, so the record can replay the comparison on every later read of
471
+ // this carrier. The PATHS stay out of the record: the ledger derives them from
472
+ // the record's own identity.
478
473
  const persisted = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
479
- carrierPath = persisted.path;
480
474
  carrierDigest = persisted.digest;
481
- draftPath = persisted.draftPath;
482
475
  }
483
476
  else {
484
477
  // P31 T5 §2.4 — a round that books NO carrier still owns its two names: the
@@ -514,9 +507,9 @@ export class Lifecycle {
514
507
  targetAction: !blocked,
515
508
  },
516
509
  violations,
517
- carrierPath,
518
- carrierDigest,
519
- draftPath,
510
+ // A round that persisted no carrier records no digest column at all — the
511
+ // absence is the fact, never a null placeholder.
512
+ ...(carrierDigest === null ? {} : { carrierDigest }),
520
513
  }, frame.type);
521
514
  // The completed-round revision write-back is gated on the round's VERDICT (a
522
515
  // hard-failed round must not bind the current revision — that would silently
@@ -582,23 +575,29 @@ export class Lifecycle {
582
575
  * review or fix round. Null plan path / underivable brief records nothing (present
583
576
  * facts only). */
584
577
  #recordReviewedWaveBrief(frame) {
585
- if (frame.target.kind !== "wave" || this.#planPath === null)
578
+ const planPath = this.#plan.stationPath();
579
+ if (frame.target.kind !== "wave" || planPath === null)
586
580
  return;
587
- this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
581
+ this.#ledger.recordReviewedBrief(String(frame.key), planPath);
588
582
  }
589
583
  /** The branch line's reviewed identity (P21 §4.1) — its PLAN document's
590
584
  * `doc-revision`, the same ref kind the doc lines bind (no new ref kind, no commit
591
585
  * sha). A later plan revision reopens the line; an unchanged plan keeps it closed.
592
- * 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). */
593
590
  #recordReviewedBranchRevision(frame) {
594
- if (this.#planPath === null)
591
+ const planPath = this.#plan.stationPath();
592
+ if (planPath === null)
595
593
  return;
596
- this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
594
+ this.#ledger.recordReviewedPlanRevision(frame.key, planPath, frame.type);
597
595
  }
598
596
  /** The doc-revision write-back body — read the round's document and bind its
599
- * current revision to the line row (the ONE read + hash + record path the doc and
600
- * branch legs share; each passes its own path source). An unreadable input records
601
- * 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). */
602
601
  #recordDocRevisionOf(key, path, identity) {
603
602
  try {
604
603
  const content = readFileSync(path, "utf8");
@@ -630,34 +629,30 @@ export class Lifecycle {
630
629
  this.#recordPlanSnapshot(frame);
631
630
  }
632
631
  /** Record the closing wave's plan-task snapshot — the plan's CURRENT task-id set
633
- * read from the plan document (`#planPath`, the same source the brief renders
634
- * from) through the contract parse face. An unreadable plan or a null plan path
635
- * records nothing: the snapshot is a present fact only, never a fabricated `[]`
636
- * (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). */
637
637
  #recordPlanSnapshot(frame) {
638
- if (this.#planPath === null)
638
+ const doc = this.#plan.doc();
639
+ if (doc === null)
639
640
  return;
640
- try {
641
- const lines = readFileSync(this.#planPath, "utf8").split("\n");
642
- const parsed = new PlanDocType("plan").parse(lines);
643
- this.#ledger.recordPlanTasks(String(frame.key), parsed.taskBlocks.map((block) => block.id));
644
- }
645
- catch {
646
- // unreadable plan — skip the snapshot (present facts only)
647
- }
641
+ this.#ledger.recordPlanTasks(String(frame.key), doc.taskBlocks.map((block) => block.id));
648
642
  }
649
643
  /** The handoff-family op of a phase — branch-review rides the review family. */
650
644
  #opOf(phase) {
651
645
  return phase === "branch-review" ? "review" : phase;
652
646
  }
653
647
  /** P31 §2.4 — seal one round's OWN carrier names (its draft and its final). The
654
- * derivation is the same pair the lifecycle's preflight opens; a round-less family
655
- * (implement) resolves both to one path, so the seal is idempotent by construction. */
648
+ * derivation is the same pair the lifecycle's preflight opens, off the frame's own
649
+ * identity (cycle + attempt): two rounds of the same line never close each other's
650
+ * window. */
656
651
  #sealRoundCarriers(frame) {
657
652
  const op = this.#opOf(frame.phase);
658
- const draftName = this.#ledger.handoffName(op, frame.type, frame.params);
659
- CarrierSeal.seal(this.#ledger.handoffPath(op, frame.type, frame.params));
660
- CarrierSeal.seal(this.#ledger.naming().finalPath(draftName, frame.params.round));
653
+ const artifact = RoundNaming.artifactOf(op, frame.type, frame.params);
654
+ CarrierSeal.seal(this.#ledger.naming().renderPath(artifact, "draft"));
655
+ CarrierSeal.seal(this.#ledger.naming().renderPath(artifact, "final"));
661
656
  }
662
657
  // -------------------------------------------------------------------------
663
658
  // next routing + the capsule interaction
@@ -711,7 +706,7 @@ export class Lifecycle {
711
706
  if (frame.target.kind === "plan" || frame.target.kind === "spec")
712
707
  return frame.target.doc;
713
708
  if (frame.target.kind === "branch")
714
- return this.#planPath;
709
+ return this.#plan.stationPath();
715
710
  return null;
716
711
  }
717
712
  /** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
@@ -731,8 +726,8 @@ export class Lifecycle {
731
726
  return {
732
727
  specType: this.#specType,
733
728
  specPath: this.#specPath,
734
- planPath: this.#planPath,
735
- planGraph: this.#planGraph,
729
+ planPath: this.#plan.stationPath(),
730
+ plan: this.#plan,
736
731
  };
737
732
  }
738
733
  /** Whether the branch line has a dispatchable open round — the wave closure's
@@ -740,7 +735,7 @@ export class Lifecycle {
740
735
  * shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
741
736
  * route combination. */
742
737
  #branchLineOpen() {
743
- return this.#frontier.branchLineOpen(this.#planPath);
738
+ return this.#frontier.branchLineOpen(this.#plan.stationPath());
744
739
  }
745
740
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
746
741
  * interaction point). A success round carries the handoff carrier path; a failure
@@ -775,7 +770,11 @@ export class Lifecycle {
775
770
  #routeTarget(frame) {
776
771
  switch (frame.type) {
777
772
  case "wave":
778
- 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
+ };
779
778
  case "branch":
780
779
  // The branch line's stable id — the workspace plan path carries the
781
780
  // fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
@@ -784,7 +783,7 @@ export class Lifecycle {
784
783
  return {
785
784
  type: "branch",
786
785
  id: "branch",
787
- plan: this.#planPath ?? undefined,
786
+ plan: this.#plan.stationPath() ?? undefined,
788
787
  };
789
788
  case "phase-spec":
790
789
  case "overall":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.10.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": {