@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
@@ -0,0 +1,33 @@
1
+ // packages/cdd-engine/src-next/session/line-identity.ts
2
+ // T3 — LineIdentity: the ONE drift judgment of the three line kinds (P21 §4.1).
3
+ // Today's session carried two parallel comparisons (the doc line's doc-revision and
4
+ // the wave line's brief-revision); the branch line had none at all. This class is the
5
+ // single identity face all three read:
6
+ // · spec / plan — the document's `doc-revision` (a hash of the whole content);
7
+ // · wave — the RENDERED brief's `brief-revision` (its task sections plus the
8
+ // plan's `## Constraints` — a plan edit elsewhere is not a drift);
9
+ // · branch — its plan document's `doc-revision` (the SAME kind, no new ref
10
+ // kind, no commit sha — the ledger keeps no second code identity).
11
+ //
12
+ // The judgment is deliberately two-valued + unknown: `same` (the recorded identity
13
+ // still describes the current input), `drift` (the input moved past it — the line
14
+ // reopens), `null` (no recorded identity, or an unreadable input — only PRESENT facts
15
+ // land a judgment, and a line with no record keeps the legacy closed face). The
16
+ // same-ref predicate itself stays where it already lived (`ReviewRefs.sameRef`,
17
+ // injected) so the identity kind comparison has exactly one definition.
18
+ //
19
+ // Module-level exports are types / the class — zero behavior-carrying bare functions.
20
+ /** LineIdentity — the one drift judgment of the three line kinds. */
21
+ export class LineIdentity {
22
+ /** The same-ref predicate's home (`ReviewRefs`) — injected, never re-declared. */
23
+ #refs;
24
+ constructor(refs) {
25
+ this.#refs = refs;
26
+ }
27
+ /** Judge a line: the recorded reviewed identity against the current input. */
28
+ verdict(recorded, current) {
29
+ if (recorded === null || current === null)
30
+ return null;
31
+ return this.#refs.sameRef(recorded, current.ref) ? "same" : "drift";
32
+ }
33
+ }
@@ -27,17 +27,25 @@
27
27
  //
28
28
  // D40 — ONE "next step" concept: the face-INTERNAL C5 hop and the face-TO-face
29
29
  // handoff are the SAME `Route` union (a `handoff` kind carries the pipeline entry),
30
- // so a consumer never consults a second table. `NextStepRouter.resolve` is the ONE
31
- // "one line → next" resolver: an active C5 hop passes through, a drained line yields
32
- // the face-to-face handoff. Both the board (its per-line walk) and the capsule
33
- // (the round's own line) call it — single resolver, single renderer.
30
+ // so a consumer never consults a second table. The face-to-face station selection
31
+ // rides the ONE derivation (`nextHop`): a `done` route's `to` cell is
32
+ // `PIPELINE_NEXT`'s row for the judged doc class, a `handoff` route carries its own
33
+ // entry, and the pipeline traversal itself belongs to the board's assembly face —
34
+ // no second resolver.
34
35
  //
35
36
  // Module-level exports are types / constants / the class — zero behavior-carrying
36
37
  // bare functions (the plan's zero-bare-function discipline).
38
+ var _a;
37
39
  /** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
38
40
  * defers the next hop to user adjudication (soft by nature: a default suggestion,
39
41
  * never a hard stop — the user / the plan write authority override it). */
40
- export const REVIEW_CYCLE_CAP = 20;
42
+ export const REVIEW_CYCLE_CAP = 50;
43
+ /** The wave-width ceiling (design spec §6) — at most this many tasks per dispatch wave.
44
+ * Declared once on the contract plane (`contract/wave-width.ts`), so the plan-scope
45
+ * rule reads it without importing this session plane, and re-exported here as the
46
+ * dispatch face's constant beside `REVIEW_CYCLE_CAP`. Three readers share the one
47
+ * value: the plan rule, the wave gate's two rejections and their wording. */
48
+ export { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
41
49
  /** The decision-edge words of the Route union — the C5 hop kinds that a review/fix
42
50
  * closure decision edge renders as a `next:` label (`done` · `next-wave` · `review`
43
51
  * · `fix` · `soft-cap`). The pure face-to-face `handoff` kind is EXCLUDED: it carries
@@ -46,34 +54,48 @@ export const REVIEW_CYCLE_CAP = 20;
46
54
  * runtime Route lexicon is the ONE source, never a second hand-written list. */
47
55
  export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft-cap"];
48
56
  /** The pipeline next table — the ONE face-indirection source (D33 · single-addressed
49
- * at session/next.ts):
50
- * the doc-class key → the next pipeline entrypoint. The skill refs ride REFS
51
- * (face/host.ts) resolved per host at the render — never a hard-coded plugin
52
- * spelling; the wave literal's `<plan>` slot is filled by the capsule with the
53
- * frame's plan fact. */
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. */
54
63
  export const PIPELINE_NEXT = {
55
64
  "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
56
65
  overall: { kind: "done" },
57
66
  plan: { kind: "ref", ref: "kairos:cdd-dev" },
67
+ "single-spec": { kind: "done" },
58
68
  wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
59
69
  branch: { kind: "ref", ref: "kairos:cdd-close" },
60
70
  };
61
71
  /** The pipeline's phase-level face order (D40) — the face-to-face traversal
62
- * `spec → plan → wave → branch`, the ONE order declaration; `NextStepRouter.walk`
63
- * iterates it, so a consumer maps key → facts and declares NO order of its own. */
72
+ * `spec → plan → wave → branch`, the ONE order declaration: the board's assembly
73
+ * face iterates it, so a consumer maps key → facts and declares NO order of its own. */
64
74
  export const PIPELINE_FACES = ["phase-spec", "plan", "wave", "branch"];
75
+ /** The single reason table (§5.2) — every `NextHop.reason` value comes from here, so
76
+ * the four read faces and the CLI rejection message name a fact by ONE spelling (a
77
+ * hyphenated fact name, never a sentence). */
78
+ export const NEXT_HOP_REASON = {
79
+ docDrift: "doc-drift",
80
+ pendingFix: "pending-fix",
81
+ closedLine: "closed-line",
82
+ faceClosed: "face-closed",
83
+ softCap: "soft-cap",
84
+ taskOpen: "task-open",
85
+ docClassBlocked: "doc-class-blocked",
86
+ };
65
87
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
66
88
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
67
89
  /** The fix-route readback suffix — appended verbatim to the fix findings path on the
68
- * route's `next:` render (`(confirm the findings · if a finding needs a ruling,
69
- * record the ruling in the findings file)`), a pure wording prompt: the
90
+ * route's `next:` render (`(confirm the reviews handoff · if a finding needs a
91
+ * ruling, record the ruling in the handoff file)`), a pure wording prompt: the
70
92
  * anti-blind-fix mechanical guard is the ledger round / C5-1, the suffix only
71
93
  * reminds the orchestrator to confirm the captured findings and, when a finding
72
- * needs a user ruling, record that ruling back into the findings file the fix
94
+ * needs a user ruling, record that ruling back into the reviews handoff the fix
73
95
  * round consumes. `annotate` names the carrier action alone — distinct from
74
96
  * `backfill` (a durable fact landed into its owning doc), which stays the
75
97
  * ruling's destination when it asserts a project-level fact. */
76
- export const FIX_READBACK_SUFFIX = "(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
98
+ export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record the ruling in the handoff file)";
77
99
  /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
78
100
  * produces no `next:` line on any op. Exported as the ONE failure-status set: the
79
101
  * skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
@@ -137,6 +159,105 @@ export class NextStepRouter {
137
159
  #blockerCount(ref) {
138
160
  return ref.findings.filter((finding) => finding.severity === "blocker").length;
139
161
  }
162
+ // ---------------------------------------------------------------------------
163
+ // the ONE next-hop derivation (§5.2) — a presentation read of the count table
164
+ // ---------------------------------------------------------------------------
165
+ /** hopOf(route, face) — the ONE constant Route → Hop mapping. It reads the face
166
+ * because a `review` route carries NO face of its own: the branch face's review is
167
+ * the `branch-review` skill, every other face's is `review`. `done` / `handoff` /
168
+ * `soft-cap` are not hops — they close the line (the count table's judgment). */
169
+ hopOf(route, face) {
170
+ switch (route.kind) {
171
+ case "next-wave":
172
+ return "implement";
173
+ case "review":
174
+ return face === "branch" ? "branch-review" : "review";
175
+ case "fix":
176
+ return "fix";
177
+ case "soft-cap":
178
+ case "done":
179
+ case "handoff":
180
+ return null;
181
+ }
182
+ }
183
+ /** nextHop(input) — the ONE derivation of a line's next hop (§5.2), once per call
184
+ * and per line (never cached, never shared across calls).
185
+ *
186
+ * The judgment stays the count table's: `hop` is READ OUT of the route the table
187
+ * produced (`hopOf`), never re-derived here, and `reason` names the fact that
188
+ * selected it (§5.1: any second criterion is the regression the phase names). The
189
+ * face axis is read out of the ONE verdict (`#faceOf`), so the three read faces
190
+ * fill facts and never re-assemble the chain. `to` follows the same path for
191
+ * `done` and `handoff`; the doc-class discrimination is injected at the assembly
192
+ * entry, so this module never imports a face class. */
193
+ nextHop(input) {
194
+ const route = input.route;
195
+ const verdict = input.verdict;
196
+ const face = _a.#faceOf(verdict);
197
+ return {
198
+ face,
199
+ target: input.target,
200
+ // No route (the failure face) is no hop; otherwise `hopOf` is the ONE answer to
201
+ // "which route kinds are hops" — the closure kinds are not enumerated twice.
202
+ hop: route === null ? null : this.hopOf(route, face),
203
+ to: this.#entryOf(input, route, verdict),
204
+ reason: this.#reasonOf(input, route, verdict),
205
+ route,
206
+ };
207
+ }
208
+ /** message(hop, station) — the ONE rejection-message shape (§5.2): a hop names the
209
+ * verb, a closed face names its handoff station (`station` renders the entry through
210
+ * the shared route renderer), and neither renders the bare reason — no invented
211
+ * verb slot. */
212
+ message(hop, station) {
213
+ if (hop.hop !== null)
214
+ return `${hop.reason} · the next round is ${hop.hop}`;
215
+ if (hop.to !== null)
216
+ return `${hop.reason} · next: ${station(hop.to)}`;
217
+ return hop.reason;
218
+ }
219
+ /** The face axis of one verdict — the ONE `verdict → face` assembly (§5.2): the two
220
+ * unroutable classes carry no face, every pipeline key is its own face. */
221
+ static #faceOf(verdict) {
222
+ return verdict === "blocked" || verdict === "terminal" ? null : verdict;
223
+ }
224
+ /** The pipeline station of a closure route — `handoff` carries its own entry, `done`
225
+ * derives it from the doc class (`PIPELINE_NEXT` is data, never a judgment), and a
226
+ * `blocked` / `terminal` class (or no route at all) has no station. The wave face is
227
+ * the ONE class whose row depends on the NEXT line (P21 §4.2): a closed branch line
228
+ * hands the wave line to the branch face's own exit, not a literal its gate refuses. */
229
+ #entryOf(input, route, verdict) {
230
+ if (route === null)
231
+ return null;
232
+ if (route.kind === "handoff")
233
+ return route.entry;
234
+ if (route.kind !== "done")
235
+ return null;
236
+ if (verdict === "blocked" || verdict === "terminal")
237
+ return null;
238
+ if (verdict === "wave" && input.nextLineOpen === false)
239
+ return PIPELINE_NEXT.branch;
240
+ return PIPELINE_NEXT[verdict];
241
+ }
242
+ /** The named fact behind the hop — one `NEXT_HOP_REASON` row, in this order: the
243
+ * soft cap · a pending fix · a drift-reopened line · an open line advancing · an
244
+ * unjudgeable doc class · a closed face · the closed line's handoff. Drift never
245
+ * outranks a pending fix (an unclosed line's blocker keeps the fix hop). */
246
+ #reasonOf(input, route, verdict) {
247
+ if (route?.kind === "soft-cap")
248
+ return NEXT_HOP_REASON.softCap;
249
+ if (route?.kind === "fix")
250
+ return NEXT_HOP_REASON.pendingFix;
251
+ if (route?.kind === "review" && input.gate.drift)
252
+ return NEXT_HOP_REASON.docDrift;
253
+ if (route !== null && this.hopOf(route, _a.#faceOf(verdict)) !== null)
254
+ return NEXT_HOP_REASON.taskOpen;
255
+ if (verdict === "blocked")
256
+ return NEXT_HOP_REASON.docClassBlocked;
257
+ if (route === null || verdict === "terminal")
258
+ return NEXT_HOP_REASON.faceClosed;
259
+ return NEXT_HOP_REASON.closedLine;
260
+ }
140
261
  /** The face-to-face handoff route for a pipeline doc-class (D40) — the next-face
141
262
  * entry (`PIPELINE_NEXT[key]`). One of the two ways the ONE "next step" concept
142
263
  * is produced (the C5 hop is the other), so a consumer never consults a second
@@ -144,68 +265,5 @@ export class NextStepRouter {
144
265
  static handoff(key) {
145
266
  return { kind: "handoff", entry: PIPELINE_NEXT[key] };
146
267
  }
147
- /** Resolve a line's next step (D40) — the capsule's "one line → next" point for the
148
- * round's OWN line: an ACTIVE C5 hop (`review` / `fix` / `implement` / `next-wave` /
149
- * `soft-cap`) passes through as the line's next step; a drained / not-yet-started
150
- * line (the C5 `done` / no active round) yields the face-to-face handoff carrying
151
- * the pipeline entry. A null doc-class (no face seam — the overall line / a bare
152
- * terminal) renders the bare `done` word. A whole-slug walk is `walk` (the board's
153
- * face-to-face traversal); this is the single-line form the capsule holds. Pure. */
154
- static resolve(active, key) {
155
- if (active !== null && active.kind !== "done")
156
- return active;
157
- return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
158
- }
159
- /** Walk(face report) → the ONE next step (D40 · the board's face-to-face traversal
160
- * as a single router method). The caller REPORTS each face's facts keyed by its
161
- * `PIPELINE_FACES` key; the router iterates the ONE order and DECIDES the next step
162
- * — so no consumer re-derives the order OR the face-transition rule (the retired
163
- * board fork handed off via the frontier LINE's own key, so a slug whose spec just
164
- * closed but whose plan was not yet authored rendered `plan`'s exit `cdd-dev`
165
- * instead of the spec's exit `cdd-plan` — a face-boundary off-by-one the ONE walk
166
- * eliminates). The rule:
167
- * · the FRONTIER face (first not-closed) with an active C5 hop → render that hop
168
- * (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
169
- * · the frontier has no active hop but IS entered (`target` present — an empty
170
- * wave segment, a drained-but-reached face) → its OWN pipeline exit entry;
171
- * · the frontier is NOT entered (no target — an absent doc, e.g. no plan yet) →
172
- * the transition INTO it, i.e. the PRECEDING entered face's exit entry (so a
173
- * just-closed spec hands off to the spec's exit `cdd-plan`, never the absent
174
- * plan's exit); no preceding entered face → the FIRST face's exit entry;
175
- * · every face closed → the LAST entered face's exit entry (the pipeline
176
- * terminus — `cdd-close` for a phase slug). */
177
- static walk(report) {
178
- const states = PIPELINE_FACES.map((key) => report[key]);
179
- const frontierIndex = states.findIndex((face) => !face.closed);
180
- if (frontierIndex === -1) {
181
- const terminalIndex = NextStepRouter.#lastEnteredIndex(states);
182
- const terminal = terminalIndex === -1 ? null : states[terminalIndex];
183
- return terminal === null
184
- ? { route: { kind: "done" }, target: null }
185
- : {
186
- route: NextStepRouter.handoff(PIPELINE_FACES[terminalIndex]),
187
- target: terminal.target,
188
- };
189
- }
190
- const frontier = states[frontierIndex];
191
- if (frontier.active !== null)
192
- return { route: frontier.active, target: frontier.target };
193
- const anchorIndex = frontier.target !== null
194
- ? frontierIndex
195
- : Math.max(0, NextStepRouter.#lastEnteredIndex(states.slice(0, frontierIndex)));
196
- const anchor = states[anchorIndex];
197
- return {
198
- route: NextStepRouter.handoff(PIPELINE_FACES[anchorIndex]),
199
- target: anchor.target,
200
- };
201
- }
202
- /** The index of the last OBSERVED face carrying a render target — the last face the
203
- * pipeline has REACHED (a face with no target was never entered). -1 when none is. */
204
- static #lastEnteredIndex(states) {
205
- for (let i = states.length - 1; i >= 0; i--) {
206
- if (states[i].target !== null)
207
- return i;
208
- }
209
- return -1;
210
- }
211
268
  }
269
+ _a = NextStepRouter;