@oscaner-skills/cdd-engine 2.0.0 → 3.0.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -70,8 +70,10 @@ export type AuditTarget =
70
70
  /** branch: the branch line itself (no commit identity — the review's scope anchor
71
71
  * rides the engine-injected BASE_BRANCH, never a stored range). */
72
72
  | { kind: "branch" }
73
- /** spec/plan: the audit document path. */
74
- | { kind: "doc"; doc: string };
73
+ /** plan: the audit plan document path. */
74
+ | { kind: "plan"; doc: string }
75
+ /** spec: the audit spec document path. */
76
+ | { kind: "spec"; doc: string };
75
77
 
76
78
  /** One dispatch step's full identity — what the lifecycle dispatches. */
77
79
  export interface OpenFrame {
@@ -98,19 +100,20 @@ export interface DispatchOutcome {
98
100
  /** The round's findings (review: this round's own; fix: the source review's
99
101
  * input findings, C5-1). */
100
102
  findings?: readonly RoundFinding[];
101
- /** The artifact paths the round produced (brief/report/…). */
102
- artifacts?: Record<string, string>;
103
103
  /** The materialized final carrier (the production dispatch's read-back
104
104
  * reconstruct — §3.6: the child draft validated and built into the carrier the
105
105
  * bookkeep persists verbatim, full-replace at the SAME path; agent draft →
106
106
  * finalized, the engine stays the single author). Absent for the hermetic /
107
- * dry-run dispatchers — the bookkeep builds the carrier from the outcome fields. */
107
+ * injected dispatchers — the bookkeep builds the carrier from the outcome fields. */
108
108
  carrier?: Record<string, unknown>;
109
109
  }
110
110
 
111
111
  /** The dispatch instruction — runs one round's actual work (the harness call in
112
- * production; a stub in tests). The lifecycle never inspects how the work runs. */
113
- export type DispatchStep = (frame: OpenFrame) => DispatchOutcome;
112
+ * production; a stub in tests). The lifecycle never inspects how the work runs.
113
+ * Asynchronous by necessity: the child's process lifecycle (group kill · wall-clock
114
+ * ceiling · parent-exit cleanup) lives on execa's asynchronous face alone — the
115
+ * synchronous face forbids every one of those options. */
116
+ export type DispatchStep = (frame: OpenFrame) => Promise<DispatchOutcome>;
114
117
 
115
118
  /** The capsule interaction seam — the face/capsule contact. T10's Capsule satisfies
116
119
  * this shape; the lifecycle advances without a capsule (non-hard consumption) and
@@ -239,7 +242,7 @@ export class Lifecycle {
239
242
  * exhausted or a capped line defers to the user). A refused pre-flight gate blocks
240
243
  * the dispatch (child zero) and returns the frame as a preflight-blocked step —
241
244
  * neither persisted nor recorded (the frontier re-offers it: resume). */
242
- advance(): StepResult | null {
245
+ async advance(): Promise<StepResult | null> {
243
246
  const frame = this.#openFrame();
244
247
  if (frame === null) return null;
245
248
  if (this.#preflight !== null) {
@@ -254,7 +257,7 @@ export class Lifecycle {
254
257
  };
255
258
  }
256
259
  }
257
- const outcome = this.#dispatch(frame);
260
+ const outcome = await this.#dispatch(frame);
258
261
  const round = this.#bookkeep(frame, outcome);
259
262
  // The closure verdict rides the recorded round's C5 route — mark the task done
260
263
  // when the route kind says the line closed (the router's single point, never a
@@ -348,7 +351,7 @@ export class Lifecycle {
348
351
  target: AuditTarget,
349
352
  reviewLead: ReviewLead,
350
353
  ): DispatchPhase | null {
351
- if (target.kind === "doc") {
354
+ if (target.kind === "plan" || target.kind === "spec") {
352
355
  const verdict = this.#ledger.reviewGate(key, target.doc, this.#face.type);
353
356
  if (verdict.kind === "open") return reviewLead;
354
357
  if (verdict.kind === "same" && verdict.pending) return "fix";
@@ -380,7 +383,7 @@ export class Lifecycle {
380
383
  * relative) must not fork the same line into two ledger rows). The task face
381
384
  * never routes here — frames key by the wave key. */
382
385
  #lineKey(target: AuditTarget): LedgerKey {
383
- if (target.kind === "doc") return this.#face.type;
386
+ if (target.kind === "plan" || target.kind === "spec") return this.#face.type;
384
387
  return "branch";
385
388
  }
386
389
 
@@ -420,8 +423,8 @@ export class Lifecycle {
420
423
  * The persisted carrier is either the dispatch's materialized form (the production
421
424
  * read-back reconstruct — outcome.carrier, full-replace at the SAME path, so the
422
425
  * child's draft becomes the finalized carrier — the two-state single file, the engine is the single
423
- * author) or the engine-built fallback from the outcome fields (hermetic / dry-run
424
- * dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
426
+ * author) or the engine-built fallback from the outcome fields (the hermetic /
427
+ * injected dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
425
428
  * recorded — the child's draft (if any) stays untouched (no-overwrite on failure) and the
426
429
  * frontier re-offers the same round (resume = re-run the same command); a BLOCKED
427
430
  * round WITH a carrier (e.g. the evidence-contract override — the child's work is
@@ -447,11 +450,8 @@ export class Lifecycle {
447
450
  (face === "findings"
448
451
  ? this.#ledger.buildHandoff("findings", {
449
452
  findings: [...(outcome.findings ?? [])],
450
- artifacts: outcome.artifacts,
451
453
  })
452
- : this.#ledger.buildHandoff("work", {
453
- artifacts: outcome.artifacts,
454
- }));
454
+ : this.#ledger.buildHandoff("work", {}));
455
455
  // The work face ALONE persists the conclusion (the child's declared status); the
456
456
  // findings carrier holds no status — its conclusion derives at judgment time
457
457
  // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
@@ -478,7 +478,8 @@ export class Lifecycle {
478
478
  // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
479
479
  // wave row — null stays backward compatible.
480
480
  if (frame.phase === "review") {
481
- if (frame.target.kind === "doc") this.#recordReviewedDocRevision(frame);
481
+ if (frame.target.kind === "plan" || frame.target.kind === "spec")
482
+ this.#recordReviewedDocRevision(frame);
482
483
  else if (frame.target.kind === "wave") this.#recordReviewedWaveBrief(frame);
483
484
  }
484
485
  return count;
@@ -494,7 +495,7 @@ export class Lifecycle {
494
495
  * void a reviewed wave). An unreadable input records nothing — the line keeps the
495
496
  * legacy closed face (only present facts land, never an invented identity). */
496
497
  #recordReviewedDocRevision(frame: OpenFrame): void {
497
- if (frame.target.kind !== "doc") return;
498
+ if (frame.target.kind !== "plan" && frame.target.kind !== "spec") return;
498
499
  try {
499
500
  const content = readFileSync(frame.target.doc, "utf8");
500
501
  this.#ledger.recordReviewedRevision(
@@ -600,7 +601,10 @@ export class Lifecycle {
600
601
  };
601
602
  case "spec":
602
603
  case "plan":
603
- return { type: frame.type, id: (frame.target as { kind: "doc"; doc: string }).doc };
604
+ return {
605
+ type: frame.type,
606
+ id: (frame.target as { kind: "plan" | "spec"; doc: string }).doc,
607
+ };
604
608
  }
605
609
  }
606
610
  }
@@ -9,45 +9,6 @@
9
9
  "kairos:cdd-report",
10
10
  "kairos:cdd-close"
11
11
  ],
12
- "severities": [
13
- "blocker",
14
- "warn",
15
- "nit"
16
- ],
17
- "metaFields": [
18
- { "key": "skill", "label": "Skill" },
19
- { "key": "step", "label": "Step" }
20
- ],
21
- "sectionLabels": {
22
- "bug": {
23
- "en": {
24
- "context": "## Context",
25
- "problem": "## Problem",
26
- "impact": "## Impact",
27
- "suggestedFix": "## Suggested fix"
28
- },
29
- "zh": {
30
- "context": "## 背景",
31
- "problem": "## 问题",
32
- "impact": "## 影响",
33
- "suggestedFix": "## 建议修复"
34
- }
35
- },
36
- "enhancement": {
37
- "en": {
38
- "context": "## Context",
39
- "problem": "## Current behavior",
40
- "impact": "## Desired behavior",
41
- "suggestedFix": "## Suggested approach"
42
- },
43
- "zh": {
44
- "context": "## 背景",
45
- "problem": "## 当前行为",
46
- "impact": "## 期望行为",
47
- "suggestedFix": "## 建议方案"
48
- }
49
- }
50
- },
51
12
  "formFieldDefs": {
52
13
  "bug_report": {
53
14
  "frontmatter": {
@@ -191,12 +152,5 @@
191
152
  }
192
153
  ]
193
154
  }
194
- },
195
- "reportDef": {
196
- "labels": ["kairos", "cdd-engine"]
197
- },
198
- "masterDef": {
199
- "sessionTitle": "## Session",
200
- "harnessRow": "- Harness: <harness>"
201
155
  }
202
156
  }
@@ -1,70 +0,0 @@
1
- // packages/cdd-engine/src-next/face/__tests__/sync-runner.test.ts
2
- // The SyncRunner colocated pins (spec §14 · D36 — the host-channel integrity):
3
- // the sync child-process face collects UNBOUNDED output (the retired fixed 1 MiB
4
- // output-buffer cap — the W1 truncation class — is gone: execa's sync face
5
- // buffers without bound by default):
6
- // · >1 MiB output (exactly the retired default-ceiling byte count + 1) arrives
7
- // whole — the tail block the read-back gate parses is intact;
8
- // · a `status: APPROVED` RETURN_STDOUT_BLOCK tail survives the biggest pipe —
9
- // the W1 failure class (tail truncation losing the status line) is dead;
10
- // · stderr aggregates by the same face;
11
- // · the fail-open semantics hold — a non-zero child rides its code, a broken
12
- // command never throws.
13
- // The child is a real hermetic shell process (no network, no repo writes).
14
-
15
- import { describe, expect, it } from "vitest";
16
- import { SyncRunner } from "../lifecycle.ts";
17
-
18
- describe("SyncRunner — the unbounded sync child-channel collection (spec §14 · D36)", () => {
19
- const runner = new SyncRunner();
20
-
21
- it("collects >1 MiB stdout whole — exactly the retired default ceiling + 1 byte", () => {
22
- // 1 MiB + 1 byte of 'x' — the byte count that trips the retired default
23
- // output-buffer cap; every byte must arrive.
24
- const result = runner.run(
25
- "sh",
26
- ["-c", "head -c 1048577 /dev/zero | tr '\\0' x"],
27
- process.cwd(),
28
- );
29
- expect(result.code).toBe(0);
30
- expect(result.stdout.length).toBe(1048577);
31
- });
32
-
33
- it("keeps the `status: APPROVED` tail block intact behind a huge narrative — the W1 truncation class is dead", () => {
34
- // A big narrative stdout followed by the canonical return block — the exact
35
- // W1 incident shape (work fine, tail block lost). The status line MUST reach.
36
- const result = runner.run(
37
- "sh",
38
- [
39
- "-c",
40
- "head -c 2000000 /dev/zero | tr '\\0' x; printf '\\nstatus: APPROVED\\nartifacts: report=/tmp/r.md\\n'",
41
- ],
42
- process.cwd(),
43
- );
44
- expect(result.code).toBe(0);
45
- expect(result.stdout.length).toBeGreaterThan(2000000);
46
- expect(result.stdout).toMatch(/^status: APPROVED$/m);
47
- expect(result.stdout).toMatch(/^artifacts: report=\/tmp\/r\.md$/m);
48
- });
49
-
50
- it("aggregates stderr by the same streaming face", () => {
51
- const result = runner.run(
52
- "sh",
53
- ["-c", "head -c 1100000 /dev/zero | tr '\\0' e >&2"],
54
- process.cwd(),
55
- );
56
- expect(result.code).toBe(0);
57
- expect(result.stderr.length).toBe(1100000);
58
- expect(result.stderr).toMatch(/^e+$/);
59
- });
60
-
61
- it("stays fail-open — a non-zero child rides its code, a broken command never throws", () => {
62
- const nonZero = runner.run("sh", ["-c", "echo partial; exit 7"], process.cwd());
63
- expect(nonZero.code).toBe(7);
64
- expect(nonZero.stdout).toBe("partial\n");
65
- const broken = runner.run("cdd-no-such-binary-xyz", [], process.cwd());
66
- expect(broken.code).toBe(1);
67
- expect(broken.stdout).toBe("");
68
- expect(broken.stderr.length).toBeGreaterThan(0);
69
- });
70
- });