@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.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/package.json +4 -3
- package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
- package/src-next/__tests__/floor.guard.test.ts +69 -0
- package/src-next/__tests__/issue-body.guard.test.ts +66 -0
- package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
- package/src-next/__tests__/smoke.integration.test.ts +60 -77
- package/src-next/__tests__/support/strip-comments.ts +99 -0
- package/src-next/__tests__/zero-dep.test.ts +6 -46
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
- package/src-next/contract/__tests__/declare.test.ts +251 -12
- package/src-next/contract/__tests__/doc.test.ts +214 -45
- package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
- package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
- package/src-next/contract/__tests__/judge.test.ts +410 -172
- package/src-next/contract/__tests__/lint.test.ts +49 -39
- package/src-next/contract/__tests__/project.test.ts +60 -19
- package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
- package/src-next/contract/declare.ts +179 -91
- package/src-next/contract/doc.ts +227 -164
- package/src-next/contract/frontmatter.ts +233 -0
- package/src-next/contract/home-extractors.ts +397 -0
- package/src-next/contract/invariants.ts +214 -69
- package/src-next/contract/judge.ts +28 -19
- package/src-next/contract/lint.ts +5 -41
- package/src-next/contract/project.ts +103 -43
- package/src-next/contract/skill-anatomy.ts +39 -11
- package/src-next/face/__tests__/board-view.test.ts +318 -115
- package/src-next/face/__tests__/capsule.test.ts +49 -25
- package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
- package/src-next/face/__tests__/cli.test.ts +1091 -837
- package/src-next/face/__tests__/face.test.ts +5 -5
- package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
- package/src-next/face/__tests__/preview.test.ts +374 -0
- package/src-next/face/__tests__/projection.test.ts +5 -3
- package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
- package/src-next/face/__tests__/termination.test.ts +650 -0
- package/src-next/face/artifacts.ts +90 -37
- package/src-next/face/board-view.ts +128 -138
- package/src-next/face/capsule.ts +30 -16
- package/src-next/face/cli.ts +306 -97
- package/src-next/face/declare.ts +15 -18
- package/src-next/face/gate.ts +19 -18
- package/src-next/face/host.ts +6 -30
- package/src-next/face/lifecycle.ts +213 -188
- package/src-next/face/preview.ts +151 -0
- package/src-next/face/projection.ts +4 -1
- package/src-next/face/route-render.ts +39 -14
- package/src-next/face/termination.ts +573 -0
- package/src-next/face/words.ts +20 -2
- package/src-next/infra/__tests__/infra.test.ts +49 -3
- package/src-next/infra/__tests__/root.test.ts +56 -0
- package/src-next/infra/doc-roots.ts +29 -0
- package/src-next/infra/root.ts +73 -0
- package/src-next/infra/runtime.ts +12 -65
- package/src-next/infra/workspace.ts +95 -5
- package/src-next/render/__tests__/render.test.ts +92 -41
- package/src-next/render/__tests__/skeleton.test.ts +282 -64
- package/src-next/render/issue-body.ts +5 -2
- package/src-next/render/skeleton.ts +155 -90
- package/src-next/render/templates.ts +51 -56
- package/src-next/session/__tests__/graph.test.ts +11 -4
- package/src-next/session/__tests__/ledger.test.ts +3 -2
- package/src-next/session/__tests__/next.test.ts +100 -8
- package/src-next/session/__tests__/preflight.test.ts +79 -25
- package/src-next/session/__tests__/round-naming.test.ts +142 -0
- package/src-next/session/__tests__/run.test.ts +140 -128
- package/src-next/session/__tests__/wave.test.ts +11 -4
- package/src-next/session/ledger.ts +96 -24
- package/src-next/session/next.ts +116 -15
- package/src-next/session/preflight.ts +41 -10
- package/src-next/session/round-naming.ts +84 -0
- package/src-next/session/run.ts +24 -20
- package/templates/report/issue-body.json +0 -46
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
|
@@ -41,12 +41,19 @@ const fixture = (): { ledger: Ledger; repo: string; cleanup: () => void } => {
|
|
|
41
41
|
};
|
|
42
42
|
};
|
|
43
43
|
|
|
44
|
-
/** A plan document over `### Task N:` blocks + `- **DependsOn**:` values
|
|
44
|
+
/** A plan document over `### Task N:` blocks + `- **DependsOn**:` values (the
|
|
45
|
+
* front-matter head the plan parser reads). */
|
|
45
46
|
const planDoc = (blocks: readonly (readonly string[])[]): string => {
|
|
46
47
|
return [
|
|
47
|
-
"
|
|
48
|
-
"
|
|
49
|
-
"-
|
|
48
|
+
"---",
|
|
49
|
+
"title: Test Plan",
|
|
50
|
+
"doc-type: plan",
|
|
51
|
+
"version: v1.0",
|
|
52
|
+
"date: 2026-10-09",
|
|
53
|
+
"spec: docs/kairos/specs/x-design.md",
|
|
54
|
+
"parent-program: docs/kairos/specs/x-overall.md",
|
|
55
|
+
"parent-version: v1.0",
|
|
56
|
+
"---",
|
|
50
57
|
"",
|
|
51
58
|
"## Constraints",
|
|
52
59
|
"",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
// handoff carrier's union).
|
|
16
16
|
// · round — the round carrier: the handoff presented as the Round the dispatch
|
|
17
17
|
// next-router judges. A fix round carries the SOURCE review's findings (the
|
|
18
|
-
// `--
|
|
18
|
+
// `--reviews` input content, C5-1), never its own; the consecutive-S1 run is
|
|
19
19
|
// walked from the round history (the review-cycle soft-cap basis).
|
|
20
20
|
//
|
|
21
21
|
// Module-level exports are types / constant data / the class — zero behavior-
|
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
import { createHash } from "node:crypto";
|
|
25
25
|
import { readFileSync } from "node:fs";
|
|
26
26
|
import type { ConfigLoader } from "../infra/config.ts";
|
|
27
|
+
import type { RepoPath, RepoRoot } from "../infra/root.ts";
|
|
27
28
|
import type { HandoffFamily } from "../infra/runtime.ts";
|
|
28
29
|
import type { Workspace } from "../infra/workspace.ts";
|
|
29
30
|
import { BriefRenderer } from "../render/brief.ts";
|
|
@@ -88,8 +89,8 @@ export interface Round {
|
|
|
88
89
|
status?: RoundStatus;
|
|
89
90
|
/** The findings the next-hop derivation judges. */
|
|
90
91
|
findings: readonly RoundFinding[];
|
|
91
|
-
/** The
|
|
92
|
-
|
|
92
|
+
/** The review handoff path (fix: the `--reviews` input; review: its own handoff). */
|
|
93
|
+
reviewsPath?: string;
|
|
93
94
|
/** The consecutive-S1 run (the leading blocker-lead reviews, newest first) — the
|
|
94
95
|
* review-cycle soft-cap basis. */
|
|
95
96
|
consecutiveS1: number;
|
|
@@ -146,28 +147,57 @@ export interface ProgressData {
|
|
|
146
147
|
/** The ledger lookup key — a scalar task id or the group key string. */
|
|
147
148
|
export type LedgerKey = number | string;
|
|
148
149
|
|
|
150
|
+
/** The dispatch-termination vocabulary — why a round was cut short (single source:
|
|
151
|
+
* the terminator derives the cause from the child's own result face, the crash
|
|
152
|
+
* record carries it as a postmortem fact, zero behavior fork — resume never routes
|
|
153
|
+
* on it). `stalled` = the engine's stall judgment killed the child; `over-budget` =
|
|
154
|
+
* the wall-clock ceiling was reached; `signal` = an external signal killed the
|
|
155
|
+
* child (any signal, one semantic — never the SIGTERM literal). */
|
|
156
|
+
export type TerminationCause = "stalled" | "over-budget" | "signal";
|
|
157
|
+
|
|
158
|
+
/** The stall judge's verdict per sample tick: `progress` (a leg advanced), `unknown`
|
|
159
|
+
* (a leg is unreadable — the fail-open state, never a kill), `idled` (no progress
|
|
160
|
+
* yet, the idle window is open) and `stalled` (no progress and the window is spent
|
|
161
|
+
* — the kill). */
|
|
162
|
+
export type StallVerdict = "progress" | "unknown" | "idled" | "stalled";
|
|
163
|
+
|
|
164
|
+
/** One sample tick's two legs — the process group's cumulative CPU (ms) and the
|
|
165
|
+
* newest mtime (ms) of the scanned tree. `null` = that leg is unreadable (the
|
|
166
|
+
* fail-open face: an unreadable leg never authorizes a kill). The field names are
|
|
167
|
+
* the heartbeat record's names (one naming, two references). */
|
|
168
|
+
export interface Sample {
|
|
169
|
+
groupCpuMs: number | null;
|
|
170
|
+
newestMtimeMs: number | null;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** The recorded sample — a `Sample` extended with its tick's timestamp and the
|
|
174
|
+
* judge's verdict (the heartbeat file's field set; the crash record embeds it). */
|
|
175
|
+
export interface SampleRecord extends Sample {
|
|
176
|
+
sampledAt: number;
|
|
177
|
+
verdict: StallVerdict;
|
|
178
|
+
}
|
|
179
|
+
|
|
149
180
|
/** The lane-crash cause vocabulary — postmortem classification of why a dispatch
|
|
150
181
|
* terminated before the exit gate (zero behavior fork: resume never routes on it).
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
| "engine-over-budget"
|
|
158
|
-
| "engine-timeout"
|
|
159
|
-
| "contract-violation"
|
|
160
|
-
| "unknown";
|
|
182
|
+
* The termination causes cover the round that was cut short; `child-exit` is the
|
|
183
|
+
* child's own non-zero exit, `contract-violation` the read-back face (the child
|
|
184
|
+
* exited 0 but produced no draft or a schema-violating one — the engine BLOCKs +
|
|
185
|
+
* preserves the draft + stores the same-command resume), and `unknown` the
|
|
186
|
+
* unattributable termination fallback. */
|
|
187
|
+
export type CrashCause = TerminationCause | "child-exit" | "contract-violation" | "unknown";
|
|
161
188
|
|
|
162
189
|
/** The crash record — the lane crash's recovery record (`crash-<lane>-<round>.json`):
|
|
163
190
|
* the same-command resume's decision source (the resume command + the dead child's
|
|
164
191
|
* tails), never the handoff carrier. */
|
|
165
192
|
export interface CrashRecord {
|
|
166
|
-
/** The dead child's exit code
|
|
167
|
-
|
|
168
|
-
|
|
193
|
+
/** The dead child's exit code — null when the child never spawned (a broken
|
|
194
|
+
* command) or was terminated by a signal (a signalled child has no exit code;
|
|
195
|
+
* the signal semantics ride the `cause`). */
|
|
196
|
+
exitCode: number | null;
|
|
197
|
+
/** The dead child's stderr tail (the "403 / abort without trace" tail — the
|
|
198
|
+
* caller's captured lines, no fixed tail-length constant). */
|
|
169
199
|
stderrTail: readonly string[];
|
|
170
|
-
/** The
|
|
200
|
+
/** The dead child's stdout tail. */
|
|
171
201
|
stdoutTail: readonly string[];
|
|
172
202
|
/** The handoff path the dead child was expected to write (null when the lane carries none). */
|
|
173
203
|
attemptedHandoff: string | null;
|
|
@@ -175,6 +205,11 @@ export interface CrashRecord {
|
|
|
175
205
|
next: string;
|
|
176
206
|
/** The unified termination cause — postmortem, zero behavior fork. */
|
|
177
207
|
cause: CrashCause;
|
|
208
|
+
/** The terminated round's last observed sample (the stall face's postmortem pair) —
|
|
209
|
+
* null when the round was not cut short or no sample was ever taken. The sample
|
|
210
|
+
* rides the termination fact in memory (zero re-read of the heartbeat file the
|
|
211
|
+
* engine itself wrote); the on-disk heartbeat stays for a human's postmortem. */
|
|
212
|
+
lastSample: SampleRecord | null;
|
|
178
213
|
}
|
|
179
214
|
|
|
180
215
|
// ---------------------------------------------------------------------------
|
|
@@ -338,6 +373,28 @@ export class Ledger {
|
|
|
338
373
|
return this.#refs;
|
|
339
374
|
}
|
|
340
375
|
|
|
376
|
+
/** The ledger's repo-basis value object — the ONE conversion exit every persisted
|
|
377
|
+
* path field normalizes through (T1 `RepoRoot` · P9 T4 §2.7). The basis is the
|
|
378
|
+
* workspace root's OWN value object (built once at the root's boundary) — never
|
|
379
|
+
* re-wrapped here (branch-review-1 F2: one basis, one form). */
|
|
380
|
+
#basis(): RepoRoot {
|
|
381
|
+
return this.#workspace.root.basis;
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
/** Normalize a path value to the canonical repoRoot-relative `RepoPath` — the
|
|
385
|
+
* comparison/write side of the shapes fix (a persisted relative value and an
|
|
386
|
+
* incoming absolute argv value compare on ONE basis). */
|
|
387
|
+
#rel(value: string): RepoPath {
|
|
388
|
+
return this.#basis().relativize(value);
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Erase a (possibly relative) path value to the absolute syscall string for a
|
|
392
|
+
* read (a legacy relative persisted value resolves against the basis, never
|
|
393
|
+
* `process.cwd()`). */
|
|
394
|
+
#abs(value: string): string {
|
|
395
|
+
return this.#basis().resolve(this.#basis().relativize(value));
|
|
396
|
+
}
|
|
397
|
+
|
|
341
398
|
// ---- the single author's write/read primitives ----
|
|
342
399
|
|
|
343
400
|
/** Persist a JSON artifact — the ledger's single write point (engine sole author). */
|
|
@@ -468,8 +525,10 @@ export class Ledger {
|
|
|
468
525
|
#briefRevision(waveKey: string, planPath: string): BriefRevisionRef | null {
|
|
469
526
|
try {
|
|
470
527
|
const tasks = waveKey.split(",").map((part) => Number(part));
|
|
471
|
-
|
|
472
|
-
|
|
528
|
+
// The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
|
|
529
|
+
// every persisted path field; the read erases to absolute at the syscall edge.
|
|
530
|
+
const brief = this.#brief.render(readFileSync(this.#abs(planPath), "utf8"), tasks);
|
|
531
|
+
return this.#refs.briefRevision(this.#rel(planPath), brief);
|
|
473
532
|
} catch {
|
|
474
533
|
return null;
|
|
475
534
|
}
|
|
@@ -504,7 +563,11 @@ export class Ledger {
|
|
|
504
563
|
const reviewed = this.reviewedDocRevisionOf(key);
|
|
505
564
|
if (reviewed === null) return null;
|
|
506
565
|
try {
|
|
507
|
-
|
|
566
|
+
// Both sides on ONE basis (P9 T4 §2.7): the recorded ref is repoRoot-relative;
|
|
567
|
+
// the incoming target (an absolute argv-erasure) is relativized here so the
|
|
568
|
+
// false-drift comparison never reads one document as two.
|
|
569
|
+
const rel = this.#rel(doc);
|
|
570
|
+
const current = this.#refs.docRevision(rel, readFileSync(this.#abs(doc), "utf8"));
|
|
508
571
|
return this.#refs.sameRef(reviewed, current) ? "same" : "drift";
|
|
509
572
|
} catch {
|
|
510
573
|
return null;
|
|
@@ -585,7 +648,7 @@ export class Ledger {
|
|
|
585
648
|
if (reviewed !== null && this.#briefDrift(waveKey, reviewed)) return { kind: "review" };
|
|
586
649
|
return {
|
|
587
650
|
kind: "fix",
|
|
588
|
-
|
|
651
|
+
reviews: this.handoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
|
|
589
652
|
};
|
|
590
653
|
}
|
|
591
654
|
return null;
|
|
@@ -647,6 +710,15 @@ export class Ledger {
|
|
|
647
710
|
return this.readProgress()?.[key] ?? 0;
|
|
648
711
|
}
|
|
649
712
|
|
|
713
|
+
/** Increment the timeout counter — the terminated-round write point (one TIMEOUT
|
|
714
|
+
* round lands, the count goes up by one). The counter's only writer. */
|
|
715
|
+
incrementTimeoutCount(): number {
|
|
716
|
+
const data = this.readProgress() ?? this.emptyProgress();
|
|
717
|
+
data.timeoutCount += 1;
|
|
718
|
+
this.writeProgress(data);
|
|
719
|
+
return data.timeoutCount;
|
|
720
|
+
}
|
|
721
|
+
|
|
650
722
|
// -------------------------------------------------------------------------
|
|
651
723
|
// closedWaves — the closure single read face (v1.20)
|
|
652
724
|
// -------------------------------------------------------------------------
|
|
@@ -944,7 +1016,7 @@ export class Ledger {
|
|
|
944
1016
|
* a rejected child's leftover draft is never read back as a completed round
|
|
945
1017
|
* (the §2.8 gate; without it a BLOCKED round with a stale draft rendered a
|
|
946
1018
|
* contradictory `status: BLOCKED · next: done`). A fix round carries the SOURCE
|
|
947
|
-
* review's findings (C5-1: the `--
|
|
1019
|
+
* review's findings (C5-1: the `--reviews` input content, never its own
|
|
948
1020
|
* carrier); the consecutive-S1 run is walked from the review history.
|
|
949
1021
|
* Missing/corrupt evaluated handoff → null too — a fix round whose source review
|
|
950
1022
|
* is unreadable is never a zero-findings fabrication: a round whose blocker set
|
|
@@ -977,7 +1049,7 @@ export class Ledger {
|
|
|
977
1049
|
// shared with the fix leg below (`HandoffSchema.conclusionOf`).
|
|
978
1050
|
status: this.#handoffSchema.conclusionOf("findings", carrier),
|
|
979
1051
|
findings: this.#findingsOf(carrier),
|
|
980
|
-
|
|
1052
|
+
reviewsPath: this.handoffPath("review", type, reviewParams),
|
|
981
1053
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
|
982
1054
|
};
|
|
983
1055
|
}
|
|
@@ -997,7 +1069,7 @@ export class Ledger {
|
|
|
997
1069
|
// the same `conclusionOf` single source (D27).
|
|
998
1070
|
status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
|
|
999
1071
|
findings: this.#findingsOf(reviewCarrier),
|
|
1000
|
-
|
|
1072
|
+
reviewsPath: this.handoffPath("review", type, reviewParams),
|
|
1001
1073
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
|
1002
1074
|
};
|
|
1003
1075
|
}
|
package/src-next/session/next.ts
CHANGED
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
// Module-level exports are types / constants / the class — zero behavior-carrying
|
|
36
36
|
// bare functions (the plan's zero-bare-function discipline).
|
|
37
37
|
|
|
38
|
+
import type { RouteTarget } from "./faces.ts";
|
|
38
39
|
import type { Round } from "./ledger.ts";
|
|
39
40
|
import type { ExecutionState } from "./state.ts";
|
|
40
41
|
|
|
@@ -48,8 +49,8 @@ export type Route =
|
|
|
48
49
|
| { kind: "next-wave"; tasks: string }
|
|
49
50
|
/** a review hop — a review judges the live tree, carrying no commit identity. */
|
|
50
51
|
| { kind: "review" }
|
|
51
|
-
/** the one-way fix hop —
|
|
52
|
-
| { kind: "fix";
|
|
52
|
+
/** the one-way fix hop — reviewsPath = the review handoff the fix reads (`--reviews`). */
|
|
53
|
+
| { kind: "fix"; reviews?: string }
|
|
53
54
|
/** the review-cycle soft cap — the suggestion defers to user adjudication. */
|
|
54
55
|
| { kind: "soft-cap"; message: string }
|
|
55
56
|
/** the face-to-face handoff (D40) — the line's C5 frontier exhausted, so the next
|
|
@@ -59,8 +60,16 @@ export type Route =
|
|
|
59
60
|
|
|
60
61
|
/** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
|
|
61
62
|
* defers the next hop to user adjudication (soft by nature: a default suggestion,
|
|
62
|
-
* never a hard stop — the user /
|
|
63
|
-
export const REVIEW_CYCLE_CAP =
|
|
63
|
+
* never a hard stop — the user / the plan write authority override it). */
|
|
64
|
+
export const REVIEW_CYCLE_CAP = 20;
|
|
65
|
+
|
|
66
|
+
/** The decision-edge words of the Route union — the C5 hop kinds that a review/fix
|
|
67
|
+
* closure decision edge renders as a `next:` label (`done` · `next-wave` · `review`
|
|
68
|
+
* · `fix` · `soft-cap`). The pure face-to-face `handoff` kind is EXCLUDED: it carries
|
|
69
|
+
* no decision word (it renders the pipeline entry ref/literal, never a branch label).
|
|
70
|
+
* The skill-anatomy contract's `edgeConditionWords` derives from this tuple — the
|
|
71
|
+
* runtime Route lexicon is the ONE source, never a second hand-written list. */
|
|
72
|
+
export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft-cap"] as const;
|
|
64
73
|
|
|
65
74
|
// ---------------------------------------------------------------------------
|
|
66
75
|
// the face indirection line — the pipeline's face-to-face `done` routing table (D33)
|
|
@@ -92,6 +101,42 @@ export const PIPELINE_NEXT: Readonly<Record<PipelineKey, PipelineEntry>> = {
|
|
|
92
101
|
branch: { kind: "ref", ref: "kairos:cdd-close" },
|
|
93
102
|
};
|
|
94
103
|
|
|
104
|
+
/** The pipeline's phase-level face keys (D40) — `PipelineKey` minus the program-level
|
|
105
|
+
* `overall-spec` (whose closure is the pipeline terminus, rendered by the capsule,
|
|
106
|
+
* never walked). */
|
|
107
|
+
export type PhaseFaceKey = Exclude<PipelineKey, "overall-spec">;
|
|
108
|
+
|
|
109
|
+
/** The pipeline's phase-level face order (D40) — the face-to-face traversal
|
|
110
|
+
* `spec → plan → wave → branch`, the ONE order declaration; `NextStepRouter.walk`
|
|
111
|
+
* iterates it, so a consumer maps key → facts and declares NO order of its own. */
|
|
112
|
+
export const PIPELINE_FACES: readonly PhaseFaceKey[] = ["phase-spec", "plan", "wave", "branch"];
|
|
113
|
+
|
|
114
|
+
/** One pipeline face's OBSERVED state — the per-face facts a consumer reads off
|
|
115
|
+
* disk and the ledger (never a judgment): whether the face is closed, its ACTIVE
|
|
116
|
+
* C5 hop (null when the face never started), and the render target the literal
|
|
117
|
+
* needs. The walk (`NextStepRouter.walk`) is the ONE decider over these
|
|
118
|
+
* observations — a consumer reports facts, the router resolves the next step. */
|
|
119
|
+
export interface PipelineFaceState {
|
|
120
|
+
/** Whether the face's line is closed (its latest C5 route lies on the closure
|
|
121
|
+
* side) — a face holding no open work (an empty wave segment) is closed. */
|
|
122
|
+
closed: boolean;
|
|
123
|
+
/** The face's active C5 hop — null when the face holds no open hop (not started). */
|
|
124
|
+
active: Route | null;
|
|
125
|
+
/** The face's render target (the literal's type + id + plan), or null when absent. */
|
|
126
|
+
target: RouteTarget | null;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** The consumer's face report — one observation per phase face, keyed by its
|
|
130
|
+
* `PIPELINE_FACES` key (the order stays the router's; the consumer names faces). */
|
|
131
|
+
export type PipelineFaceReport = Readonly<Record<PhaseFaceKey, PipelineFaceState>>;
|
|
132
|
+
|
|
133
|
+
/** The walk's verdict — the ONE next Route + the render target it belongs to (the
|
|
134
|
+
* frontier face's own target; the last face's on the all-closed terminal). */
|
|
135
|
+
export interface PipelineNext {
|
|
136
|
+
route: Route;
|
|
137
|
+
target: RouteTarget | null;
|
|
138
|
+
}
|
|
139
|
+
|
|
95
140
|
/** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
|
|
96
141
|
export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
|
|
97
142
|
|
|
@@ -108,8 +153,11 @@ export const FIX_READBACK_SUFFIX =
|
|
|
108
153
|
"(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
|
|
109
154
|
|
|
110
155
|
/** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
|
|
111
|
-
* produces no `next:` line on any op.
|
|
112
|
-
|
|
156
|
+
* produces no `next:` line on any op. Exported as the ONE failure-status set: the
|
|
157
|
+
* skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
|
|
158
|
+
* failure statuses from the decision-edge status words (a failure round carries no
|
|
159
|
+
* closure edge — the reason rides the CDD_BLOCKED channel). */
|
|
160
|
+
export const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
|
|
113
161
|
|
|
114
162
|
/**
|
|
115
163
|
* NextStepRouter — the C5 decision table as one instance method. The router keeps
|
|
@@ -131,7 +179,7 @@ export class NextStepRouter {
|
|
|
131
179
|
// One-way: any findings (any severity) → the fix round — a review never previews
|
|
132
180
|
// what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
|
|
133
181
|
// ready batch decides whether the next wave continues or the run is exhausted.
|
|
134
|
-
if (ref.findings.length > 0) return { kind: "fix",
|
|
182
|
+
if (ref.findings.length > 0) return { kind: "fix", reviews: ref.reviewsPath };
|
|
135
183
|
return this.#close(state);
|
|
136
184
|
case "fix": {
|
|
137
185
|
// C5-1: the fix face is the re-review / closure decision point. The soft cap
|
|
@@ -152,7 +200,7 @@ export class NextStepRouter {
|
|
|
152
200
|
// The branch terminal face — findings route the fix; zero findings close the line
|
|
153
201
|
// through the same unified closure terminal.
|
|
154
202
|
return ref.findings.length > 0
|
|
155
|
-
? { kind: "fix",
|
|
203
|
+
? { kind: "fix", reviews: ref.reviewsPath }
|
|
156
204
|
: this.#close(state);
|
|
157
205
|
}
|
|
158
206
|
}
|
|
@@ -178,15 +226,68 @@ export class NextStepRouter {
|
|
|
178
226
|
return { kind: "handoff", entry: PIPELINE_NEXT[key] };
|
|
179
227
|
}
|
|
180
228
|
|
|
181
|
-
/** Resolve a line's next step (D40) — the
|
|
182
|
-
*
|
|
183
|
-
*
|
|
184
|
-
*
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
229
|
+
/** Resolve a line's next step (D40) — the capsule's "one line → next" point for the
|
|
230
|
+
* round's OWN line: an ACTIVE C5 hop (`review` / `fix` / `implement` / `next-wave` /
|
|
231
|
+
* `soft-cap`) passes through as the line's next step; a drained / not-yet-started
|
|
232
|
+
* line (the C5 `done` / no active round) yields the face-to-face handoff carrying
|
|
233
|
+
* the pipeline entry. A null doc-class (no face seam — the overall line / a bare
|
|
234
|
+
* terminal) renders the bare `done` word. A whole-slug walk is `walk` (the board's
|
|
235
|
+
* face-to-face traversal); this is the single-line form the capsule holds. Pure. */
|
|
188
236
|
static resolve(active: Route | null, key: PipelineKey | null): Route {
|
|
189
237
|
if (active !== null && active.kind !== "done") return active;
|
|
190
238
|
return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
|
|
191
239
|
}
|
|
240
|
+
|
|
241
|
+
/** Walk(face report) → the ONE next step (D40 · the board's face-to-face traversal
|
|
242
|
+
* as a single router method). The caller REPORTS each face's facts keyed by its
|
|
243
|
+
* `PIPELINE_FACES` key; the router iterates the ONE order and DECIDES the next step
|
|
244
|
+
* — so no consumer re-derives the order OR the face-transition rule (the retired
|
|
245
|
+
* board fork handed off via the frontier LINE's own key, so a slug whose spec just
|
|
246
|
+
* closed but whose plan was not yet authored rendered `plan`'s exit `cdd-dev`
|
|
247
|
+
* instead of the spec's exit `cdd-plan` — a face-boundary off-by-one the ONE walk
|
|
248
|
+
* eliminates). The rule:
|
|
249
|
+
* · the FRONTIER face (first not-closed) with an active C5 hop → render that hop
|
|
250
|
+
* (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
|
|
251
|
+
* · the frontier has no active hop but IS entered (`target` present — an empty
|
|
252
|
+
* wave segment, a drained-but-reached face) → its OWN pipeline exit entry;
|
|
253
|
+
* · the frontier is NOT entered (no target — an absent doc, e.g. no plan yet) →
|
|
254
|
+
* the transition INTO it, i.e. the PRECEDING entered face's exit entry (so a
|
|
255
|
+
* just-closed spec hands off to the spec's exit `cdd-plan`, never the absent
|
|
256
|
+
* plan's exit); no preceding entered face → the FIRST face's exit entry;
|
|
257
|
+
* · every face closed → the LAST entered face's exit entry (the pipeline
|
|
258
|
+
* terminus — `cdd-close` for a phase slug). */
|
|
259
|
+
static walk(report: PipelineFaceReport): PipelineNext {
|
|
260
|
+
const states = PIPELINE_FACES.map((key) => report[key]);
|
|
261
|
+
const frontierIndex = states.findIndex((face) => !face.closed);
|
|
262
|
+
if (frontierIndex === -1) {
|
|
263
|
+
const terminalIndex = NextStepRouter.#lastEnteredIndex(states);
|
|
264
|
+
const terminal = terminalIndex === -1 ? null : states[terminalIndex]!;
|
|
265
|
+
return terminal === null
|
|
266
|
+
? { route: { kind: "done" }, target: null }
|
|
267
|
+
: {
|
|
268
|
+
route: NextStepRouter.handoff(PIPELINE_FACES[terminalIndex]!),
|
|
269
|
+
target: terminal.target,
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
const frontier = states[frontierIndex]!;
|
|
273
|
+
if (frontier.active !== null) return { route: frontier.active, target: frontier.target };
|
|
274
|
+
const anchorIndex =
|
|
275
|
+
frontier.target !== null
|
|
276
|
+
? frontierIndex
|
|
277
|
+
: Math.max(0, NextStepRouter.#lastEnteredIndex(states.slice(0, frontierIndex)));
|
|
278
|
+
const anchor = states[anchorIndex]!;
|
|
279
|
+
return {
|
|
280
|
+
route: NextStepRouter.handoff(PIPELINE_FACES[anchorIndex]!),
|
|
281
|
+
target: anchor.target,
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/** The index of the last OBSERVED face carrying a render target — the last face the
|
|
286
|
+
* pipeline has REACHED (a face with no target was never entered). -1 when none is. */
|
|
287
|
+
static #lastEnteredIndex(states: readonly PipelineFaceState[]): number {
|
|
288
|
+
for (let i = states.length - 1; i >= 0; i--) {
|
|
289
|
+
if (states[i]!.target !== null) return i;
|
|
290
|
+
}
|
|
291
|
+
return -1;
|
|
292
|
+
}
|
|
192
293
|
}
|
|
@@ -24,11 +24,13 @@
|
|
|
24
24
|
|
|
25
25
|
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
26
26
|
import { PlanDocType } from "../contract/doc.ts";
|
|
27
|
+
import { FrontMatterExtractor } from "../contract/frontmatter.ts";
|
|
27
28
|
import type { DocFs } from "../contract/invariants.ts";
|
|
28
29
|
import type { Contract } from "../contract/judge.ts";
|
|
29
30
|
import type { DocKey } from "../contract/project.ts";
|
|
30
31
|
import type { Words } from "../face/words.ts";
|
|
31
32
|
import type { GitClient } from "../infra/git.ts";
|
|
33
|
+
import { type RepoPath, RepoRoot } from "../infra/root.ts";
|
|
32
34
|
import type { TargetType } from "./faces.ts";
|
|
33
35
|
import { TaskGraph } from "./graph.ts";
|
|
34
36
|
import type { Ledger } from "./ledger.ts";
|
|
@@ -60,14 +62,19 @@ export interface PreFlightVerdict {
|
|
|
60
62
|
|
|
61
63
|
/** The doc-contract target of a spec/plan dispatch. */
|
|
62
64
|
export interface PreFlightDoc {
|
|
63
|
-
/** The target doc type's registry key — read from the doc's
|
|
64
|
-
*
|
|
65
|
-
* the
|
|
66
|
-
* null when a present doc carries no
|
|
65
|
+
/** The target doc type's registry key — read from the doc's front-matter
|
|
66
|
+
* `doc-type:` key (spec §12 · D34; both the spec and the plan faces key by
|
|
67
|
+
* the head key, zero command-type carve-out).
|
|
68
|
+
* null when a present doc carries no key — the seam BLOCKs (zero
|
|
67
69
|
* filename-suffix fallback, one declaration reading face `BoardView.readDocType`). */
|
|
68
70
|
docKey: DocKey | null;
|
|
69
|
-
/** The target doc's path
|
|
70
|
-
|
|
71
|
+
/** The target doc's path — the branded repoRoot-relative `RepoPath` (T4 §2.2: a
|
|
72
|
+
* bare `string` never reaches this read face; the caller feeds the funnel-shaped
|
|
73
|
+
* relative value). The seam erases it to the absolute syscall form through its
|
|
74
|
+
* OWN `RepoRoot(ctx.repoRoot)` just before the read — the brand is REAL (the
|
|
75
|
+
* absolute state is unrepresentable as a `RepoPath`), the same shape as
|
|
76
|
+
* `artifacts.readText(node, root, file: RepoPath)`). */
|
|
77
|
+
path: RepoPath;
|
|
71
78
|
}
|
|
72
79
|
|
|
73
80
|
/** One dispatch's pre-flight inputs — the facts the seam judges. */
|
|
@@ -177,13 +184,37 @@ export class PreFlight {
|
|
|
177
184
|
// Contract.validate (the interpreter's single judgment entry) before its
|
|
178
185
|
// review/fix round dispatches. An unreadable doc carries no judgment (no
|
|
179
186
|
// fabricated findings from an absent surface). A PRESENT doc carrying no
|
|
180
|
-
//
|
|
187
|
+
// `doc-type:` key BLOCKs (spec §12 · D34: the declared type is
|
|
181
188
|
// the one reading face, zero filename-suffix fallback).
|
|
182
189
|
if (ctx.type === "spec" || ctx.type === "plan") {
|
|
183
190
|
gates.push("doc-contract");
|
|
184
191
|
const doc = ctx.doc;
|
|
185
|
-
|
|
186
|
-
|
|
192
|
+
// The relative `RepoPath` erases to the absolute syscall form through the ONE
|
|
193
|
+
// value object (the seam's OWN `RepoRoot(ctx.repoRoot)`) just before the read.
|
|
194
|
+
const docAbsolute = doc === null ? null : new RepoRoot(ctx.repoRoot).resolve(doc.path);
|
|
195
|
+
const content = docAbsolute === null ? null : this.#fs.read(docAbsolute);
|
|
196
|
+
if (content !== null && doc !== null && docAbsolute !== null) {
|
|
197
|
+
// D1 (position-carrying error): a front-matter block the `yaml` engine cannot parse is
|
|
198
|
+
// BLOCKed with the REAL failure (line · column · reason) BEFORE the
|
|
199
|
+
// doc-type judgment — an unparseable head also reads no doc-type, so the
|
|
200
|
+
// parse check must precede the missing-key check (the misread fix: a
|
|
201
|
+
// `[`-led author line reports "invalid YAML", never "no doc-type").
|
|
202
|
+
const { head } = FrontMatterExtractor.split(content);
|
|
203
|
+
const parseError = head.parseError;
|
|
204
|
+
if (parseError !== null) {
|
|
205
|
+
return {
|
|
206
|
+
ok: false,
|
|
207
|
+
gate: "doc-contract",
|
|
208
|
+
reason: "doc-contract",
|
|
209
|
+
message: this.#words
|
|
210
|
+
.routeWord("frontmatterParse")
|
|
211
|
+
.replace("{reason}", parseError.reason)
|
|
212
|
+
.replace("{line}", String(parseError.line))
|
|
213
|
+
.replace("{column}", String(parseError.column))
|
|
214
|
+
.replace("{source}", parseError.source),
|
|
215
|
+
order: gates,
|
|
216
|
+
};
|
|
217
|
+
}
|
|
187
218
|
if (doc.docKey === null) {
|
|
188
219
|
return {
|
|
189
220
|
ok: false,
|
|
@@ -195,7 +226,7 @@ export class PreFlight {
|
|
|
195
226
|
}
|
|
196
227
|
const findings = this.#contract.validate({
|
|
197
228
|
docKey: doc.docKey,
|
|
198
|
-
path:
|
|
229
|
+
path: docAbsolute,
|
|
199
230
|
content,
|
|
200
231
|
root: ctx.repoRoot,
|
|
201
232
|
fs: this.#fs,
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/session/round-naming.ts
|
|
2
|
+
// P11 T4 — the round-naming single source: the frame → artifact-name derivations
|
|
3
|
+
// (report · evidence · brief) the lifecycle's read-back and the dry-run preview
|
|
4
|
+
// share, plus the frame → family-op mapping those names key on. The handoff carrier
|
|
5
|
+
// name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table (the
|
|
6
|
+
// naming table is the single truth, never a second list).
|
|
7
|
+
//
|
|
8
|
+
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
9
|
+
|
|
10
|
+
import type { Workspace } from "../infra/workspace.ts";
|
|
11
|
+
import type { OpType } from "./ledger.ts";
|
|
12
|
+
import type { OpenFrame } from "./run.ts";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* RoundNaming — the one home of a round's prescribed artifact names. A frame's
|
|
16
|
+
* report / evidence / brief names derive here, so every consumer (the lifecycle's
|
|
17
|
+
* write-back and read-back, the dry-run preview, the brief render) names the same
|
|
18
|
+
* artifacts by the same rule — one fact, one place. The class holds only the
|
|
19
|
+
* workspace the names resolve against.
|
|
20
|
+
*/
|
|
21
|
+
export class RoundNaming {
|
|
22
|
+
readonly #workspace: Workspace;
|
|
23
|
+
|
|
24
|
+
constructor(workspace: Workspace) {
|
|
25
|
+
this.#workspace = workspace;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** The handoff-family op of a frame — branch-review rides the review family. The
|
|
29
|
+
* artifact stems embed this op, so the mapping is a naming fact owned here (the
|
|
30
|
+
* lifecycle's op read delegates, never a second copy of the rule). */
|
|
31
|
+
op(frame: OpenFrame): OpType {
|
|
32
|
+
return frame.phase === "branch-review" ? "review" : frame.phase;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The engine-rendered brief path of a wave's task group —
|
|
36
|
+
* `tasks-{tasks}-brief.md` (the implement dispatch's read input; its producer is
|
|
37
|
+
* `CliGate#renderBrief`). */
|
|
38
|
+
brief(tasks: string): string {
|
|
39
|
+
return this.#workspace.resolve(this.briefName(tasks));
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The brief's workspace-relative NAME — the write face takes the name, the read
|
|
43
|
+
* faces take the resolved path (one derivation, both spellings). */
|
|
44
|
+
briefName(tasks: string): string {
|
|
45
|
+
return `tasks-${tasks}-brief.md`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The prescribed report path of a round — the doc line's
|
|
49
|
+
* `{type}-{op}-{round}-report.md` stem, the wave/branch line's
|
|
50
|
+
* `{family}-{op}{-round}-report.md` (the implement round carries no round token:
|
|
51
|
+
* the line keys the implement round alone). */
|
|
52
|
+
report(frame: OpenFrame): string {
|
|
53
|
+
if (frame.type === "spec" || frame.type === "plan") {
|
|
54
|
+
return this.#workspace.resolve(`${frame.type}-${this.op(frame)}-${frame.round}-report.md`);
|
|
55
|
+
}
|
|
56
|
+
const family = frame.type === "wave" ? `tasks-${frame.params.tasks ?? ""}` : "branch";
|
|
57
|
+
const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
|
|
58
|
+
return this.#workspace.resolve(`${family}-${this.op(frame)}${suffix}-report.md`);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The prescribed test-evidence path of a round — "" off the work faces (the doc
|
|
62
|
+
* lines and the review rounds prescribe no evidence file). */
|
|
63
|
+
evidence(frame: OpenFrame): string {
|
|
64
|
+
const name = this.evidenceName(frame);
|
|
65
|
+
return name === "" ? "" : this.#workspace.resolve(name);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The test-evidence file NAME of a work frame — the workspace-relative face the
|
|
69
|
+
* read-back gate reads it by (`{line}-test-evidence.json`: the task families key
|
|
70
|
+
* the line, the branch line names the family alone). "" off the work faces. */
|
|
71
|
+
evidenceName(frame: OpenFrame): string {
|
|
72
|
+
if (frame.type === "spec" || frame.type === "plan") return "";
|
|
73
|
+
if (frame.phase !== "implement" && frame.phase !== "fix") return "";
|
|
74
|
+
const key = frame.type === "wave" ? (frame.params.tasks ?? "") : "";
|
|
75
|
+
const line = key === "" ? this.prefix(frame) : `${this.prefix(frame)}-${key}`;
|
|
76
|
+
return `${line}-test-evidence.json`;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** The evidence file's family prefix — `tasks` for the wave families, `branch`
|
|
80
|
+
* for the branch line (never the misleading tasks- spine). */
|
|
81
|
+
prefix(frame: OpenFrame): string {
|
|
82
|
+
return frame.type === "wave" ? "tasks" : "branch";
|
|
83
|
+
}
|
|
84
|
+
}
|