@oscaner-skills/cdd-engine 3.0.1 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -1
- package/README.zh-CN.md +10 -2
- package/dist/contract/declare.js +52 -59
- package/dist/contract/doc.js +31 -35
- package/dist/contract/frontmatter.js +10 -13
- package/dist/contract/invariants.js +172 -96
- package/dist/contract/judge.js +6 -3
- package/dist/contract/lint.js +4 -3
- package/dist/contract/project.js +15 -15
- package/dist/face/board-view.js +203 -242
- package/dist/face/capsule.js +18 -10
- package/dist/face/cli.js +170 -60
- package/dist/face/declare.js +5 -6
- package/dist/face/host.js +1 -1
- package/dist/face/lifecycle.js +192 -92
- package/dist/face/preview.js +1 -1
- package/dist/face/termination.js +33 -5
- package/dist/face/words.js +73 -8
- package/dist/infra/doc-roots.js +1 -0
- package/dist/infra/runtime.js +4 -13
- package/dist/infra/slug-index.js +325 -0
- package/dist/infra/workspace.js +3 -76
- package/dist/render/skeleton.js +21 -30
- package/dist/render/templates.js +48 -23
- package/dist/session/handoff-schema.js +84 -72
- package/dist/session/ledger.js +24 -16
- package/dist/session/next.js +1 -1
- package/dist/session/preflight.js +27 -24
- package/dist/session/round-naming.js +2 -2
- package/dist/session/run.js +28 -16
- package/dist/session/wave.js +30 -7
- package/package.json +1 -1
package/dist/face/lifecycle.js
CHANGED
|
@@ -15,12 +15,12 @@
|
|
|
15
15
|
// bare functions.
|
|
16
16
|
import process from "node:process";
|
|
17
17
|
import { printParseErrorCode } from "jsonc-parser";
|
|
18
|
-
import { ConfigLoader } from "../infra/config.js";
|
|
19
18
|
import { TemplateAssembler } from "../render/templates.js";
|
|
20
19
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
21
20
|
import { RoundNaming } from "../session/round-naming.js";
|
|
22
21
|
import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
|
|
23
22
|
import { TerminationPolicy, Terminator, } from "./termination.js";
|
|
23
|
+
import { Words } from "./words.js";
|
|
24
24
|
/** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
|
|
25
25
|
* non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
|
|
26
26
|
* channel; the child's Return is prose, never the round's content). */
|
|
@@ -39,11 +39,14 @@ const STDOUT_TAIL_MAX = 40;
|
|
|
39
39
|
export class CliLifecycle {
|
|
40
40
|
#env;
|
|
41
41
|
#sync;
|
|
42
|
-
#config;
|
|
43
42
|
#template;
|
|
44
43
|
#io;
|
|
45
44
|
#scene;
|
|
46
45
|
#reviews;
|
|
46
|
+
/** The single word table (the promotion WARN wording + its station) — one instance,
|
|
47
|
+
* injected at the composition root, so the lifecycle never re-types a user-facing
|
|
48
|
+
* line. */
|
|
49
|
+
#words;
|
|
47
50
|
/** The round-naming single source (P11 T4) — every prescribed artifact name of a
|
|
48
51
|
* frame derives here (the report/evidence/brief names + the family op), so the
|
|
49
52
|
* lifecycle and the dry-run preview name the same artifacts by one rule. */
|
|
@@ -60,8 +63,8 @@ export class CliLifecycle {
|
|
|
60
63
|
this.#scene = opts.scene;
|
|
61
64
|
this.#naming = new RoundNaming(opts.scene.workspace);
|
|
62
65
|
this.#sync = opts.sync ?? new Terminator();
|
|
63
|
-
this.#config = opts.config ?? new ConfigLoader();
|
|
64
66
|
this.#template = opts.template ?? new TemplateAssembler();
|
|
67
|
+
this.#words = opts.words ?? new Words();
|
|
65
68
|
this.#io = opts.io ?? {
|
|
66
69
|
stdout: (t) => process.stdout.write(t),
|
|
67
70
|
stderr: (t) => process.stderr.write(t),
|
|
@@ -120,7 +123,17 @@ export class CliLifecycle {
|
|
|
120
123
|
// cause. `termination !== null` → the round concludes TIMEOUT (the words table's
|
|
121
124
|
// status is already there), the reason rides the CDD_BLOCKED channel, and the
|
|
122
125
|
// failure face (no `next:` line) follows from the status alone.
|
|
126
|
+
//
|
|
127
|
+
// The ONE promotion exception (D53 Q12's deliberate narrowing): a terminated
|
|
128
|
+
// REVIEW round whose draft already sits on disk — valid against the findings
|
|
129
|
+
// schema and carrying at least one finding — has done its work; its conclusion is
|
|
130
|
+
// derived from the handoff, never from the termination word (termination ⊥
|
|
131
|
+
// conclusion). Every other terminated round keeps the TIMEOUT failure face.
|
|
123
132
|
if (result.termination !== null) {
|
|
133
|
+
const draft = this.#probeDraft(frame);
|
|
134
|
+
if (draft !== null) {
|
|
135
|
+
return this.#promote(frame, draft, result.termination, result);
|
|
136
|
+
}
|
|
124
137
|
return this.#reject(frame, this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params), `child ${cliName} was terminated: ${result.termination.cause}`,
|
|
125
138
|
// the terminated round's OWN death facts — the termination rides whole
|
|
126
139
|
// (cause + last sample), the signalled child's code is null verbatim
|
|
@@ -235,6 +248,13 @@ export class CliLifecycle {
|
|
|
235
248
|
: frame.type === "plan" || frame.type === "branch"
|
|
236
249
|
? this.#rel(scene.specLink ?? "")
|
|
237
250
|
: "",
|
|
251
|
+
// The parent charter of the spec the face reads (INPUT_OVERALL) — the same
|
|
252
|
+
// value condition as INPUT_SPEC, one face (spec = its own `program:`; plan/
|
|
253
|
+
// branch = the same-slug identity doc's `program:`); empty off those faces and
|
|
254
|
+
// when the spec names no program (the assembler drops the empty slot).
|
|
255
|
+
INPUT_OVERALL: frame.type === "spec" || frame.type === "plan" || frame.type === "branch"
|
|
256
|
+
? this.#rel(scene.overallLink ?? "")
|
|
257
|
+
: "",
|
|
238
258
|
// The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
|
|
239
259
|
// from the base artifact at dispatch; empty off those faces (spec/plan reviews
|
|
240
260
|
// carry none, and the empty slot is dropped by the assembler).
|
|
@@ -291,6 +311,57 @@ export class CliLifecycle {
|
|
|
291
311
|
// -------------------------------------------------------------------------
|
|
292
312
|
// the read-back reconstruct (§3.6) — the draft is the round's content
|
|
293
313
|
// -------------------------------------------------------------------------
|
|
314
|
+
/** The ONE draft-read point — the frame's handoff draft read with the lenient
|
|
315
|
+
* child-authored dialect (D39). The reconstruct reports its tri-state outcome;
|
|
316
|
+
* the terminated-round probe only asks "is there a promotable draft?". */
|
|
317
|
+
#readDraft(frame) {
|
|
318
|
+
const op = this.#opOf(frame);
|
|
319
|
+
return this.#scene.workspace.readJsonLenient(this.#scene.ledger.handoffName(op, frame.type, frame.params));
|
|
320
|
+
}
|
|
321
|
+
/** The non-rejecting draft probe of the termination branch — a terminated REVIEW
|
|
322
|
+
* round's draft is promotable iff it exists, parses, passes the judge plane's schema,
|
|
323
|
+
* and carries at least one finding. Returns the validated draft (the promotion
|
|
324
|
+
* then rides the reconstruct's existing validation/persistence/conclusion path) or
|
|
325
|
+
* null (the round keeps the TIMEOUT failure face). It calls no `#reject` and
|
|
326
|
+
* produces no outcome — a probe is a question, never a verdict. Implement/fix
|
|
327
|
+
* rounds are outside the promotion domain (their `op` is not the review family). */
|
|
328
|
+
#probeDraft(frame) {
|
|
329
|
+
const op = this.#opOf(frame);
|
|
330
|
+
if (op !== "review")
|
|
331
|
+
return null;
|
|
332
|
+
const plane = HandoffSchema.planeOf(op);
|
|
333
|
+
const read = this.#readDraft(frame);
|
|
334
|
+
if (read.kind !== "ok")
|
|
335
|
+
return null;
|
|
336
|
+
const draft = read.value;
|
|
337
|
+
if (this.#handoffSchema.violations(plane, draft).length > 0)
|
|
338
|
+
return null;
|
|
339
|
+
const findings = Array.isArray(draft.findings) ? draft.findings : [];
|
|
340
|
+
return findings.length >= 1 ? draft : null;
|
|
341
|
+
}
|
|
342
|
+
/** Promote a terminated review round whose draft is valid and carries findings —
|
|
343
|
+
* the terminal ⊥ conclusion exception (D53 Q12): the conclusion derives from the
|
|
344
|
+
* handoff, never from the termination word. The crash record still lands
|
|
345
|
+
* (`promoted: true`, carrying the termination's `idleMs`/last sample), and the
|
|
346
|
+
* lifecycle emits the ONE `CDD_WARN` line — the CLI layer emits none. The outcome
|
|
347
|
+
* is the ordinary read-back outcome (carrier + findings + derived status) plus the
|
|
348
|
+
* termination fact, so the bookkeep records the round and the route derives
|
|
349
|
+
* normally. */
|
|
350
|
+
#promote(frame, draft, termination, dead) {
|
|
351
|
+
const op = this.#opOf(frame);
|
|
352
|
+
const path = this.#scene.ledger.handoffPath(op, frame.type, frame.params);
|
|
353
|
+
const outcome = this.#reconstruct(frame, draft);
|
|
354
|
+
this.#writeCrash(frame, path, `child was terminated: ${termination.cause}`, { exitCode: dead.code, cause: termination.cause, termination }, true);
|
|
355
|
+
const findings = outcome.findings ?? [];
|
|
356
|
+
const text = this.#words.promotionWarning({
|
|
357
|
+
cause: termination.cause,
|
|
358
|
+
idleMs: termination.idleMs,
|
|
359
|
+
verdict: termination.lastSample?.verdict ?? "none",
|
|
360
|
+
count: findings.length,
|
|
361
|
+
});
|
|
362
|
+
this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
|
|
363
|
+
return { ...outcome, termination };
|
|
364
|
+
}
|
|
294
365
|
/** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
|
|
295
366
|
* content source of truth: read it, validate it against the mode's writable
|
|
296
367
|
* subset (projection ② of session/handoff-schema.ts — the SAME declared objects
|
|
@@ -299,62 +370,77 @@ export class CliLifecycle {
|
|
|
299
370
|
* remains the carrier's single author). A missing or schema-violating draft →
|
|
300
371
|
* BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
|
|
301
372
|
* (on failure, no overwrite — the child's work is never clobbered; resume re-runs the same
|
|
302
|
-
* command, which re-offers the round). The test-evidence file (
|
|
303
|
-
* rounds only) is read back with the same stakes: a missing/violating file
|
|
373
|
+
* command, which re-offers the round). The test-evidence file (work-plane wave /
|
|
374
|
+
* branch rounds only) is read back with the same stakes: a missing/violating file
|
|
304
375
|
* rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
|
|
305
|
-
* bad), the second fix for a prose-only claim.
|
|
306
|
-
|
|
376
|
+
* bad), the second fix for a prose-only claim.
|
|
377
|
+
*
|
|
378
|
+
* `prefetched` is the terminated-review promotion's already-probed draft — the ONE
|
|
379
|
+
* draft parse stays single-sourced (`#readDraft`), and the promotion rides this
|
|
380
|
+
* same validation/persistence/conclusion path rather than a second implementation. */
|
|
381
|
+
#reconstruct(frame, prefetched) {
|
|
307
382
|
const scene = this.#scene;
|
|
308
383
|
const op = this.#opOf(frame);
|
|
309
|
-
const
|
|
384
|
+
const plane = HandoffSchema.planeOf(op);
|
|
310
385
|
const schema = this.#handoffSchema;
|
|
311
386
|
const path = scene.ledger.handoffPath(op, frame.type, frame.params);
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
// is LENIENT (D39): the draft is a child-LLM-authored carrier, and a trailing comma
|
|
316
|
-
// (a routine model slip) must not void the whole round — jsonc-parser tolerates the
|
|
317
|
-
// lenient dialect while a real break (a missing brace, …) still reports malformed.
|
|
318
|
-
const draftRead = scene.workspace.readJsonLenient(scene.ledger.handoffName(op, frame.type, frame.params));
|
|
319
|
-
if (draftRead.kind === "missing") {
|
|
320
|
-
return this.#reject(frame, path, `the handoff draft was not written at ${path}`);
|
|
387
|
+
let draft;
|
|
388
|
+
if (prefetched !== undefined) {
|
|
389
|
+
draft = prefetched;
|
|
321
390
|
}
|
|
322
|
-
|
|
323
|
-
// The
|
|
324
|
-
//
|
|
325
|
-
// "
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
391
|
+
else {
|
|
392
|
+
// The tri-state draft read — a MISSING draft ("never written") and a MALFORMED
|
|
393
|
+
// one (present but unparseable JSON) are different facts: the rejection reports
|
|
394
|
+
// each truly, so a corrupt draft is never misreported as "not written" (D27).
|
|
395
|
+
// The read is LENIENT (D39): the draft is a child-LLM-authored carrier, and a
|
|
396
|
+
// trailing comma (a routine model slip) must not void the whole round —
|
|
397
|
+
// jsonc-parser tolerates the lenient dialect while a real break (a missing
|
|
398
|
+
// brace, …) still reports malformed.
|
|
399
|
+
const draftRead = this.#readDraft(frame);
|
|
400
|
+
if (draftRead.kind === "missing") {
|
|
401
|
+
return this.#reject(frame, path, `the handoff draft was not written at ${path}`, {
|
|
402
|
+
exitCode: 0,
|
|
403
|
+
cause: "handoff-absent",
|
|
404
|
+
termination: null,
|
|
405
|
+
});
|
|
406
|
+
}
|
|
407
|
+
if (draftRead.kind === "malformed") {
|
|
408
|
+
// The lenient face carries the parser's precise error codes (D39) — surface
|
|
409
|
+
// them in the rejection so a genuinely corrupt draft is diagnosable, not just
|
|
410
|
+
// "malformed".
|
|
411
|
+
const codes = (draftRead.errors ?? [])
|
|
412
|
+
.map((error) => printParseErrorCode(error.error))
|
|
413
|
+
.join(", ");
|
|
414
|
+
const detail = codes === "" ? "" : ` (${codes})`;
|
|
415
|
+
return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
|
|
416
|
+
}
|
|
417
|
+
draft = draftRead.value;
|
|
331
418
|
}
|
|
332
|
-
const
|
|
333
|
-
const problems = schema.violations(face, draft);
|
|
419
|
+
const problems = schema.violations(plane, draft);
|
|
334
420
|
if (problems.length > 0) {
|
|
335
|
-
return this.#reject(frame, path, `the handoff draft at ${path} violates the ${
|
|
421
|
+
return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${problems.join("; ")}`);
|
|
336
422
|
}
|
|
337
|
-
// T2 — the
|
|
338
|
-
// own declared required field — rolled up to the conclusion); the work
|
|
339
|
-
// derives its status from the draft's declared status, never the findings
|
|
423
|
+
// T2 — the plane-aware read: the judge plane ALONE reads `draft.findings` (its
|
|
424
|
+
// own declared required field — rolled up to the conclusion); the work plane
|
|
425
|
+
// derives its status from the draft's declared status, never the findings slot
|
|
340
426
|
// (the work writable subset declares no findings field — zero findings read).
|
|
341
427
|
// The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
|
|
342
428
|
// legs read too — the reconstruct never rules a work status by a second path.
|
|
343
|
-
const findings =
|
|
344
|
-
// A validated draft's conclusion is total: the
|
|
345
|
-
// required findings, and the work
|
|
429
|
+
const findings = plane === "judge" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
|
|
430
|
+
// A validated draft's conclusion is total: the judge plane rolls up its own
|
|
431
|
+
// required findings, and the work plane's `status` passed the `required` gate above
|
|
346
432
|
// — so the `?? "BLOCKED"` never fires here (a work draft without a status never
|
|
347
433
|
// reaches this line; the absent→undefined case exists only for on-disk legacy
|
|
348
434
|
// carriers the ledger reads back, never a schema-validated draft).
|
|
349
|
-
let status = schema.conclusionOf(
|
|
435
|
+
let status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
|
|
350
436
|
let reason = null;
|
|
351
|
-
// The evidence gate (v1.9) — the work
|
|
352
|
-
// the canonical `{family-prefix}-{key}-test-evidence.json` under
|
|
353
|
-
// (§3.7 naming: tasks- for the task families, branch- for the branch
|
|
354
|
-
//
|
|
355
|
-
// missing/malformed/schema-violating file rewrites the draft to BLOCKED
|
|
356
|
-
// cause reported truly — the tri-state read, D27).
|
|
357
|
-
if (
|
|
437
|
+
// The evidence gate (v1.9) — the work plane's wave / branch rounds (implement/fix
|
|
438
|
+
// task+branch) write the canonical `{family-prefix}-{key}-test-evidence.json` under
|
|
439
|
+
// the workspace (§3.7 naming: tasks- for the task families, branch- for the branch
|
|
440
|
+
// fix); the doc rounds (review/docs-fix) carry no evidence file. The read-back is
|
|
441
|
+
// REAL — a missing/malformed/schema-violating file rewrites the draft to BLOCKED
|
|
442
|
+
// (each cause reported truly — the tri-state read, D27).
|
|
443
|
+
if (plane === "work" && (frame.type === "wave" || frame.type === "branch")) {
|
|
358
444
|
const evidenceName = this.#naming.evidenceName(frame);
|
|
359
445
|
const evidencePath = scene.workspace.resolve(evidenceName);
|
|
360
446
|
const evidenceRead = scene.workspace.readJson(evidenceName);
|
|
@@ -377,17 +463,18 @@ export class CliLifecycle {
|
|
|
377
463
|
}
|
|
378
464
|
return {
|
|
379
465
|
status,
|
|
380
|
-
findings:
|
|
381
|
-
carrier: this.#materialize(frame,
|
|
466
|
+
findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
|
|
467
|
+
carrier: this.#materialize(frame, plane, draft, status, reason),
|
|
382
468
|
};
|
|
383
469
|
}
|
|
384
470
|
/** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
|
|
385
471
|
* same-command resume's decision source: the attempted handoff + the resume
|
|
386
472
|
* command) + NO carrier (the bookkeep leaves the draft untouched). The crash
|
|
387
|
-
* record carries the caller's REAL death facts: an absent draft
|
|
388
|
-
*
|
|
473
|
+
* record carries the caller's REAL death facts: an absent draft is the
|
|
474
|
+
* `handoff-absent` read-back face (exit 0), a present-but-unqualified draft
|
|
475
|
+
* (malformed JSON / schema) is `contract-violation` (the default), a dead
|
|
389
476
|
* child passes its own exit code + `child-exit`, and a terminated round passes
|
|
390
|
-
* its whole `termination` fact (cause + last sample) — one record shape,
|
|
477
|
+
* its whole `termination` fact (cause + last sample) — one record shape, four
|
|
391
478
|
* truthful callers (the record is the postmortem artifact; a misreported death
|
|
392
479
|
* sends a maintainer hunting the wrong fault).
|
|
393
480
|
*
|
|
@@ -400,8 +487,29 @@ export class CliLifecycle {
|
|
|
400
487
|
cause: "contract-violation",
|
|
401
488
|
termination: null,
|
|
402
489
|
}) {
|
|
403
|
-
this.#
|
|
490
|
+
this.#writeCrash(frame, path, reason, death, false);
|
|
491
|
+
// A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
|
|
492
|
+
// last sample's verdict (the crash record carries the full sample).
|
|
493
|
+
const detail = death.termination === null
|
|
494
|
+
? ""
|
|
495
|
+
: this.#words.terminationDetail({
|
|
496
|
+
idleMs: death.termination.idleMs,
|
|
497
|
+
verdict: death.termination.lastSample?.verdict ?? "none",
|
|
498
|
+
});
|
|
499
|
+
this.#io.stderr(`CDD_BLOCKED: ${reason}${detail}\n`);
|
|
500
|
+
if (death.termination === null)
|
|
501
|
+
return { status: "BLOCKED" };
|
|
502
|
+
return { status: "TIMEOUT", termination: death.termination };
|
|
503
|
+
}
|
|
504
|
+
/** Write the lane's crash record — the postmortem artifact and same-command
|
|
505
|
+
* resume's decision source. One writer serves both the rejection face
|
|
506
|
+
* (`promoted: false`) and the termination branch's promotion (`promoted: true`):
|
|
507
|
+
* the record shape is identical, only the promotion fact differs. */
|
|
508
|
+
#writeCrash(frame, path, reason, death, promoted) {
|
|
404
509
|
const op = this.#opOf(frame);
|
|
510
|
+
// The cause rides the termination fact when one is present (one of the three
|
|
511
|
+
// causes or the `unknown` fallback); without it, the caller's own cause.
|
|
512
|
+
const cause = death.termination?.cause ?? death.cause;
|
|
405
513
|
this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
|
|
406
514
|
exitCode: death.exitCode,
|
|
407
515
|
stderrTail: [reason],
|
|
@@ -410,22 +518,26 @@ export class CliLifecycle {
|
|
|
410
518
|
// shape (never the absolute `handoffPath` syscall form — §2.7).
|
|
411
519
|
attemptedHandoff: this.#rel(path),
|
|
412
520
|
next: this.#resumeOf(frame),
|
|
413
|
-
|
|
414
|
-
// causes or the `unknown` fallback); without it, the caller's own cause.
|
|
415
|
-
cause: death.termination?.cause ?? death.cause,
|
|
521
|
+
cause,
|
|
416
522
|
// The last sample rides WITH the termination (in memory, zero re-read of the
|
|
417
523
|
// heartbeat file) — null on every non-terminated face.
|
|
418
524
|
lastSample: death.termination?.lastSample ?? null,
|
|
525
|
+
promoted,
|
|
526
|
+
idleMs: death.termination?.idleMs ?? null,
|
|
419
527
|
});
|
|
420
|
-
|
|
528
|
+
// P14 — the sole contractViolationCount write seam: observe the FINAL crash
|
|
529
|
+
// cause (termination override wins). Never keyed off status === "BLOCKED".
|
|
530
|
+
if (cause === "handoff-absent" || cause === "contract-violation") {
|
|
531
|
+
this.#scene.ledger.incrementContractViolationCount();
|
|
532
|
+
}
|
|
421
533
|
}
|
|
422
534
|
/** Build the final carrier — the validated writable fields from the draft (the
|
|
423
535
|
* engine-seated identity rides the canonical file name, never inline: phase/tasks
|
|
424
536
|
* are not declared and never written — v1.30), persisted by the bookkeep
|
|
425
537
|
* full-replace at the SAME path (agent draft → finalized). The evidence override
|
|
426
|
-
* rewrites the status to BLOCKED +
|
|
427
|
-
*
|
|
428
|
-
#materialize(frame,
|
|
538
|
+
* rewrites the status to BLOCKED + the reason note (the child's work preserved,
|
|
539
|
+
* marked bad). */
|
|
540
|
+
#materialize(frame, plane, draft, status, reason) {
|
|
429
541
|
const ledger = this.#scene.ledger;
|
|
430
542
|
const notes = [];
|
|
431
543
|
// The §8.7 classification ruling — the SAME judgment the read-back validator makes
|
|
@@ -433,42 +545,40 @@ export class CliLifecycle {
|
|
|
433
545
|
// AT MOST ONE WARN on the carrier's notes (auditable, non-interrupting — replacing
|
|
434
546
|
// the retired "BLOCK + crash-resume + reopen" chain). The engine stays the carrier's
|
|
435
547
|
// single author; a child's stray key is surfaced, not obeyed.
|
|
436
|
-
const dropped = this.#handoffSchema.droppedKeys(
|
|
548
|
+
const dropped = this.#handoffSchema.droppedKeys(plane, draft);
|
|
437
549
|
if (dropped.length > 0) {
|
|
438
550
|
notes.push(`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`);
|
|
439
551
|
}
|
|
440
|
-
// The per-
|
|
552
|
+
// The per-plane carrier — buildHandoff's typed overloads: the judge plane REQUIRES
|
|
441
553
|
// its findings payload (the schema-required field — cli.test pins the review
|
|
442
|
-
// carrier's findings + status), the work
|
|
443
|
-
// (the work writable subset declares no findings field —
|
|
444
|
-
//
|
|
445
|
-
// conclusion (status — a RoundStatus, wider than the carrier's declared union)
|
|
446
|
-
// the engine's extended fields ride the caller's set below.
|
|
447
|
-
const carrier =
|
|
448
|
-
? ledger.buildHandoff("
|
|
554
|
+
// carrier's findings + status), the work plane builds a findings-FREE typed carrier
|
|
555
|
+
// (the work writable subset declares no findings field — a docs-fix draft's residual
|
|
556
|
+
// findings are dropped, never materialized). `Record<string, unknown>` local: the
|
|
557
|
+
// round conclusion (status — a RoundStatus, wider than the carrier's declared union)
|
|
558
|
+
// and the engine's extended fields ride the caller's set below.
|
|
559
|
+
const carrier = plane === "judge"
|
|
560
|
+
? ledger.buildHandoff("judge", {
|
|
449
561
|
artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
|
|
450
562
|
findings: this.#findingsList(draft.findings),
|
|
451
563
|
})
|
|
452
564
|
: ledger.buildHandoff("work", {
|
|
453
565
|
artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
|
|
454
566
|
});
|
|
455
|
-
// The work
|
|
456
|
-
// declared status (the schema enum pinned it to APPROVED | BLOCKED). The
|
|
457
|
-
//
|
|
458
|
-
// (`HandoffSchema.conclusionOf("
|
|
459
|
-
// persisted
|
|
567
|
+
// The work plane ALONE persists the round conclusion — it is the child's own
|
|
568
|
+
// declared status (the schema enum pinned it to APPROVED | BLOCKED). The judge
|
|
569
|
+
// plane holds NO status field: its conclusion is DERIVED at judgment time
|
|
570
|
+
// (`HandoffSchema.conclusionOf("judge", carrier)` → rollup(findings)), so the
|
|
571
|
+
// persisted judge carrier stays the pure declaration plane
|
|
460
572
|
// (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
|
|
461
|
-
// status-free (the judgment
|
|
573
|
+
// status-free (the judgment plane is perpendicular to the input plane · D27).
|
|
462
574
|
const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
|
|
463
|
-
if (
|
|
575
|
+
if (plane === "work") {
|
|
464
576
|
carrier.status = status;
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
//
|
|
468
|
-
// work round's evidence file) rewrites the persisted conclusion to BLOCKED.
|
|
577
|
+
// The evidence-contract override (work-plane wave / branch rounds only — the
|
|
578
|
+
// evidence gate reads that round's evidence file) rewrites the persisted
|
|
579
|
+
// conclusion to BLOCKED.
|
|
469
580
|
if (reason !== null) {
|
|
470
581
|
carrier.status = "BLOCKED";
|
|
471
|
-
carrier.failure_category = "evidence-contract";
|
|
472
582
|
draftNotes.push(reason);
|
|
473
583
|
}
|
|
474
584
|
}
|
|
@@ -526,23 +636,13 @@ export class CliLifecycle {
|
|
|
526
636
|
}
|
|
527
637
|
/** The `## Handoff schema` section value — the mode's writable-subset fence
|
|
528
638
|
* (projection ①; byte-fixed per mode so the prompt's fixed prefix stays
|
|
529
|
-
* cache-friendly). The
|
|
530
|
-
*
|
|
531
|
-
* docs-fix fence only). */
|
|
639
|
+
* cache-friendly). The op-derived plane selects the subset: work → carrier +
|
|
640
|
+
* evidence fence on the wave / branch rounds; judge → the review fence only. */
|
|
532
641
|
#schemaText(frame) {
|
|
533
|
-
const
|
|
534
|
-
const
|
|
535
|
-
const evidence = face === "work";
|
|
642
|
+
const plane = HandoffSchema.planeOf(this.#opOf(frame));
|
|
643
|
+
const evidence = plane === "work" && (frame.type === "wave" || frame.type === "branch");
|
|
536
644
|
const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
|
|
537
|
-
return this.#handoffSchema.schemaText(
|
|
538
|
-
}
|
|
539
|
-
/** The op.type family record — the engine-config handoff namespace single truth
|
|
540
|
-
* (loud on an unknown family: never a second naming table). */
|
|
541
|
-
#familyOf(op, type) {
|
|
542
|
-
const family = this.#config.engineConfig().handoffNamespace.families[`${op}.${type}`];
|
|
543
|
-
if (family === undefined)
|
|
544
|
-
throw new Error(`unknown handoff family: ${op}.${type}`);
|
|
545
|
-
return family;
|
|
645
|
+
return this.#handoffSchema.schemaText(plane, evidence, prefix);
|
|
546
646
|
}
|
|
547
647
|
/** The artifacts field as a string-map (only string values land — non-string rows
|
|
548
648
|
* are dropped, never coerced). */
|
package/dist/face/preview.js
CHANGED
|
@@ -84,7 +84,7 @@ export class Preview {
|
|
|
84
84
|
return this.#rel(this.#scene.planPath ?? "");
|
|
85
85
|
}
|
|
86
86
|
/** The artifacts the round would write — the frame's prescribed output set (the
|
|
87
|
-
* handoff carrier, the round report and the
|
|
87
|
+
* handoff carrier, the round report and the evidence rounds' test evidence), named by
|
|
88
88
|
* the ONE naming source. A slot the frame's family does not consume (a review
|
|
89
89
|
* round prescribes no evidence file) is dropped, never rendered blank. */
|
|
90
90
|
#writesOf(frame) {
|
package/dist/face/termination.js
CHANGED
|
@@ -37,6 +37,12 @@ export class TerminationPolicy {
|
|
|
37
37
|
fix: 3 * 60 * 60 * 1000,
|
|
38
38
|
"branch-review": 3 * 60 * 60 * 1000,
|
|
39
39
|
};
|
|
40
|
+
/** The child's per-command Bash ceiling (ms) — a DISCIPLINE constant, never a
|
|
41
|
+
* phase budget: the child prompt tells the child to put a `timeout` on every
|
|
42
|
+
* Bash invocation, no longer than this. It is deliberately not a `RoundPhase`
|
|
43
|
+
* key (no dispatch phase maps to it) and not an engine-side kill: the engine
|
|
44
|
+
* cannot see commands inside the child. */
|
|
45
|
+
static CHILD_BASH_TIMEOUT_MS = 15 * 60 * 1000;
|
|
40
46
|
/** The stall window (ms) — how long a round may make no progress before the
|
|
41
47
|
* judge rules it stalled (not per phase: "no progress" means the same thing on
|
|
42
48
|
* every phase). */
|
|
@@ -95,6 +101,11 @@ export class StallJudge {
|
|
|
95
101
|
this.#idleWindowMs = idleWindowMs;
|
|
96
102
|
this.#idleSince = spawnedAt;
|
|
97
103
|
}
|
|
104
|
+
/** The idle time (ms) at `now` — how long since the last progress (the spawn instant
|
|
105
|
+
* until the first one). */
|
|
106
|
+
idleMs(now) {
|
|
107
|
+
return Math.max(0, now - this.#idleSince);
|
|
108
|
+
}
|
|
98
109
|
/** Judge one tick: feed the tick's sample and the instant it was taken. */
|
|
99
110
|
observe(sample, now) {
|
|
100
111
|
const cpuMs = sample.groupCpuMs;
|
|
@@ -297,6 +308,10 @@ class SamplingLoop {
|
|
|
297
308
|
lastSample() {
|
|
298
309
|
return this.#last;
|
|
299
310
|
}
|
|
311
|
+
/** The judge's idle reading (ms) at this instant — the termination fact's idle time. */
|
|
312
|
+
idleMs() {
|
|
313
|
+
return this.#judge.idleMs(Date.now());
|
|
314
|
+
}
|
|
300
315
|
/** End the loop at the dispatch's terminal state: the cadence stops, and the
|
|
301
316
|
* heartbeat is removed iff the round ended by itself — a terminated round's file
|
|
302
317
|
* stays for a human's postmortem. */
|
|
@@ -377,10 +392,22 @@ export class Terminator {
|
|
|
377
392
|
cwd: run.cwd,
|
|
378
393
|
reject: false,
|
|
379
394
|
stripFinalNewline: false,
|
|
395
|
+
// fd 0 on /dev/null: a child that reads stdin sees EOF at once, never a pipe nobody closes.
|
|
396
|
+
stdin: "ignore",
|
|
380
397
|
killDescendants: true,
|
|
381
398
|
forceKillAfterDelay: Terminator.FORCE_KILL_AFTER_DELAY_MS,
|
|
382
399
|
timeout: run.policy.budgetMs,
|
|
383
400
|
});
|
|
401
|
+
// Reclaim the group the instant the direct child exits: a grandchild holding the stdout
|
|
402
|
+
// / stderr pipes would otherwise keep the `await` open. No execa option does this (its
|
|
403
|
+
// group kill is on-demand only), so execa's own group-aware `kill()` is called once, at
|
|
404
|
+
// the `exit` event, and only on the group the engine created (`killDescendants`). With
|
|
405
|
+
// live members the pgid is still reserved; with none (no grandchild) the kill is a no-op
|
|
406
|
+
// unless the pgid was reused inside a vanishingly small window. Every ordinary child exit in
|
|
407
|
+
// termination.test.ts (no grandchild) passes through this kill.
|
|
408
|
+
subprocess.nodeChildProcess.once("exit", () => {
|
|
409
|
+
subprocess.kill();
|
|
410
|
+
});
|
|
384
411
|
const sampling = this.#startSampling(run, subprocess.pid, spawnedAt, () => {
|
|
385
412
|
// The engine's own group kill — execa kills the process group and escalates
|
|
386
413
|
// SIGTERM → SIGKILL after the grace. No signal logic of the engine's own.
|
|
@@ -400,6 +427,7 @@ export class Terminator {
|
|
|
400
427
|
killedByStall,
|
|
401
428
|
signal: result.signal,
|
|
402
429
|
isTerminated: result.isTerminated,
|
|
430
|
+
idleMs: sampling?.idleMs() ?? 0,
|
|
403
431
|
lastSample: sampling?.lastSample() ?? null,
|
|
404
432
|
});
|
|
405
433
|
endedByItself = termination === null;
|
|
@@ -468,15 +496,15 @@ export class Terminator {
|
|
|
468
496
|
* signalled and read `stalled` — the idle verdict, not the kill landing, is the
|
|
469
497
|
* criterion. */
|
|
470
498
|
static terminationOf(facts) {
|
|
471
|
-
const { timedOut, killedByStall, signal, isTerminated, lastSample } = facts;
|
|
499
|
+
const { timedOut, killedByStall, signal, isTerminated, idleMs, lastSample } = facts;
|
|
472
500
|
if (timedOut)
|
|
473
|
-
return { cause: "over-budget", lastSample };
|
|
501
|
+
return { cause: "over-budget", idleMs, lastSample };
|
|
474
502
|
if (killedByStall)
|
|
475
|
-
return { cause: "stalled", lastSample };
|
|
503
|
+
return { cause: "stalled", idleMs, lastSample };
|
|
476
504
|
if (signal !== undefined)
|
|
477
|
-
return { cause: "signal", lastSample };
|
|
505
|
+
return { cause: "signal", idleMs, lastSample };
|
|
478
506
|
if (isTerminated)
|
|
479
|
-
return { cause: "unknown", lastSample };
|
|
507
|
+
return { cause: "unknown", idleMs, lastSample };
|
|
480
508
|
return null;
|
|
481
509
|
}
|
|
482
510
|
}
|