@oscaner-skills/cdd-engine 4.2.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 (55) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +43 -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 +116 -35
  27. package/dist/face/declare.js +36 -18
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/init.js +1 -1
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/preview.js +43 -10
  32. package/dist/face/route-render.js +51 -21
  33. package/dist/face/termination.js +135 -261
  34. package/dist/face/words.js +134 -12
  35. package/dist/infra/atomic.js +15 -0
  36. package/dist/infra/git.js +25 -0
  37. package/dist/infra/proc.js +150 -0
  38. package/dist/infra/round-log.js +104 -0
  39. package/dist/infra/runtime.js +16 -4
  40. package/dist/infra/workspace.js +7 -2
  41. package/dist/render/brief.js +15 -17
  42. package/dist/render/skeleton.js +41 -28
  43. package/dist/render/templates.js +128 -84
  44. package/dist/session/faces.js +47 -20
  45. package/dist/session/graph.js +13 -37
  46. package/dist/session/handoff-schema.js +16 -8
  47. package/dist/session/inflight.js +282 -0
  48. package/dist/session/ledger.js +581 -136
  49. package/dist/session/line-identity.js +33 -0
  50. package/dist/session/next.js +138 -80
  51. package/dist/session/preflight.js +276 -68
  52. package/dist/session/round-naming.js +56 -8
  53. package/dist/session/run.js +317 -78
  54. package/dist/session/wave.js +94 -14
  55. package/package.json +13 -3
package/dist/face/gate.js CHANGED
@@ -1,16 +1,22 @@
1
1
  // packages/cdd-engine/src-next/face/gate.ts
2
2
  // T8 — the split contract's gate face (§6.2: face/gate.ts — the target/line gate
3
3
  // family). The work commands' readiness gates — the single-target line's phase
4
- // derivation (#lineGate/#linePhase/#lineKey/#lineParams/#lineRoundRoute/#lineFixRoute),
5
- // the doc line's revision-aware BLOCK + pending-fix faces (#docLineBlock/
6
- // #pendingFixBlock/#docContent/#docVersionOf) and the group/line helpers
7
- // (#tasksOf/#renderBrief/#refFromHandoff). The method bodies are the pre-split Cli
8
- // members moved verbatim — behavior bytes identical; the root Cli holds the gate
9
- // instance and composes through it via its .action thin shells (zero bare functions).
4
+ // derivation (lineGate/#linePhase/#lineKey), the doc line's revision-aware BLOCK +
5
+ // pending-fix faces (#docLineBlock/#pendingFixBlock/#docContent/#docVersionOf), the
6
+ // ONE line-hop object the CLI refusal renders (lineHop + lineHopMessage, P22 §5.2)
7
+ // and the group/line helpers (#tasksOf/#renderBrief). The method bodies are the
8
+ // pre-split Cli members moved verbatim — behavior bytes identical; the root Cli
9
+ // holds the gate instance and composes through it via its .action thin shells (zero
10
+ // bare functions).
10
11
  import { readFileSync } from "node:fs";
12
+ import process from "node:process";
11
13
  import { FrontMatterExtractor } from "../contract/frontmatter.js";
12
14
  import { BriefRenderer } from "../render/brief.js";
13
15
  import { RoundNaming } from "../session/round-naming.js";
16
+ import { BoardView } from "./board-view.js";
17
+ import { ARGV_CHANNEL } from "./declare.js";
18
+ import { HostDetect } from "./host.js";
19
+ import { RouteRenderer } from "./route-render.js";
14
20
  /**
15
21
  * CliGate — the target/line gate family (the split contract's gate face): the
16
22
  * readiness judgments the work commands consult before dispatching a round. The
@@ -29,40 +35,54 @@ export class CliGate {
29
35
  * only the derived pending face, never a recomputed one. The task face holds no
30
36
  * separate gate here: the WaveGate's wrong-phase verdict (the pre-flight) IS the
31
37
  * task-face phase authority — the wave gate is the single phase authority. A
32
- * doc line's gate is the reviewGate method family (T8 · §3.5 · judgment order =
33
- * doc revision FIRST, shared by the lifecycle's frame phase so an opened gate
34
- * dispatches): a moved doc opens the review lead whatever the round/route state
35
- * says (fix after · backfill after · user-decision after are the SAME case — the
36
- * stuck "next round is fix after an aborted fix" never freezes a revised doc),
37
- * an unchanged doc yields the gate's "same" verdict — the pending fix DERIVED
38
- * from the latest review's non-APPROVED conclusion opens only the fix phase,
39
- * while the no-pending face falls back to the legacy rounds/routes judgment: a
40
- * completed-fix line reopens the review lead through its fix round's C5-1 route
41
- * (the lifecycle's own fall-through — an open gate and a dispatchable frame
42
- * agree), a truly closed line keeps the revision-aware BLOCK. An unbound line
43
- * (no identity on record / an unreadable doc) keeps the legacy round/route
44
- * judgment + the generic closed message (only present facts land). */
38
+ * doc line's gate is the reviewGate method family (T8 · §3.5), shared by the
39
+ * lifecycle's frame phase so an opened gate dispatches: a moved doc reopens the
40
+ * review lead on a line whose C5 hop is on the EXIT side (a closed line, `null`,
41
+ * or a face-to-face station — the ONE `Ledger#docReopens` judgment), while a
42
+ * still-pending fix keeps its hop (drift never outranks it, §5.5 ②) so the gate
43
+ * never refuses the round the ONE derivation names. An unchanged doc yields the
44
+ * gate's "same" verdict — the pending fix DERIVED from the latest review's
45
+ * non-APPROVED conclusion opens only the fix phase, while the no-pending face
46
+ * falls back to the legacy rounds/routes judgment: a completed-fix line reopens
47
+ * the review lead through its fix round's C5-1 route (the lifecycle's own
48
+ * fall-through — an open gate and a dispatchable frame agree), a truly closed line
49
+ * keeps the revision-aware BLOCK. An unbound line (no identity on record / an
50
+ * unreadable doc) keeps the legacy round/route judgment + the generic closed
51
+ * message (only present facts land).
52
+ *
53
+ * The branch line rides the SAME drift leg (its identity document is the PLAN,
54
+ * P21 §3/§4.1 — the very document a branch re-review judges): a plan revision
55
+ * moved past the bound one reopens the branch face onto its `branch-review`
56
+ * lead, so the `next:` a closure hands the user is never a command this gate
57
+ * refuses. An unchanged plan falls through to the SAME derived faces the doc lines
58
+ * reach: a branch review that left findings yields the derived `fix` face
59
+ * (`pending-fix` — no doc-class BLOCK message binds the branch face, so the refusal
60
+ * renders through the ONE line hop), while only a fully closed, drift-free branch
61
+ * line keeps the generic `face-closed` row. */
45
62
  lineGate(scene) {
46
- if (scene.target?.kind === "plan" || scene.target?.kind === "spec") {
47
- const key = this.#lineKey(scene);
48
- if (key === null)
49
- return { phase: null, verdict: null, reviewed: null };
50
- const verdict = scene.ledger.reviewGate(key, scene.target.doc, scene.face.type);
51
- if (verdict.kind === "open") {
52
- return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
53
- }
54
- if (verdict.kind === "same") {
55
- if (verdict.pending) {
56
- return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
57
- }
58
- // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
59
- // own fall-through): a completed-fix line reopens the review lead through its
60
- // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
61
- const open = this.#linePhase(scene);
62
- return open !== null
63
- ? { phase: open, verdict: null, reviewed: null }
64
- : { phase: null, verdict: "same", reviewed: verdict.reviewed };
63
+ const key = this.#lineKey(scene);
64
+ const doc = this.#docOf(scene);
65
+ const verdict = key !== null && doc !== null ? scene.ledger.reviewGate(key, doc, scene.face.type) : null;
66
+ // The drift leg reads the ONE reopen judgment (exit-side routes only): a moved doc
67
+ // reopens the review lead on a line whose C5 hop is gone, while a still-pending
68
+ // fix keeps its own hop — drift never outranks it (§5.1 · §5.5 ②), so this gate
69
+ // always accepts the round the ONE derivation names.
70
+ if (key !== null &&
71
+ verdict !== null &&
72
+ scene.ledger.docReopens(key, scene.face.type, verdict)) {
73
+ return { phase: scene.face.product.reviewLead, verdict: null, reviewed: null };
74
+ }
75
+ if (verdict !== null && verdict.kind === "same") {
76
+ if (verdict.pending) {
77
+ return { phase: "fix", verdict: "pending-fix", reviewed: verdict.reviewed };
65
78
  }
79
+ // same + no pending fix — the legacy rounds/routes judgment (the lifecycle's
80
+ // own fall-through): a completed-fix line reopens the review lead through its
81
+ // fix round's C5-1 route; a truly closed line keeps the revision-aware BLOCK.
82
+ const open = this.#linePhase(scene);
83
+ return open !== null
84
+ ? { phase: open, verdict: null, reviewed: null }
85
+ : { phase: null, verdict: "same", reviewed: verdict.reviewed };
66
86
  }
67
87
  const open = this.#linePhase(scene);
68
88
  return { phase: open, verdict: null, reviewed: null };
@@ -92,6 +112,62 @@ export class CliGate {
92
112
  return null;
93
113
  return `the pending fix applies to the unchanged doc (doc-hash ${reviewed.doc_hash.slice(0, 12)}…) — run cdd fix first`;
94
114
  }
115
+ /** lineHop(scene) — the line's ONE next-hop object (§5.2): the SAME derivation
116
+ * the capsule, the board and the lifecycle frontier read, built from this line's
117
+ * facts through `Ledger#nextHopOf` (the ONE assembly entry: the drift gate + the
118
+ * declaration read). The CLI rejection message renders THIS object's `reason` +
119
+ * hop/station — never a second judgment, never a second shape. The doc-class
120
+ * discrimination is ROOTED in the workspace's own repo basis (the same basis the
121
+ * lifecycle frontier injects), so an engine invoked from a subdirectory reads the
122
+ * same declared `doc-type:` the board does. Null when the scene holds no
123
+ * registered line (no fixed target → there is no line to name). */
124
+ lineHop(scene) {
125
+ const key = this.#lineKey(scene);
126
+ const target = this.#routeTargetOf(scene);
127
+ if (key === null || target === null)
128
+ return null;
129
+ const basis = scene.workspace.root.basis;
130
+ return scene.ledger.nextHopOf({
131
+ type: scene.face.type,
132
+ key,
133
+ route: scene.ledger.lineRoute(key, scene.face.type),
134
+ target,
135
+ doc: this.#docOf(scene),
136
+ docClassOf: (candidate) => BoardView.docClassOf(basis, candidate),
137
+ });
138
+ }
139
+ /** lineHopMessage(scene, hop, words) — the CLI rejection prose of one `NextHop`
140
+ * (P22 §5.2, the ONE message shape): a hop names its verb, a closed face names
141
+ * its handoff station (rendered through the SAME route renderer the `next:` line
142
+ * uses), and neither renders an invented verb slot. */
143
+ lineHopMessage(scene, hop, words) {
144
+ if (hop === null)
145
+ return "the line holds no open round";
146
+ const renderer = new RouteRenderer(words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis);
147
+ return scene.router.message(hop, (entry) => renderer.render({ kind: "handoff", entry }, hop.target));
148
+ }
149
+ /** The line's judged document — the doc line's own path, the branch line's plan
150
+ * (its identity document, P21 §4.1); null off the doc faces. */
151
+ #docOf(scene) {
152
+ if (scene.target?.kind === "plan" || scene.target?.kind === "spec")
153
+ return scene.target.doc;
154
+ if (scene.target?.kind === "branch")
155
+ return scene.planPath;
156
+ return null;
157
+ }
158
+ /** The dispatch frame's own render target (§5.2's `target` cell) — the fixed
159
+ * line's type + stable key (+ the plan fact the branch literal needs). A doc shape
160
+ * (the `--spec` channel: phase-spec / overall / single-spec) renders its OWN
161
+ * target-type word, never a folded `spec` spelling. */
162
+ #routeTargetOf(scene) {
163
+ if (scene.target?.kind === "branch")
164
+ return { type: "branch", id: "branch", plan: scene.planPath ?? undefined };
165
+ if (scene.target?.kind === "spec")
166
+ return { type: scene.face.type, id: scene.target.doc };
167
+ if (scene.target?.kind === "plan")
168
+ return { type: "plan", id: scene.target.doc };
169
+ return null;
170
+ }
95
171
  /** The requested group ints — the normalized tasks value split. */
96
172
  tasksOf(parsed) {
97
173
  return (parsed.args.tasks ?? "").split(",").map((part) => Number(part));
@@ -120,8 +196,9 @@ export class CliGate {
120
196
  return scene.ledger.linePhase(key, scene.face.type);
121
197
  }
122
198
  /** The line key of a fixed-target face — the line's STABLE key (find #9 · spec
123
- * §6.5/§3.7 — `"branch"` per workspace for the branch line; the doc line keys by
124
- * its line-type constant `"spec"`/`"plan"` — never the argv path: a moved argv
199
+ * §6.5/§3.7 — `"branch"` per workspace for the branch line; a doc line keys by
200
+ * its target-type word (`"phase-spec"` / `"overall"` / `"plan"` / `"single-spec"`)
201
+ * — never the argv path: a moved argv
125
202
  * string must not fork the same line into two ledger rows, resetting its round),
126
203
  * the lifecycle's own key derivation (run.ts #lineKey). */
127
204
  #lineKey(scene) {
package/dist/face/init.js CHANGED
@@ -23,7 +23,7 @@
23
23
  // a step is spawned.
24
24
  //
25
25
  // The dispatch execution machine (`face/termination.ts` — timeout / budget / group
26
- // kill / heartbeat / stall judge) is never shared: a bootstrap step has no round,
26
+ // kill / sampling trail / stall judge) is never shared: a bootstrap step has no round,
27
27
  // no ceiling and no session state.
28
28
  //
29
29
  // Module-level exports are types / declared constants / classes — zero