@oscaner-skills/cdd-engine 3.1.0 → 4.0.1

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.
@@ -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 delivery 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 delivery 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 "";
@@ -284,25 +284,25 @@ export class Lifecycle {
284
284
  const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
285
285
  if (outcome.carrier !== undefined || !blocked) {
286
286
  const op = this.#opOf(frame.phase);
287
- // T2 — the engine-built fallback rides the FRAME's declared face (the family's
288
- // `schema` selector, never the outcome's field presence): a findings-face round
289
- // (review / docs-fix) builds the findings carrier — its schema-required findings
290
- // key, empty on a conclusion-only round (a fix advances no new findings); a
291
- // delivery-face round builds the findings-free delivery 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
292
292
  // injection. The review finding-severity route reads the round carrier's
293
- // findings; the conclusion rides only the delivery face's declared status (the
294
- // findings face derives its conclusion at judgment time).
295
- 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);
296
296
  const carrier = outcome.carrier ??
297
- (face === "findings"
298
- ? this.#ledger.buildHandoff("findings", {
297
+ (plane === "judge"
298
+ ? this.#ledger.buildHandoff("judge", {
299
299
  findings: [...(outcome.findings ?? [])],
300
300
  })
301
- : this.#ledger.buildHandoff("delivery", {}));
302
- // The delivery face ALONE persists the conclusion (the child's declared status); the
303
- // findings carrier holds no status — its conclusion derives at judgment time
301
+ : this.#ledger.buildHandoff("work", {}));
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
304
304
  // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
305
- if (face === "delivery" && carrier.status === undefined && outcome.status !== undefined)
305
+ if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
306
306
  carrier.status = outcome.status;
307
307
  this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
308
308
  }
@@ -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.1.0",
3
+ "version": "4.0.1",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {