@oscaner-skills/cdd-engine 4.2.0 → 4.4.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 +38 -9
- package/README.zh-CN.md +44 -10
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +382 -172
- package/dist/face/capsule.js +73 -88
- package/dist/face/cli.js +152 -38
- package/dist/face/declare.js +42 -19
- package/dist/face/gate.js +119 -40
- package/dist/face/init.js +84 -25
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +70 -2
- package/dist/face/preview.js +69 -18
- package/dist/face/route-render.js +60 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +139 -13
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +603 -145
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +140 -80
- package/dist/session/pipeline.js +247 -0
- package/dist/session/preflight.js +276 -68
- package/dist/session/reviewed-identity.js +54 -0
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +364 -80
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
package/dist/face/capsule.js
CHANGED
|
@@ -1,26 +1,37 @@
|
|
|
1
1
|
// packages/cdd-engine/src-next/face/capsule.ts
|
|
2
|
-
// T10 — the single capsule face (design spec §3.2: the `status ·
|
|
3
|
-
//
|
|
4
|
-
//
|
|
2
|
+
// T10 — the single capsule face (design spec §3.2: the `status · handoff` + route
|
|
3
|
+
// word-face steady state; P22 §10: the output face's closeout). Both station anchors
|
|
4
|
+
// ride the word table (`next:` and the `reason:` row that follows it). Capsule#emit
|
|
5
|
+
// renders the ALL-OP single stdout face — the capsule the orchestrator greps /
|
|
6
|
+
// routes on without opening the handoff:
|
|
5
7
|
//
|
|
6
|
-
// status: <status> ·
|
|
7
|
-
// status: <status> [· handoff: <crash>]
|
|
8
|
+
// status: <status> · handoff: <handoff> (success statuses)
|
|
9
|
+
// status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
|
|
10
|
+
// fixed N · rejected M (fix rounds only — between the status line and `next:`)
|
|
8
11
|
// next: <suggestion> (optional — the C5 route / a caller-rendered text)
|
|
12
|
+
// reason: <token> (only after `next:` — the hop's named fact; no hop, no row)
|
|
9
13
|
//
|
|
10
|
-
// The
|
|
11
|
-
//
|
|
12
|
-
//
|
|
14
|
+
// The `blocker` cell is retired: its whole information content — the blocker count —
|
|
15
|
+
// is derivable from `status` (any blocker ⇒ CHANGES_REQUESTED, warn/nit-only ⇒
|
|
16
|
+
// REVIEW_FIX, empty ⇒ APPROVED, a failure round prints no cell at all), and that
|
|
17
|
+
// count is exactly the number the review criterion rules undisplayed. The key set is
|
|
18
|
+
// still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
|
|
19
|
+
// a failure status keeps the handoff cell only when the round wrote a crash record.
|
|
20
|
+
// The fix round's disposition summary rides the SAME render, placed so the
|
|
21
|
+
// dispatchable `next:` literal keeps its line: `status` → summary → `next:` →
|
|
22
|
+
// `reason:`.
|
|
13
23
|
//
|
|
14
|
-
// The byte face is v1-pinned: the key words (status ·
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
// vocabulary — a second table is excluded by
|
|
24
|
+
// The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
|
|
25
|
+
// the CapsuleKey type and the emit signature — a data-only change cannot reshape
|
|
26
|
+
// them. What rides the injected Words table (the single word-table instance) is the
|
|
27
|
+
// `·` separator, the two route station anchors (`next:` and the `reason:` row that
|
|
28
|
+
// follows it) and the route/status vocabulary — a second table is excluded by
|
|
29
|
+
// construction. The `next:` value is
|
|
19
30
|
// either a caller-rendered string or the C5 Route rendered through the route-word
|
|
20
31
|
// table as a COMPLETE EXECUTABLE command (P4.1 T4 — the v1.39 semantic-literal
|
|
21
|
-
// reversal): `implement --plan <path> --tasks 17` · `review --type spec --spec
|
|
22
|
-
// <path>` · `fix --type spec --spec <path> --reviews <handoff
|
|
23
|
-
//
|
|
32
|
+
// reversal): `implement --plan <path> --tasks 17` · `review --type phase-spec --spec
|
|
33
|
+
// <path>` · `fix --type phase-spec --spec <path> --reviews <handoff>` + the readback
|
|
34
|
+
// suffix · `done` (the bare terminal word) · the soft-cap message verbatim.
|
|
24
35
|
// The argv is composed from the frame facts (the RouteTarget's type + id + plan)
|
|
25
36
|
// through the argv-channel flag spellings (the same channel the CLI parse reads —
|
|
26
37
|
// the render source is the declared channel, never a second hard-coded format
|
|
@@ -31,28 +42,31 @@
|
|
|
31
42
|
// message — rides declared constants from session/next.ts, rendered by reference,
|
|
32
43
|
// never restated.
|
|
33
44
|
//
|
|
34
|
-
// D40 — the render delegates to the shared `RouteRenderer` (the ONE
|
|
35
|
-
// `next:` literal face, also consumed by the board)
|
|
36
|
-
// `
|
|
37
|
-
//
|
|
45
|
+
// D40 · P22 §5.2 — the render delegates to the shared `RouteRenderer` (the ONE
|
|
46
|
+
// route → `next:` literal face, also consumed by the board). The capsule reads the
|
|
47
|
+
// INJECTED `NextHop` — the ONE object every read face renders — and adds no
|
|
48
|
+
// judgment of its own: the doc-class discrimination that picks the pipeline station
|
|
49
|
+
// belongs to the derivation's injected seam (`BoardView.docClassOf`), never here.
|
|
50
|
+
// A `NextHop` that is ABSENT (the BLOCKED / TIMEOUT failure face) prints neither
|
|
51
|
+
// route row; a present hop with `hop: null` (`done` · `soft-cap` · the doc-class
|
|
52
|
+
// `terminal` / `blocked` rows) still prints its frozen line.
|
|
38
53
|
//
|
|
39
54
|
// The class satisfies the session/run.ts CapsuleFace seam (T8's interaction point) —
|
|
40
55
|
// the capsule plugs into the lifecycle's attachCapsule contact, byte-identically.
|
|
41
56
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
42
|
-
import { RepoRoot } from "../infra/root.js";
|
|
43
|
-
import { NextStepRouter } from "../session/next.js";
|
|
44
|
-
import { BoardView } from "./board-view.js";
|
|
45
57
|
import { RouteRenderer } from "./route-render.js";
|
|
46
58
|
/**
|
|
47
|
-
* Capsule — the single capsule output face. emit(status,
|
|
48
|
-
* renders one round's facts into the byte-pinned `status ·
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
59
|
+
* Capsule — the single capsule output face. emit(status, handoff, hop?,
|
|
60
|
+
* withHandoff?, summary?) renders one round's facts into the byte-pinned `status ·
|
|
61
|
+
* handoff` line, the fix round's optional disposition summary, and the optional
|
|
62
|
+
* `next:` row plus its `reason:` row LAST (the dispatchable literal keeps its exact
|
|
63
|
+
* bytes; the diagnostic fact rides the line after it). The key words are
|
|
64
|
+
* the CapsuleKey literals the kind loop renders (pin-enforced by the emit
|
|
65
|
+
* signature); the separator, station and route/status words ride the injected Words
|
|
66
|
+
* instance. The complete executable `next:` literal composes its full argv from the
|
|
67
|
+
* injected `NextHop`'s route + target through the argv-channel flag spellings (P4.1
|
|
68
|
+
* T4; same channel source the parse reads — the hop is optional, the channel an
|
|
69
|
+
* optional 2nd constructor argument).
|
|
56
70
|
*/
|
|
57
71
|
export class Capsule {
|
|
58
72
|
/** The single word table — the capsule's whole vocabulary source. */
|
|
@@ -68,24 +82,29 @@ export class Capsule {
|
|
|
68
82
|
this.#root = root;
|
|
69
83
|
this.#route = new RouteRenderer(words, channels, host, root);
|
|
70
84
|
}
|
|
71
|
-
/** emit(status,
|
|
72
|
-
*
|
|
73
|
-
* `status ·
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
|
|
85
|
+
/** emit(status, handoff, hop, withHandoff, summary) → the capsule stdout lines:
|
|
86
|
+
* the status-class key set from the word table (a success status renders
|
|
87
|
+
* `status · handoff`; a failure status renders `status`, plus `handoff` only when
|
|
88
|
+
* the round wrote a crash record), then the fix round's optional summary line,
|
|
89
|
+
* then the optional `next:` row followed by its `reason:` row — the dispatchable
|
|
90
|
+
* literal keeps its exact bytes and the diagnostic fact lands on the line after
|
|
91
|
+
* it. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
|
|
92
|
+
* BLOCKED / TIMEOUT failure face) prints neither row, while a present object
|
|
93
|
+
* renders through the shared hop face (`RouteRenderer#renderHop`: the soft-cap
|
|
94
|
+
* message · the in-line hop · the face-to-face station · the BLOCKED face · the
|
|
95
|
+
* terminal word). `withHandoff` is the caller's crash-record fact — the key set
|
|
96
|
+
* remains the table's single source (this render adds no status special case).
|
|
97
|
+
*
|
|
98
|
+
* Five parameters is one over the flat-signature limit: the positional face IS the
|
|
99
|
+
* pinned contract (the seam's emit signature), so it stays flat rather than boxed
|
|
100
|
+
* into a parameter object. */
|
|
101
|
+
emit(status, handoff, hop, withHandoff = false, summary) {
|
|
82
102
|
const words = this.#words;
|
|
83
103
|
// The `handoff:` cell is a path value — normalized to the repoRoot-relative
|
|
84
104
|
// shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
|
|
85
105
|
// it absolute).
|
|
86
106
|
const cells = {
|
|
87
107
|
status,
|
|
88
|
-
blocker,
|
|
89
108
|
handoff: this.#rel(handoff),
|
|
90
109
|
};
|
|
91
110
|
const capsuleLine = words
|
|
@@ -93,56 +112,22 @@ export class Capsule {
|
|
|
93
112
|
.map((kind) => `${kind}: ${cells[kind]}`)
|
|
94
113
|
.join(words.capsuleSeparator());
|
|
95
114
|
const lines = [capsuleLine];
|
|
96
|
-
if (
|
|
97
|
-
|
|
98
|
-
|
|
115
|
+
if (summary !== undefined)
|
|
116
|
+
lines.push(summary);
|
|
117
|
+
const hopValue = hop ?? null;
|
|
118
|
+
const next = this.#route.renderHop(hopValue);
|
|
119
|
+
if (hopValue !== null && next !== null) {
|
|
120
|
+
lines.push(`${words.station("next")} ${next}`);
|
|
121
|
+
lines.push(this.#route.renderReason(hopValue));
|
|
99
122
|
}
|
|
100
123
|
return lines;
|
|
101
124
|
}
|
|
102
|
-
/** The route → `next:` text render — the shared RouteRenderer (D40) unless the
|
|
103
|
-
* `done` face's doc-class discrimination fires (a spec doc's declared class decides
|
|
104
|
-
* the pipeline entry — or the BLOCKED face when the declaration is absent, spec
|
|
105
|
-
* §12 · D34). The capsule resolves the doc-class, then hands the resulting Route
|
|
106
|
-
* (a `handoff` carrying the entry, or the bare `done`) to the same renderer. */
|
|
107
|
-
#routeText(route, target) {
|
|
108
|
-
if (route.kind === "done" && target != null) {
|
|
109
|
-
const verdict = this.#docClassOf(target);
|
|
110
|
-
if (verdict === "blocked") {
|
|
111
|
-
return `${this.#words.station("blocked")} ${this.#words.routeWord("docType")}`;
|
|
112
|
-
}
|
|
113
|
-
// The declared doc-class (or a bare terminal) picks the pipeline entry — the
|
|
114
|
-
// same resolver + renderer the board consumes.
|
|
115
|
-
const key = verdict === "terminal" ? null : verdict;
|
|
116
|
-
return this.#route.render(NextStepRouter.resolve({ kind: "done" }, key), target);
|
|
117
|
-
}
|
|
118
|
-
return this.#route.render(route, target);
|
|
119
|
-
}
|
|
120
|
-
/** The target → doc-class verdict of the unified next face — the doc-class
|
|
121
|
-
* discrimination face (D33): the spec doc's class reads its DECLARED type (the
|
|
122
|
-
* front-matter `doc-type:` key, spec §12 · D34 — BoardView.readDocType,
|
|
123
|
-
* the one declaration reading face), never the filename suffix; the task-face
|
|
124
|
-
* targets key by type. `blocked` — the key is missing (the caller
|
|
125
|
-
* renders the BLOCKED face); `terminal` — no pipeline seam carries the declared
|
|
126
|
-
* class (`single-spec`, the table's five keys exclude it — the bare word). */
|
|
127
|
-
#docClassOf(target) {
|
|
128
|
-
if (target.type === "spec") {
|
|
129
|
-
// The read face takes the value object + the repoRoot-relative id (T4 §2.2);
|
|
130
|
-
// a `null` root (the hermetic default) keeps the value as its own basis. The
|
|
131
|
-
// `#rel` branded return needs no cast here (F3).
|
|
132
|
-
const declared = BoardView.readDocType(this.#root ?? new RepoRoot(""), this.#rel(target.id));
|
|
133
|
-
return declared === null ? "blocked" : declared === "single-spec" ? "terminal" : declared;
|
|
134
|
-
}
|
|
135
|
-
if (target.type === "plan")
|
|
136
|
-
return "plan";
|
|
137
|
-
if (target.type === "wave")
|
|
138
|
-
return "wave";
|
|
139
|
-
return "branch";
|
|
140
|
-
}
|
|
141
125
|
/** One path value normalized to the branded repoRoot-relative `RepoPath` through
|
|
142
126
|
* the ONE value object (D47); a `null` root (the hermetic default) passes the
|
|
143
127
|
* value through as its own basis. The branded return type carries the §2.2 brand
|
|
144
|
-
* to the
|
|
145
|
-
*
|
|
128
|
+
* to the render face with NO call-site cast (branch-review-1 F3); the board's doc
|
|
129
|
+
* cell and its `docClassOf` discrimination are the sibling read faces that
|
|
130
|
+
* resolve the same branded form. */
|
|
146
131
|
#rel(value) {
|
|
147
132
|
return this.#root === null ? value : this.#root.relativize(value);
|
|
148
133
|
}
|
package/dist/face/cli.js
CHANGED
|
@@ -60,14 +60,15 @@ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
|
|
|
60
60
|
import { BriefRenderer } from "../render/brief.js";
|
|
61
61
|
import { IssueBodyRenderer } from "../render/issue-body.js";
|
|
62
62
|
import { TemplateAssembler } from "../render/templates.js";
|
|
63
|
-
import { targetFaces } from "../session/faces.js";
|
|
63
|
+
import { TargetFaceTable, targetFaces } from "../session/faces.js";
|
|
64
64
|
import { TaskGraph } from "../session/graph.js";
|
|
65
|
+
import { HoldingError, InFlight } from "../session/inflight.js";
|
|
65
66
|
import { Ledger } from "../session/ledger.js";
|
|
66
67
|
import { NextStepRouter } from "../session/next.js";
|
|
67
68
|
import { PreFlight } from "../session/preflight.js";
|
|
68
69
|
import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.js";
|
|
69
70
|
import { CliArtifacts } from "./artifacts.js";
|
|
70
|
-
import { BoardView } from "./board-view.js";
|
|
71
|
+
import { BoardNext, BoardView } from "./board-view.js";
|
|
71
72
|
import { Capsule } from "./capsule.js";
|
|
72
73
|
import { ARGV_CHANNEL } from "./declare.js";
|
|
73
74
|
import { CliGate } from "./gate.js";
|
|
@@ -104,8 +105,8 @@ export class Cli {
|
|
|
104
105
|
/** The pre-flight board face (the blocked-dispatch wave hint). */
|
|
105
106
|
#graphView;
|
|
106
107
|
/** The lifecycle pre-flight seam (P4.1 T1) — the single dispatch gate the work
|
|
107
|
-
* commands consult before ANY child dispatch (tree-clean →
|
|
108
|
-
* doc-contract; the CLI orchestrates
|
|
108
|
+
* commands consult before ANY child dispatch (tree-clean → in-flight → graph →
|
|
109
|
+
* plan-ledger → wave → doc-contract; the CLI orchestrates, never a re-type). */
|
|
109
110
|
#preflight;
|
|
110
111
|
/** The contract coordinator — the doc-contract judgment face the pre-flight's
|
|
111
112
|
* doc gate reads (the single interpreter entry; spec §12 · D34 retired the
|
|
@@ -287,13 +288,22 @@ export class Cli {
|
|
|
287
288
|
if (parsed.harness === undefined)
|
|
288
289
|
this.#usage(command, "cdd init: missing --harness");
|
|
289
290
|
const update = parsed.update ?? false;
|
|
291
|
+
// The recommended tier is its own parsed boolean — an absent flag means the
|
|
292
|
+
// core-only face, never a derived default.
|
|
293
|
+
const recommended = parsed.includeRecommends ?? false;
|
|
294
|
+
// The flatten request — the ONE shape `preview` and `run` both read.
|
|
295
|
+
const request = {
|
|
296
|
+
host: parsed.harness,
|
|
297
|
+
shape: update ? "update" : "install",
|
|
298
|
+
recommended,
|
|
299
|
+
};
|
|
290
300
|
if (dryRun) {
|
|
291
|
-
for (const line of this.#init.preview(
|
|
301
|
+
for (const line of this.#init.preview(request))
|
|
292
302
|
this.#initHeader(line);
|
|
293
303
|
this.#exitCode = 0;
|
|
294
304
|
return;
|
|
295
305
|
}
|
|
296
|
-
this.#exitCode = await this.#init.run(
|
|
306
|
+
this.#exitCode = await this.#init.run(request);
|
|
297
307
|
});
|
|
298
308
|
}
|
|
299
309
|
/** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
|
|
@@ -353,7 +363,16 @@ export class Cli {
|
|
|
353
363
|
if (entry === null)
|
|
354
364
|
return 2;
|
|
355
365
|
const host = HostDetect.detect(process.env);
|
|
356
|
-
|
|
366
|
+
// The in-flight fact is TREE-level: the board inspects it (read-only — the gate
|
|
367
|
+
// and the board share `InFlight.inspect()`, never a second liveness judgment).
|
|
368
|
+
const inflight = new InFlight(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), entry.slug ?? "");
|
|
369
|
+
// The board's `next:` line renders ONE injected `NextHop` (P22 §5.2 · P24 §11):
|
|
370
|
+
// the pipeline FACTS come from the board face, and the ONE hop assembly (the four
|
|
371
|
+
// face-order rules + the six hop cells) lives in the session plane's
|
|
372
|
+
// `PipelineFrontier` — the same assembly the capsule renders, so the board and the
|
|
373
|
+
// capsule state one hop. Neither face judges anything here.
|
|
374
|
+
const next = BoardNext.of(index, entry, root);
|
|
375
|
+
const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
|
|
357
376
|
for (const line of board.lines)
|
|
358
377
|
this.#io.stdout(`${line}\n`);
|
|
359
378
|
return board.exitCode;
|
|
@@ -395,6 +414,7 @@ export class Cli {
|
|
|
395
414
|
// boolean, never a truthy string.
|
|
396
415
|
harness: HOST_IDS.find((id) => id === harnessToken),
|
|
397
416
|
update: globals.update === true,
|
|
417
|
+
includeRecommends: globals.includeRecommends === true,
|
|
398
418
|
};
|
|
399
419
|
}
|
|
400
420
|
/** The invocation's `--dry-run` scope — the constructor flag OR the program-scope
|
|
@@ -451,9 +471,9 @@ export class Cli {
|
|
|
451
471
|
if (scene === null)
|
|
452
472
|
return 1;
|
|
453
473
|
// THE pre-flight seam (P4.1 T1 · design §1): the single dispatch gate —
|
|
454
|
-
// tree-clean → graph → wave → doc-contract — ONE call,
|
|
455
|
-
// lives in the seam (session/preflight.ts), the CLI
|
|
456
|
-
// + the verdict render (zero re-implemented gate here). A refused verdict
|
|
474
|
+
// tree-clean → in-flight → graph → plan-ledger → wave → doc-contract — ONE call,
|
|
475
|
+
// the whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
|
|
476
|
+
// the call + the verdict render (zero re-implemented gate here). A refused verdict
|
|
457
477
|
// returns before any brief/lifecycle: no child dispatch ever runs. The
|
|
458
478
|
// dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel; the
|
|
459
479
|
// graph / wave refusals keep the pre-existing refusal face. The doc-face read
|
|
@@ -466,6 +486,10 @@ export class Cli {
|
|
|
466
486
|
const docRel = root.relativize(scene.target !== null && (scene.target.kind === "plan" || scene.target.kind === "spec")
|
|
467
487
|
? scene.target.doc
|
|
468
488
|
: "");
|
|
489
|
+
// The in-flight handle of this tree — ONE instance per invocation, built at the
|
|
490
|
+
// tree root (not the slug workspace: the collision domain is the tree). The gate
|
|
491
|
+
// only inspects it; the lifecycle's real dispatch path acquires it after the gate.
|
|
492
|
+
const inflight = new InFlight(scene.workspace.root, scene.workspace.slug);
|
|
469
493
|
const preflight = await this.#preflight.vet({
|
|
470
494
|
verb: verb,
|
|
471
495
|
type,
|
|
@@ -473,21 +497,40 @@ export class Cli {
|
|
|
473
497
|
planText: scene.planText,
|
|
474
498
|
tasks: type === "wave" ? new Set(this.#gate.tasksOf(parsed)) : null,
|
|
475
499
|
ledger: scene.ledger,
|
|
476
|
-
doc: type
|
|
500
|
+
doc: TargetFaceTable.isDocShape(type)
|
|
477
501
|
? {
|
|
478
|
-
// The ONE declaration reading face (spec §12 · D34) —
|
|
479
|
-
//
|
|
502
|
+
// The ONE declaration reading face (spec §12 · D34) — every doc shape
|
|
503
|
+
// dispatch reads the doc's front-matter `doc-type:` key;
|
|
480
504
|
// a key-less doc reads null and the seam BLOCKs (zero command-type
|
|
481
505
|
// carve-out, zero filename-suffix fallback).
|
|
482
506
|
docKey: BoardView.readDocType(root, docRel),
|
|
483
507
|
path: docRel,
|
|
484
508
|
}
|
|
485
509
|
: null,
|
|
510
|
+
inflight,
|
|
511
|
+
// The explicit takeover flag — VOID under --dry-run: the preview face never
|
|
512
|
+
// acquires, so a takeover there would have no write channel at all. The
|
|
513
|
+
// preview still judges the same gate, sees the same holder facts, and exits 1.
|
|
514
|
+
stealStale: !parsed.dryRun && parsed.args.stealStale === "true",
|
|
486
515
|
});
|
|
487
516
|
if (!preflight.ok) {
|
|
517
|
+
if (parsed.dryRun && preflight.gate === "in-flight" && preflight.holding !== undefined) {
|
|
518
|
+
// The preview's read-only held face: the SAME gate verdict, rendered as the
|
|
519
|
+
// lock row + the takeover hint, exit 1. Zero write (the preview never
|
|
520
|
+
// acquires / steals / releases).
|
|
521
|
+
for (const line of new Preview({ scene, words: this.#words }).heldBlock(verb, preflight.holding))
|
|
522
|
+
this.#io.stdout(`${line}\n`);
|
|
523
|
+
// The checked face rides the SAME stdout stream here: every dry-run shape
|
|
524
|
+
// (pass / dirty / held / blocked) reports which gates ran.
|
|
525
|
+
this.#renderChecked(preflight, (text) => this.#io.stdout(text));
|
|
526
|
+
return 1;
|
|
527
|
+
}
|
|
488
528
|
this.#renderPreflightBlocked(verb, preflight, scene);
|
|
489
529
|
return 1;
|
|
490
530
|
}
|
|
531
|
+
// The approved path's checked face (P21 §3.4): the SAME rows the refusal path
|
|
532
|
+
// renders — every dispatch reports which rules ran, not only the blocked ones.
|
|
533
|
+
this.#renderChecked(preflight);
|
|
491
534
|
// The real run's first write point (P11 · §4.2): the workspace — and the
|
|
492
535
|
// namespace's `.gitignore` keep-out marker — is built HERE, after the
|
|
493
536
|
// pre-flight verdict and before the brief render / the child dispatch, for
|
|
@@ -554,7 +597,14 @@ export class Cli {
|
|
|
554
597
|
},
|
|
555
598
|
target: scene.target ?? undefined,
|
|
556
599
|
capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
|
|
557
|
-
planPath: scene.planPath,
|
|
600
|
+
planPath: scene.pipeline.planPath,
|
|
601
|
+
specType: scene.pipeline.specType,
|
|
602
|
+
specPath: scene.pipeline.specPath,
|
|
603
|
+
planGraph: scene.pipeline.planGraph,
|
|
604
|
+
// The hop derivation's pipeline-station discrimination (§5.2) — the ONE
|
|
605
|
+
// declaration-reading judgment, injected so the session plane never imports a
|
|
606
|
+
// face class.
|
|
607
|
+
docClassOf: (candidate) => BoardView.docClassOf(scene.workspace.root.basis, candidate),
|
|
558
608
|
});
|
|
559
609
|
// The requested-phase gate — the line faces (branch/spec/plan) keep the
|
|
560
610
|
// line-phase readiness check; the task face needs no second gate (the WaveGate's
|
|
@@ -564,7 +614,16 @@ export class Cli {
|
|
|
564
614
|
if (open !== expected) {
|
|
565
615
|
const pendingBlock = verdict === "pending-fix" ? this.#gate.pendingFixBlock(scene, reviewed) : null;
|
|
566
616
|
const docBlock = open === null ? this.#gate.docLineBlock(scene, reviewed) : null;
|
|
567
|
-
|
|
617
|
+
// The generic refusal renders this LINE's own hop (the line frontier's
|
|
618
|
+
// assembly): `<reason> · the next round is <hop>` · `<reason> · next:
|
|
619
|
+
// <station>` · the bare reason. The capsule and the board render the PIPELINE
|
|
620
|
+
// frontier's assembly — a different reader, a different object. The two
|
|
621
|
+
// identity-aware block messages above own their facts (`reviewed` has no
|
|
622
|
+
// Home in `NextHop`) and stay verbatim.
|
|
623
|
+
const reject = pendingBlock ??
|
|
624
|
+
docBlock ??
|
|
625
|
+
this.#gate.lineHopMessage(scene, this.#gate.lineHop(scene), this.#words);
|
|
626
|
+
this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
|
|
568
627
|
return 1;
|
|
569
628
|
}
|
|
570
629
|
}
|
|
@@ -580,15 +639,22 @@ export class Cli {
|
|
|
580
639
|
let latest = [];
|
|
581
640
|
let lastStatus = null;
|
|
582
641
|
for (;;) {
|
|
583
|
-
const
|
|
584
|
-
if (
|
|
642
|
+
const peeked = run.peekNext();
|
|
643
|
+
if (peeked === null)
|
|
585
644
|
break;
|
|
645
|
+
const frame = peeked.frame;
|
|
586
646
|
const waveTasks = frame.target.kind === "wave" ? frame.target.tasks : null;
|
|
587
647
|
const mismatch = frame.phase !== expected ||
|
|
588
648
|
(group !== null && (waveTasks === null || !waveTasks.every((id) => group.has(id))));
|
|
589
649
|
if (mismatch) {
|
|
590
650
|
if (dispatched === 0) {
|
|
591
|
-
|
|
651
|
+
// The lookahead refusal renders the SAME `NextHop` the frame's line just
|
|
652
|
+
// derived (`peekNext`), through the ONE message shape — so one command can
|
|
653
|
+
// never print two different "next round" answers (the gate refusal above
|
|
654
|
+
// and this one name one object). The wave key stays an added clause.
|
|
655
|
+
const waveContext = waveTasks !== null ? ` for wave ${waveTasks.join(",")}` : "";
|
|
656
|
+
const reject = `${this.#gate.lineHopMessage(scene, peeked.hop, this.#words)}${waveContext}`;
|
|
657
|
+
this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
|
|
592
658
|
return 1;
|
|
593
659
|
}
|
|
594
660
|
break;
|
|
@@ -603,7 +669,19 @@ export class Cli {
|
|
|
603
669
|
this.#io.stdout(`${line}\n`);
|
|
604
670
|
return 0;
|
|
605
671
|
}
|
|
606
|
-
|
|
672
|
+
// The gate→acquire race: another dispatch took the lock between the in-flight
|
|
673
|
+
// gate's read and this dispatch's acquire. `HoldingError` carries the holder's
|
|
674
|
+
// facts and renders the SAME held BLOCK message the gate renders.
|
|
675
|
+
let step;
|
|
676
|
+
try {
|
|
677
|
+
step = await run.advance();
|
|
678
|
+
}
|
|
679
|
+
catch (error) {
|
|
680
|
+
if (!(error instanceof HoldingError))
|
|
681
|
+
throw error;
|
|
682
|
+
this.#renderHeld(error);
|
|
683
|
+
return 1;
|
|
684
|
+
}
|
|
607
685
|
if (step === null)
|
|
608
686
|
break;
|
|
609
687
|
// The dispatch-entry gate's refusal (the lifecycle's hard child zero-dispatch wiring —
|
|
@@ -677,6 +755,9 @@ export class Cli {
|
|
|
677
755
|
overallLink: scene.overallLink,
|
|
678
756
|
},
|
|
679
757
|
reviews: parsed.paths.reviews,
|
|
758
|
+
// The explicit takeover flag (`--steal-stale`): the ONLY path that displaces a
|
|
759
|
+
// standing in-flight record — and only when its holder is dead.
|
|
760
|
+
stealStale: parsed.args.stealStale === "true",
|
|
680
761
|
});
|
|
681
762
|
return harness.step();
|
|
682
763
|
}
|
|
@@ -689,18 +770,6 @@ export class Cli {
|
|
|
689
770
|
const artifact = read.kind === "ok" ? read.value : null;
|
|
690
771
|
return typeof artifact?.base === "string" ? artifact.base : "";
|
|
691
772
|
}
|
|
692
|
-
/** The phase-mismatch hint — what to run instead. */
|
|
693
|
-
#phaseHint(phase) {
|
|
694
|
-
switch (phase) {
|
|
695
|
-
case "implement":
|
|
696
|
-
return " — run cdd implement first";
|
|
697
|
-
case "review":
|
|
698
|
-
case "branch-review":
|
|
699
|
-
return " — run cdd review first";
|
|
700
|
-
default:
|
|
701
|
-
return " — run cdd fix first";
|
|
702
|
-
}
|
|
703
|
-
}
|
|
704
773
|
/** Render a refused pre-flight verdict — the work command's BLOCK face (P4.1 T1).
|
|
705
774
|
* The dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel (the
|
|
706
775
|
* commit/discard guidance + the named structural findings); the graph / wave
|
|
@@ -708,10 +777,13 @@ export class Cli {
|
|
|
708
777
|
* wave gate's split row — its done face rides the SAME closedWaves() read the gate
|
|
709
778
|
* judged, one closed set, one source). */
|
|
710
779
|
#renderPreflightBlocked(verb, verdict, scene) {
|
|
711
|
-
if (verdict.gate === "tree-clean" ||
|
|
780
|
+
if (verdict.gate === "tree-clean" ||
|
|
781
|
+
verdict.gate === "in-flight" ||
|
|
782
|
+
verdict.gate === "doc-contract") {
|
|
712
783
|
this.#io.stderr(`${this.#words.station("blocked")} ${verdict.message ?? ""}\n`);
|
|
713
784
|
for (const detail of verdict.details ?? [])
|
|
714
785
|
this.#io.stderr(` ${detail}\n`);
|
|
786
|
+
this.#renderChecked(verdict);
|
|
715
787
|
return;
|
|
716
788
|
}
|
|
717
789
|
this.#io.stderr(`cdd ${verb}: ${verdict.message ?? "the dispatch gate refused the request"}\n`);
|
|
@@ -729,6 +801,27 @@ export class Cli {
|
|
|
729
801
|
.split("\n"))
|
|
730
802
|
this.#io.stderr(` ${line}\n`);
|
|
731
803
|
}
|
|
804
|
+
this.#renderChecked(verdict);
|
|
805
|
+
}
|
|
806
|
+
/** Render the acquire race's held BLOCK — the in-flight gate's own message face
|
|
807
|
+
* (`Words.inFlightBlocked`, one filler for both call sites), exit 1 at the caller. */
|
|
808
|
+
#renderHeld(error) {
|
|
809
|
+
const message = this.#words.inFlightBlocked(error.record, true);
|
|
810
|
+
this.#io.stderr(`${this.#words.station("blocked")} ${message}\n`);
|
|
811
|
+
}
|
|
812
|
+
/** Render the checked face — the pre-flight's per-gate / per-rule rows, derived by
|
|
813
|
+
* the seam from the ONE rule declaration surface (P21 §3.4). It renders on BOTH
|
|
814
|
+
* pre-flight paths (approved and refused) into the diagnostic channel by default;
|
|
815
|
+
* the dry-run held preview passes its stdout writer so every dry-run shape reports
|
|
816
|
+
* the same face: "which rule ran, and what it judged" is a production read face,
|
|
817
|
+
* never a test-only field. The heading and the outcome words come from the word
|
|
818
|
+
* table (zero CLI literal), and the rows indent exactly like the details face
|
|
819
|
+
* above them. */
|
|
820
|
+
#renderChecked(verdict, write) {
|
|
821
|
+
const out = write ?? ((text) => this.#io.stderr(text));
|
|
822
|
+
out(`${this.#words.checkedWords().heading}\n`);
|
|
823
|
+
for (const row of verdict.checked)
|
|
824
|
+
out(` ${row}\n`);
|
|
732
825
|
}
|
|
733
826
|
// ---------------------------------------------------------------------------
|
|
734
827
|
// the work scene — the composition of contract/session/face objects
|
|
@@ -775,9 +868,11 @@ export class Cli {
|
|
|
775
868
|
slug = resolved;
|
|
776
869
|
break;
|
|
777
870
|
}
|
|
778
|
-
case "spec":
|
|
871
|
+
case "phase-spec":
|
|
872
|
+
case "overall":
|
|
873
|
+
case "single-spec": {
|
|
779
874
|
if (specPath === null || specRel === null)
|
|
780
|
-
this.#usage(node, `cdd ${verb} --type
|
|
875
|
+
this.#usage(node, `cdd ${verb} --type ${type}: missing required --spec <path>`);
|
|
781
876
|
// An unreadable target declares no identity: the SAME slug carrier hard-refuses
|
|
782
877
|
// it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
|
|
783
878
|
// face covers the other shape — a document ON DISK that declares no
|
|
@@ -787,10 +882,11 @@ export class Cli {
|
|
|
787
882
|
return null;
|
|
788
883
|
slug = resolved;
|
|
789
884
|
target = { kind: "spec", doc: specPath };
|
|
790
|
-
// The judged
|
|
791
|
-
// spec
|
|
792
|
-
// (a single-spec) leaves the slot null; an
|
|
793
|
-
// and the existing slug-ref invariant reports
|
|
885
|
+
// The judged document's own `program:` — the parent charter (INPUT_OVERALL)
|
|
886
|
+
// the phase-spec reviewer judges the phase against. A document without
|
|
887
|
+
// `program:` (an overall charter or a single-spec) leaves the slot null; an
|
|
888
|
+
// off-disk target reads null here and the existing slug-ref invariant reports
|
|
889
|
+
// it (never a second reporter).
|
|
794
890
|
const specEntry = index.entryAt(specRel);
|
|
795
891
|
const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
|
|
796
892
|
overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
|
|
@@ -838,6 +934,23 @@ export class Cli {
|
|
|
838
934
|
const state = type === "wave"
|
|
839
935
|
? new TaskGraph(new PlanDocType("plan").parse(planText.split("\n")))
|
|
840
936
|
: EMPTY_RUN_STATE;
|
|
937
|
+
// The pipeline frontier's four declared cells (§11) — the composition root's ONE
|
|
938
|
+
// collection point. The identity word + path come from the document index (never
|
|
939
|
+
// the argv `--type` spelling): every non-plan declared document owns the identity
|
|
940
|
+
// slot, so `phase-spec` / `single-spec` / `overall` all reach the same assembly.
|
|
941
|
+
// The plan path is the argv value on the plan / branch lines and the index's
|
|
942
|
+
// same-slug plan on a `--spec` round whose argv names none — a spec round that
|
|
943
|
+
// dropped it would leave the frontier blind to the plan face and the capsule
|
|
944
|
+
// printing this line's own exit. The graph is the ONE guarded plan read (the wave
|
|
945
|
+
// run's already-parsed state stands in; the session plane reads no file).
|
|
946
|
+
const identity = index.identityDoc(slug);
|
|
947
|
+
const hopPlanPath = planPath ?? index.planOf(slug)?.path ?? null;
|
|
948
|
+
const pipeline = {
|
|
949
|
+
specType: identity?.docType ?? null,
|
|
950
|
+
specPath: identity?.path ?? null,
|
|
951
|
+
planPath: hopPlanPath,
|
|
952
|
+
planGraph: state instanceof TaskGraph ? state : BoardView.planGraph(hopPlanPath),
|
|
953
|
+
};
|
|
841
954
|
return {
|
|
842
955
|
workspace,
|
|
843
956
|
ledger,
|
|
@@ -848,6 +961,7 @@ export class Cli {
|
|
|
848
961
|
target,
|
|
849
962
|
state,
|
|
850
963
|
router: new NextStepRouter(),
|
|
964
|
+
pipeline,
|
|
851
965
|
briefPath: null,
|
|
852
966
|
specLink,
|
|
853
967
|
overallLink,
|