@oscaner-skills/cdd-engine 3.0.1 → 4.0.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.
@@ -25,7 +25,7 @@ import { createHash } from "node:crypto";
25
25
  import { readFileSync } from "node:fs";
26
26
  import { BriefRenderer } from "../render/brief.js";
27
27
  import { targetFaces } from "./faces.js";
28
- import { HandoffSchema, } from "./handoff-schema.js";
28
+ import { HandoffSchema } from "./handoff-schema.js";
29
29
  import { NextStepRouter } from "./next.js";
30
30
  import { EMPTY_RUN_STATE } from "./run.js";
31
31
  // ---------------------------------------------------------------------------
@@ -93,7 +93,7 @@ export class Ledger {
93
93
  * the `closedWaves()` read face and the wave gate share the same router). */
94
94
  #router = new NextStepRouter();
95
95
  /** The handoff-schema face — the conclusion single source (`conclusionOf`), one
96
- * instance per ledger (the round verdict derives from the face's own plane at
96
+ * instance per ledger (the round verdict derives from the op's carrier plane at
97
97
  * judgment time · D27). */
98
98
  #handoffSchema = new HandoffSchema();
99
99
  /** The review-reference face (T25) — the refKind classification + the same-ref
@@ -446,6 +446,15 @@ export class Ledger {
446
446
  this.writeProgress(data);
447
447
  return data.timeoutCount;
448
448
  }
449
+ /** Increment the contract-violation counter — the read-back write point (one
450
+ * `handoff-absent` or `contract-violation` crash lands, the count goes up by
451
+ * one). The counter's only writer. */
452
+ incrementContractViolationCount() {
453
+ const data = this.readProgress() ?? this.emptyProgress();
454
+ data.contractViolationCount += 1;
455
+ this.writeProgress(data);
456
+ return data.contractViolationCount;
457
+ }
449
458
  // -------------------------------------------------------------------------
450
459
  // closedWaves — the closure single read face (v1.20)
451
460
  // -------------------------------------------------------------------------
@@ -583,12 +592,12 @@ export class Ledger {
583
592
  throw new Error(`unknown handoff family: ${op}.${type}`);
584
593
  return family;
585
594
  }
586
- /** The handoff FACE of an op/type pair — the family's `schema` selector (work when
587
- * the family declares none). The face-aware read/write/bookkeep spine (T2): a
588
- * findings-face round rides the findings writable subset, a work-face round rides
589
- * the findings-free work subset — never the caller's guess. */
590
- handoffFaceOf(op, type) {
591
- return this.#family(op, type).schema ?? "work";
595
+ /** The carrier PLANE of an op — the ONE op-derived derivation (`HandoffSchema.planeOf`).
596
+ * The plane-aware read/write/bookkeep spine: a judge-plane round (review) rides the
597
+ * findings writable subset, a work-plane round (implement / fix) rides the
598
+ * status-bearing work subset — never the caller's guess, never a per-family declaration. */
599
+ planeOf(op) {
600
+ return HandoffSchema.planeOf(op);
592
601
  }
593
602
  /** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
594
603
  handoffName(op, type, params = {}) {
@@ -600,9 +609,9 @@ export class Ledger {
600
609
  handoffPath(op, type, params = {}) {
601
610
  return this.#workspace.resolve(this.handoffName(op, type, params));
602
611
  }
603
- buildHandoff(face, init = {}) {
612
+ buildHandoff(plane, init = {}) {
604
613
  const carrier = { artifacts: init.artifacts ?? {} };
605
- if (face === "findings" || init.findings !== undefined)
614
+ if (plane === "judge" || init.findings !== undefined)
606
615
  carrier.findings = init.findings;
607
616
  return carrier;
608
617
  }
@@ -729,9 +738,9 @@ export class Ledger {
729
738
  return {
730
739
  phase: "review",
731
740
  // The conclusion is DERIVED from the review carrier's own findings at judgment
732
- // time (D27 · the findings carrier holds no status field) — the single source
733
- // shared with the fix leg below (`HandoffSchema.conclusionOf`).
734
- status: this.#handoffSchema.conclusionOf("findings", carrier),
741
+ // time (D27 · the judge-plane carrier holds no status field) — the single
742
+ // source shared with the fix leg below (`HandoffSchema.conclusionOf`).
743
+ status: this.#handoffSchema.conclusionOf("judge", carrier),
735
744
  findings: this.#findingsOf(carrier),
736
745
  reviewsPath: this.handoffPath("review", type, reviewParams),
737
746
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
@@ -750,9 +759,8 @@ export class Ledger {
750
759
  return {
751
760
  phase: "fix",
752
761
  // The fix round's conclusion derives from ITS OWN carrier's declared plane (the
753
- // work face reads its status; a docs-fix findings face rolls its findings up) —
754
- // the same `conclusionOf` single source (D27).
755
- status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
762
+ // work plane reads its status) — the same `conclusionOf` single source (D27).
763
+ status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
756
764
  findings: this.#findingsOf(reviewCarrier),
757
765
  reviewsPath: this.handoffPath("review", type, reviewParams),
758
766
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
@@ -53,7 +53,7 @@ export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft
53
53
  * frame's plan fact. */
54
54
  export const PIPELINE_NEXT = {
55
55
  "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
56
- "overall-spec": { kind: "done" },
56
+ overall: { kind: "done" },
57
57
  plan: { kind: "ref", ref: "kairos:cdd-dev" },
58
58
  wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
59
59
  branch: { kind: "ref", ref: "kairos:cdd-close" },
@@ -21,10 +21,11 @@
21
21
  //
22
22
  // Module-level exports are types / the class — zero behavior-carrying bare
23
23
  // functions (the plan's zero-bare-function discipline).
24
- import { existsSync, readdirSync, readFileSync } from "node:fs";
25
24
  import { PlanDocType } from "../contract/doc.js";
26
25
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
26
+ import { NodeFs } from "../contract/invariants.js";
27
27
  import { RepoRoot } from "../infra/root.js";
28
+ import { SlugIndex } from "../infra/slug-index.js";
28
29
  import { TaskGraph } from "./graph.js";
29
30
  import { WaveGate } from "./wave.js";
30
31
  /**
@@ -140,11 +141,32 @@ export class PreFlight {
140
141
  };
141
142
  }
142
143
  if (doc.docKey === null) {
144
+ // Two shapes, one gate: a head carrying no `doc-type:` key reads the
145
+ // missing-key word; a head carrying an out-of-domain value reads the
146
+ // word that names the value and lists the declared domain.
147
+ const message = head.docType === null
148
+ ? this.#words.routeWord("docType")
149
+ : this.#words.docTypeValueWord(head.docType);
143
150
  return {
144
151
  ok: false,
145
152
  gate: "doc-contract",
146
153
  reason: "doc-contract",
147
- message: this.#words.routeWord("docType"),
154
+ message,
155
+ order: gates,
156
+ };
157
+ }
158
+ // The identity gate (spec §2.1/§2.2) — same face, same carrier: the
159
+ // workspace key is the declared `slug:`, and the four-way judgment is the
160
+ // SAME `SlugIndex` one the board and the dispatch carrier read (one fact,
161
+ // one rule; this carrier supplies the pre-flight verdict shape only).
162
+ const index = SlugIndex.build(ctx.repoRoot, this.#fs);
163
+ const verdict = index.slugVerdict(doc.path, head.slug);
164
+ if (verdict.kind !== "accepted") {
165
+ return {
166
+ ok: false,
167
+ gate: "doc-contract",
168
+ reason: "doc-contract",
169
+ message: this.#words.slugRefusal(verdict),
148
170
  order: gates,
149
171
  };
150
172
  }
@@ -153,6 +175,9 @@ export class PreFlight {
153
175
  path: docAbsolute,
154
176
  content,
155
177
  root: ctx.repoRoot,
178
+ // The SAME index the identity gates above read — one scan per dispatch,
179
+ // and the contract's chain / slug-ref lookups judge the identical facts.
180
+ slugIndex: index,
156
181
  fs: this.#fs,
157
182
  });
158
183
  if (findings.length > 0) {
@@ -170,25 +195,3 @@ export class PreFlight {
170
195
  return { ok: true, order: gates };
171
196
  }
172
197
  }
173
- /** The node:fs default — the production seam for the doc-contract's file reads. */
174
- class NodeFs {
175
- read(p) {
176
- try {
177
- return readFileSync(p, "utf8");
178
- }
179
- catch {
180
- return null;
181
- }
182
- }
183
- exists(p) {
184
- return existsSync(p);
185
- }
186
- list(p) {
187
- try {
188
- return readdirSync(p);
189
- }
190
- catch {
191
- return [];
192
- }
193
- }
194
- }
@@ -47,7 +47,7 @@ export class RoundNaming {
47
47
  const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
48
48
  return this.#workspace.resolve(`${family}-${this.op(frame)}${suffix}-report.md`);
49
49
  }
50
- /** The prescribed test-evidence path of a round — "" off the work faces (the doc
50
+ /** The prescribed test-evidence path of a round — "" off the evidence rounds (the doc
51
51
  * lines and the review rounds prescribe no evidence file). */
52
52
  evidence(frame) {
53
53
  const name = this.evidenceName(frame);
@@ -55,7 +55,7 @@ export class RoundNaming {
55
55
  }
56
56
  /** The test-evidence file NAME of a work frame — the workspace-relative face the
57
57
  * read-back gate reads it by (`{line}-test-evidence.json`: the task families key
58
- * the line, the branch line names the family alone). "" off the work faces. */
58
+ * the line, the branch line names the family alone). "" off the evidence rounds. */
59
59
  evidenceName(frame) {
60
60
  if (frame.type === "spec" || frame.type === "plan")
61
61
  return "";
@@ -131,6 +131,7 @@ export class Lifecycle {
131
131
  round,
132
132
  route,
133
133
  capsuleLines: this.#capsuleLines(frame, outcome, route),
134
+ termination: outcome.termination,
134
135
  };
135
136
  }
136
137
  // -------------------------------------------------------------------------
@@ -283,25 +284,25 @@ export class Lifecycle {
283
284
  const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
284
285
  if (outcome.carrier !== undefined || !blocked) {
285
286
  const op = this.#opOf(frame.phase);
286
- // T2 — the engine-built fallback rides the FRAME's declared face (the family's
287
- // `schema` selector, never the outcome's field presence): a findings-face round
288
- // (review / docs-fix) builds the findings carrier — its schema-required findings
289
- // key, empty on a conclusion-only round (a fix advances no new findings); a
290
- // work-face round builds the findings-free work carrier — zero findings
287
+ // T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
288
+ // outcome's field presence): a judge-plane round (review) builds the findings
289
+ // carrier — its schema-required findings key, empty on a conclusion-only round
290
+ // (a review advances no new findings); a work-plane round (implement / fix,
291
+ // docs-fix included) builds the findings-free work carrier — zero findings
291
292
  // injection. The review finding-severity route reads the round carrier's
292
- // findings; the conclusion rides only the work face's declared status (the
293
- // findings face derives its conclusion at judgment time).
294
- const face = this.#ledger.handoffFaceOf(op, frame.type);
293
+ // findings; the conclusion rides only the work plane's declared status (the
294
+ // judge plane derives its conclusion at judgment time).
295
+ const plane = this.#ledger.planeOf(op);
295
296
  const carrier = outcome.carrier ??
296
- (face === "findings"
297
- ? this.#ledger.buildHandoff("findings", {
297
+ (plane === "judge"
298
+ ? this.#ledger.buildHandoff("judge", {
298
299
  findings: [...(outcome.findings ?? [])],
299
300
  })
300
301
  : this.#ledger.buildHandoff("work", {}));
301
- // The work face ALONE persists the conclusion (the child's declared status); the
302
- // findings carrier holds no status — its conclusion derives at judgment time
302
+ // The work plane ALONE persists the conclusion (the child's declared status); the
303
+ // judge carrier holds no status — its conclusion derives at judgment time
303
304
  // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
304
- if (face === "work" && carrier.status === undefined && outcome.status !== undefined)
305
+ if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
305
306
  carrier.status = outcome.status;
306
307
  this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
307
308
  }
@@ -400,7 +401,10 @@ export class Lifecycle {
400
401
  return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
401
402
  }
402
403
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
403
- * interaction point). The blocker cell carries the round's blocker count; the
404
+ * interaction point). A success round carries the real blocker count and the
405
+ * handoff carrier path. A failure round (TIMEOUT / BLOCKED) carries no blocker
406
+ * cell (its count would be a filler); its handoff cell is the crash record and is
407
+ * emitted only when that record exists (a no-host BLOCKED writes none). The
404
408
  * dispatch-ready `next:` literal rides the frame's own RouteTarget identity
405
409
  * (type + id — the v1.25 combination point: frame.type + params.tasks + route
406
410
  * are all present here). */
@@ -408,9 +412,17 @@ export class Lifecycle {
408
412
  if (this.#capsule === null)
409
413
  return [];
410
414
  const op = this.#opOf(frame.phase);
415
+ const failure = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
416
+ const lane = `${op}.${frame.type}`;
417
+ // The failure face's handoff is the crash record — the engine's own postmortem
418
+ // artifact, its existence the emission condition; the success face keeps the
419
+ // round's handoff carrier path.
420
+ const crash = failure ? this.#ledger.readCrash(lane, frame.round) : null;
411
421
  const blockers = (outcome.findings ?? []).filter((finding) => finding.severity === "blocker").length;
412
- const handoff = this.#ledger.handoffPath(op, frame.type, frame.params);
413
- return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame));
422
+ const handoff = crash !== null
423
+ ? this.#ledger.crashPath(lane, frame.round)
424
+ : this.#ledger.handoffPath(op, frame.type, frame.params);
425
+ return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame), crash !== null);
414
426
  }
415
427
  /** The frame's RouteTarget — the dispatch-ready literal's target identity (the
416
428
  * frame's own facts: the wave task key · the branch line key · the doc path).
@@ -8,10 +8,13 @@
8
8
  //
9
9
  // The gate's only read face is `open = frontier(closedWaves())` — the derived
10
10
  // wave over the ledger's C5 closure set (ledger.ts, the same closure predicate as
11
- // the lifecycle's #markTerminal). The two judgments:
12
- // 1. requested ≠ open → the split/subset BLOCK (dispatch the full derived wave,
11
+ // the lifecycle's #markTerminal). The three judgments:
12
+ // 1. requested hits a derived static batch (graph.batches()) that mixes closed
13
+ // and open tasks → the mixed-batch BLOCK (a batch closes as a unit — a plan
14
+ // revision must not strand the rest of a partly-executed batch as its own wave);
15
+ // 2. requested ≠ open → the split/subset BLOCK (dispatch the full derived wave,
13
16
  // with the wave-board hint);
14
- // 2. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
17
+ // 3. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
15
18
  // (v1.28 — the heterogeneous-phase row RETIRED: the wave-unitary ledger has ONE row
16
19
  // per wave, so mixed per-task phases are structurally impossible — a per-task phase
17
20
  // read was the T26 regression {16,22,24} exposed (the row key `16` never matched
@@ -25,8 +28,9 @@
25
28
  /**
26
29
  * WaveGate — the three-verb unified wave gate (implement / review / fix share the
27
30
  * single gate). One OOP method: vet(requested, verb) judges the request against
28
- * the derived open wave + the ledger's per-task phases; the CLI calls it before
29
- * ANY task-face dispatch, never a variant gate per verb.
31
+ * the plan's static batches, the derived open wave, and the ledger's per-task
32
+ * phases; the CLI calls it before ANY task-face dispatch, never a variant gate per
33
+ * verb.
30
34
  */
31
35
  export class WaveGate {
32
36
  /** vet(requested, verb, graph, ledger, words) — the three-verb gate: the verdict
@@ -39,7 +43,26 @@ export class WaveGate {
39
43
  const openKey = open.join(",");
40
44
  const wordsGate = words.waveGateWords();
41
45
  const exact = asked.length === open.length && asked.every((id, index) => id === open[index]);
42
- // 1. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
46
+ // 1. The static-batch mix BLOCK — the requested set hits a derived batch that
47
+ // mixes closed and open tasks. A batch closes as a unit: a plan revision
48
+ // that adds tasks to a partly-executed batch must re-declare the edges, not
49
+ // let the leftover tasks ride out as their own wave. Judged BEFORE the exact
50
+ // read (the derived open wave alone cannot see the closed batch siblings).
51
+ const batch = graph.batches().find((derived) => derived.some((id) => requested.has(id)));
52
+ if (batch?.some((id) => closed.has(id)) && batch.some((id) => !closed.has(id))) {
53
+ return {
54
+ ok: false,
55
+ reason: "mixed-batch",
56
+ message: this.#fill(wordsGate.mixedBatch, {
57
+ batch: batch.join(","),
58
+ closed: batch.filter((id) => closed.has(id)).join(","),
59
+ open: batch.filter((id) => !closed.has(id)).join(","),
60
+ }),
61
+ open,
62
+ phases: this.#phasesOf(ledger, open),
63
+ };
64
+ }
65
+ // 2. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
43
66
  // mismatches the derived wave is refused for ANY verb (a subset never reorders
44
67
  // the wave, never half-approves it). The full-wave hint rides the message.
45
68
  if (!exact) {
@@ -51,7 +74,7 @@ export class WaveGate {
51
74
  phases: this.#phasesOf(ledger, open),
52
75
  };
53
76
  }
54
- // 2. The open wave's phase — the single phase of the wave's own row (wave-unitary:
77
+ // 3. The open wave's phase — the single phase of the wave's own row (wave-unitary:
55
78
  // one ledger row per wave, so every member shares the phase; a per-task read
56
79
  // never matches the wave row — the T26 migration regression).
57
80
  const phases = this.#phasesOf(ledger, open);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "3.0.1",
3
+ "version": "4.0.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {