@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.
@@ -1,8 +1,10 @@
1
1
  // packages/cdd-engine/src-next/session/round-naming.ts
2
2
  // P34 T1 — the naming single source: ONE round identity renders every artifact name
3
- // (draft · final · report · log · crash · evidence) through `renderName`, so a kind's
4
- // spelling and its siblings' can never drift, and the reverse attribution
5
- // (`Ledger#handoffOwner`) parses back exactly the identity this face renders.
3
+ // (draft · final · report · log · crash · evidence · the orchestrator's rulings) through
4
+ // `renderName`, so a kind's spelling and its siblings' can never drift. The REVERSE
5
+ // direction (name → identity) is the artifact matrix's (`session/round-artifacts.ts`
6
+ // `attribute`), never a second predicate here: a carrier-name grammar kept beside the
7
+ // matrix would be the second spelling this phase retires (P36 §2.5).
6
8
  //
7
9
  // The identity is a triple: the LINE (`tasks-{tasks}` · `branch` · the doc word), the
8
10
  // OP (`implement` · `review` · `fix` — branch-review rides the review family), the
@@ -13,42 +15,9 @@
13
15
  // cycle segment too, never a `-undefined` token.
14
16
  //
15
17
  // Module-level exports are types / the class — zero behavior-carrying bare functions.
16
- // One module-level value: the compiled carrier predicate below (`CARRIER`).
17
18
  var _a;
18
- import { TargetFaceTable, targetFaces } from "./faces.js";
19
- /** The two carrier-name shapes this engine MINTS — the draft and its final twin.
20
- * Both accept the `-a{n}` attempt segment and the final's `.c{cycle}` suffix; every
21
- * other artifact (report · log · crash · evidence) is deliberately outside the
22
- * predicate, so the seal sweep can never touch it. The legacy cycle-less implement
23
- * spelling (`tasks-{tasks}-implement.json`) stays accepted for the drafts a
24
- * pre-P34 engine left on disk.
25
- *
26
- * Module scope, not a `static readonly #CARRIER` field: tsc down-levels a static
27
- * field initializer that reads the class's own private static member into a temp
28
- * (`static #CARRIER = _a.#carrierPattern()`) assigned only AFTER the class body, so
29
- * the module threw `Receiver must be class RoundNaming` at import. Reading a plain
30
- * const keeps the pattern out of that transform's reach.
31
- *
32
- * A wave line takes the wave-only `tasks-` spine, every other line word takes the
33
- * round-bearing ops; the op set and the line words come from the ONE target-face
34
- * table, so neither is re-spelled here. The `.c{cycle}` final suffix hangs off the
35
- * CYCLE-BEARING alternatives alone — a cycle-less identity has no cycle to suffix, so
36
- * `tasks-1-implement.c1.json` is a shape the renderer can never mint. */
37
- const carrierPattern = () => {
38
- const lines = Object.keys(targetFaces).filter((word) => word !== "wave");
39
- const attempt = "(?:-a\\d+)?";
40
- const final = "(?:\\.c\\d+)?";
41
- const cycleBearing = [
42
- "tasks-.+?-implement-\\d+",
43
- "tasks-.+?-(?:review|fix)-\\d+",
44
- `(?:${lines.join("|")})-(?:review|fix)-\\d+`,
45
- ].join("|");
46
- // The legacy cycle-less implement draft: a draft on disk, never a final and never
47
- // an attempt — this engine mints neither on a cycle-less identity.
48
- const legacy = "tasks-.+?-implement";
49
- return new RegExp(`^(?:(?:${cycleBearing})${attempt}${final}|${legacy})\\.json$`);
50
- };
51
- const CARRIER = carrierPattern();
19
+ import { TargetFaceTable } from "./faces.js";
20
+ import { ArtifactRegistry, renderRound } from "./round-artifacts.js";
52
21
  /**
53
22
  * RoundNaming — the one home of a round's prescribed artifact names. A frame's
54
23
  * report / log / crash / evidence / carrier names derive here, so every consumer
@@ -76,55 +45,20 @@ export class RoundNaming {
76
45
  static lineOf(type, params) {
77
46
  return type === "wave" ? `tasks-${params.tasks ?? ""}` : type;
78
47
  }
79
- /** Render one round identity as one artifact name — the ONE naming rule. The four
80
- * segments (`line` · `op` · cycle · attempt) join in this order for every kind, so
81
- * a kind only picks its own prefix/suffix around the shared stem. A `final` has no
82
- * cycle to key on when the identity carries none: it renders the draft name back,
83
- * never a malformed `.cundefined` suffix. The stem's cycle segment is omitted for a
48
+ /** Render one round identity as one artifact name — the ONE naming rule, delegated
49
+ * to the artifact matrix's round row (`renderRound`): one spelling, two entry forms
50
+ * (this static method and `ArtifactRegistry#render`). A `final` has no cycle to key
51
+ * on when the identity carries none: it renders the draft name back, never a
52
+ * malformed `.cundefined` suffix. The stem's cycle segment is omitted for a
84
53
  * cycle-less identity; its attempt segment is omitted on the first attempt (an
85
54
  * `-a1` never appears). */
86
55
  static renderName(artifact, kind) {
87
- const cycle = artifact.cycle === undefined || artifact.cycle === "" ? "" : `-${artifact.cycle}`;
88
- const attempt = artifact.attempt === undefined || artifact.attempt <= 1 ? "" : `-a${artifact.attempt}`;
89
- const stem = `${artifact.line}-${artifact.op}${cycle}${attempt}`;
90
- switch (kind) {
91
- case "draft":
92
- return `${stem}.json`;
93
- case "final":
94
- return artifact.cycle === undefined || artifact.cycle === ""
95
- ? `${stem}.json`
96
- : `${stem}.c${artifact.cycle}.json`;
97
- case "report":
98
- return `${stem}-report.md`;
99
- case "log":
100
- return `${stem}.log`;
101
- case "crash":
102
- return `crash-${stem}.json`;
103
- case "evidence":
104
- return `${stem}-test-evidence.json`;
105
- }
56
+ return renderRound({ domain: "round", ...artifact }, kind);
106
57
  }
107
- /** The carrier-name predicate's compiled pattern — a wave line takes the wave-only
108
- * `tasks-` spine, every other line word takes the round-bearing ops. The op set and
109
- * the line words come from the ONE target-face table, so neither is re-spelled here.
110
- * Only `implement` has a cycle-less spelling (the pre-P34 draft on disk); `review`
111
- * and `fix` always carry their cycle, so a `tasks-1-review.json` is no carrier at all.
112
- * The `.c{cycle}` final suffix hangs off the CYCLE-BEARING alternatives alone — a
113
- * cycle-less identity has no cycle to suffix, so `tasks-1-implement.c1.json` is a
114
- * shape the renderer can never mint. */
115
58
  /** The rendered name resolved against the workspace — the read/write syscall form. */
116
59
  renderPath(artifact, kind) {
117
60
  return this.#workspace.resolve(_a.renderName(artifact, kind));
118
61
  }
119
- /** Whether a workspace file name is one of the two carrier shapes this engine mints.
120
- * Every neighbouring artifact — `progress.json` · `base.json` · the test-evidence
121
- * sibling · a carrier's `.rulings.json` sidecar · a report · a crash record — is NOT
122
- * a carrier, so the sweep that seals carriers can never touch them. Static: the
123
- * judgment reads a NAME and nothing else, so the seal sweep (`CarrierSeal`) applies
124
- * the same predicate without holding a workspace. */
125
- static isCarrierName(name) {
126
- return CARRIER.test(name);
127
- }
128
62
  /** The handoff-family op of a frame — branch-review rides the review family. The
129
63
  * artifact names embed this op, so the mapping is a naming fact owned here (the
130
64
  * lifecycle's op read delegates, never a second copy of the rule). */
@@ -139,9 +73,10 @@ export class RoundNaming {
139
73
  return this.#workspace.resolve(this.briefName(tasks));
140
74
  }
141
75
  /** The brief's workspace-relative NAME — the write face takes the name, the read
142
- * faces take the resolved path (one derivation, both spellings). */
76
+ * faces take the resolved path (one derivation, both spellings). The template is the
77
+ * artifact matrix's `brief` row; this is a delegate, never a second rendering. */
143
78
  briefName(tasks) {
144
- return `tasks-${tasks}-brief.md`;
79
+ return ArtifactRegistry.nameOf("brief", tasks);
145
80
  }
146
81
  /** The prescribed report path of a round — the shared stem with `-report.md`. */
147
82
  report(frame) {
@@ -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;
@@ -179,14 +177,16 @@ export class Lifecycle {
179
177
  this.#state = opts.state;
180
178
  this.#ledger = opts.ledger;
181
179
  this.#dispatch = opts.dispatch;
182
- this.#router = opts.router ?? new NextStepRouter();
180
+ // The router is built in the constructor body (never a field initializer): the
181
+ // injected artifact matrix rides the opts field, so the readback face and this
182
+ // hop share ONE registry.
183
+ this.#router = opts.router ?? new NextStepRouter(opts.artifacts ?? null);
183
184
  this.#target = opts.target ?? null;
184
185
  this.#capsule = opts.capsule ?? null;
185
186
  this.#preflight = opts.preflight ?? null;
186
- this.#planPath = opts.planPath ?? null;
187
+ this.#plan = opts.plan;
187
188
  this.#specType = opts.specType ?? null;
188
189
  this.#specPath = opts.specPath ?? null;
189
- this.#planGraph = opts.planGraph ?? null;
190
190
  this.#frontier = new PipelineFrontier(this.#ledger);
191
191
  this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
192
192
  }
@@ -240,7 +240,7 @@ export class Lifecycle {
240
240
  if (verdict !== null && !verdict.ok) {
241
241
  return {
242
242
  frame,
243
- round: this.#ledger.roundCount(frame.key, frame.phase, frame.type),
243
+ round: this.#ledger.roundCount(frame.key, frame.phase),
244
244
  route: null,
245
245
  capsuleLines: [],
246
246
  preflight: verdict,
@@ -311,9 +311,7 @@ export class Lifecycle {
311
311
  * records (`RoundNaming#attemptOf`, the naming single source) and shared by the
312
312
  * round record and the round log's name. */
313
313
  #attemptFor(phase, key, round) {
314
- return this.#ledger
315
- .naming()
316
- .attemptOf(this.#ledger.recordsOf(key, this.#face.type), this.#opOf(phase), round);
314
+ return this.#ledger.naming().attemptOf(this.#ledger.recordsOf(key), this.#opOf(phase), round);
317
315
  }
318
316
  /** The next phase of one wave line — the SAME single derivation the wave gate reads
319
317
  * (`Ledger#waveLinePhase` · D26: one fact, one place). The lifecycle's frame
@@ -366,8 +364,9 @@ export class Lifecycle {
366
364
  // after the terminal branch review reopens the branch-review lead, an unchanged
367
365
  // plan keeps the line closed. Same gate, same judgment — only the doc path is
368
366
  // 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");
367
+ const planPath = this.#plan.stationPath();
368
+ if (target.kind === "branch" && planPath !== null) {
369
+ const verdict = this.#ledger.reviewGate(key, planPath, "branch");
371
370
  if (this.#ledger.docReopens(key, "branch", verdict))
372
371
  return reviewLead;
373
372
  if (verdict.kind === "same" && verdict.pending)
@@ -383,7 +382,7 @@ export class Lifecycle {
383
382
  if (phase === "implement")
384
383
  return 1;
385
384
  if (phase === "fix") {
386
- const completed = this.#ledger.completedCycles(key, "review", this.#face.type);
385
+ const completed = this.#ledger.completedCycles(key, "review");
387
386
  return completed.length > 0 ? Math.max(...completed) : 1;
388
387
  }
389
388
  return this.#reviewCount(key) + 1;
@@ -391,7 +390,7 @@ export class Lifecycle {
391
390
  /** The review-lead round count of a key (branch counts its branch-review mode,
392
391
  * the others the review mode — the face row's single source). */
393
392
  #reviewCount(key) {
394
- return this.#ledger.roundCount(key, this.#face.product.reviewLead, this.#face.type);
393
+ return this.#ledger.roundCount(key, this.#face.product.reviewLead);
395
394
  }
396
395
  /** The progress key of a single-target line — the line's STABLE key (find #9 ·
397
396
  * spec §6.5/§3.7 — `"branch"` per workspace for the branch line, accumulating
@@ -512,7 +511,7 @@ export class Lifecycle {
512
511
  // A round that persisted no carrier records no digest column at all — the
513
512
  // absence is the fact, never a null placeholder.
514
513
  ...(carrierDigest === null ? {} : { carrierDigest }),
515
- }, frame.type);
514
+ });
516
515
  // The completed-round revision write-back is gated on the round's VERDICT (a
517
516
  // hard-failed round must not bind the current revision — that would silently
518
517
  // close the drift identity the round never delivered). WHICH reviewed input the
@@ -555,7 +554,7 @@ export class Lifecycle {
555
554
  break;
556
555
  }
557
556
  }
558
- return this.#ledger.roundCount(frame.key, frame.phase, frame.type);
557
+ return this.#ledger.roundCount(frame.key, frame.phase);
559
558
  }
560
559
  /** The reviewed-revision write-back — bind the completed round's input revision to
561
560
  * the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
@@ -569,7 +568,7 @@ export class Lifecycle {
569
568
  #recordReviewedDocRevision(frame) {
570
569
  if (frame.target.kind !== "plan" && frame.target.kind !== "spec")
571
570
  return;
572
- this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
571
+ this.#recordDocRevisionOf(frame.key, frame.target.doc);
573
572
  }
574
573
  /** The wave line's reviewed-brief write-back (D30 · P29 §2.2) — bind the wave's
575
574
  * TASK-ONLY projection revision (`BriefRenderer#taskBody` — the same face the
@@ -577,27 +576,33 @@ export class Lifecycle {
577
576
  * review or fix round. Null plan path / underivable brief records nothing (present
578
577
  * facts only). */
579
578
  #recordReviewedWaveBrief(frame) {
580
- if (frame.target.kind !== "wave" || this.#planPath === null)
579
+ const planPath = this.#plan.stationPath();
580
+ if (frame.target.kind !== "wave" || planPath === null)
581
581
  return;
582
- this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
582
+ this.#ledger.recordReviewedBrief(String(frame.key), planPath);
583
583
  }
584
584
  /** The branch line's reviewed identity (P21 §4.1) — its PLAN document's
585
585
  * `doc-revision`, the same ref kind the doc lines bind (no new ref kind, no commit
586
586
  * 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). */
587
+ * The document is re-read at round completion THROUGH the ledger's plan seam (the
588
+ * ONE plan read point), so a fix that edited the plan binds the edited bytes and
589
+ * the write-back never turns a repoRoot-relative path into a cwd-relative syscall.
590
+ * A null plan path records nothing (present facts only). */
588
591
  #recordReviewedBranchRevision(frame) {
589
- if (this.#planPath === null)
592
+ const planPath = this.#plan.stationPath();
593
+ if (planPath === null)
590
594
  return;
591
- this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
595
+ this.#ledger.recordReviewedPlanRevision(frame.key, planPath);
592
596
  }
593
597
  /** 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
- #recordDocRevisionOf(key, path, identity) {
598
+ * current revision to the line row (the ONE read + hash + record path the doc
599
+ * leg owns; the branch leg binds the plan read it already judged). An unreadable
600
+ * input records nothing — the line keeps the legacy closed face (present facts
601
+ * only). */
602
+ #recordDocRevisionOf(key, path) {
598
603
  try {
599
604
  const content = readFileSync(path, "utf8");
600
- this.#ledger.recordReviewedRevision(key, this.#ledger.refs().docRevision(path, content), identity);
605
+ this.#ledger.recordReviewedRevision(key, this.#ledger.refs().docRevision(path, content));
601
606
  }
602
607
  catch {
603
608
  // unreadable input — no reviewed identity recorded (present facts only)
@@ -625,21 +630,16 @@ export class Lifecycle {
625
630
  this.#recordPlanSnapshot(frame);
626
631
  }
627
632
  /** 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). */
633
+ * read from the SAME plan read the brief hashes (the injected `PlanRead`), so the
634
+ * snapshot and the reviewed basis can never describe two different documents. A
635
+ * non-ready plan records nothing: the snapshot is a present fact only, never a
636
+ * fabricated `[]` (an absent snapshot reads conservatively as "stall" in the wave
637
+ * gate). */
632
638
  #recordPlanSnapshot(frame) {
633
- if (this.#planPath === null)
639
+ const doc = this.#plan.doc();
640
+ if (doc === null)
634
641
  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
- }
642
+ this.#ledger.recordPlanTasks(String(frame.key), doc.taskBlocks.map((block) => block.id));
643
643
  }
644
644
  /** The handoff-family op of a phase — branch-review rides the review family. */
645
645
  #opOf(phase) {
@@ -707,7 +707,7 @@ export class Lifecycle {
707
707
  if (frame.target.kind === "plan" || frame.target.kind === "spec")
708
708
  return frame.target.doc;
709
709
  if (frame.target.kind === "branch")
710
- return this.#planPath;
710
+ return this.#plan.stationPath();
711
711
  return null;
712
712
  }
713
713
  /** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
@@ -727,8 +727,8 @@ export class Lifecycle {
727
727
  return {
728
728
  specType: this.#specType,
729
729
  specPath: this.#specPath,
730
- planPath: this.#planPath,
731
- planGraph: this.#planGraph,
730
+ planPath: this.#plan.stationPath(),
731
+ plan: this.#plan,
732
732
  };
733
733
  }
734
734
  /** Whether the branch line has a dispatchable open round — the wave closure's
@@ -736,7 +736,7 @@ export class Lifecycle {
736
736
  * shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
737
737
  * route combination. */
738
738
  #branchLineOpen() {
739
- return this.#frontier.branchLineOpen(this.#planPath);
739
+ return this.#frontier.branchLineOpen(this.#plan.stationPath());
740
740
  }
741
741
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
742
742
  * interaction point). A success round carries the handoff carrier path; a failure
@@ -771,7 +771,11 @@ export class Lifecycle {
771
771
  #routeTarget(frame) {
772
772
  switch (frame.type) {
773
773
  case "wave":
774
- return { type: "wave", id: frame.params.tasks ?? "", plan: this.#planPath ?? undefined };
774
+ return {
775
+ type: "wave",
776
+ id: frame.params.tasks ?? "",
777
+ plan: this.#plan.stationPath() ?? undefined,
778
+ };
775
779
  case "branch":
776
780
  // The branch line's stable id — the workspace plan path carries the
777
781
  // fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
@@ -780,7 +784,7 @@ export class Lifecycle {
780
784
  return {
781
785
  type: "branch",
782
786
  id: "branch",
783
- plan: this.#planPath ?? undefined,
787
+ plan: this.#plan.stationPath() ?? undefined,
784
788
  };
785
789
  case "phase-spec":
786
790
  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.13.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {