@oscaner-skills/cdd-engine 4.1.0 → 4.3.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.
Files changed (59) hide show
  1. package/README.md +39 -9
  2. package/README.zh-CN.md +44 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +174 -48
  27. package/dist/face/declare.js +59 -23
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/host.js +9 -35
  30. package/dist/face/init.js +108 -0
  31. package/dist/face/lifecycle.js +540 -123
  32. package/dist/face/plugins.js +73 -0
  33. package/dist/face/preview.js +43 -10
  34. package/dist/face/projection.js +3 -3
  35. package/dist/face/route-render.js +51 -21
  36. package/dist/face/termination.js +135 -261
  37. package/dist/face/words.js +134 -12
  38. package/dist/infra/atomic.js +15 -0
  39. package/dist/infra/git.js +25 -0
  40. package/dist/infra/proc.js +150 -0
  41. package/dist/infra/round-log.js +104 -0
  42. package/dist/infra/runtime.js +16 -4
  43. package/dist/infra/workspace.js +7 -2
  44. package/dist/render/brief.js +15 -17
  45. package/dist/render/skeleton.js +41 -28
  46. package/dist/render/templates.js +128 -84
  47. package/dist/session/faces.js +47 -20
  48. package/dist/session/graph.js +13 -37
  49. package/dist/session/handoff-schema.js +16 -8
  50. package/dist/session/inflight.js +282 -0
  51. package/dist/session/ledger.js +581 -136
  52. package/dist/session/line-identity.js +33 -0
  53. package/dist/session/next.js +138 -80
  54. package/dist/session/preflight.js +276 -68
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +317 -78
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
  59. package/dist/infra/process.js +0 -22
@@ -8,13 +8,19 @@
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 three judgments:
11
+ // the lifecycle's #markTerminal). The judgments, in order (the order is part of the
12
+ // judgment — a shape that matches an earlier row keeps that earlier row's cause):
12
13
  // 1. requested hits a derived static batch (graph.batches()) that mixes closed
13
14
  // and open tasks → the mixed-batch BLOCK (a batch closes as a unit — a plan
14
15
  // 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,
16
+ // 2. the derived wave is wider than MAX_TASKS_PER_WAVE → the wave-too-wide BLOCK
17
+ // (the plan's DependsOn must narrow the wave; the engine never re-shapes it —
18
+ // judged before the exact read so a wide frontier is never misreported as split);
19
+ // 3. the requested set is wider than MAX_TASKS_PER_WAVE → the too-many-tasks BLOCK
20
+ // (never truncated, never silently halved);
21
+ // 4. requested ≠ open → the split/subset BLOCK (dispatch the full derived wave,
16
22
  // with the wave-board hint);
17
- // 3. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
23
+ // 5. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
18
24
  // (v1.28 — the heterogeneous-phase row RETIRED: the wave-unitary ledger has ONE row
19
25
  // per wave, so mixed per-task phases are structurally impossible — a per-task phase
20
26
  // read was the T26 regression {16,22,24} exposed (the row key `16` never matched
@@ -25,6 +31,7 @@
25
31
  //
26
32
  // Module-level exports are types / the class — zero behavior-carrying bare
27
33
  // functions (the plan's zero-bare-function discipline).
34
+ import { MAX_TASKS_PER_WAVE } from "./next.js";
28
35
  /**
29
36
  * WaveGate — the three-verb unified wave gate (implement / review / fix share the
30
37
  * single gate). One OOP method: vet(requested, verb) judges the request against
@@ -44,25 +51,66 @@ export class WaveGate {
44
51
  const wordsGate = words.waveGateWords();
45
52
  const exact = asked.length === open.length && asked.every((id, index) => id === open[index]);
46
53
  // 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).
54
+ // mixes closed and open tasks. A batch closes as a unit, so the leftovers must
55
+ // not ride out as their own wave UNLESS the plan grew them after the closure
56
+ // (the supported append path, P21 §5.1): the closed batch's snapshot is the
57
+ // historical task set, and an open member absent from it was added later —
58
+ // the plan leads the ledger by an append, not by a stranded batch. An absent
59
+ // snapshot (a historical row) keeps the conservative BLOCK. Judged BEFORE the
60
+ // exact read (the derived open wave alone cannot see the closed siblings).
51
61
  const batch = graph.batches().find((derived) => derived.some((id) => requested.has(id)));
52
62
  if (batch?.some((id) => closed.has(id)) && batch.some((id) => !closed.has(id))) {
63
+ const closedMembers = batch.filter((id) => closed.has(id));
64
+ const openMembers = batch.filter((id) => !closed.has(id));
65
+ if (!this.#appendedSinceClosure(ledger, closed, closedMembers, openMembers)) {
66
+ return {
67
+ ok: false,
68
+ reason: "mixed-batch",
69
+ message: this.#fill(wordsGate.mixedBatch, {
70
+ batch: batch.join(","),
71
+ closed: closedMembers.join(","),
72
+ open: openMembers.join(","),
73
+ }),
74
+ open,
75
+ phases: this.#phasesOf(ledger, open),
76
+ };
77
+ }
78
+ }
79
+ // 2. The wave-width hard gate — the derived wave is wider than the ceiling. A wave
80
+ // this wide is a PLAN defect (`DependsOn` layers), so the engine refuses and names
81
+ // the fix instead of re-shaping the wave. Judged BEFORE the exact read: the same
82
+ // shape would otherwise be reported as `split` (requested ≠ open), pointing the
83
+ // author at the wrong repair. The append shape that legitimately widens a wave
84
+ // across layers (a partially closed batch, exempted above) lands here too.
85
+ if (open.length > MAX_TASKS_PER_WAVE) {
86
+ return {
87
+ ok: false,
88
+ reason: "wave-too-wide",
89
+ message: this.#fill(wordsGate.waveTooWide, {
90
+ tasks: openKey,
91
+ max: String(MAX_TASKS_PER_WAVE),
92
+ }),
93
+ open,
94
+ phases: this.#phasesOf(ledger, open),
95
+ };
96
+ }
97
+ // 3. The request-width hard gate — the caller asked for more tasks than a wave may
98
+ // carry. Never truncated and never silently halved: the caller's hand-picked set
99
+ // is not the engine's judgment to reshape.
100
+ if (asked.length > MAX_TASKS_PER_WAVE) {
53
101
  return {
54
102
  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(","),
103
+ reason: "too-many-tasks",
104
+ message: this.#fill(wordsGate.tooManyTasks, {
105
+ tasks: requestedKey,
106
+ count: String(asked.length),
107
+ max: String(MAX_TASKS_PER_WAVE),
60
108
  }),
61
109
  open,
62
110
  phases: this.#phasesOf(ledger, open),
63
111
  };
64
112
  }
65
- // 2. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
113
+ // 4. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
66
114
  // mismatches the derived wave is refused for ANY verb (a subset never reorders
67
115
  // the wave, never half-approves it). The full-wave hint rides the message.
68
116
  if (!exact) {
@@ -74,7 +122,7 @@ export class WaveGate {
74
122
  phases: this.#phasesOf(ledger, open),
75
123
  };
76
124
  }
77
- // 3. The open wave's phase — the single phase of the wave's own row (wave-unitary:
125
+ // 5. The open wave's phase — the single phase of the wave's own row (wave-unitary:
78
126
  // one ledger row per wave, so every member shares the phase; a per-task read
79
127
  // never matches the wave row — the T26 migration regression).
80
128
  const phases = this.#phasesOf(ledger, open);
@@ -90,6 +138,38 @@ export class WaveGate {
90
138
  }
91
139
  return { ok: true, open, phases };
92
140
  }
141
+ /** Whether the batch's open members were APPENDED after its closed members closed
142
+ * — read from the ledger's plan-task snapshot of the most recently closed wave row
143
+ * touching the batch (the row order in progress.json is the write order, so the
144
+ * reverse scan lands on the latest closure). True only when a snapshot exists AND
145
+ * none of the open members is in it: the plan grew the batch afterwards. A missing
146
+ * snapshot (a historical row, or a wave that closed before the fact existed) is
147
+ * never an append — the conservative BLOCK stands (zero migration). */
148
+ #appendedSinceClosure(ledger, closed, closedMembers, openMembers) {
149
+ const data = ledger.readProgress();
150
+ if (data === null)
151
+ return false;
152
+ for (let index = data.waves.length - 1; index >= 0; index -= 1) {
153
+ const row = data.waves[index];
154
+ const ids = row.wave
155
+ .split(",")
156
+ .map((part) => Number(part))
157
+ .filter((id) => Number.isInteger(id) && id > 0);
158
+ if (ids.length === 0)
159
+ continue;
160
+ if (!ids.some((id) => closedMembers.includes(id)))
161
+ continue;
162
+ if (!ids.every((id) => closed.has(id)))
163
+ continue;
164
+ // The snapshot rides the row already in hand — the gate never re-reads and
165
+ // re-parses progress.json once per row on this hot path.
166
+ const snapshot = row.planTasks ?? null;
167
+ if (snapshot === null)
168
+ return false;
169
+ return openMembers.every((id) => !snapshot.includes(id));
170
+ }
171
+ return false;
172
+ }
93
173
  /** The open wave's per-task phases — every member resolves the WAVE row's single
94
174
  * phase (implement → review → fix → re-review → closure; null = no open round). */
95
175
  #phasesOf(ledger, open) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.1.0",
3
+ "version": "4.3.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -20,13 +20,23 @@
20
20
  },
21
21
  "dependencies": {
22
22
  "commander": "^15.0.0",
23
- "execa": "^10.1.1",
23
+ "execa": "^10.2.1",
24
24
  "jsonc-parser": "^3.3.1",
25
+ "mdast-util-from-markdown": "^2.1.0",
26
+ "mdast-util-frontmatter": "^2.0.1",
27
+ "mdast-util-gfm": "^3.1.0",
28
+ "micromark-extension-frontmatter": "^2.0.0",
29
+ "micromark-extension-gfm": "^3.0.0",
30
+ "proper-lockfile": "^4.1.2",
31
+ "ps-list": "^9.0.0",
25
32
  "simple-git": "^4.0.2",
33
+ "write-file-atomic": "^8.0.0",
26
34
  "yaml": "^2.9.1"
27
35
  },
28
36
  "devDependencies": {
29
- "@types/node": "^24.19.2",
37
+ "@types/node": "^26.6.6",
38
+ "@types/proper-lockfile": "^4.1.4",
39
+ "@types/write-file-atomic": "^4.0.3",
30
40
  "typescript": "^7.0.2",
31
41
  "vitest": "^5.0.5"
32
42
  },
@@ -1,22 +0,0 @@
1
- // packages/cdd-engine/src-next/infra/process.ts
2
- // T12 — ProcessRunner: the new tree's process seam. Subprocess invocations are
3
- // async instance methods over the node:child_process execFile — a fail-open run
4
- // returns a { code, stdout, stderr } result (a missing binary or a non-zero exit
5
- // rides the code, never a thrown exception across the seam).
6
- import { execFile } from "node:child_process";
7
- /** ProcessRunner — the subprocess adapter. Stateless and fail-open. */
8
- export class ProcessRunner {
9
- /** Run a command with args in an optional working directory. */
10
- run(command, args, cwd) {
11
- return new Promise((resolve) => {
12
- execFile(command, [...args], { cwd }, (error, stdout, stderr) => {
13
- if (error === null) {
14
- resolve({ code: 0, stdout, stderr });
15
- return;
16
- }
17
- const code = typeof error.code === "number" ? error.code : 1;
18
- resolve({ code, stdout, stderr });
19
- });
20
- });
21
- }
22
- }