@oscaner-skills/cdd-engine 4.2.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 +38 -9
- package/README.zh-CN.md +43 -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 +116 -35
- package/dist/face/declare.js +36 -18
- package/dist/face/gate.js +117 -40
- package/dist/face/init.js +1 -1
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/preview.js +43 -10
- 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/face/lifecycle.js
CHANGED
|
@@ -11,20 +11,34 @@
|
|
|
11
11
|
// The root Cli holds the lifecycle instances and composes through them via its .action
|
|
12
12
|
// thin shells — zero bare functions; every collaborator stays injectable (the tests
|
|
13
13
|
// substitute the hermetic ones).
|
|
14
|
+
var _a;
|
|
14
15
|
// The module exports the shared seams + the lifecycle class — zero behavior-carrying
|
|
15
16
|
// bare functions.
|
|
17
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
16
18
|
import process from "node:process";
|
|
17
19
|
import { printParseErrorCode } from "jsonc-parser";
|
|
20
|
+
import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
|
|
21
|
+
import { GitClient } from "../infra/git.js";
|
|
22
|
+
import { ProcessFacts } from "../infra/proc.js";
|
|
23
|
+
import { RoundLog } from "../infra/round-log.js";
|
|
18
24
|
import { TemplateAssembler } from "../render/templates.js";
|
|
25
|
+
import { TargetFaceTable } from "../session/faces.js";
|
|
19
26
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
27
|
+
import { InFlight } from "../session/inflight.js";
|
|
28
|
+
import { Ledger, RoundViolation, } from "../session/ledger.js";
|
|
20
29
|
import { RoundNaming } from "../session/round-naming.js";
|
|
30
|
+
import { PlanStructure } from "../session/run.js";
|
|
21
31
|
import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
|
|
22
32
|
import { TerminationPolicy, Terminator, } from "./termination.js";
|
|
23
|
-
import { Words } from "./words.js";
|
|
33
|
+
import { FIX_DISPOSITIONS_SUMMARY, Words } from "./words.js";
|
|
24
34
|
/** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
|
|
25
35
|
* non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
|
|
26
36
|
* channel; the child's Return is prose, never the round's content). */
|
|
27
37
|
const STDOUT_TAIL_MAX = 40;
|
|
38
|
+
/** The structure-face change message — the round's graded entry when the plan's Task id
|
|
39
|
+
* set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
|
|
40
|
+
* vanished / unreadable document cases name their own damage instead. */
|
|
41
|
+
const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the Task id set or a task's DependsOn set) — the structure face belongs to the orchestrator and lands as its own commit";
|
|
28
42
|
/**
|
|
29
43
|
* CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
|
|
30
44
|
* lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
|
|
@@ -37,6 +51,9 @@ const STDOUT_TAIL_MAX = 40;
|
|
|
37
51
|
* BLOCKED outcome over the CDD_BLOCKED channel (never a thrown dispatch).
|
|
38
52
|
*/
|
|
39
53
|
export class CliLifecycle {
|
|
54
|
+
/** The workspace-relative directory every round log lands in — built by
|
|
55
|
+
* `RoundLog.create` on first use, never by the workspace's own mkdir. */
|
|
56
|
+
static LOGS_DIR = "logs";
|
|
40
57
|
#env;
|
|
41
58
|
#sync;
|
|
42
59
|
#template;
|
|
@@ -54,14 +71,44 @@ export class CliLifecycle {
|
|
|
54
71
|
/** The handoff-schema face — stateless, one shared instance (the read-back
|
|
55
72
|
* validator + the injected prompt text). */
|
|
56
73
|
#handoffSchema = new HandoffSchema();
|
|
74
|
+
/** The in-flight record handle of this dispatch's workspace root — the ONE write
|
|
75
|
+
* point of the running dispatch (acquire before the spawn, release at the normal
|
|
76
|
+
* end; a crash leaves the record behind). */
|
|
77
|
+
#inflight;
|
|
78
|
+
/** The git read face — the crash record's `dispatchBase` / `commitsSince` facts. */
|
|
79
|
+
#git;
|
|
80
|
+
/** The recorded side of the liveness judgment — the holder pid's own start instant
|
|
81
|
+
* (`ProcessFacts.startOf`; injected by the tests to span a long session). */
|
|
82
|
+
#proc;
|
|
83
|
+
/** Whether this invocation asked to take over a dead holder's record (the
|
|
84
|
+
* `--steal-stale` flag — the only takeover path). */
|
|
85
|
+
#stealStale;
|
|
86
|
+
/** The HEAD the current dispatch started from (null off a repo / before a spawn) —
|
|
87
|
+
* the postmortem baseline of `commitsSince`. */
|
|
88
|
+
#dispatchBase = null;
|
|
89
|
+
/** The commits added after `#dispatchBase` (computed once the child returned). */
|
|
90
|
+
#commitsSince = [];
|
|
57
91
|
/** The current dispatch's child-stdout diagnostic tail (the crash-record channel,
|
|
58
92
|
* P11 T2) — set in #dispatch after the child returns, read by #reject. The child's
|
|
59
93
|
* Return is prose; the engine never parses it — this is the failure channel only. */
|
|
60
94
|
#stdoutTail = [];
|
|
95
|
+
/** The current dispatch's round log path (repoRoot-relative), null when the round has
|
|
96
|
+
* no log channel — the crash record's postmortem pointer (one file to open instead
|
|
97
|
+
* of reading `ps` from outside). */
|
|
98
|
+
#roundLogPath = null;
|
|
99
|
+
/** The current dispatch's log-channel failure (a SOFT entry naming the path), null
|
|
100
|
+
* when the channel opened — the record face must see a channel that never opened,
|
|
101
|
+
* not only the stderr notice. */
|
|
102
|
+
#logUnavailable = null;
|
|
61
103
|
constructor(opts) {
|
|
62
104
|
this.#env = opts.env ?? process.env;
|
|
63
105
|
this.#scene = opts.scene;
|
|
64
106
|
this.#naming = new RoundNaming(opts.scene.workspace);
|
|
107
|
+
this.#inflight =
|
|
108
|
+
opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
|
|
109
|
+
this.#git = opts.git ?? new GitClient();
|
|
110
|
+
this.#proc = opts.proc ?? ProcessFacts;
|
|
111
|
+
this.#stealStale = opts.stealStale ?? false;
|
|
65
112
|
this.#sync = opts.sync ?? new Terminator();
|
|
66
113
|
this.#template = opts.template ?? new TemplateAssembler();
|
|
67
114
|
this.#words = opts.words ?? new Words();
|
|
@@ -82,10 +129,237 @@ export class CliLifecycle {
|
|
|
82
129
|
step() {
|
|
83
130
|
return (frame) => this.#dispatch(frame);
|
|
84
131
|
}
|
|
85
|
-
/** One dispatch —
|
|
86
|
-
*
|
|
87
|
-
*
|
|
132
|
+
/** One dispatch — the round's work, the observation facts every record carries (the
|
|
133
|
+
* dispatch baseline HEAD captured before the spawn, the dispatch-after
|
|
134
|
+
* `treeClean` observation) and the TERMINAL VERDICT the round is booked under
|
|
135
|
+
* (design spec §3.1: the verdict is written first, the violation family splits the
|
|
136
|
+
* gate second — never the child's exit code). A hard verdict is the round's
|
|
137
|
+
* failure face: `targetAction: false`, the concluded status is BLOCKED (so the
|
|
138
|
+
* invocation exits non-zero and the same command re-offers the round), and the ONE
|
|
139
|
+
* `CDD_BLOCKED` line names the round's own log file (§4.1). A soft entry is
|
|
140
|
+
* bookkeeping only — it never touches the exit code. */
|
|
88
141
|
async #dispatch(frame) {
|
|
142
|
+
// The round's STRUCTURE baseline (design spec §7.3): taken HERE — after the
|
|
143
|
+
// pre-flight gate (which ran before the step was handed over) and before the
|
|
144
|
+
// spawn — so the close-time comparison judges this round's OWN plan edit only.
|
|
145
|
+
// It rides the frame and nowhere else (no progress key, no carrier slot, no
|
|
146
|
+
// in-flight field).
|
|
147
|
+
const baseline = PlanStructure.of(this.#scene.planPath);
|
|
148
|
+
const carried = {
|
|
149
|
+
...frame,
|
|
150
|
+
structure: baseline.kind === "ok" ? baseline.structure : null,
|
|
151
|
+
};
|
|
152
|
+
const drafted = await this.#runDispatch(carried);
|
|
153
|
+
const terminal = drafted.status === "BLOCKED" || drafted.status === "TIMEOUT";
|
|
154
|
+
const observed = {
|
|
155
|
+
...drafted,
|
|
156
|
+
dispatchBase: this.#dispatchBase,
|
|
157
|
+
treeClean: await this.#git.isClean(this.#scene.workspace.root.repoRoot),
|
|
158
|
+
};
|
|
159
|
+
const judged = await this.#verdictOf(carried, observed);
|
|
160
|
+
// The death faces author their own entry AND emit their own line (`#reject`), so
|
|
161
|
+
// only a hard verdict concluded HERE adds the shared line.
|
|
162
|
+
if (judged.violations.some((violation) => violation.grade === "hard") && !terminal) {
|
|
163
|
+
this.#blocked(this.#hardReason(judged.violations), false);
|
|
164
|
+
}
|
|
165
|
+
this.#warnSoft(judged.violations);
|
|
166
|
+
return {
|
|
167
|
+
...observed,
|
|
168
|
+
// A hard round's conclusion is the failure: no hard entry can leave a round
|
|
169
|
+
// reading as approved. A soft-only round keeps its handoff conclusion, and a
|
|
170
|
+
// round whose handoff was never written concludes APPROVED on its criterion
|
|
171
|
+
// alone (the missing carrier is bookkeeping, never a gate).
|
|
172
|
+
status: this.#concludedStatus(judged.verdict, observed.status),
|
|
173
|
+
verdict: judged.verdict,
|
|
174
|
+
violations: judged.violations,
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
/** The round's concluded status under its verdict — a done round keeps its handoff
|
|
178
|
+
* conclusion (APPROVED when the handoff was never written: the completion criterion
|
|
179
|
+
* concluded it), and a hard-failed round concludes BLOCKED — or keeps TIMEOUT, the
|
|
180
|
+
* terminated round's own conveyed face (the §4.3 judging order is unchanged). */
|
|
181
|
+
#concludedStatus(verdict, drafted) {
|
|
182
|
+
if (verdict.targetAction)
|
|
183
|
+
return drafted ?? "APPROVED";
|
|
184
|
+
return drafted === "TIMEOUT" ? "TIMEOUT" : "BLOCKED";
|
|
185
|
+
}
|
|
186
|
+
/** The terminal verdict of one dispatched round (design spec §3.1/§3.2) — the
|
|
187
|
+
* completion criterion of the round's verb judge its OWN facts (the group's
|
|
188
|
+
* records, the persisted carrier, the round's baseline) plus the work plane's
|
|
189
|
+
* evidence gate, and the graded entries decide the verdict: a round with no hard
|
|
190
|
+
* entry is done. The judgment's two provider cells are supplied HERE, the single
|
|
191
|
+
* point: `records` is the key's in-register history read with the line's DECLARED
|
|
192
|
+
* word, and `reviewsPath` is the fix route's `--reviews` carrier or the ledger's
|
|
193
|
+
* RESOLVED review-carrier fallback — the retired twin's name when the canonical
|
|
194
|
+
* file is absent, never the never-minted canonical spelling.
|
|
195
|
+
*
|
|
196
|
+
* A death face (a killed child, a non-zero exit, a rejected draft) already carries
|
|
197
|
+
* its authored hard entry and needs no second judgment — the criterion table and
|
|
198
|
+
* the violation family never judge the same round twice. */
|
|
199
|
+
async #verdictOf(frame, outcome) {
|
|
200
|
+
const treeClean = outcome.treeClean ?? true;
|
|
201
|
+
// The log channel's own failure is booked on every face: a round whose record
|
|
202
|
+
// face never opened is not a silent absence (§3.3), and a dead round carries the
|
|
203
|
+
// fact too.
|
|
204
|
+
const logEntries = this.#logUnavailable === null ? [] : [this.#logUnavailable];
|
|
205
|
+
if (outcome.status === "BLOCKED" || outcome.status === "TIMEOUT") {
|
|
206
|
+
const authored = outcome.violations ?? [];
|
|
207
|
+
return {
|
|
208
|
+
verdict: { treeClean, targetAction: false },
|
|
209
|
+
// A failure is never a silent absence (§3.3): a concluded BLOCKED round that
|
|
210
|
+
// authored no entry books one here (`contract-violation`, the existing cause).
|
|
211
|
+
violations: [
|
|
212
|
+
...(authored.length > 0
|
|
213
|
+
? authored
|
|
214
|
+
: [RoundViolation.hard(`the round concluded ${outcome.status}`)]),
|
|
215
|
+
...logEntries,
|
|
216
|
+
],
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
const violations = [
|
|
220
|
+
...(outcome.violations ?? []),
|
|
221
|
+
...(await this.#criterionViolations(frame, outcome)),
|
|
222
|
+
...this.#evidenceViolations(frame),
|
|
223
|
+
...this.#structureViolations(frame),
|
|
224
|
+
...logEntries,
|
|
225
|
+
];
|
|
226
|
+
return {
|
|
227
|
+
verdict: {
|
|
228
|
+
treeClean,
|
|
229
|
+
targetAction: !violations.some((violation) => violation.grade === "hard"),
|
|
230
|
+
},
|
|
231
|
+
violations,
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
/** The verb's completion-criterion verdict as graded entries — the criterion's own
|
|
235
|
+
* hard violation plus its SOFT observations (design spec §3.2/§3.3). */
|
|
236
|
+
async #criterionViolations(frame, outcome) {
|
|
237
|
+
const scene = this.#scene;
|
|
238
|
+
const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
|
|
239
|
+
record: this.#judgedRecordOf(frame, outcome),
|
|
240
|
+
row: this.#rowOf(frame),
|
|
241
|
+
records: scene.ledger.recordsOf(frame.key, frame.type),
|
|
242
|
+
carrier: outcome.carrier ?? null,
|
|
243
|
+
reviewsPath: this.#reviewsPath(frame),
|
|
244
|
+
git: this.#git,
|
|
245
|
+
repoRoot: scene.workspace.root.repoRoot,
|
|
246
|
+
});
|
|
247
|
+
return [
|
|
248
|
+
...(judged.violation === null ? [] : [judged.violation]),
|
|
249
|
+
...(judged.observations ?? []),
|
|
250
|
+
];
|
|
251
|
+
}
|
|
252
|
+
/** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
|
|
253
|
+
* group baseline and the carrier path the round writes. Deliberately verdict-free:
|
|
254
|
+
* this judgment PRODUCES the verdict, so a verdict cell here would be a
|
|
255
|
+
* self-fulfilling input. The group's already-recorded verdicts arrive through
|
|
256
|
+
* `CompletionContext.records`, never through this cell. */
|
|
257
|
+
#judgedRecordOf(frame, outcome) {
|
|
258
|
+
const op = this.#opOf(frame);
|
|
259
|
+
return {
|
|
260
|
+
op,
|
|
261
|
+
cycle: frame.round,
|
|
262
|
+
attempt: frame.attempt ?? 1,
|
|
263
|
+
dispatchBase: outcome.dispatchBase ?? null,
|
|
264
|
+
carrierPath: outcome.carrier === undefined
|
|
265
|
+
? null
|
|
266
|
+
: this.#scene.ledger.handoffPath(op, frame.type, frame.params),
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
/** The progress row the round belongs to (the criterion's context cell) — the key's
|
|
270
|
+
* row when it exists, else the fresh entry form of that key. */
|
|
271
|
+
#rowOf(frame) {
|
|
272
|
+
const ledger = this.#scene.ledger;
|
|
273
|
+
const data = ledger.readProgress();
|
|
274
|
+
return ((data === null ? undefined : Ledger.rowFor(data, frame.key, frame.type)) ??
|
|
275
|
+
ledger.entryFor(frame.key));
|
|
276
|
+
}
|
|
277
|
+
/** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
|
|
278
|
+
* branch rounds write the canonical `{family-prefix}-{key}-test-evidence.json`; a
|
|
279
|
+
* missing / malformed / schema-violating file is HARD. The tri-state read reports
|
|
280
|
+
* each cause truly (D27): a corrupt file is never misreported as absent. */
|
|
281
|
+
#evidenceViolations(frame) {
|
|
282
|
+
if (HandoffSchema.planeOf(this.#opOf(frame)) !== "work")
|
|
283
|
+
return [];
|
|
284
|
+
if (TargetFaceTable.isDocShape(frame.type))
|
|
285
|
+
return [];
|
|
286
|
+
const scene = this.#scene;
|
|
287
|
+
const evidencePath = scene.workspace.resolve(this.#naming.evidenceName(frame));
|
|
288
|
+
const read = scene.workspace.readJson(this.#naming.evidenceName(frame));
|
|
289
|
+
if (read.kind === "malformed") {
|
|
290
|
+
return [this.#hard(`the test evidence at ${evidencePath} is malformed JSON`)];
|
|
291
|
+
}
|
|
292
|
+
if (read.kind === "missing") {
|
|
293
|
+
return [this.#hard(`the test evidence at ${evidencePath} was not written`)];
|
|
294
|
+
}
|
|
295
|
+
const problems = this.#handoffSchema.evidenceViolations(read.value);
|
|
296
|
+
if (problems.length === 0)
|
|
297
|
+
return [];
|
|
298
|
+
return [
|
|
299
|
+
this.#hard(`the test evidence at ${evidencePath} violates the contract: ${problems.join("; ")}`),
|
|
300
|
+
];
|
|
301
|
+
}
|
|
302
|
+
/** The round's OWN plan-structure edit as a graded entry (design spec §7.3) — the
|
|
303
|
+
* close-time comparison against the dispatch-time snapshot: a changed Task-id set
|
|
304
|
+
* or a changed `DependsOn` set is a HARD entry under the existing
|
|
305
|
+
* `contract-violation` cause (zero new violation enum), because the structure face
|
|
306
|
+
* belongs to the orchestrator and lands as its own commit. A content-only amendment
|
|
307
|
+
* differs on neither face and judges nothing.
|
|
308
|
+
*
|
|
309
|
+
* The two sides are judged apart. An ABSENT baseline (no plan fact, or a document
|
|
310
|
+
* already unreadable at dispatch) judges nothing — there is nothing to compare
|
|
311
|
+
* against. A PRESENT baseline with a missing / unreadable current side is the
|
|
312
|
+
* round's own damage: the document the dispatch read is gone or damaged inside this
|
|
313
|
+
* round, which is the structure face's most extreme edit and is judged hard rather
|
|
314
|
+
* than skipped. */
|
|
315
|
+
#structureViolations(frame) {
|
|
316
|
+
const baseline = frame.structure ?? null;
|
|
317
|
+
if (baseline === null)
|
|
318
|
+
return [];
|
|
319
|
+
const current = PlanStructure.of(this.#scene.planPath);
|
|
320
|
+
if (current.kind === "ok") {
|
|
321
|
+
if (!current.structure.differsFrom(baseline))
|
|
322
|
+
return [];
|
|
323
|
+
return [this.#hard(STRUCTURE_CHANGED)];
|
|
324
|
+
}
|
|
325
|
+
return [
|
|
326
|
+
this.#hard(current.kind === "absent"
|
|
327
|
+
? "the plan document disappeared inside this round — the structure face belongs to the orchestrator and lands as its own commit"
|
|
328
|
+
: `the plan document became unreadable inside this round (${current.reason}) — the structure face belongs to the orchestrator and lands as its own commit`),
|
|
329
|
+
];
|
|
330
|
+
}
|
|
331
|
+
/** One self-authored HARD entry — the ledger's existing `contract-violation` cause,
|
|
332
|
+
* zero new violation enum (design spec §3.3). */
|
|
333
|
+
#hard(message) {
|
|
334
|
+
return RoundViolation.hard(message);
|
|
335
|
+
}
|
|
336
|
+
/** The hard entries' one-line reason (the `CDD_BLOCKED` line's message). */
|
|
337
|
+
#hardReason(violations) {
|
|
338
|
+
return violations
|
|
339
|
+
.filter((violation) => violation.grade === "hard")
|
|
340
|
+
.map((violation) => violation.message)
|
|
341
|
+
.join("; ");
|
|
342
|
+
}
|
|
343
|
+
/** Warn once per round about its SOFT entries (design spec §3.3 — soft is
|
|
344
|
+
* bookkeeping only, so it never touches the verdict, the exit code or the gate). */
|
|
345
|
+
#warnSoft(violations) {
|
|
346
|
+
const soft = violations
|
|
347
|
+
.filter((violation) => violation.grade === "soft")
|
|
348
|
+
.map((violation) => violation.message);
|
|
349
|
+
if (soft.length === 0)
|
|
350
|
+
return;
|
|
351
|
+
this.#io.stderr(`${this.#words.station("warn")} ${this.#words.softViolation(soft.join("; "))}\n`);
|
|
352
|
+
}
|
|
353
|
+
/** One dispatch's round work — prompt from the template plane + the frame, host
|
|
354
|
+
* child via the harness-contract rows, the child's write-back read in (the draft
|
|
355
|
+
* at OUTPUT_HANDOFF is the round's content; the child's Return is prose, never
|
|
356
|
+
* parsed). */
|
|
357
|
+
async #runDispatch(frame) {
|
|
358
|
+
// The baseline belongs to THIS dispatch alone: cleared at entry, so an early
|
|
359
|
+
// return (no host harness) records "no baseline" rather than a previous round's.
|
|
360
|
+
this.#dispatchBase = null;
|
|
361
|
+
this.#roundLogPath = null;
|
|
362
|
+
this.#logUnavailable = null;
|
|
89
363
|
const host = this.detectHost();
|
|
90
364
|
if (host === "") {
|
|
91
365
|
this.#io.stderr("CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n");
|
|
@@ -96,26 +370,54 @@ export class CliLifecycle {
|
|
|
96
370
|
const cliName = row.cli;
|
|
97
371
|
const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
|
|
98
372
|
const ref = this.#skillRef(host, frame);
|
|
373
|
+
// The dispatch's ONE write point: publish the intent BEFORE the child exists, so
|
|
374
|
+
// any later crash / kill / timeout leaves a record naming who was running. The
|
|
375
|
+
// gates read `InFlight.inspect()` only — this call is the real dispatch's alone.
|
|
376
|
+
// A sibling dispatch that won the lock in between makes `acquire` throw
|
|
377
|
+
// `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
|
|
378
|
+
this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
|
|
379
|
+
await this.#inflight.acquire(await this.#recordOf(frame), { stealStale: this.#stealStale });
|
|
380
|
+
// The round's own log file — created BEFORE the spawn (append stream open, zero
|
|
381
|
+
// bytes), so the channel exists from the dispatch's first millisecond. A create
|
|
382
|
+
// failure is a named soft observation and the round continues on the CPU leg
|
|
383
|
+
// alone (the log leg is null, never a kill authorization).
|
|
384
|
+
const roundLog = await this.#openRoundLog(frame);
|
|
385
|
+
// The postmortem pointer of THIS round — the log the child's bytes land in (absent
|
|
386
|
+
// when the channel could not be opened: the record then carries the honest null).
|
|
387
|
+
this.#roundLogPath = roundLog === null ? null : this.#rel(roundLog.path);
|
|
99
388
|
// The child receives ONE prompt argument — per the host's promptForm data column
|
|
100
389
|
// (§3.5): the ref-prefixed form embeds the slash ref at the start of the single
|
|
101
390
|
// prompt positional (claude -p consumes the whole first positional as the prompt;
|
|
102
391
|
// a standalone ref arg after the flags would be swallowed, losing everything after
|
|
103
392
|
// the ref) — the prompt assembly is data, never a code assumption.
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
393
|
+
let result;
|
|
394
|
+
try {
|
|
395
|
+
result = await this.#sync.run({
|
|
396
|
+
command: cliName,
|
|
397
|
+
args: [...args, this.#childPrompt(row.promptForm, ref, prompt)],
|
|
398
|
+
// The child's spawn directory is the repo root; the in-flight record handle
|
|
399
|
+
// carries the sampler's own write path (the record is the ONE trail, and its
|
|
400
|
+
// path is the tree leg's exclusion). The same `cwd` is also the tree-leg scan
|
|
401
|
+
// root, so the scan root ≡ child cwd correspondence is structural.
|
|
402
|
+
cwd: this.#scene.workspace.root.repoRoot,
|
|
403
|
+
inflight: this.#inflight,
|
|
404
|
+
policy: TerminationPolicy.of(frame.phase),
|
|
405
|
+
// The host row's own child env — the TTL pin the terminator layers over the
|
|
406
|
+
// inherited env at spawn (the host difference is data, never a dispatcher branch).
|
|
407
|
+
env: row.env,
|
|
408
|
+
log: roundLog ?? undefined,
|
|
409
|
+
});
|
|
410
|
+
}
|
|
411
|
+
finally {
|
|
412
|
+
// Drain → close BEFORE any read-back judgment: the append stream's tail bytes can
|
|
413
|
+
// land after the exit event, so the postmortem face is only complete after close.
|
|
414
|
+
if (roundLog !== null)
|
|
415
|
+
await roundLog.close();
|
|
416
|
+
}
|
|
417
|
+
// The postmortem pair's second leg: what the (possibly crashed) child added on top
|
|
418
|
+
// of the dispatch baseline. Computed ONCE here, so every reject path below writes
|
|
419
|
+
// the same facts without a second git read.
|
|
420
|
+
this.#commitsSince = await this.#git.commitsSince(this.#scene.workspace.root.repoRoot, this.#dispatchBase);
|
|
119
421
|
// The child's stdout rides the diagnostic channel — #reject reads it into the
|
|
120
422
|
// crash record on either failure face. Child Return is prose: the engine never
|
|
121
423
|
// parses it; the round's content is the OUTPUT_HANDOFF draft, read in #reconstruct.
|
|
@@ -148,7 +450,78 @@ export class CliLifecycle {
|
|
|
148
450
|
// this branch sits AFTER the termination leg, so the termination is null
|
|
149
451
|
{ exitCode: result.code, cause: "child-exit", termination: null });
|
|
150
452
|
}
|
|
151
|
-
|
|
453
|
+
// The normal end: the child finished on its own and its handoff was read back —
|
|
454
|
+
// the ONE release point. The read-back's own refusals (a malformed / schema-
|
|
455
|
+
// violating draft) still release: the CHILD did not die, the round's artifacts were
|
|
456
|
+
// judged. The record survives only the round-ending paths above (a non-zero child
|
|
457
|
+
// exit, a kill, a timeout) and an uncaught throw — i.e. the process-death paths the
|
|
458
|
+
// record exists for.
|
|
459
|
+
const outcome = this.#reconstruct(frame);
|
|
460
|
+
await this.#inflight.release();
|
|
461
|
+
return outcome;
|
|
462
|
+
}
|
|
463
|
+
/** The in-flight record of one frame — the identity facts written before the spawn.
|
|
464
|
+
* `pid` is the dispatching engine process, the command is the same-command resume
|
|
465
|
+
* form, and the brief hash is computed NOW from the rendered brief (the ledger's ONE
|
|
466
|
+
* hash face — never a new hash surface).
|
|
467
|
+
* `startedAt` is the recorded pid's OWN start instant (`ProcessFacts.startOf`), the
|
|
468
|
+
* instant `ProcessFacts.live` compares against: the dispatch instant drifts away
|
|
469
|
+
* from it, and on a session older than the tolerance that drift would judge a live
|
|
470
|
+
* holder dead — the one direction the guard must never take. The dispatch instant
|
|
471
|
+
* is only the fallback when the process table cannot answer, and an unreadable
|
|
472
|
+
* start time then folds to "alive" on the read side (never to a takeover). */
|
|
473
|
+
async #recordOf(frame) {
|
|
474
|
+
const scene = this.#scene;
|
|
475
|
+
return {
|
|
476
|
+
pid: process.pid,
|
|
477
|
+
command: this.#resumeOf(frame),
|
|
478
|
+
slug: scene.workspace.slug,
|
|
479
|
+
startedAt: (await this.#proc.startOf(process.pid)) ?? Date.now(),
|
|
480
|
+
wave: frame.type === "wave" ? (frame.params.tasks ?? null) : null,
|
|
481
|
+
phase: frame.phase,
|
|
482
|
+
cycle: frame.round,
|
|
483
|
+
attempt: frame.attempt ?? 1,
|
|
484
|
+
briefHash: this.#briefHashOf(frame),
|
|
485
|
+
plan: scene.planPath === null ? null : this.#rel(scene.planPath),
|
|
486
|
+
sampledAt: null,
|
|
487
|
+
verdict: null,
|
|
488
|
+
};
|
|
489
|
+
}
|
|
490
|
+
/** Open one round's log file — the per-round channel the child's stdout/stderr
|
|
491
|
+
* land in, under the workspace's `logs/` directory (which no other writer creates).
|
|
492
|
+
* A create failure is a named soft observation and the round continues on the CPU
|
|
493
|
+
* leg alone (the log leg stays null); a fault AFTER the channel is live marks the
|
|
494
|
+
* log leg dead and is reported through the same channel — never a second notice. */
|
|
495
|
+
async #openRoundLog(frame) {
|
|
496
|
+
const name = this.#naming.logName(this.#opOf(frame), frame.type, frame.params, frame.attempt ?? 1);
|
|
497
|
+
const target = this.#scene.workspace.resolve(`${_a.LOGS_DIR}/${name}`);
|
|
498
|
+
try {
|
|
499
|
+
return await RoundLog.create(target, () => this.#io.stderr(`${this.#words.station("warn")} round log write failed at ${this.#rel(target)}\n`));
|
|
500
|
+
}
|
|
501
|
+
catch {
|
|
502
|
+
this.#io.stderr(`${this.#words.station("warn")} round log unavailable at ${this.#rel(target)}\n`);
|
|
503
|
+
// The record sees the same fact the stderr notice names (design spec §3.3): a
|
|
504
|
+
// soft entry, so the round concludes and the derived count carries it.
|
|
505
|
+
this.#logUnavailable = RoundViolation.soft(`the round log could not be created at ${this.#rel(target)} — the round ran on CPU evidence alone`);
|
|
506
|
+
return null;
|
|
507
|
+
}
|
|
508
|
+
}
|
|
509
|
+
/** The wave frame's brief hash at acquire time — `ReviewRefs.briefRevision` over the
|
|
510
|
+
* brief file this dispatch rendered (the SAME hash face the ledger binds as the
|
|
511
|
+
* reviewed revision). Computed independently of the ledger's records, so a wave's
|
|
512
|
+
* FIRST dispatch (no `brief-revision` row yet) still carries the hash. Null off the
|
|
513
|
+
* wave face and when the brief is not on disk yet. */
|
|
514
|
+
#briefHashOf(frame) {
|
|
515
|
+
const scene = this.#scene;
|
|
516
|
+
if (frame.type !== "wave" || scene.planPath === null || scene.briefPath === null)
|
|
517
|
+
return null;
|
|
518
|
+
try {
|
|
519
|
+
const brief = readFileSync(scene.briefPath, "utf8");
|
|
520
|
+
return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), brief).brief_hash;
|
|
521
|
+
}
|
|
522
|
+
catch {
|
|
523
|
+
return null;
|
|
524
|
+
}
|
|
152
525
|
}
|
|
153
526
|
/** The work-mode of a frame phase — branch-review rides the review family. The
|
|
154
527
|
* mapping itself lives in `RoundNaming` (the artifact stems key on it); this is
|
|
@@ -156,11 +529,11 @@ export class CliLifecycle {
|
|
|
156
529
|
#opOf(frame) {
|
|
157
530
|
return this.#naming.op(frame);
|
|
158
531
|
}
|
|
159
|
-
/** The dispatch-table work-mode (ROLE) of a frame — the
|
|
532
|
+
/** The dispatch-table work-mode (ROLE) of a frame — the doc shapes' fix faces ride
|
|
160
533
|
* the docs-fix mode; everything else maps by its phase (§3.5's four-mode table). */
|
|
161
534
|
#roleOf(frame) {
|
|
162
535
|
if (frame.phase === "fix") {
|
|
163
|
-
return
|
|
536
|
+
return TargetFaceTable.isDocShape(frame.type) ? "docs-fix" : "fix";
|
|
164
537
|
}
|
|
165
538
|
return frame.phase === "implement" ? "implement" : "review";
|
|
166
539
|
}
|
|
@@ -230,9 +603,7 @@ export class CliLifecycle {
|
|
|
230
603
|
// v1.9: INPUT_REVIEWS is fix/docs-fix only — the source review's handoff
|
|
231
604
|
// carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
|
|
232
605
|
// would be a short-circuit).
|
|
233
|
-
INPUT_REVIEWS: op === "fix"
|
|
234
|
-
? this.#rel(this.#reviews ?? scene.ledger.handoffPath("review", frame.type, params))
|
|
235
|
-
: "",
|
|
606
|
+
INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
|
|
236
607
|
// The kind-named judged-doc anchors (the semantic retirement of the generic
|
|
237
608
|
// INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
|
|
238
609
|
// doc path on a plan line, the plan path on a branch line, whose review/fix
|
|
@@ -246,18 +617,23 @@ export class CliLifecycle {
|
|
|
246
617
|
: frame.type === "branch"
|
|
247
618
|
? this.#rel(scene.planPath ?? "")
|
|
248
619
|
: "",
|
|
249
|
-
INPUT_SPEC: frame.type === "
|
|
620
|
+
INPUT_SPEC: frame.type === "plan" || frame.type === "branch"
|
|
621
|
+
? this.#rel(scene.specLink ?? "")
|
|
622
|
+
: frame.type === "wave"
|
|
623
|
+
? ""
|
|
624
|
+
: // the doc shapes (phase-spec · overall · single-spec) carry the judged
|
|
625
|
+
// document — the charter line's own charter is its spec anchor.
|
|
626
|
+
this.#rel(docPath ?? ""),
|
|
627
|
+
// The parent charter of the spec the face reads (INPUT_OVERALL) — the same
|
|
628
|
+
// value condition as INPUT_SPEC, one face (the phase-spec line = its own
|
|
629
|
+
// `program:`; plan/branch = the same-slug identity doc's `program:`; the
|
|
630
|
+
// overall line itself = the judged charter); empty off those faces and when
|
|
631
|
+
// the named program is absent (the assembler drops the empty slot).
|
|
632
|
+
INPUT_OVERALL: frame.type === "overall"
|
|
250
633
|
? this.#rel(docPath ?? "")
|
|
251
|
-
: frame.type === "plan" || frame.type === "branch"
|
|
252
|
-
? this.#rel(scene.
|
|
634
|
+
: frame.type === "phase-spec" || frame.type === "plan" || frame.type === "branch"
|
|
635
|
+
? this.#rel(scene.overallLink ?? "")
|
|
253
636
|
: "",
|
|
254
|
-
// The parent charter of the spec the face reads (INPUT_OVERALL) — the same
|
|
255
|
-
// value condition as INPUT_SPEC, one face (spec = its own `program:`; plan/
|
|
256
|
-
// branch = the same-slug identity doc's `program:`); empty off those faces and
|
|
257
|
-
// when the spec names no program (the assembler drops the empty slot).
|
|
258
|
-
INPUT_OVERALL: frame.type === "spec" || frame.type === "plan" || frame.type === "branch"
|
|
259
|
-
? this.#rel(scene.overallLink ?? "")
|
|
260
|
-
: "",
|
|
261
637
|
// The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
|
|
262
638
|
// from the base artifact at dispatch; empty off those faces (spec/plan reviews
|
|
263
639
|
// carry none, and the empty slot is dropped by the assembler).
|
|
@@ -362,7 +738,7 @@ export class CliLifecycle {
|
|
|
362
738
|
verdict: termination.lastSample?.verdict ?? "none",
|
|
363
739
|
count: findings.length,
|
|
364
740
|
});
|
|
365
|
-
this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
|
|
741
|
+
this.#io.stderr(`${this.#words.station("warn")} ${text} — ${this.#words.lateLandingHint()}\n`);
|
|
366
742
|
return { ...outcome, termination };
|
|
367
743
|
}
|
|
368
744
|
/** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
|
|
@@ -370,13 +746,13 @@ export class CliLifecycle {
|
|
|
370
746
|
* subset (projection ② of session/handoff-schema.ts — the SAME declared objects
|
|
371
747
|
* the prompt injected), then build the final carrier the lifecycle persists in
|
|
372
748
|
* place (agent draft → finalized, full-replace at the same path — the engine
|
|
373
|
-
* remains the carrier's single author). A
|
|
374
|
-
*
|
|
375
|
-
*
|
|
376
|
-
*
|
|
377
|
-
*
|
|
378
|
-
*
|
|
379
|
-
*
|
|
749
|
+
* remains the carrier's single author). A malformed or schema-violating draft is a
|
|
750
|
+
* contract violation at the read-back face (the draft untouched — the child's work
|
|
751
|
+
* is never clobbered; resume re-runs the same command, which re-offers the round).
|
|
752
|
+
* A MISSING draft is not a rejection: the completion criterion owns it (§3.3) — an
|
|
753
|
+
* implement round continues on its commits with a soft observation, a review/fix
|
|
754
|
+
* round fails on its carrier criterion — so no carrier is materialized and the
|
|
755
|
+
* verdict is written against the null status.
|
|
380
756
|
*
|
|
381
757
|
* `prefetched` is the terminated-review promotion's already-probed draft — the ONE
|
|
382
758
|
* draft parse stays single-sourced (`#readDraft`), and the promotion rides this
|
|
@@ -400,13 +776,8 @@ export class CliLifecycle {
|
|
|
400
776
|
// jsonc-parser tolerates the lenient dialect while a real break (a missing
|
|
401
777
|
// brace, …) still reports malformed.
|
|
402
778
|
const draftRead = this.#readDraft(frame);
|
|
403
|
-
if (draftRead.kind === "missing")
|
|
404
|
-
return
|
|
405
|
-
exitCode: 0,
|
|
406
|
-
cause: "handoff-absent",
|
|
407
|
-
termination: null,
|
|
408
|
-
});
|
|
409
|
-
}
|
|
779
|
+
if (draftRead.kind === "missing")
|
|
780
|
+
return { status: null };
|
|
410
781
|
if (draftRead.kind === "malformed") {
|
|
411
782
|
// The lenient face carries the parser's precise error codes (D39) — surface
|
|
412
783
|
// them in the rejection so a genuinely corrupt draft is diagnosable, not just
|
|
@@ -435,51 +806,65 @@ export class CliLifecycle {
|
|
|
435
806
|
// — so the `?? "BLOCKED"` never fires here (a work draft without a status never
|
|
436
807
|
// reaches this line; the absent→undefined case exists only for on-disk legacy
|
|
437
808
|
// carriers the ledger reads back, never a schema-validated draft).
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
// The evidence gate (v1.9) — the work plane's wave / branch rounds (implement/fix
|
|
441
|
-
// task+branch) write the canonical `{family-prefix}-{key}-test-evidence.json` under
|
|
442
|
-
// the workspace (§3.7 naming: tasks- for the task families, branch- for the branch
|
|
443
|
-
// fix); the doc rounds (review/docs-fix) carry no evidence file. The read-back is
|
|
444
|
-
// REAL — a missing/malformed/schema-violating file rewrites the draft to BLOCKED
|
|
445
|
-
// (each cause reported truly — the tri-state read, D27).
|
|
446
|
-
if (plane === "work" && (frame.type === "wave" || frame.type === "branch")) {
|
|
447
|
-
const evidenceName = this.#naming.evidenceName(frame);
|
|
448
|
-
const evidencePath = scene.workspace.resolve(evidenceName);
|
|
449
|
-
const evidenceRead = scene.workspace.readJson(evidenceName);
|
|
450
|
-
// The SAME tri-state discrimination as the draft leg (D27): a PRESENT-but-corrupt
|
|
451
|
-
// evidence file reports its true cause, never the misleading "missing" — only a
|
|
452
|
-
// genuinely absent file (or a schema-violating present one) rides the schema
|
|
453
|
-
// verdict below.
|
|
454
|
-
if (evidenceRead.kind === "malformed") {
|
|
455
|
-
status = "BLOCKED";
|
|
456
|
-
reason = `the test evidence at ${evidencePath} is malformed JSON`;
|
|
457
|
-
}
|
|
458
|
-
else {
|
|
459
|
-
const evidence = evidenceRead.kind === "ok" ? evidenceRead.value : null;
|
|
460
|
-
const evidenceProblems = schema.evidenceViolations(evidence);
|
|
461
|
-
if (evidenceProblems.length > 0) {
|
|
462
|
-
status = "BLOCKED";
|
|
463
|
-
reason = `the test evidence at ${evidencePath} violates the contract: ${evidenceProblems.join("; ")}`;
|
|
464
|
-
}
|
|
465
|
-
}
|
|
466
|
-
}
|
|
809
|
+
const status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
|
|
810
|
+
const carrier = this.#materialize(frame, plane, draft, status);
|
|
467
811
|
return {
|
|
468
812
|
status,
|
|
469
813
|
findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
|
|
470
|
-
carrier
|
|
814
|
+
carrier,
|
|
815
|
+
dispositionsSummary: this.#dispositionsSummary(frame, plane, carrier),
|
|
471
816
|
};
|
|
472
817
|
}
|
|
818
|
+
/** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
|
|
819
|
+
* carrier's dispositions and the REQUESTING carrier's input set (the same pair the
|
|
820
|
+
* fix criterion judges), never stored: no record field, no carrier key, no capsule
|
|
821
|
+
* key, no second read face. Undefined off the fix face and when the input set
|
|
822
|
+
* cannot be located or read (the round fails on grounds the line cannot describe).
|
|
823
|
+
* The criterion supplies the counts; the `FIX_DISPOSITIONS_SUMMARY` template — the
|
|
824
|
+
* presentation plane's byte fact — renders the row here. */
|
|
825
|
+
#dispositionsSummary(frame, plane, carrier) {
|
|
826
|
+
if (plane !== "work" || this.#opOf(frame) !== "fix")
|
|
827
|
+
return undefined;
|
|
828
|
+
const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
|
|
829
|
+
if (requester.kind !== "read")
|
|
830
|
+
return undefined;
|
|
831
|
+
const counts = new FixDispositions().summaryOf(carrier, requester.summaries);
|
|
832
|
+
return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
|
|
833
|
+
}
|
|
834
|
+
/** The requesting review carrier's path — the fix round's `--reviews` input, or the
|
|
835
|
+
* ledger's resolved review handoff path when the route carried none (the ONE
|
|
836
|
+
* resolution the round context's INPUT_REVIEWS and the disposition summary share).
|
|
837
|
+
* A migrated line resolves the carrier that EXISTS — the retired twin's name, never
|
|
838
|
+
* the never-minted canonical spelling.
|
|
839
|
+
*
|
|
840
|
+
* A same-cycle review record that RECORDED no carrier path, with no carrier at
|
|
841
|
+
* either spelling on disk, leaves the requester input UNRECORDED: the answer is
|
|
842
|
+
* null, and the fix criterion books its visible skip (design spec §3.4's legacy
|
|
843
|
+
* row) instead of failing the round on a hard absent-carrier refusal. An absent
|
|
844
|
+
* record is a different fact — it keeps the resolved path, so the criterion reports
|
|
845
|
+
* the missing requesting carrier it truly is. */
|
|
846
|
+
#reviewsPath(frame) {
|
|
847
|
+
if (this.#reviews !== null)
|
|
848
|
+
return this.#reviews;
|
|
849
|
+
const resolved = this.#scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
|
|
850
|
+
if (existsSync(resolved))
|
|
851
|
+
return resolved;
|
|
852
|
+
const legacy = this.#scene.ledger
|
|
853
|
+
.recordsOf(frame.key, frame.type)
|
|
854
|
+
.some((record) => record.op === "review" && record.cycle === frame.round && record.carrierPath === null);
|
|
855
|
+
return legacy ? null : resolved;
|
|
856
|
+
}
|
|
473
857
|
/** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
|
|
474
858
|
* same-command resume's decision source: the attempted handoff + the resume
|
|
475
859
|
* command) + NO carrier (the bookkeep leaves the draft untouched). The crash
|
|
476
|
-
* record carries the caller's REAL death facts:
|
|
477
|
-
* `
|
|
478
|
-
*
|
|
479
|
-
*
|
|
480
|
-
*
|
|
481
|
-
*
|
|
482
|
-
*
|
|
860
|
+
* record carries the caller's REAL death facts: a present-but-unqualified draft
|
|
861
|
+
* (malformed JSON / schema) is `contract-violation` (the default), a dead child
|
|
862
|
+
* passes its own exit code + `child-exit`, and a terminated round passes its whole
|
|
863
|
+
* `termination` fact (cause + last sample) — one record shape, three truthful
|
|
864
|
+
* callers (the record is the postmortem artifact; a misreported death sends a
|
|
865
|
+
* maintainer hunting the wrong fault). A MISSING draft is not this face: the
|
|
866
|
+
* completion criterion owns it, so no rejection — and no crash record — ever fires
|
|
867
|
+
* for an absent draft.
|
|
483
868
|
*
|
|
484
869
|
* The returned status derives from the death facts alone (§4.3 — no status
|
|
485
870
|
* parameter): a termination rides it → `TIMEOUT`; otherwise → `BLOCKED` (the
|
|
@@ -490,6 +875,7 @@ export class CliLifecycle {
|
|
|
490
875
|
cause: "contract-violation",
|
|
491
876
|
termination: null,
|
|
492
877
|
}) {
|
|
878
|
+
const cause = this.#causeOf(death);
|
|
493
879
|
this.#writeCrash(frame, path, reason, death, false);
|
|
494
880
|
// A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
|
|
495
881
|
// last sample's verdict (the crash record carries the full sample).
|
|
@@ -499,21 +885,42 @@ export class CliLifecycle {
|
|
|
499
885
|
idleMs: death.termination.idleMs,
|
|
500
886
|
verdict: death.termination.lastSample?.verdict ?? "none",
|
|
501
887
|
});
|
|
502
|
-
|
|
888
|
+
// Every cut-short round (kill · timeout · crash) carries the late-landing hint: the
|
|
889
|
+
// child may still write after the engine stopped watching, and the recovery starts
|
|
890
|
+
// from the working tree, never from the assumption that nothing landed.
|
|
891
|
+
this.#blocked(`${reason}${detail}`, true);
|
|
892
|
+
// The rejected round's own HARD entry — the verdict is `targetAction: false` and the
|
|
893
|
+
// failure is named, never a silent absence (§3.3). The cause rides the death facts'
|
|
894
|
+
// existing vocabulary (no new enum row).
|
|
895
|
+
const violations = [RoundViolation.hard(reason, cause)];
|
|
503
896
|
if (death.termination === null)
|
|
504
|
-
return { status: "BLOCKED" };
|
|
505
|
-
return { status: "TIMEOUT", termination: death.termination };
|
|
897
|
+
return { status: "BLOCKED", violations };
|
|
898
|
+
return { status: "TIMEOUT", termination: death.termination, violations };
|
|
899
|
+
}
|
|
900
|
+
/** The crash cause of one death fact — the termination's own cause when present,
|
|
901
|
+
* else the caller's. One derivation, two readers (the crash record and the round's
|
|
902
|
+
* hard entry). */
|
|
903
|
+
#causeOf(death) {
|
|
904
|
+
return death.termination?.cause ?? death.cause;
|
|
905
|
+
}
|
|
906
|
+
/** The ONE `CDD_BLOCKED` line (§3.3): the hard verdict and the rejected / cut-short
|
|
907
|
+
* rounds share it, and every line names the round's own log file (§4.1) — a
|
|
908
|
+
* diagnose-one-round job is one path away, never a `ps` read from outside. The
|
|
909
|
+
* late-landing hint is a CUT-SHORT fact alone (a hard round's child finished). */
|
|
910
|
+
#blocked(reason, cutShort) {
|
|
911
|
+
const log = this.#roundLogPath === null ? "" : ` — log: ${this.#roundLogPath}`;
|
|
912
|
+
const hint = cutShort ? ` — ${this.#words.lateLandingHint()}` : "";
|
|
913
|
+
this.#io.stderr(`CDD_BLOCKED: ${reason}${log}${hint}\n`);
|
|
506
914
|
}
|
|
507
915
|
/** Write the lane's crash record — the postmortem artifact and same-command
|
|
508
916
|
* resume's decision source. One writer serves both the rejection face
|
|
509
917
|
* (`promoted: false`) and the termination branch's promotion (`promoted: true`):
|
|
510
918
|
* the record shape is identical, only the promotion fact differs. */
|
|
511
919
|
#writeCrash(frame, path, reason, death, promoted) {
|
|
512
|
-
const op = this.#opOf(frame);
|
|
513
920
|
// The cause rides the termination fact when one is present (one of the three
|
|
514
921
|
// causes or the `unknown` fallback); without it, the caller's own cause.
|
|
515
|
-
const cause = death
|
|
516
|
-
this.#scene.ledger.writeCrash(
|
|
922
|
+
const cause = this.#causeOf(death);
|
|
923
|
+
this.#scene.ledger.writeCrash(this.#naming.crashName(frame), {
|
|
517
924
|
exitCode: death.exitCode,
|
|
518
925
|
stderrTail: [reason],
|
|
519
926
|
stdoutTail: this.#stdoutTail,
|
|
@@ -522,25 +929,31 @@ export class CliLifecycle {
|
|
|
522
929
|
attemptedHandoff: this.#rel(path),
|
|
523
930
|
next: this.#resumeOf(frame),
|
|
524
931
|
cause,
|
|
525
|
-
// The
|
|
526
|
-
//
|
|
932
|
+
// The postmortem's observation pair: the round's own log file (one file to open
|
|
933
|
+
// instead of reading `ps` from outside) and its last sample, which rides WITH the
|
|
934
|
+
// termination (in memory, zero re-read of the in-flight record) — null on every
|
|
935
|
+
// non-terminated face.
|
|
936
|
+
logPath: this.#roundLogPath,
|
|
527
937
|
lastSample: death.termination?.lastSample ?? null,
|
|
528
938
|
promoted,
|
|
529
939
|
idleMs: death.termination?.idleMs ?? null,
|
|
940
|
+
// The postmortem's git facts: the HEAD the dispatch started from and whatever
|
|
941
|
+
// the (possibly crashed) child committed before it died.
|
|
942
|
+
dispatchBase: this.#dispatchBase,
|
|
943
|
+
commitsSince: this.#commitsSince,
|
|
530
944
|
});
|
|
531
|
-
//
|
|
532
|
-
//
|
|
533
|
-
|
|
534
|
-
this.#scene.ledger.incrementContractViolationCount();
|
|
535
|
-
}
|
|
945
|
+
// P22 — the crash record is the postmortem, never a counter write: the soft
|
|
946
|
+
// counter derives from the round records (`Ledger#softViolations`), and a hard
|
|
947
|
+
// crash reads as the round's failed verdict (design spec §3.3).
|
|
536
948
|
}
|
|
537
949
|
/** Build the final carrier — the validated writable fields from the draft (the
|
|
538
950
|
* engine-seated identity rides the canonical file name, never inline: phase/tasks
|
|
539
951
|
* are not declared and never written — v1.30), persisted by the bookkeep
|
|
540
|
-
* full-replace at the SAME path (agent draft → finalized). The
|
|
541
|
-
*
|
|
542
|
-
*
|
|
543
|
-
|
|
952
|
+
* full-replace at the SAME path (agent draft → finalized). The ROUND VERDICT is a
|
|
953
|
+
* separate fact (`#verdictOf`): a hard round fails on its record + exit code, while
|
|
954
|
+
* the carrier keeps the child's own declared status (the engine never rewrites a
|
|
955
|
+
* declaration to encode a judgment). */
|
|
956
|
+
#materialize(frame, plane, draft, status) {
|
|
544
957
|
const ledger = this.#scene.ledger;
|
|
545
958
|
const notes = [];
|
|
546
959
|
// The §8.7 classification ruling — the SAME judgment the read-back validator makes
|
|
@@ -577,13 +990,10 @@ export class CliLifecycle {
|
|
|
577
990
|
const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
|
|
578
991
|
if (plane === "work") {
|
|
579
992
|
carrier.status = status;
|
|
580
|
-
// The
|
|
581
|
-
//
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
carrier.status = "BLOCKED";
|
|
585
|
-
draftNotes.push(reason);
|
|
586
|
-
}
|
|
993
|
+
// The fix dispositions ride the carrier VERBATIM (the child's declaration, never
|
|
994
|
+
// an engine rewrite) — the schema pinned the slot's object shape.
|
|
995
|
+
if (draft.dispositions !== undefined)
|
|
996
|
+
carrier.dispositions = draft.dispositions;
|
|
587
997
|
}
|
|
588
998
|
if (notes.length > 0 || draftNotes.length > 0)
|
|
589
999
|
carrier.notes = [...notes, ...draftNotes];
|
|
@@ -679,21 +1089,27 @@ export class CliLifecycle {
|
|
|
679
1089
|
// engine-injected at dispatch), so no range rides the command.
|
|
680
1090
|
return `cdd review --type branch --plan ${plan}`;
|
|
681
1091
|
case "review":
|
|
682
|
-
if (frame.type === "
|
|
683
|
-
return `cdd review --type
|
|
1092
|
+
if (frame.type === "wave")
|
|
1093
|
+
return `cdd review --type wave --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
|
|
1094
|
+
if (frame.type === "branch")
|
|
1095
|
+
return `cdd review --type branch --plan ${plan}`;
|
|
684
1096
|
if (frame.type === "plan")
|
|
685
1097
|
return `cdd review --type plan --plan ${this.#docOf(frame)}`;
|
|
686
|
-
|
|
1098
|
+
// phase-spec · overall · single-spec — the document under review rides
|
|
1099
|
+
// the retained `--spec` flag.
|
|
1100
|
+
return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
|
|
687
1101
|
case "fix": {
|
|
688
|
-
const findings = scene.ledger.
|
|
689
|
-
const target = frame.target.kind === "plan"
|
|
690
|
-
?
|
|
691
|
-
:
|
|
692
|
-
|
|
693
|
-
//
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
1102
|
+
const findings = scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
|
|
1103
|
+
const target = frame.target.kind === "plan"
|
|
1104
|
+
? `--plan ${frame.target.doc}`
|
|
1105
|
+
: frame.target.kind === "spec"
|
|
1106
|
+
? `--spec ${frame.target.doc}`
|
|
1107
|
+
: // The branch fix carries no refs — the source findings ride the
|
|
1108
|
+
// --reviews handoff; the workspace-identity `--plan` still rides
|
|
1109
|
+
// (the plan is the branch line's identity, zero orchestrator fallback).
|
|
1110
|
+
frame.target.kind === "branch"
|
|
1111
|
+
? `--plan ${plan}`
|
|
1112
|
+
: `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
|
|
697
1113
|
return `cdd fix --type ${frame.type} ${target} --reviews ${findings}`;
|
|
698
1114
|
}
|
|
699
1115
|
}
|
|
@@ -704,3 +1120,4 @@ export class CliLifecycle {
|
|
|
704
1120
|
return frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : "";
|
|
705
1121
|
}
|
|
706
1122
|
}
|
|
1123
|
+
_a = CliLifecycle;
|