@oscaner-skills/cdd-engine 3.0.1 → 4.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 +9 -1
- package/README.zh-CN.md +10 -2
- package/dist/contract/declare.js +52 -59
- package/dist/contract/doc.js +31 -35
- package/dist/contract/frontmatter.js +10 -13
- package/dist/contract/invariants.js +172 -96
- package/dist/contract/judge.js +6 -3
- package/dist/contract/lint.js +4 -3
- package/dist/contract/project.js +15 -15
- package/dist/face/board-view.js +203 -242
- package/dist/face/capsule.js +18 -10
- package/dist/face/cli.js +170 -60
- package/dist/face/declare.js +5 -6
- package/dist/face/host.js +1 -1
- package/dist/face/lifecycle.js +192 -92
- package/dist/face/preview.js +1 -1
- package/dist/face/termination.js +33 -5
- package/dist/face/words.js +73 -8
- package/dist/infra/doc-roots.js +1 -0
- package/dist/infra/runtime.js +4 -13
- package/dist/infra/slug-index.js +325 -0
- package/dist/infra/workspace.js +3 -76
- package/dist/render/skeleton.js +21 -30
- package/dist/render/templates.js +48 -23
- package/dist/session/handoff-schema.js +84 -72
- package/dist/session/ledger.js +24 -16
- package/dist/session/next.js +1 -1
- package/dist/session/preflight.js +27 -24
- package/dist/session/round-naming.js +2 -2
- package/dist/session/run.js +28 -16
- package/dist/session/wave.js +30 -7
- package/package.json +1 -1
package/dist/session/ledger.js
CHANGED
|
@@ -25,7 +25,7 @@ import { createHash } from "node:crypto";
|
|
|
25
25
|
import { readFileSync } from "node:fs";
|
|
26
26
|
import { BriefRenderer } from "../render/brief.js";
|
|
27
27
|
import { targetFaces } from "./faces.js";
|
|
28
|
-
import { HandoffSchema
|
|
28
|
+
import { HandoffSchema } from "./handoff-schema.js";
|
|
29
29
|
import { NextStepRouter } from "./next.js";
|
|
30
30
|
import { EMPTY_RUN_STATE } from "./run.js";
|
|
31
31
|
// ---------------------------------------------------------------------------
|
|
@@ -93,7 +93,7 @@ export class Ledger {
|
|
|
93
93
|
* the `closedWaves()` read face and the wave gate share the same router). */
|
|
94
94
|
#router = new NextStepRouter();
|
|
95
95
|
/** The handoff-schema face — the conclusion single source (`conclusionOf`), one
|
|
96
|
-
* instance per ledger (the round verdict derives from the
|
|
96
|
+
* instance per ledger (the round verdict derives from the op's carrier plane at
|
|
97
97
|
* judgment time · D27). */
|
|
98
98
|
#handoffSchema = new HandoffSchema();
|
|
99
99
|
/** The review-reference face (T25) — the refKind classification + the same-ref
|
|
@@ -446,6 +446,15 @@ export class Ledger {
|
|
|
446
446
|
this.writeProgress(data);
|
|
447
447
|
return data.timeoutCount;
|
|
448
448
|
}
|
|
449
|
+
/** Increment the contract-violation counter — the read-back write point (one
|
|
450
|
+
* `handoff-absent` or `contract-violation` crash lands, the count goes up by
|
|
451
|
+
* one). The counter's only writer. */
|
|
452
|
+
incrementContractViolationCount() {
|
|
453
|
+
const data = this.readProgress() ?? this.emptyProgress();
|
|
454
|
+
data.contractViolationCount += 1;
|
|
455
|
+
this.writeProgress(data);
|
|
456
|
+
return data.contractViolationCount;
|
|
457
|
+
}
|
|
449
458
|
// -------------------------------------------------------------------------
|
|
450
459
|
// closedWaves — the closure single read face (v1.20)
|
|
451
460
|
// -------------------------------------------------------------------------
|
|
@@ -583,12 +592,12 @@ export class Ledger {
|
|
|
583
592
|
throw new Error(`unknown handoff family: ${op}.${type}`);
|
|
584
593
|
return family;
|
|
585
594
|
}
|
|
586
|
-
/** The
|
|
587
|
-
*
|
|
588
|
-
* findings
|
|
589
|
-
*
|
|
590
|
-
|
|
591
|
-
return
|
|
595
|
+
/** The carrier PLANE of an op — the ONE op-derived derivation (`HandoffSchema.planeOf`).
|
|
596
|
+
* The plane-aware read/write/bookkeep spine: a judge-plane round (review) rides the
|
|
597
|
+
* findings writable subset, a work-plane round (implement / fix) rides the
|
|
598
|
+
* status-bearing work subset — never the caller's guess, never a per-family declaration. */
|
|
599
|
+
planeOf(op) {
|
|
600
|
+
return HandoffSchema.planeOf(op);
|
|
592
601
|
}
|
|
593
602
|
/** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
|
|
594
603
|
handoffName(op, type, params = {}) {
|
|
@@ -600,9 +609,9 @@ export class Ledger {
|
|
|
600
609
|
handoffPath(op, type, params = {}) {
|
|
601
610
|
return this.#workspace.resolve(this.handoffName(op, type, params));
|
|
602
611
|
}
|
|
603
|
-
buildHandoff(
|
|
612
|
+
buildHandoff(plane, init = {}) {
|
|
604
613
|
const carrier = { artifacts: init.artifacts ?? {} };
|
|
605
|
-
if (
|
|
614
|
+
if (plane === "judge" || init.findings !== undefined)
|
|
606
615
|
carrier.findings = init.findings;
|
|
607
616
|
return carrier;
|
|
608
617
|
}
|
|
@@ -729,9 +738,9 @@ export class Ledger {
|
|
|
729
738
|
return {
|
|
730
739
|
phase: "review",
|
|
731
740
|
// The conclusion is DERIVED from the review carrier's own findings at judgment
|
|
732
|
-
// time (D27 · the
|
|
733
|
-
// shared with the fix leg below (`HandoffSchema.conclusionOf`).
|
|
734
|
-
status: this.#handoffSchema.conclusionOf("
|
|
741
|
+
// time (D27 · the judge-plane carrier holds no status field) — the single
|
|
742
|
+
// source shared with the fix leg below (`HandoffSchema.conclusionOf`).
|
|
743
|
+
status: this.#handoffSchema.conclusionOf("judge", carrier),
|
|
735
744
|
findings: this.#findingsOf(carrier),
|
|
736
745
|
reviewsPath: this.handoffPath("review", type, reviewParams),
|
|
737
746
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
|
@@ -750,9 +759,8 @@ export class Ledger {
|
|
|
750
759
|
return {
|
|
751
760
|
phase: "fix",
|
|
752
761
|
// The fix round's conclusion derives from ITS OWN carrier's declared plane (the
|
|
753
|
-
// work
|
|
754
|
-
|
|
755
|
-
status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
|
|
762
|
+
// work plane reads its status) — the same `conclusionOf` single source (D27).
|
|
763
|
+
status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
|
|
756
764
|
findings: this.#findingsOf(reviewCarrier),
|
|
757
765
|
reviewsPath: this.handoffPath("review", type, reviewParams),
|
|
758
766
|
consecutiveS1: this.#consecutiveS1Run(type, params, round),
|
package/dist/session/next.js
CHANGED
|
@@ -53,7 +53,7 @@ export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft
|
|
|
53
53
|
* frame's plan fact. */
|
|
54
54
|
export const PIPELINE_NEXT = {
|
|
55
55
|
"phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
|
|
56
|
-
|
|
56
|
+
overall: { kind: "done" },
|
|
57
57
|
plan: { kind: "ref", ref: "kairos:cdd-dev" },
|
|
58
58
|
wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
|
|
59
59
|
branch: { kind: "ref", ref: "kairos:cdd-close" },
|
|
@@ -21,10 +21,11 @@
|
|
|
21
21
|
//
|
|
22
22
|
// Module-level exports are types / the class — zero behavior-carrying bare
|
|
23
23
|
// functions (the plan's zero-bare-function discipline).
|
|
24
|
-
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
25
24
|
import { PlanDocType } from "../contract/doc.js";
|
|
26
25
|
import { FrontMatterExtractor } from "../contract/frontmatter.js";
|
|
26
|
+
import { NodeFs } from "../contract/invariants.js";
|
|
27
27
|
import { RepoRoot } from "../infra/root.js";
|
|
28
|
+
import { SlugIndex } from "../infra/slug-index.js";
|
|
28
29
|
import { TaskGraph } from "./graph.js";
|
|
29
30
|
import { WaveGate } from "./wave.js";
|
|
30
31
|
/**
|
|
@@ -140,11 +141,32 @@ export class PreFlight {
|
|
|
140
141
|
};
|
|
141
142
|
}
|
|
142
143
|
if (doc.docKey === null) {
|
|
144
|
+
// Two shapes, one gate: a head carrying no `doc-type:` key reads the
|
|
145
|
+
// missing-key word; a head carrying an out-of-domain value reads the
|
|
146
|
+
// word that names the value and lists the declared domain.
|
|
147
|
+
const message = head.docType === null
|
|
148
|
+
? this.#words.routeWord("docType")
|
|
149
|
+
: this.#words.docTypeValueWord(head.docType);
|
|
143
150
|
return {
|
|
144
151
|
ok: false,
|
|
145
152
|
gate: "doc-contract",
|
|
146
153
|
reason: "doc-contract",
|
|
147
|
-
message
|
|
154
|
+
message,
|
|
155
|
+
order: gates,
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
// The identity gate (spec §2.1/§2.2) — same face, same carrier: the
|
|
159
|
+
// workspace key is the declared `slug:`, and the four-way judgment is the
|
|
160
|
+
// SAME `SlugIndex` one the board and the dispatch carrier read (one fact,
|
|
161
|
+
// one rule; this carrier supplies the pre-flight verdict shape only).
|
|
162
|
+
const index = SlugIndex.build(ctx.repoRoot, this.#fs);
|
|
163
|
+
const verdict = index.slugVerdict(doc.path, head.slug);
|
|
164
|
+
if (verdict.kind !== "accepted") {
|
|
165
|
+
return {
|
|
166
|
+
ok: false,
|
|
167
|
+
gate: "doc-contract",
|
|
168
|
+
reason: "doc-contract",
|
|
169
|
+
message: this.#words.slugRefusal(verdict),
|
|
148
170
|
order: gates,
|
|
149
171
|
};
|
|
150
172
|
}
|
|
@@ -153,6 +175,9 @@ export class PreFlight {
|
|
|
153
175
|
path: docAbsolute,
|
|
154
176
|
content,
|
|
155
177
|
root: ctx.repoRoot,
|
|
178
|
+
// The SAME index the identity gates above read — one scan per dispatch,
|
|
179
|
+
// and the contract's chain / slug-ref lookups judge the identical facts.
|
|
180
|
+
slugIndex: index,
|
|
156
181
|
fs: this.#fs,
|
|
157
182
|
});
|
|
158
183
|
if (findings.length > 0) {
|
|
@@ -170,25 +195,3 @@ export class PreFlight {
|
|
|
170
195
|
return { ok: true, order: gates };
|
|
171
196
|
}
|
|
172
197
|
}
|
|
173
|
-
/** The node:fs default — the production seam for the doc-contract's file reads. */
|
|
174
|
-
class NodeFs {
|
|
175
|
-
read(p) {
|
|
176
|
-
try {
|
|
177
|
-
return readFileSync(p, "utf8");
|
|
178
|
-
}
|
|
179
|
-
catch {
|
|
180
|
-
return null;
|
|
181
|
-
}
|
|
182
|
-
}
|
|
183
|
-
exists(p) {
|
|
184
|
-
return existsSync(p);
|
|
185
|
-
}
|
|
186
|
-
list(p) {
|
|
187
|
-
try {
|
|
188
|
-
return readdirSync(p);
|
|
189
|
-
}
|
|
190
|
-
catch {
|
|
191
|
-
return [];
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
}
|
|
@@ -47,7 +47,7 @@ export class RoundNaming {
|
|
|
47
47
|
const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
|
|
48
48
|
return this.#workspace.resolve(`${family}-${this.op(frame)}${suffix}-report.md`);
|
|
49
49
|
}
|
|
50
|
-
/** The prescribed test-evidence path of a round — "" off the
|
|
50
|
+
/** The prescribed test-evidence path of a round — "" off the evidence rounds (the doc
|
|
51
51
|
* lines and the review rounds prescribe no evidence file). */
|
|
52
52
|
evidence(frame) {
|
|
53
53
|
const name = this.evidenceName(frame);
|
|
@@ -55,7 +55,7 @@ export class RoundNaming {
|
|
|
55
55
|
}
|
|
56
56
|
/** The test-evidence file NAME of a work frame — the workspace-relative face the
|
|
57
57
|
* read-back gate reads it by (`{line}-test-evidence.json`: the task families key
|
|
58
|
-
* the line, the branch line names the family alone). "" off the
|
|
58
|
+
* the line, the branch line names the family alone). "" off the evidence rounds. */
|
|
59
59
|
evidenceName(frame) {
|
|
60
60
|
if (frame.type === "spec" || frame.type === "plan")
|
|
61
61
|
return "";
|
package/dist/session/run.js
CHANGED
|
@@ -131,6 +131,7 @@ export class Lifecycle {
|
|
|
131
131
|
round,
|
|
132
132
|
route,
|
|
133
133
|
capsuleLines: this.#capsuleLines(frame, outcome, route),
|
|
134
|
+
termination: outcome.termination,
|
|
134
135
|
};
|
|
135
136
|
}
|
|
136
137
|
// -------------------------------------------------------------------------
|
|
@@ -283,25 +284,25 @@ export class Lifecycle {
|
|
|
283
284
|
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
284
285
|
if (outcome.carrier !== undefined || !blocked) {
|
|
285
286
|
const op = this.#opOf(frame.phase);
|
|
286
|
-
// T2 — the engine-built fallback rides the FRAME's
|
|
287
|
-
//
|
|
288
|
-
//
|
|
289
|
-
//
|
|
290
|
-
//
|
|
287
|
+
// T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
|
|
288
|
+
// outcome's field presence): a judge-plane round (review) builds the findings
|
|
289
|
+
// carrier — its schema-required findings key, empty on a conclusion-only round
|
|
290
|
+
// (a review advances no new findings); a work-plane round (implement / fix,
|
|
291
|
+
// docs-fix included) builds the findings-free work carrier — zero findings
|
|
291
292
|
// injection. The review finding-severity route reads the round carrier's
|
|
292
|
-
// findings; the conclusion rides only the work
|
|
293
|
-
//
|
|
294
|
-
const
|
|
293
|
+
// findings; the conclusion rides only the work plane's declared status (the
|
|
294
|
+
// judge plane derives its conclusion at judgment time).
|
|
295
|
+
const plane = this.#ledger.planeOf(op);
|
|
295
296
|
const carrier = outcome.carrier ??
|
|
296
|
-
(
|
|
297
|
-
? this.#ledger.buildHandoff("
|
|
297
|
+
(plane === "judge"
|
|
298
|
+
? this.#ledger.buildHandoff("judge", {
|
|
298
299
|
findings: [...(outcome.findings ?? [])],
|
|
299
300
|
})
|
|
300
301
|
: this.#ledger.buildHandoff("work", {}));
|
|
301
|
-
// The work
|
|
302
|
-
//
|
|
302
|
+
// The work plane ALONE persists the conclusion (the child's declared status); the
|
|
303
|
+
// judge carrier holds no status — its conclusion derives at judgment time
|
|
303
304
|
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
304
|
-
if (
|
|
305
|
+
if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
305
306
|
carrier.status = outcome.status;
|
|
306
307
|
this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
307
308
|
}
|
|
@@ -400,7 +401,10 @@ export class Lifecycle {
|
|
|
400
401
|
return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
|
|
401
402
|
}
|
|
402
403
|
/** The capsule lines of one step — empty unless a capsule is attached (the non-hard
|
|
403
|
-
* interaction point).
|
|
404
|
+
* interaction point). A success round carries the real blocker count and the
|
|
405
|
+
* handoff carrier path. A failure round (TIMEOUT / BLOCKED) carries no blocker
|
|
406
|
+
* cell (its count would be a filler); its handoff cell is the crash record and is
|
|
407
|
+
* emitted only when that record exists (a no-host BLOCKED writes none). The
|
|
404
408
|
* dispatch-ready `next:` literal rides the frame's own RouteTarget identity
|
|
405
409
|
* (type + id — the v1.25 combination point: frame.type + params.tasks + route
|
|
406
410
|
* are all present here). */
|
|
@@ -408,9 +412,17 @@ export class Lifecycle {
|
|
|
408
412
|
if (this.#capsule === null)
|
|
409
413
|
return [];
|
|
410
414
|
const op = this.#opOf(frame.phase);
|
|
415
|
+
const failure = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
416
|
+
const lane = `${op}.${frame.type}`;
|
|
417
|
+
// The failure face's handoff is the crash record — the engine's own postmortem
|
|
418
|
+
// artifact, its existence the emission condition; the success face keeps the
|
|
419
|
+
// round's handoff carrier path.
|
|
420
|
+
const crash = failure ? this.#ledger.readCrash(lane, frame.round) : null;
|
|
411
421
|
const blockers = (outcome.findings ?? []).filter((finding) => finding.severity === "blocker").length;
|
|
412
|
-
const handoff =
|
|
413
|
-
|
|
422
|
+
const handoff = crash !== null
|
|
423
|
+
? this.#ledger.crashPath(lane, frame.round)
|
|
424
|
+
: this.#ledger.handoffPath(op, frame.type, frame.params);
|
|
425
|
+
return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame), crash !== null);
|
|
414
426
|
}
|
|
415
427
|
/** The frame's RouteTarget — the dispatch-ready literal's target identity (the
|
|
416
428
|
* frame's own facts: the wave task key · the branch line key · the doc path).
|
package/dist/session/wave.js
CHANGED
|
@@ -8,10 +8,13 @@
|
|
|
8
8
|
//
|
|
9
9
|
// The gate's only read face is `open = frontier(closedWaves())` — the derived
|
|
10
10
|
// wave over the ledger's C5 closure set (ledger.ts, the same closure predicate as
|
|
11
|
-
// the lifecycle's #markTerminal). The
|
|
12
|
-
// 1. requested
|
|
11
|
+
// the lifecycle's #markTerminal). The three judgments:
|
|
12
|
+
// 1. requested hits a derived static batch (graph.batches()) that mixes closed
|
|
13
|
+
// and open tasks → the mixed-batch BLOCK (a batch closes as a unit — a plan
|
|
14
|
+
// revision must not strand the rest of a partly-executed batch as its own wave);
|
|
15
|
+
// 2. requested ≠ open → the split/subset BLOCK (dispatch the full derived wave,
|
|
13
16
|
// with the wave-board hint);
|
|
14
|
-
//
|
|
17
|
+
// 3. the open wave's phase ≠ verb → the wrong-phase BLOCK (run the matching phase).
|
|
15
18
|
// (v1.28 — the heterogeneous-phase row RETIRED: the wave-unitary ledger has ONE row
|
|
16
19
|
// per wave, so mixed per-task phases are structurally impossible — a per-task phase
|
|
17
20
|
// read was the T26 regression {16,22,24} exposed (the row key `16` never matched
|
|
@@ -25,8 +28,9 @@
|
|
|
25
28
|
/**
|
|
26
29
|
* WaveGate — the three-verb unified wave gate (implement / review / fix share the
|
|
27
30
|
* single gate). One OOP method: vet(requested, verb) judges the request against
|
|
28
|
-
* the derived open wave
|
|
29
|
-
* ANY task-face dispatch, never a variant gate per
|
|
31
|
+
* the plan's static batches, the derived open wave, and the ledger's per-task
|
|
32
|
+
* phases; the CLI calls it before ANY task-face dispatch, never a variant gate per
|
|
33
|
+
* verb.
|
|
30
34
|
*/
|
|
31
35
|
export class WaveGate {
|
|
32
36
|
/** vet(requested, verb, graph, ledger, words) — the three-verb gate: the verdict
|
|
@@ -39,7 +43,26 @@ export class WaveGate {
|
|
|
39
43
|
const openKey = open.join(",");
|
|
40
44
|
const wordsGate = words.waveGateWords();
|
|
41
45
|
const exact = asked.length === open.length && asked.every((id, index) => id === open[index]);
|
|
42
|
-
// 1. The
|
|
46
|
+
// 1. The static-batch mix BLOCK — the requested set hits a derived batch that
|
|
47
|
+
// mixes closed and open tasks. A batch closes as a unit: a plan revision
|
|
48
|
+
// that adds tasks to a partly-executed batch must re-declare the edges, not
|
|
49
|
+
// let the leftover tasks ride out as their own wave. Judged BEFORE the exact
|
|
50
|
+
// read (the derived open wave alone cannot see the closed batch siblings).
|
|
51
|
+
const batch = graph.batches().find((derived) => derived.some((id) => requested.has(id)));
|
|
52
|
+
if (batch?.some((id) => closed.has(id)) && batch.some((id) => !closed.has(id))) {
|
|
53
|
+
return {
|
|
54
|
+
ok: false,
|
|
55
|
+
reason: "mixed-batch",
|
|
56
|
+
message: this.#fill(wordsGate.mixedBatch, {
|
|
57
|
+
batch: batch.join(","),
|
|
58
|
+
closed: batch.filter((id) => closed.has(id)).join(","),
|
|
59
|
+
open: batch.filter((id) => !closed.has(id)).join(","),
|
|
60
|
+
}),
|
|
61
|
+
open,
|
|
62
|
+
phases: this.#phasesOf(ledger, open),
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
// 2. The split/subset BLOCK — requested ≠ open: a `--tasks` set that splits or
|
|
43
66
|
// mismatches the derived wave is refused for ANY verb (a subset never reorders
|
|
44
67
|
// the wave, never half-approves it). The full-wave hint rides the message.
|
|
45
68
|
if (!exact) {
|
|
@@ -51,7 +74,7 @@ export class WaveGate {
|
|
|
51
74
|
phases: this.#phasesOf(ledger, open),
|
|
52
75
|
};
|
|
53
76
|
}
|
|
54
|
-
//
|
|
77
|
+
// 3. The open wave's phase — the single phase of the wave's own row (wave-unitary:
|
|
55
78
|
// one ledger row per wave, so every member shares the phase; a per-task read
|
|
56
79
|
// never matches the wave row — the T26 migration regression).
|
|
57
80
|
const phases = this.#phasesOf(ledger, open);
|