@oscaner-skills/cdd-engine 4.4.0 → 4.6.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.
@@ -55,16 +55,17 @@ export { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
55
55
  export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft-cap"];
56
56
  /** The pipeline next table — the ONE face-indirection source (D33 · single-addressed
57
57
  * at session/next.ts), keyed by the SAME TargetType the CLI declares: the target
58
- * type → the next pipeline entrypoint. The two program-level rows (`overall` and
59
- * the standalone `single-spec`) are the pipeline's terminals — nothing follows a
60
- * closed charter line. The skill refs ride REFS (face/host.ts) resolved per host
61
- * at the render — never a hard-coded plugin spelling; the wave literal's `<plan>`
62
- * slot is filled by the capsule with the frame's plan fact. */
58
+ * type → the next pipeline entrypoint. The ONE program-level terminal row is
59
+ * `overall` — nothing follows a closed charter line; a closed `single-spec` is a
60
+ * spec line like any other, so it hands off to `cdd-plan`. The skill refs ride REFS
61
+ * (face/host.ts) resolved per host at the render — never a hard-coded plugin
62
+ * spelling; the wave literal's `<plan>` slot is filled by the capsule with the
63
+ * frame's plan fact. */
63
64
  export const PIPELINE_NEXT = {
64
65
  "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
65
66
  overall: { kind: "done" },
66
67
  plan: { kind: "ref", ref: "kairos:cdd-dev" },
67
- "single-spec": { kind: "done" },
68
+ "single-spec": { kind: "ref", ref: "kairos:cdd-plan" },
68
69
  wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
69
70
  branch: { kind: "ref", ref: "kairos:cdd-close" },
70
71
  };
@@ -73,17 +74,55 @@ export const PIPELINE_NEXT = {
73
74
  * `PipelineFrontier` iterates it, so a consumer maps key → facts and declares NO
74
75
  * order of its own. */
75
76
  export const PIPELINE_FACES = ["phase-spec", "plan", "wave", "branch"];
76
- /** The single reason table (§5.2) — every `NextHop.reason` value comes from here, so
77
- * the four read faces and the CLI rejection message name a fact by ONE spelling (a
78
- * hyphenated fact name, never a sentence). */
77
+ /** The single reason table (§2.5) — every refusal row and every `NextHop.reason`
78
+ * value names a fact by ONE spelling from here (a hyphenated fact name, never a
79
+ * sentence). The structure rows reuse the pre-flight gate ids as their tokens (no
80
+ * newly minted token); the line rows are the wave gate's five plus the doc/branch
81
+ * refusals (including the same-revision `unchanged` row); the station rows are the
82
+ * signs a `next:` hop is named by. */
83
+ export const DISPATCH_REASON = {
84
+ // structure — the pre-flight gate ids, reused as tokens
85
+ treeClean: { token: "tree-clean", leg: "structure" },
86
+ inFlight: { token: "in-flight", leg: "structure" },
87
+ graph: { token: "graph", leg: "structure" },
88
+ planLedger: { token: "plan-ledger", leg: "structure" },
89
+ docContract: { token: "doc-contract", leg: "structure" },
90
+ // line — the wave gate's five rows
91
+ mixedBatch: { token: "mixed-batch", leg: "line" },
92
+ waveTooWide: { token: "wave-too-wide", leg: "line" },
93
+ tooManyTasks: { token: "too-many-tasks", leg: "line" },
94
+ split: { token: "split", leg: "line" },
95
+ wrongPhase: { token: "wrong-phase", leg: "line" },
96
+ // line — the doc/branch refusals
97
+ pendingFix: { token: "pending-fix", leg: "line" },
98
+ unchanged: { token: "unchanged", leg: "line" },
99
+ closedLine: { token: "closed-line", leg: "line" },
100
+ faceClosed: { token: "face-closed", leg: "line" },
101
+ // station — the signs a `next:` hop is named by
102
+ docDrift: { token: "doc-drift", leg: "station" },
103
+ softCap: { token: "soft-cap", leg: "station" },
104
+ taskOpen: { token: "task-open", leg: "station" },
105
+ docClassBlocked: { token: "doc-class-blocked", leg: "station" },
106
+ };
107
+ /** The wave gate's five rows — the table's `leg: "line"` wave rows as a typed view
108
+ * (the token spellings live in the table ONLY; `wave.ts` carries no second copy). */
109
+ export const WAVE_GATE_REASON = {
110
+ mixedBatch: DISPATCH_REASON.mixedBatch.token,
111
+ waveTooWide: DISPATCH_REASON.waveTooWide.token,
112
+ tooManyTasks: DISPATCH_REASON.tooManyTasks.token,
113
+ split: DISPATCH_REASON.split.token,
114
+ wrongPhase: DISPATCH_REASON.wrongPhase.token,
115
+ };
116
+ /** The named accessors for `NextHop.reason` — every value is the table's own token
117
+ * (one spelling source; the hop reason domain spans both the line and station legs). */
79
118
  export const NEXT_HOP_REASON = {
80
- docDrift: "doc-drift",
81
- pendingFix: "pending-fix",
82
- closedLine: "closed-line",
83
- faceClosed: "face-closed",
84
- softCap: "soft-cap",
85
- taskOpen: "task-open",
86
- docClassBlocked: "doc-class-blocked",
119
+ docDrift: DISPATCH_REASON.docDrift.token,
120
+ pendingFix: DISPATCH_REASON.pendingFix.token,
121
+ closedLine: DISPATCH_REASON.closedLine.token,
122
+ faceClosed: DISPATCH_REASON.faceClosed.token,
123
+ softCap: DISPATCH_REASON.softCap.token,
124
+ taskOpen: DISPATCH_REASON.taskOpen.token,
125
+ docClassBlocked: DISPATCH_REASON.docClassBlocked.token,
87
126
  };
88
127
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
89
128
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
@@ -215,6 +215,19 @@ export class PipelineFrontier {
215
215
  return WAVE_ROUND_MODES.some((mode) => this.#ledger.roundCount(key, mode) > 0);
216
216
  });
217
217
  }
218
+ /** Whether the wave FACE was ever entered — the face-level predicate (P25 §6), never
219
+ * a per-key one (the private scan's own judgment). Public because the dispatch
220
+ * authority's upstream leg asks the SAME question (P27 §2.3: a face the pipeline
221
+ * never entered holds no station), and no second entered-scan may exist. */
222
+ wavesEntered(graph) {
223
+ return this.#wavesEntered(graph);
224
+ }
225
+ /** Whether every derived wave is done — the wave face's closure cell (a plan with
226
+ * no wave holds nothing closed). Public for the same reason as `wavesEntered`: the
227
+ * upstream leg's criterion ② reads this ONE judge, never a local task walk. */
228
+ wavesExhausted(graph) {
229
+ return this.#wavesExhausted(graph);
230
+ }
218
231
  /** Whether every derived wave is done — the wave face's closure cell (a plan with
219
232
  * no wave holds nothing closed). */
220
233
  #wavesExhausted(graph) {
@@ -1,14 +1,16 @@
1
1
  // packages/cdd-engine/src-next/session/preflight.ts
2
- // P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the dispatch gates
2
+ // P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the STRUCTURE gates
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 plan/ledger structure gate (`plan-ledger`, P21 §3.1/§6.4), the
7
- // wave-side gates (graph validate + the three-verb WaveGate) and the doc-side gate
8
- // (Contract.validate over the target doc).
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.
9
11
  //
10
12
  // Gate order (the design's pinned sequence, judgeable on every verdict):
11
- // tree-clean → in-flight → graph → plan-ledger → (wave face) WaveGate.vet →
13
+ // tree-clean → in-flight → graph → plan-ledger →
12
14
  // (spec/plan faces) Contract.validate → dispatch
13
15
  // The evidence/read-back gates stay at the dispatch child face (the seam never
14
16
  // touches the round's produced artifacts — non-pre-flight by design).
@@ -32,7 +34,6 @@ import { SlugIndex } from "../infra/slug-index.js";
32
34
  import { TargetFaceTable } from "./faces.js";
33
35
  import { TaskGraph } from "./graph.js";
34
36
  import { RoundRecords } from "./ledger.js";
35
- import { WaveGate } from "./wave.js";
36
37
  /**
37
38
  * PreFlight — the single pre-flight seam of the work dispatch. One `vet` call runs
38
39
  * the whole gate sequence in the pinned order and returns the verdict the CLI
@@ -44,8 +45,6 @@ export class PreFlight {
44
45
  #git;
45
46
  /** The doc-contract coordinator the doc faces judge through. */
46
47
  #contract;
47
- /** The three-verb unified wave gate the wave face consults. */
48
- #waveGate;
49
48
  /** The word table the BLOCK wording rides. */
50
49
  #words;
51
50
  /** The filesystem seam the doc-contract gate reads (defaults to node:fs). */
@@ -54,12 +53,11 @@ export class PreFlight {
54
53
  this.#git = opts.git;
55
54
  this.#contract = opts.contract;
56
55
  this.#words = opts.words;
57
- this.#waveGate = opts.waveGate ?? new WaveGate();
58
56
  this.#fs = opts.fs ?? new NodeFs();
59
57
  }
60
58
  /** vet(ctx) — the single seam call: tree-clean → in-flight → graph → plan-ledger
61
- * → wave → doc-contract. The first refused gate owns the verdict; the gates that
62
- * ran precede it (the judgeable order). */
59
+ * → doc-contract. The first refused gate owns the verdict; the gates that ran
60
+ * precede it (the judgeable order). */
63
61
  async vet(ctx) {
64
62
  const gates = [];
65
63
  const checked = [];
@@ -135,21 +133,7 @@ export class PreFlight {
135
133
  }
136
134
  }
137
135
  }
138
- // 5. wave — the three-verb unified wave gate.
139
- if (ctx.type === "wave" && graph !== null && ctx.ledger !== null && ctx.tasks !== null) {
140
- gates.push("wave");
141
- checked.push("wave");
142
- const verdict = this.#waveGate.vet(ctx.tasks, ctx.verb, graph, ctx.ledger, this.#words);
143
- if (!verdict.ok) {
144
- return this.#refusal({
145
- ok: false,
146
- gate: "wave",
147
- reason: verdict.reason,
148
- message: verdict.message ?? "",
149
- }, gates, checked, this.#docOutcomeOf(ctx), ledgerOutcome);
150
- }
151
- }
152
- // 6. doc-contract — the doc shapes' structural gate (the doc-scope rules).
136
+ // 5. doc-contract — the doc shapes' structural gate (the doc-scope rules).
153
137
  // The four document shapes (`phase-spec` · `overall` · `plan` · `single-spec`)
154
138
  // are judged by the SAME gate: the document's declared `doc-type:` picks the
155
139
  // contract, never the command's `--type` spelling.
@@ -184,13 +184,13 @@ export class Lifecycle {
184
184
  this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
185
185
  }
186
186
  /** The session-plane default discrimination — the target type's own pipeline key.
187
- * Every target type but the standalone `single-spec` IS a pipeline key (the
188
- * `PipelineKey` derivation), so the map is the identity plus the one terminal row
189
- * (a single-spec carries no pipeline seam). The declaration-reading judgment (a
190
- * doc's `doc-type:`) belongs to the face plane; the composition root injects it as
191
- * `BoardView.docClassOf`. */
187
+ * Every declared target type IS a pipeline key (the `PipelineKey` derivation), so
188
+ * the map is the identity: a standalone `single-spec` reads as `single-spec` and its
189
+ * closure hands off to `cdd-plan` like any other spec line. The declaration-reading
190
+ * judgment (a doc's `doc-type:`) belongs to the face plane; the composition root
191
+ * injects it as `BoardView.docClassOf`. */
192
192
  static #docClassByType(target) {
193
- return target.type === "single-spec" ? "terminal" : target.type;
193
+ return target.type;
194
194
  }
195
195
  /** The face row this instance drives. */
196
196
  face() {
@@ -517,7 +517,8 @@ export class Lifecycle {
517
517
  }
518
518
  /** The reviewed-revision write-back — bind the completed round's input revision to
519
519
  * the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
520
- * doc face binds its target doc's whole-content revision; the wave face binds its
520
+ * doc face binds its target doc's BODY revision (the front matter and
521
+ * `## Change history` projected away, P26 T1); the wave face binds its
521
522
  * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
522
523
  * never the whole plan: transcript edits outside the wave's task sections must not
523
524
  * void a reviewed wave). An unreadable input records nothing — the line keeps the
@@ -31,7 +31,7 @@
31
31
  //
32
32
  // Module-level exports are types / the class — zero behavior-carrying bare
33
33
  // functions (the plan's zero-bare-function discipline).
34
- import { MAX_TASKS_PER_WAVE } from "./next.js";
34
+ import { MAX_TASKS_PER_WAVE, WAVE_GATE_REASON } from "./next.js";
35
35
  /**
36
36
  * WaveGate — the three-verb unified wave gate (implement / review / fix share the
37
37
  * single gate). One OOP method: vet(requested, verb) judges the request against
@@ -65,7 +65,7 @@ export class WaveGate {
65
65
  if (!this.#appendedSinceClosure(ledger, closed, closedMembers, openMembers)) {
66
66
  return {
67
67
  ok: false,
68
- reason: "mixed-batch",
68
+ reason: WAVE_GATE_REASON.mixedBatch,
69
69
  message: this.#fill(wordsGate.mixedBatch, {
70
70
  batch: batch.join(","),
71
71
  closed: closedMembers.join(","),
@@ -85,7 +85,7 @@ export class WaveGate {
85
85
  if (open.length > MAX_TASKS_PER_WAVE) {
86
86
  return {
87
87
  ok: false,
88
- reason: "wave-too-wide",
88
+ reason: WAVE_GATE_REASON.waveTooWide,
89
89
  message: this.#fill(wordsGate.waveTooWide, {
90
90
  tasks: openKey,
91
91
  max: String(MAX_TASKS_PER_WAVE),
@@ -100,7 +100,7 @@ export class WaveGate {
100
100
  if (asked.length > MAX_TASKS_PER_WAVE) {
101
101
  return {
102
102
  ok: false,
103
- reason: "too-many-tasks",
103
+ reason: WAVE_GATE_REASON.tooManyTasks,
104
104
  message: this.#fill(wordsGate.tooManyTasks, {
105
105
  tasks: requestedKey,
106
106
  count: String(asked.length),
@@ -116,7 +116,7 @@ export class WaveGate {
116
116
  if (!exact) {
117
117
  return {
118
118
  ok: false,
119
- reason: "split",
119
+ reason: WAVE_GATE_REASON.split,
120
120
  message: this.#fill(wordsGate.split, { requested: requestedKey, open: openKey }),
121
121
  open,
122
122
  phases: this.#phasesOf(ledger, open),
@@ -130,7 +130,7 @@ export class WaveGate {
130
130
  if (phase !== verb) {
131
131
  return {
132
132
  ok: false,
133
- reason: "wrong-phase",
133
+ reason: WAVE_GATE_REASON.wrongPhase,
134
134
  message: this.#fill(wordsGate.wrongPhase, { phase: phase ?? "held" }),
135
135
  open,
136
136
  phases,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.4.0",
3
+ "version": "4.6.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {