@oscaner-skills/cdd-engine 4.1.0 → 4.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -9
- package/README.zh-CN.md +44 -9
- 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 +401 -131
- package/dist/face/capsule.js +66 -89
- package/dist/face/cli.js +174 -48
- package/dist/face/declare.js +59 -23
- package/dist/face/gate.js +117 -40
- package/dist/face/host.js +9 -35
- package/dist/face/init.js +108 -0
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +73 -0
- package/dist/face/preview.js +43 -10
- package/dist/face/projection.js +3 -3
- package/dist/face/route-render.js +51 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +134 -12
- 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 +581 -136
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +138 -80
- package/dist/session/preflight.js +276 -68
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +317 -78
- package/dist/session/wave.js +94 -14
- package/package.json +13 -3
- package/dist/infra/process.js +0 -22
package/dist/face/capsule.js
CHANGED
|
@@ -1,26 +1,33 @@
|
|
|
1
1
|
// packages/cdd-engine/src-next/face/capsule.ts
|
|
2
|
-
// T10 — the single capsule face (design spec §3.2: the `status ·
|
|
3
|
-
//
|
|
4
|
-
// face — the capsule the orchestrator greps /
|
|
2
|
+
// T10 — the single capsule face (design spec §3.2: the `status · handoff · next:`
|
|
3
|
+
// word-face steady state; P22 §10: the output face's closeout). Capsule#emit
|
|
4
|
+
// renders the ALL-OP single stdout face — the capsule the orchestrator greps /
|
|
5
|
+
// routes on without opening the handoff:
|
|
5
6
|
//
|
|
6
|
-
// status: <status> ·
|
|
7
|
-
// status: <status> [· handoff: <crash>]
|
|
7
|
+
// status: <status> · handoff: <handoff> (success statuses)
|
|
8
|
+
// status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
|
|
9
|
+
// fixed N · rejected M (fix rounds only — between the status line and `next:`)
|
|
8
10
|
// next: <suggestion> (optional — the C5 route / a caller-rendered text)
|
|
9
11
|
//
|
|
10
|
-
// The
|
|
11
|
-
//
|
|
12
|
-
//
|
|
12
|
+
// The `blocker` cell is retired: its whole information content — the blocker count —
|
|
13
|
+
// is derivable from `status` (any blocker ⇒ CHANGES_REQUESTED, warn/nit-only ⇒
|
|
14
|
+
// REVIEW_FIX, empty ⇒ APPROVED, a failure round prints no cell at all), and that
|
|
15
|
+
// count is exactly the number the review criterion rules undisplayed. The key set is
|
|
16
|
+
// still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
|
|
17
|
+
// a failure status keeps the handoff cell only when the round wrote a crash record.
|
|
18
|
+
// The fix round's disposition summary rides the SAME render, placed so the
|
|
19
|
+
// dispatchable `next:` literal closes the output: `status` → summary → `next:`.
|
|
13
20
|
//
|
|
14
|
-
// The byte face is v1-pinned: the key words (status ·
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
//
|
|
21
|
+
// The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
|
|
22
|
+
// the CapsuleKey type and the emit signature — a data-only change cannot reshape
|
|
23
|
+
// them. What rides the injected Words table (the single word-table instance) is the
|
|
24
|
+
// `·` separator, the `next:` station anchor and the route/status vocabulary — a
|
|
25
|
+
// second table is excluded by construction. The `next:` value is
|
|
19
26
|
// either a caller-rendered string or the C5 Route rendered through the route-word
|
|
20
27
|
// 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
|
-
//
|
|
28
|
+
// reversal): `implement --plan <path> --tasks 17` · `review --type phase-spec --spec
|
|
29
|
+
// <path>` · `fix --type phase-spec --spec <path> --reviews <handoff>` + the readback
|
|
30
|
+
// suffix · `done` (the bare terminal word) · the soft-cap message verbatim.
|
|
24
31
|
// The argv is composed from the frame facts (the RouteTarget's type + id + plan)
|
|
25
32
|
// through the argv-channel flag spellings (the same channel the CLI parse reads —
|
|
26
33
|
// the render source is the declared channel, never a second hard-coded format
|
|
@@ -31,28 +38,30 @@
|
|
|
31
38
|
// message — rides declared constants from session/next.ts, rendered by reference,
|
|
32
39
|
// never restated.
|
|
33
40
|
//
|
|
34
|
-
// D40 — the render delegates to the shared `RouteRenderer` (the ONE
|
|
35
|
-
// `next:` literal face, also consumed by the board)
|
|
36
|
-
// `
|
|
37
|
-
//
|
|
41
|
+
// D40 · P22 §5.2 — the render delegates to the shared `RouteRenderer` (the ONE
|
|
42
|
+
// route → `next:` literal face, also consumed by the board). The capsule reads the
|
|
43
|
+
// INJECTED `NextHop` — the ONE object every read face renders — and adds no
|
|
44
|
+
// judgment of its own: the doc-class discrimination that picks the pipeline station
|
|
45
|
+
// belongs to the derivation's injected seam (`BoardView.docClassOf`), never here.
|
|
46
|
+
// A `NextHop` that is ABSENT (the BLOCKED / TIMEOUT failure face) prints no `next:`
|
|
47
|
+
// line; a present hop with `hop: null` (`done` · `soft-cap` · the doc-class
|
|
48
|
+
// `terminal` / `blocked` rows) still prints its frozen line.
|
|
38
49
|
//
|
|
39
50
|
// The class satisfies the session/run.ts CapsuleFace seam (T8's interaction point) —
|
|
40
51
|
// the capsule plugs into the lifecycle's attachCapsule contact, byte-identically.
|
|
41
52
|
// 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
53
|
import { RouteRenderer } from "./route-render.js";
|
|
46
54
|
/**
|
|
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
|
-
*
|
|
55
|
+
* Capsule — the single capsule output face. emit(status, handoff, hop?,
|
|
56
|
+
* withHandoff?, summary?) renders one round's facts into the byte-pinned `status ·
|
|
57
|
+
* handoff` line, the fix round's optional disposition summary, and the optional
|
|
58
|
+
* `next:` line LAST (the dispatchable literal closes the output). The key words are
|
|
59
|
+
* the CapsuleKey literals the kind loop renders (pin-enforced by the emit
|
|
60
|
+
* signature); the separator, station and route/status words ride the injected Words
|
|
61
|
+
* instance. The complete executable `next:` literal composes its full argv from the
|
|
62
|
+
* injected `NextHop`'s route + target through the argv-channel flag spellings (P4.1
|
|
63
|
+
* T4; same channel source the parse reads — the hop is optional, the channel an
|
|
64
|
+
* optional 2nd constructor argument).
|
|
56
65
|
*/
|
|
57
66
|
export class Capsule {
|
|
58
67
|
/** The single word table — the capsule's whole vocabulary source. */
|
|
@@ -68,24 +77,29 @@ export class Capsule {
|
|
|
68
77
|
this.#root = root;
|
|
69
78
|
this.#route = new RouteRenderer(words, channels, host, root);
|
|
70
79
|
}
|
|
71
|
-
/** emit(status,
|
|
72
|
-
*
|
|
73
|
-
* `status ·
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
* renders
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
|
|
80
|
+
/** emit(status, handoff, hop, withHandoff, summary) → the capsule stdout lines:
|
|
81
|
+
* the status-class key set from the word table (a success status renders
|
|
82
|
+
* `status · handoff`; a failure status renders `status`, plus `handoff` only when
|
|
83
|
+
* the round wrote a crash record), then the fix round's optional summary line,
|
|
84
|
+
* then the optional `next:` line LAST — the dispatchable literal is the output's
|
|
85
|
+
* close. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
|
|
86
|
+
* BLOCKED / TIMEOUT failure face) prints no `next:` line at all, while a present
|
|
87
|
+
* object renders through the shared hop face (`RouteRenderer#renderHop`: the
|
|
88
|
+
* soft-cap message · the in-line hop · the face-to-face station · the BLOCKED
|
|
89
|
+
* face · the terminal word). `withHandoff` is the caller's crash-record fact — the
|
|
90
|
+
* key set remains the table's single source (this render adds no status special
|
|
91
|
+
* case).
|
|
92
|
+
*
|
|
93
|
+
* Five parameters is one over the flat-signature limit: the positional face IS the
|
|
94
|
+
* pinned contract (the seam's emit signature), so it stays flat rather than boxed
|
|
95
|
+
* into a parameter object. */
|
|
96
|
+
emit(status, handoff, hop, withHandoff = false, summary) {
|
|
82
97
|
const words = this.#words;
|
|
83
98
|
// The `handoff:` cell is a path value — normalized to the repoRoot-relative
|
|
84
99
|
// shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
|
|
85
100
|
// it absolute).
|
|
86
101
|
const cells = {
|
|
87
102
|
status,
|
|
88
|
-
blocker,
|
|
89
103
|
handoff: this.#rel(handoff),
|
|
90
104
|
};
|
|
91
105
|
const capsuleLine = words
|
|
@@ -93,56 +107,19 @@ export class Capsule {
|
|
|
93
107
|
.map((kind) => `${kind}: ${cells[kind]}`)
|
|
94
108
|
.join(words.capsuleSeparator());
|
|
95
109
|
const lines = [capsuleLine];
|
|
96
|
-
if (
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
110
|
+
if (summary !== undefined)
|
|
111
|
+
lines.push(summary);
|
|
112
|
+
const next = this.#route.renderHop(hop ?? null);
|
|
113
|
+
if (next !== null)
|
|
114
|
+
lines.push(`${words.station("next")} ${next}`);
|
|
100
115
|
return lines;
|
|
101
116
|
}
|
|
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
117
|
/** One path value normalized to the branded repoRoot-relative `RepoPath` through
|
|
142
118
|
* the ONE value object (D47); a `null` root (the hermetic default) passes the
|
|
143
119
|
* value through as its own basis. The branded return type carries the §2.2 brand
|
|
144
|
-
* to the
|
|
145
|
-
*
|
|
120
|
+
* to the render face with NO call-site cast (branch-review-1 F3); the board's doc
|
|
121
|
+
* cell and its `docClassOf` discrimination are the sibling read faces that
|
|
122
|
+
* resolve the same branded form. */
|
|
146
123
|
#rel(value) {
|
|
147
124
|
return this.#root === null ? value : this.#root.relativize(value);
|
|
148
125
|
}
|
package/dist/face/cli.js
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
// packages/cdd-engine/src-next/face/cli.ts
|
|
2
2
|
// T11 + T8 — the command face + composition root (design spec §3.3: the cdd CLI
|
|
3
|
-
// command surface — implement / review / fix / schema / issue /
|
|
4
|
-
// kept as a steady word face; T20 converges the base command face to `base
|
|
5
|
-
// adds the board observability command
|
|
3
|
+
// command surface — implement / review / fix / base / schema / issue / board / init —
|
|
4
|
+
// is kept as a steady word face; T20 converges the base command face to `base`, T5
|
|
5
|
+
// adds the board observability command and P20 adds the repo-independent init
|
|
6
|
+
// bootstrap — the eight-command surface). This module is
|
|
6
7
|
// the new tree's composition root: the
|
|
7
8
|
// `Cli.create` static factory — the class face is the entry, the module carries zero
|
|
8
9
|
// bare functions (the composition root's deliberate class form) — wires the contract /
|
|
9
10
|
// session / face objects into the ONE CLI the bin thin entry boots. Task 3 (P1)
|
|
10
11
|
// reorganized the face into one boundary per responsibility — the CLI declaration
|
|
11
|
-
// single surface (face/declare.ts, §2.4 — the
|
|
12
|
+
// single surface (face/declare.ts, §2.4 — the eight subcommand rows + the argv
|
|
12
13
|
// channel), the declaration projection (face/projection.ts — the CommandTreeBuilder
|
|
13
14
|
// whose commander program OWNS the parse + help + validation pipeline), and the run
|
|
14
15
|
// face; the typed argv parse channel (face/argv.ts) was deleted at T6 — the parse
|
|
@@ -41,7 +42,7 @@
|
|
|
41
42
|
// delegate to the split faces above — the root orchestrates, never re-types).
|
|
42
43
|
// Module-level exports are types / constant data / classes — zero behavior-carrying
|
|
43
44
|
// bare functions (the composition root is the Cli class's static create factory).
|
|
44
|
-
import { existsSync, readFileSync } from "node:fs";
|
|
45
|
+
import { existsSync, readFileSync, writeSync } from "node:fs";
|
|
45
46
|
import path from "node:path";
|
|
46
47
|
import process from "node:process";
|
|
47
48
|
import { CommanderError } from "commander";
|
|
@@ -59,19 +60,21 @@ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
|
|
|
59
60
|
import { BriefRenderer } from "../render/brief.js";
|
|
60
61
|
import { IssueBodyRenderer } from "../render/issue-body.js";
|
|
61
62
|
import { TemplateAssembler } from "../render/templates.js";
|
|
62
|
-
import { targetFaces } from "../session/faces.js";
|
|
63
|
+
import { TargetFaceTable, targetFaces } from "../session/faces.js";
|
|
63
64
|
import { TaskGraph } from "../session/graph.js";
|
|
65
|
+
import { HoldingError, InFlight } from "../session/inflight.js";
|
|
64
66
|
import { Ledger } from "../session/ledger.js";
|
|
65
67
|
import { NextStepRouter } from "../session/next.js";
|
|
66
68
|
import { PreFlight } from "../session/preflight.js";
|
|
67
69
|
import { EMPTY_RUN_STATE, Lifecycle } from "../session/run.js";
|
|
68
70
|
import { CliArtifacts } from "./artifacts.js";
|
|
69
|
-
import { BoardView } from "./board-view.js";
|
|
71
|
+
import { BoardNext, BoardView } from "./board-view.js";
|
|
70
72
|
import { Capsule } from "./capsule.js";
|
|
71
73
|
import { ARGV_CHANNEL } from "./declare.js";
|
|
72
74
|
import { CliGate } from "./gate.js";
|
|
73
75
|
import { GraphView } from "./graph-view.js";
|
|
74
|
-
import { HostDetect } from "./host.js";
|
|
76
|
+
import { HOST_IDS, HostDetect } from "./host.js";
|
|
77
|
+
import { CliInit, ExecaStepRunner } from "./init.js";
|
|
75
78
|
import { CliLifecycle } from "./lifecycle.js";
|
|
76
79
|
import { Preview } from "./preview.js";
|
|
77
80
|
import { CommandTreeBuilder } from "./projection.js";
|
|
@@ -102,8 +105,8 @@ export class Cli {
|
|
|
102
105
|
/** The pre-flight board face (the blocked-dispatch wave hint). */
|
|
103
106
|
#graphView;
|
|
104
107
|
/** The lifecycle pre-flight seam (P4.1 T1) — the single dispatch gate the work
|
|
105
|
-
* commands consult before ANY child dispatch (tree-clean →
|
|
106
|
-
* 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). */
|
|
107
110
|
#preflight;
|
|
108
111
|
/** The contract coordinator — the doc-contract judgment face the pre-flight's
|
|
109
112
|
* doc gate reads (the single interpreter entry; spec §12 · D34 retired the
|
|
@@ -123,6 +126,13 @@ export class Cli {
|
|
|
123
126
|
/** The pure-command domain (T8 — the split contract's artifacts face,
|
|
124
127
|
* face/artifacts.ts): the schema/issue/base run bodies. */
|
|
125
128
|
#artifacts;
|
|
129
|
+
/** The harness plugin bootstrap (P20 — face/init.ts): the repo-independent
|
|
130
|
+
* install/update sequence face. */
|
|
131
|
+
#init;
|
|
132
|
+
/** The bootstrap's synchronous line writer — the step headers of a real run and
|
|
133
|
+
* the `would run:` lines of a `--dry-run` preview ride the SAME seam (one writer,
|
|
134
|
+
* so a preview and a run never format the same plan differently). */
|
|
135
|
+
#initHeader;
|
|
126
136
|
constructor(opts = {}) {
|
|
127
137
|
this.#io = opts.io ?? {
|
|
128
138
|
stdout: (t) => process.stdout.write(t),
|
|
@@ -160,6 +170,14 @@ export class Cli {
|
|
|
160
170
|
stdinRead: this.#stdinRead,
|
|
161
171
|
usage: (node, message) => this.#usage(node, message),
|
|
162
172
|
});
|
|
173
|
+
// The synchronous writer — the step header must land before the spawned
|
|
174
|
+
// child writes to the same fd (a piped log would otherwise reorder them).
|
|
175
|
+
this.#initHeader = opts.initHeader ?? ((line) => writeSync(1, `${line}\n`));
|
|
176
|
+
this.#init = new CliInit({
|
|
177
|
+
io: this.#io,
|
|
178
|
+
runner: opts.initRunner ?? new ExecaStepRunner(),
|
|
179
|
+
header: this.#initHeader,
|
|
180
|
+
});
|
|
163
181
|
}
|
|
164
182
|
// ---------------------------------------------------------------------------
|
|
165
183
|
// the commander parse pipeline — the composition root parses through the
|
|
@@ -257,6 +275,27 @@ export class Cli {
|
|
|
257
275
|
commandNode("board").action(async (_opts, command) => {
|
|
258
276
|
this.#exitCode = await this.#runBoard(command, this.#runInput(null, command));
|
|
259
277
|
});
|
|
278
|
+
// the repo-independent bootstrap — zero #rootOf(), zero workspace writes. The
|
|
279
|
+
// preview flag renders the step plan through the same header seam and returns
|
|
280
|
+
// before the first spawn (spec §2.7): a preview must never install packages.
|
|
281
|
+
commandNode("init").action(async (_opts, command) => {
|
|
282
|
+
const dryRun = this.#dryRunOf(command);
|
|
283
|
+
const parsed = this.#runInput(null, command);
|
|
284
|
+
// The declaration marks --harness as requiredOption, so commander rejects a
|
|
285
|
+
// missing flag before this shell; the guard keeps the run input's narrowed
|
|
286
|
+
// type honest (the usage face belongs to the root's private surface, so it
|
|
287
|
+
// stays here rather than sinking into CliInit).
|
|
288
|
+
if (parsed.harness === undefined)
|
|
289
|
+
this.#usage(command, "cdd init: missing --harness");
|
|
290
|
+
const update = parsed.update ?? false;
|
|
291
|
+
if (dryRun) {
|
|
292
|
+
for (const line of this.#init.preview(parsed.harness, update))
|
|
293
|
+
this.#initHeader(line);
|
|
294
|
+
this.#exitCode = 0;
|
|
295
|
+
return;
|
|
296
|
+
}
|
|
297
|
+
this.#exitCode = await this.#init.run(parsed.harness, update);
|
|
298
|
+
});
|
|
260
299
|
}
|
|
261
300
|
/** `cdd board --plan <path> / --spec <path>` — the entry document's progress board
|
|
262
301
|
* (spec §3.1): a PURE READ — zero preflight gate, zero tree writes, zero ledger
|
|
@@ -315,7 +354,15 @@ export class Cli {
|
|
|
315
354
|
if (entry === null)
|
|
316
355
|
return 2;
|
|
317
356
|
const host = HostDetect.detect(process.env);
|
|
318
|
-
|
|
357
|
+
// The in-flight fact is TREE-level: the board inspects it (read-only — the gate
|
|
358
|
+
// and the board share `InFlight.inspect()`, never a second liveness judgment).
|
|
359
|
+
const inflight = new InFlight(new WorkspaceRoot(repoRoot, this.#config.handoffNamespace().workspaceRoot), entry.slug ?? "");
|
|
360
|
+
// The board's `next:` line renders ONE injected `NextHop` (P22 §5.2): the
|
|
361
|
+
// pipeline OBSERVATION comes from the board face, the four face-order rules and
|
|
362
|
+
// the ONE derivation from this assembly point (`BoardNext`) — the board itself
|
|
363
|
+
// holds no ledger for the next line and judges nothing.
|
|
364
|
+
const next = BoardNext.of(index, entry, root);
|
|
365
|
+
const board = BoardView.render(index, entry, repoRoot, this.#words, host, ARGV_CHANNEL, await inflight.inspect(), next);
|
|
319
366
|
for (const line of board.lines)
|
|
320
367
|
this.#io.stdout(`${line}\n`);
|
|
321
368
|
return board.exitCode;
|
|
@@ -343,6 +390,7 @@ export class Cli {
|
|
|
343
390
|
continue;
|
|
344
391
|
args[key] = typeof value === "boolean" ? (value ? "true" : "false") : String(value);
|
|
345
392
|
}
|
|
393
|
+
const harnessToken = typeof globals.harness === "string" ? globals.harness : "";
|
|
346
394
|
return {
|
|
347
395
|
leaf,
|
|
348
396
|
args,
|
|
@@ -351,6 +399,11 @@ export class Cli {
|
|
|
351
399
|
paths: { plan: null, spec: null, reviews: null },
|
|
352
400
|
positionals: command.processedArgs,
|
|
353
401
|
dryRun: this.#dryRunOf(command),
|
|
402
|
+
// The harness word is narrowed through the ONE host vocabulary (a cast would
|
|
403
|
+
// let a foreign token ride into the roster index); `--update` is the parsed
|
|
404
|
+
// boolean, never a truthy string.
|
|
405
|
+
harness: HOST_IDS.find((id) => id === harnessToken),
|
|
406
|
+
update: globals.update === true,
|
|
354
407
|
};
|
|
355
408
|
}
|
|
356
409
|
/** The invocation's `--dry-run` scope — the constructor flag OR the program-scope
|
|
@@ -361,16 +414,17 @@ export class Cli {
|
|
|
361
414
|
const globals = command.optsWithGlobals();
|
|
362
415
|
return this.#dryRun || globals.dryRun === true;
|
|
363
416
|
}
|
|
364
|
-
/** The `--dry-run` scope guard (P11 T5 · §3.5) — the
|
|
365
|
-
*
|
|
366
|
-
*
|
|
367
|
-
*
|
|
368
|
-
*
|
|
369
|
-
*
|
|
417
|
+
/** The `--dry-run` scope guard (P11 T5 · §3.5) — the pure commands' rejection face
|
|
418
|
+
* alone: a pure command carrying the program flag is a usage rejection (exit 2),
|
|
419
|
+
* never a silently ignored flag — a no-op flag the consumer has to remember to
|
|
420
|
+
* skip is a mind-share defect, not a convenience. The four preview-capable faces
|
|
421
|
+
* (implement / review / fix / init) never reach this guard; `init`'s preview is
|
|
422
|
+
* `CliInit.preview`. The usage byte is the owning node's commander-native usage
|
|
423
|
+
* line (the same `#usage` face every run body's rejection rides). */
|
|
370
424
|
#assertDryRunScope(node, dryRun) {
|
|
371
425
|
if (!dryRun)
|
|
372
426
|
return;
|
|
373
|
-
this.#usage(node, "--dry-run previews the next dispatch step and its expected artifacts — it applies to implement / review / fix only");
|
|
427
|
+
this.#usage(node, "--dry-run previews the next dispatch step and its expected artifacts — it applies to implement / review / fix / init only");
|
|
374
428
|
}
|
|
375
429
|
/** Configure every node's output into the injected io (commander writes its
|
|
376
430
|
* help/error bytes through the node that produced them — a subcommand's help
|
|
@@ -406,9 +460,9 @@ export class Cli {
|
|
|
406
460
|
if (scene === null)
|
|
407
461
|
return 1;
|
|
408
462
|
// THE pre-flight seam (P4.1 T1 · design §1): the single dispatch gate —
|
|
409
|
-
// tree-clean → graph → wave → doc-contract — ONE call,
|
|
410
|
-
// lives in the seam (session/preflight.ts), the CLI
|
|
411
|
-
// + the verdict render (zero re-implemented gate here). A refused verdict
|
|
463
|
+
// tree-clean → in-flight → graph → plan-ledger → wave → doc-contract — ONE call,
|
|
464
|
+
// the whole sequence lives in the seam (session/preflight.ts), the CLI orchestrates
|
|
465
|
+
// the call + the verdict render (zero re-implemented gate here). A refused verdict
|
|
412
466
|
// returns before any brief/lifecycle: no child dispatch ever runs. The
|
|
413
467
|
// dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel; the
|
|
414
468
|
// graph / wave refusals keep the pre-existing refusal face. The doc-face read
|
|
@@ -421,6 +475,10 @@ export class Cli {
|
|
|
421
475
|
const docRel = root.relativize(scene.target !== null && (scene.target.kind === "plan" || scene.target.kind === "spec")
|
|
422
476
|
? scene.target.doc
|
|
423
477
|
: "");
|
|
478
|
+
// The in-flight handle of this tree — ONE instance per invocation, built at the
|
|
479
|
+
// tree root (not the slug workspace: the collision domain is the tree). The gate
|
|
480
|
+
// only inspects it; the lifecycle's real dispatch path acquires it after the gate.
|
|
481
|
+
const inflight = new InFlight(scene.workspace.root, scene.workspace.slug);
|
|
424
482
|
const preflight = await this.#preflight.vet({
|
|
425
483
|
verb: verb,
|
|
426
484
|
type,
|
|
@@ -428,21 +486,40 @@ export class Cli {
|
|
|
428
486
|
planText: scene.planText,
|
|
429
487
|
tasks: type === "wave" ? new Set(this.#gate.tasksOf(parsed)) : null,
|
|
430
488
|
ledger: scene.ledger,
|
|
431
|
-
doc: type
|
|
489
|
+
doc: TargetFaceTable.isDocShape(type)
|
|
432
490
|
? {
|
|
433
|
-
// The ONE declaration reading face (spec §12 · D34) —
|
|
434
|
-
//
|
|
491
|
+
// The ONE declaration reading face (spec §12 · D34) — every doc shape
|
|
492
|
+
// dispatch reads the doc's front-matter `doc-type:` key;
|
|
435
493
|
// a key-less doc reads null and the seam BLOCKs (zero command-type
|
|
436
494
|
// carve-out, zero filename-suffix fallback).
|
|
437
495
|
docKey: BoardView.readDocType(root, docRel),
|
|
438
496
|
path: docRel,
|
|
439
497
|
}
|
|
440
498
|
: null,
|
|
499
|
+
inflight,
|
|
500
|
+
// The explicit takeover flag — VOID under --dry-run: the preview face never
|
|
501
|
+
// acquires, so a takeover there would have no write channel at all. The
|
|
502
|
+
// preview still judges the same gate, sees the same holder facts, and exits 1.
|
|
503
|
+
stealStale: !parsed.dryRun && parsed.args.stealStale === "true",
|
|
441
504
|
});
|
|
442
505
|
if (!preflight.ok) {
|
|
506
|
+
if (parsed.dryRun && preflight.gate === "in-flight" && preflight.holding !== undefined) {
|
|
507
|
+
// The preview's read-only held face: the SAME gate verdict, rendered as the
|
|
508
|
+
// lock row + the takeover hint, exit 1. Zero write (the preview never
|
|
509
|
+
// acquires / steals / releases).
|
|
510
|
+
for (const line of new Preview({ scene, words: this.#words }).heldBlock(verb, preflight.holding))
|
|
511
|
+
this.#io.stdout(`${line}\n`);
|
|
512
|
+
// The checked face rides the SAME stdout stream here: every dry-run shape
|
|
513
|
+
// (pass / dirty / held / blocked) reports which gates ran.
|
|
514
|
+
this.#renderChecked(preflight, (text) => this.#io.stdout(text));
|
|
515
|
+
return 1;
|
|
516
|
+
}
|
|
443
517
|
this.#renderPreflightBlocked(verb, preflight, scene);
|
|
444
518
|
return 1;
|
|
445
519
|
}
|
|
520
|
+
// The approved path's checked face (P21 §3.4): the SAME rows the refusal path
|
|
521
|
+
// renders — every dispatch reports which rules ran, not only the blocked ones.
|
|
522
|
+
this.#renderChecked(preflight);
|
|
446
523
|
// The real run's first write point (P11 · §4.2): the workspace — and the
|
|
447
524
|
// namespace's `.gitignore` keep-out marker — is built HERE, after the
|
|
448
525
|
// pre-flight verdict and before the brief render / the child dispatch, for
|
|
@@ -510,6 +587,10 @@ export class Cli {
|
|
|
510
587
|
target: scene.target ?? undefined,
|
|
511
588
|
capsule: new Capsule(this.#words, ARGV_CHANNEL, HostDetect.detect(process.env), scene.workspace.root.basis),
|
|
512
589
|
planPath: scene.planPath,
|
|
590
|
+
// The hop derivation's pipeline-station discrimination (§5.2) — the ONE
|
|
591
|
+
// declaration-reading judgment, injected so the session plane never imports a
|
|
592
|
+
// face class.
|
|
593
|
+
docClassOf: (candidate) => BoardView.docClassOf(scene.workspace.root.basis, candidate),
|
|
513
594
|
});
|
|
514
595
|
// The requested-phase gate — the line faces (branch/spec/plan) keep the
|
|
515
596
|
// line-phase readiness check; the task face needs no second gate (the WaveGate's
|
|
@@ -519,7 +600,15 @@ export class Cli {
|
|
|
519
600
|
if (open !== expected) {
|
|
520
601
|
const pendingBlock = verdict === "pending-fix" ? this.#gate.pendingFixBlock(scene, reviewed) : null;
|
|
521
602
|
const docBlock = open === null ? this.#gate.docLineBlock(scene, reviewed) : null;
|
|
522
|
-
|
|
603
|
+
// The generic refusal renders the SAME `NextHop` the capsule / board /
|
|
604
|
+
// frontier read (P22 §5.2 · the ONE message shape): `<reason> · the next
|
|
605
|
+
// round is <hop>` · `<reason> · next: <station>` · the bare reason. The two
|
|
606
|
+
// identity-aware block messages above own their facts (`reviewed` has no
|
|
607
|
+
// Home in `NextHop`) and stay verbatim.
|
|
608
|
+
const reject = pendingBlock ??
|
|
609
|
+
docBlock ??
|
|
610
|
+
this.#gate.lineHopMessage(scene, this.#gate.lineHop(scene), this.#words);
|
|
611
|
+
this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
|
|
523
612
|
return 1;
|
|
524
613
|
}
|
|
525
614
|
}
|
|
@@ -535,15 +624,22 @@ export class Cli {
|
|
|
535
624
|
let latest = [];
|
|
536
625
|
let lastStatus = null;
|
|
537
626
|
for (;;) {
|
|
538
|
-
const
|
|
539
|
-
if (
|
|
627
|
+
const peeked = run.peekNext();
|
|
628
|
+
if (peeked === null)
|
|
540
629
|
break;
|
|
630
|
+
const frame = peeked.frame;
|
|
541
631
|
const waveTasks = frame.target.kind === "wave" ? frame.target.tasks : null;
|
|
542
632
|
const mismatch = frame.phase !== expected ||
|
|
543
633
|
(group !== null && (waveTasks === null || !waveTasks.every((id) => group.has(id))));
|
|
544
634
|
if (mismatch) {
|
|
545
635
|
if (dispatched === 0) {
|
|
546
|
-
|
|
636
|
+
// The lookahead refusal renders the SAME `NextHop` the frame's line just
|
|
637
|
+
// derived (`peekNext`), through the ONE message shape — so one command can
|
|
638
|
+
// never print two different "next round" answers (the gate refusal above
|
|
639
|
+
// and this one name one object). The wave key stays an added clause.
|
|
640
|
+
const waveContext = waveTasks !== null ? ` for wave ${waveTasks.join(",")}` : "";
|
|
641
|
+
const reject = `${this.#gate.lineHopMessage(scene, peeked.hop, this.#words)}${waveContext}`;
|
|
642
|
+
this.#io.stderr(`cdd ${verb}: cannot dispatch a ${expected} round — ${reject}\n`);
|
|
547
643
|
return 1;
|
|
548
644
|
}
|
|
549
645
|
break;
|
|
@@ -558,7 +654,19 @@ export class Cli {
|
|
|
558
654
|
this.#io.stdout(`${line}\n`);
|
|
559
655
|
return 0;
|
|
560
656
|
}
|
|
561
|
-
|
|
657
|
+
// The gate→acquire race: another dispatch took the lock between the in-flight
|
|
658
|
+
// gate's read and this dispatch's acquire. `HoldingError` carries the holder's
|
|
659
|
+
// facts and renders the SAME held BLOCK message the gate renders.
|
|
660
|
+
let step;
|
|
661
|
+
try {
|
|
662
|
+
step = await run.advance();
|
|
663
|
+
}
|
|
664
|
+
catch (error) {
|
|
665
|
+
if (!(error instanceof HoldingError))
|
|
666
|
+
throw error;
|
|
667
|
+
this.#renderHeld(error);
|
|
668
|
+
return 1;
|
|
669
|
+
}
|
|
562
670
|
if (step === null)
|
|
563
671
|
break;
|
|
564
672
|
// The dispatch-entry gate's refusal (the lifecycle's hard child zero-dispatch wiring —
|
|
@@ -632,6 +740,9 @@ export class Cli {
|
|
|
632
740
|
overallLink: scene.overallLink,
|
|
633
741
|
},
|
|
634
742
|
reviews: parsed.paths.reviews,
|
|
743
|
+
// The explicit takeover flag (`--steal-stale`): the ONLY path that displaces a
|
|
744
|
+
// standing in-flight record — and only when its holder is dead.
|
|
745
|
+
stealStale: parsed.args.stealStale === "true",
|
|
635
746
|
});
|
|
636
747
|
return harness.step();
|
|
637
748
|
}
|
|
@@ -644,18 +755,6 @@ export class Cli {
|
|
|
644
755
|
const artifact = read.kind === "ok" ? read.value : null;
|
|
645
756
|
return typeof artifact?.base === "string" ? artifact.base : "";
|
|
646
757
|
}
|
|
647
|
-
/** The phase-mismatch hint — what to run instead. */
|
|
648
|
-
#phaseHint(phase) {
|
|
649
|
-
switch (phase) {
|
|
650
|
-
case "implement":
|
|
651
|
-
return " — run cdd implement first";
|
|
652
|
-
case "review":
|
|
653
|
-
case "branch-review":
|
|
654
|
-
return " — run cdd review first";
|
|
655
|
-
default:
|
|
656
|
-
return " — run cdd fix first";
|
|
657
|
-
}
|
|
658
|
-
}
|
|
659
758
|
/** Render a refused pre-flight verdict — the work command's BLOCK face (P4.1 T1).
|
|
660
759
|
* The dirty-tree / doc-contract refusals ride the CDD_BLOCKED channel (the
|
|
661
760
|
* commit/discard guidance + the named structural findings); the graph / wave
|
|
@@ -663,10 +762,13 @@ export class Cli {
|
|
|
663
762
|
* wave gate's split row — its done face rides the SAME closedWaves() read the gate
|
|
664
763
|
* judged, one closed set, one source). */
|
|
665
764
|
#renderPreflightBlocked(verb, verdict, scene) {
|
|
666
|
-
if (verdict.gate === "tree-clean" ||
|
|
765
|
+
if (verdict.gate === "tree-clean" ||
|
|
766
|
+
verdict.gate === "in-flight" ||
|
|
767
|
+
verdict.gate === "doc-contract") {
|
|
667
768
|
this.#io.stderr(`${this.#words.station("blocked")} ${verdict.message ?? ""}\n`);
|
|
668
769
|
for (const detail of verdict.details ?? [])
|
|
669
770
|
this.#io.stderr(` ${detail}\n`);
|
|
771
|
+
this.#renderChecked(verdict);
|
|
670
772
|
return;
|
|
671
773
|
}
|
|
672
774
|
this.#io.stderr(`cdd ${verb}: ${verdict.message ?? "the dispatch gate refused the request"}\n`);
|
|
@@ -684,6 +786,27 @@ export class Cli {
|
|
|
684
786
|
.split("\n"))
|
|
685
787
|
this.#io.stderr(` ${line}\n`);
|
|
686
788
|
}
|
|
789
|
+
this.#renderChecked(verdict);
|
|
790
|
+
}
|
|
791
|
+
/** Render the acquire race's held BLOCK — the in-flight gate's own message face
|
|
792
|
+
* (`Words.inFlightBlocked`, one filler for both call sites), exit 1 at the caller. */
|
|
793
|
+
#renderHeld(error) {
|
|
794
|
+
const message = this.#words.inFlightBlocked(error.record, true);
|
|
795
|
+
this.#io.stderr(`${this.#words.station("blocked")} ${message}\n`);
|
|
796
|
+
}
|
|
797
|
+
/** Render the checked face — the pre-flight's per-gate / per-rule rows, derived by
|
|
798
|
+
* the seam from the ONE rule declaration surface (P21 §3.4). It renders on BOTH
|
|
799
|
+
* pre-flight paths (approved and refused) into the diagnostic channel by default;
|
|
800
|
+
* the dry-run held preview passes its stdout writer so every dry-run shape reports
|
|
801
|
+
* the same face: "which rule ran, and what it judged" is a production read face,
|
|
802
|
+
* never a test-only field. The heading and the outcome words come from the word
|
|
803
|
+
* table (zero CLI literal), and the rows indent exactly like the details face
|
|
804
|
+
* above them. */
|
|
805
|
+
#renderChecked(verdict, write) {
|
|
806
|
+
const out = write ?? ((text) => this.#io.stderr(text));
|
|
807
|
+
out(`${this.#words.checkedWords().heading}\n`);
|
|
808
|
+
for (const row of verdict.checked)
|
|
809
|
+
out(` ${row}\n`);
|
|
687
810
|
}
|
|
688
811
|
// ---------------------------------------------------------------------------
|
|
689
812
|
// the work scene — the composition of contract/session/face objects
|
|
@@ -730,9 +853,11 @@ export class Cli {
|
|
|
730
853
|
slug = resolved;
|
|
731
854
|
break;
|
|
732
855
|
}
|
|
733
|
-
case "spec":
|
|
856
|
+
case "phase-spec":
|
|
857
|
+
case "overall":
|
|
858
|
+
case "single-spec": {
|
|
734
859
|
if (specPath === null || specRel === null)
|
|
735
|
-
this.#usage(node, `cdd ${verb} --type
|
|
860
|
+
this.#usage(node, `cdd ${verb} --type ${type}: missing required --spec <path>`);
|
|
736
861
|
// An unreadable target declares no identity: the SAME slug carrier hard-refuses
|
|
737
862
|
// it (CDD_BLOCKED + exit 1, never a filename-derived key). The T7 null-verdict
|
|
738
863
|
// face covers the other shape — a document ON DISK that declares no
|
|
@@ -742,10 +867,11 @@ export class Cli {
|
|
|
742
867
|
return null;
|
|
743
868
|
slug = resolved;
|
|
744
869
|
target = { kind: "spec", doc: specPath };
|
|
745
|
-
// The judged
|
|
746
|
-
// spec
|
|
747
|
-
// (a single-spec) leaves the slot null; an
|
|
748
|
-
// and the existing slug-ref invariant reports
|
|
870
|
+
// The judged document's own `program:` — the parent charter (INPUT_OVERALL)
|
|
871
|
+
// the phase-spec reviewer judges the phase against. A document without
|
|
872
|
+
// `program:` (an overall charter or a single-spec) leaves the slot null; an
|
|
873
|
+
// off-disk target reads null here and the existing slug-ref invariant reports
|
|
874
|
+
// it (never a second reporter).
|
|
749
875
|
const specEntry = index.entryAt(specRel);
|
|
750
876
|
const overallEntry = specEntry?.program == null ? null : index.overallOf(specEntry.program);
|
|
751
877
|
overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
|