@oscaner-skills/cdd-engine 3.0.1 → 3.1.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.
@@ -3,9 +3,14 @@
3
3
  // · next:` word-face steady state). Capsule#emit renders the ALL-OP single stdout
4
4
  // face — the capsule the orchestrator greps / routes on without opening the handoff:
5
5
  //
6
- // status: <status> · blocker: <blocker> · handoff: <handoff>
6
+ // status: <status> · blocker: <blocker> · handoff: <handoff> (success statuses)
7
+ // status: <status> [· handoff: <crash>] (TIMEOUT / BLOCKED)
7
8
  // next: <suggestion> (optional — the C5 route / a caller-rendered text)
8
9
  //
10
+ // The key set is the word table's single source (`Words.capsuleKeys(status,
11
+ // withHandoff)`) — a failure status drops the blocker cell whose value would be a
12
+ // filler, and keeps the handoff cell only when the round wrote a crash record.
13
+ //
9
14
  // The byte face is v1-pinned: the key words (status · blocker · handoff) are
10
15
  // pin-enforced by the CapsuleKey type and the emit signature — a data-only change
11
16
  // cannot reshape them. What rides the injected Words table (the single word-table
@@ -63,14 +68,17 @@ export class Capsule {
63
68
  this.#root = root;
64
69
  this.#route = new RouteRenderer(words, channels, host, root);
65
70
  }
66
- /** emit(status, blocker, handoff, next, target) → the capsule stdout lines: the
67
- * pinned `status · blocker · handoff` capsule line, then the optional `next:`
68
- * line (a caller-rendered text, a C5 Route rendered as the complete executable
69
- * command, or null/absent → no line). The additive optional RouteTarget supplies
70
- * the frame's own type + id + plan for the executable literal (P4.1 T4); without
71
- * it the route renders its bare classifier fallbacks (the 4-param signature stays
72
- * byte-pinned). */
73
- emit(status, blocker, handoff, next, target) {
71
+ /** emit(status, blocker, handoff, next, target, withHandoff) → the capsule stdout
72
+ * lines: the status-class key set from the word table (a success status renders
73
+ * `status · blocker · handoff`; a failure status renders `status`, plus `handoff`
74
+ * only when the round wrote a crash record), then the optional `next:` line (a
75
+ * caller-rendered text, a C5 Route rendered as the complete executable command, or
76
+ * null/absent → no line). The additive optional RouteTarget supplies the frame's
77
+ * own type + id + plan for the executable literal (P4.1 T4); without it the route
78
+ * renders its bare classifier fallbacks (the 4-param signature stays byte-pinned).
79
+ * `withHandoff` is the caller's crash-record fact — the key set remains the table's
80
+ * single source (this render adds no status special case). */
81
+ emit(status, blocker, handoff, next, target, withHandoff = false) {
74
82
  const words = this.#words;
75
83
  // The `handoff:` cell is a path value — normalized to the repoRoot-relative
76
84
  // shape through the ONE value object (D47 · the ONE basis; `handoffPath` sources
@@ -81,7 +89,7 @@ export class Capsule {
81
89
  handoff: this.#rel(handoff),
82
90
  };
83
91
  const capsuleLine = words
84
- .capsuleKeys()
92
+ .capsuleKeys(status, withHandoff)
85
93
  .map((kind) => `${kind}: ${cells[kind]}`)
86
94
  .join(words.capsuleSeparator());
87
95
  const lines = [capsuleLine];
package/dist/face/cli.js CHANGED
@@ -536,11 +536,12 @@ export class Cli {
536
536
  // (dry-run) and rendered every mid-run closure as `next: done` (the per-step
537
537
  // next was already consumed). The ledger-mirrored cursor above + markTerminal
538
538
  // together keep one wave phase per invocation.
539
+ // The timeout counter's call site (§4.2): a round that was cut short lands, the
540
+ // count goes up by one — driven by the termination fact alone, never the status
541
+ // word (the counter's only production writer).
542
+ if (step.termination !== undefined)
543
+ scene.ledger.incrementTimeoutCount();
539
544
  if (lastStatus === "BLOCKED" || lastStatus === "TIMEOUT") {
540
- // The timeout counter's call site (§4.2): a TIMEOUT round lands, the count
541
- // goes up by one — the counter's only production writer.
542
- if (lastStatus === "TIMEOUT")
543
- scene.ledger.incrementTimeoutCount();
544
545
  for (const line of latest)
545
546
  this.#io.stdout(`${line}\n`);
546
547
  return 1;
@@ -579,6 +580,7 @@ export class Cli {
579
580
  config: this.#config,
580
581
  template: this.#template,
581
582
  io: this.#io,
583
+ words: this.#words,
582
584
  scene: {
583
585
  workspace: scene.workspace,
584
586
  ledger: scene.ledger,
package/dist/face/host.js CHANGED
@@ -18,7 +18,7 @@
18
18
  // `/namespace:skill` form; pi the flat `/skill:<bare>` form — the pi flat
19
19
  // namespace has no namespace-qualification syntax).
20
20
  // · HostDetect — the module-level host judgment (the detection's single home):
21
- // the dispatch face's detectHost delegates here; the work face's Capsule wiring
21
+ // the dispatch face's detectHost delegates here; the delivery face's Capsule wiring
22
22
  // reads the same judgment over process.env.
23
23
  //
24
24
  // P5 lands here: the forbidden parallel-sub-agents prose is deleted from the review
@@ -21,6 +21,7 @@ import { HandoffSchema } from "../session/handoff-schema.js";
21
21
  import { RoundNaming } from "../session/round-naming.js";
22
22
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
23
23
  import { TerminationPolicy, Terminator, } from "./termination.js";
24
+ import { Words } from "./words.js";
24
25
  /** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
25
26
  * non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
26
27
  * channel; the child's Return is prose, never the round's content). */
@@ -44,6 +45,10 @@ export class CliLifecycle {
44
45
  #io;
45
46
  #scene;
46
47
  #reviews;
48
+ /** The single word table (the promotion WARN wording + its station) — one instance,
49
+ * injected at the composition root, so the lifecycle never re-types a user-facing
50
+ * line. */
51
+ #words;
47
52
  /** The round-naming single source (P11 T4) — every prescribed artifact name of a
48
53
  * frame derives here (the report/evidence/brief names + the family op), so the
49
54
  * lifecycle and the dry-run preview name the same artifacts by one rule. */
@@ -62,6 +67,7 @@ export class CliLifecycle {
62
67
  this.#sync = opts.sync ?? new Terminator();
63
68
  this.#config = opts.config ?? new ConfigLoader();
64
69
  this.#template = opts.template ?? new TemplateAssembler();
70
+ this.#words = opts.words ?? new Words();
65
71
  this.#io = opts.io ?? {
66
72
  stdout: (t) => process.stdout.write(t),
67
73
  stderr: (t) => process.stderr.write(t),
@@ -120,7 +126,17 @@ export class CliLifecycle {
120
126
  // cause. `termination !== null` → the round concludes TIMEOUT (the words table's
121
127
  // status is already there), the reason rides the CDD_BLOCKED channel, and the
122
128
  // failure face (no `next:` line) follows from the status alone.
129
+ //
130
+ // The ONE promotion exception (D53 Q12's deliberate narrowing): a terminated
131
+ // REVIEW round whose draft already sits on disk — valid against the findings
132
+ // schema and carrying at least one finding — has done its work; its conclusion is
133
+ // derived from the handoff, never from the termination word (termination ⊥
134
+ // conclusion). Every other terminated round keeps the TIMEOUT failure face.
123
135
  if (result.termination !== null) {
136
+ const draft = this.#probeDraft(frame);
137
+ if (draft !== null) {
138
+ return this.#promote(frame, draft, result.termination, result);
139
+ }
124
140
  return this.#reject(frame, this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params), `child ${cliName} was terminated: ${result.termination.cause}`,
125
141
  // the terminated round's OWN death facts — the termination rides whole
126
142
  // (cause + last sample), the signalled child's code is null verbatim
@@ -291,6 +307,59 @@ export class CliLifecycle {
291
307
  // -------------------------------------------------------------------------
292
308
  // the read-back reconstruct (§3.6) — the draft is the round's content
293
309
  // -------------------------------------------------------------------------
310
+ /** The ONE draft-read point — the frame's handoff draft read with the lenient
311
+ * child-authored dialect (D39). The reconstruct reports its tri-state outcome;
312
+ * the terminated-round probe only asks "is there a promotable draft?". */
313
+ #readDraft(frame) {
314
+ const op = this.#opOf(frame);
315
+ return this.#scene.workspace.readJsonLenient(this.#scene.ledger.handoffName(op, frame.type, frame.params));
316
+ }
317
+ /** The non-rejecting draft probe of the termination branch — a terminated REVIEW
318
+ * round's draft is promotable iff it exists, parses, passes the findings schema,
319
+ * and carries at least one finding. Returns the validated draft (the promotion
320
+ * then rides the reconstruct's existing validation/persistence/conclusion path) or
321
+ * null (the round keeps the TIMEOUT failure face). It calls no `#reject` and
322
+ * produces no outcome — a probe is a question, never a verdict. Implement/fix
323
+ * rounds are outside the promotion domain (their `op` is not the review family). */
324
+ #probeDraft(frame) {
325
+ const op = this.#opOf(frame);
326
+ if (op !== "review")
327
+ return null;
328
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
329
+ if (face !== "findings")
330
+ return null;
331
+ const read = this.#readDraft(frame);
332
+ if (read.kind !== "ok")
333
+ return null;
334
+ const draft = read.value;
335
+ if (this.#handoffSchema.violations(face, draft).length > 0)
336
+ return null;
337
+ const findings = Array.isArray(draft.findings) ? draft.findings : [];
338
+ return findings.length >= 1 ? draft : null;
339
+ }
340
+ /** Promote a terminated review round whose draft is valid and carries findings —
341
+ * the terminal ⊥ conclusion exception (D53 Q12): the conclusion derives from the
342
+ * handoff, never from the termination word. The crash record still lands
343
+ * (`promoted: true`, carrying the termination's `idleMs`/last sample), and the
344
+ * lifecycle emits the ONE `CDD_WARN` line — the CLI layer emits none. The outcome
345
+ * is the ordinary read-back outcome (carrier + findings + derived status) plus the
346
+ * termination fact, so the bookkeep records the round and the route derives
347
+ * normally. */
348
+ #promote(frame, draft, termination, dead) {
349
+ const op = this.#opOf(frame);
350
+ const path = this.#scene.ledger.handoffPath(op, frame.type, frame.params);
351
+ const outcome = this.#reconstruct(frame, draft);
352
+ this.#writeCrash(frame, path, `child was terminated: ${termination.cause}`, { exitCode: dead.code, cause: termination.cause, termination }, true);
353
+ const findings = outcome.findings ?? [];
354
+ const text = this.#words.promotionWarning({
355
+ cause: termination.cause,
356
+ idleMs: termination.idleMs,
357
+ verdict: termination.lastSample?.verdict ?? "none",
358
+ count: findings.length,
359
+ });
360
+ this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
361
+ return { ...outcome, termination };
362
+ }
294
363
  /** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
295
364
  * content source of truth: read it, validate it against the mode's writable
296
365
  * subset (projection ② of session/handoff-schema.ts — the SAME declared objects
@@ -299,62 +368,73 @@ export class CliLifecycle {
299
368
  * remains the carrier's single author). A missing or schema-violating draft →
300
369
  * BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
301
370
  * (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 (task-family work
371
+ * command, which re-offers the round). The test-evidence file (task-family delivery
303
372
  * rounds only) is read back with the same stakes: a missing/violating file
304
373
  * rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
305
- * bad), the second fix for a prose-only claim. */
306
- #reconstruct(frame) {
374
+ * bad), the second fix for a prose-only claim.
375
+ *
376
+ * `prefetched` is the terminated-review promotion's already-probed draft — the ONE
377
+ * draft parse stays single-sourced (`#readDraft`), and the promotion rides this
378
+ * same validation/persistence/conclusion path rather than a second implementation. */
379
+ #reconstruct(frame, prefetched) {
307
380
  const scene = this.#scene;
308
381
  const op = this.#opOf(frame);
309
- const face = this.#familyOf(op, frame.type).schema ?? "work";
382
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
310
383
  const schema = this.#handoffSchema;
311
384
  const path = scene.ledger.handoffPath(op, frame.type, frame.params);
312
- // The tri-state draft read — a MISSING draft ("never written") and a MALFORMED one
313
- // (present but unparseable JSON) are different facts: the rejection reports each
314
- // truly, so a corrupt draft is never misreported as "not written" (D27). The read
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}`);
385
+ let draft;
386
+ if (prefetched !== undefined) {
387
+ draft = prefetched;
321
388
  }
322
- if (draftRead.kind === "malformed") {
323
- // The lenient face carries the parser's precise error codes (D39) — surface
324
- // them in the rejection so a genuinely corrupt draft is diagnosable, not just
325
- // "malformed".
326
- const codes = (draftRead.errors ?? [])
327
- .map((error) => printParseErrorCode(error.error))
328
- .join(", ");
329
- const detail = codes === "" ? "" : ` (${codes})`;
330
- return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
389
+ else {
390
+ // The tri-state draft read — a MISSING draft ("never written") and a MALFORMED
391
+ // one (present but unparseable JSON) are different facts: the rejection reports
392
+ // each truly, so a corrupt draft is never misreported as "not written" (D27).
393
+ // The read is LENIENT (D39): the draft is a child-LLM-authored carrier, and a
394
+ // trailing comma (a routine model slip) must not void the whole round —
395
+ // jsonc-parser tolerates the lenient dialect while a real break (a missing
396
+ // brace, …) still reports malformed.
397
+ const draftRead = this.#readDraft(frame);
398
+ if (draftRead.kind === "missing") {
399
+ return this.#reject(frame, path, `the handoff draft was not written at ${path}`);
400
+ }
401
+ if (draftRead.kind === "malformed") {
402
+ // The lenient face carries the parser's precise error codes (D39) — surface
403
+ // them in the rejection so a genuinely corrupt draft is diagnosable, not just
404
+ // "malformed".
405
+ const codes = (draftRead.errors ?? [])
406
+ .map((error) => printParseErrorCode(error.error))
407
+ .join(", ");
408
+ const detail = codes === "" ? "" : ` (${codes})`;
409
+ return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
410
+ }
411
+ draft = draftRead.value;
331
412
  }
332
- const draft = draftRead.value;
333
413
  const problems = schema.violations(face, draft);
334
414
  if (problems.length > 0) {
335
415
  return this.#reject(frame, path, `the handoff draft at ${path} violates the ${face} schema: ${problems.join("; ")}`);
336
416
  }
337
417
  // T2 — the face-aware read: the findings face ALONE reads `draft.findings` (its
338
- // own declared required field — rolled up to the conclusion); the work face
418
+ // own declared required field — rolled up to the conclusion); the delivery face
339
419
  // derives its status from the draft's declared status, never the findings plane
340
- // (the work writable subset declares no findings field — zero findings read).
420
+ // (the delivery writable subset declares no findings field — zero findings read).
341
421
  // The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
342
- // legs read too — the reconstruct never rules a work status by a second path.
422
+ // legs read too — the reconstruct never rules a delivery status by a second path.
343
423
  const findings = face === "findings" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
344
424
  // A validated draft's conclusion is total: the findings face rolls up its own
345
- // required findings, and the work face's `status` passed the `required` gate above
346
- // — so the `?? "BLOCKED"` never fires here (a work draft without a status never
425
+ // required findings, and the delivery face's `status` passed the `required` gate above
426
+ // — so the `?? "BLOCKED"` never fires here (a delivery draft without a status never
347
427
  // reaches this line; the absent→undefined case exists only for on-disk legacy
348
428
  // carriers the ledger reads back, never a schema-validated draft).
349
429
  let status = schema.conclusionOf(face, draft) ?? "BLOCKED";
350
430
  let reason = null;
351
- // The evidence gate (v1.9) — the work faces (implement/fix task+branch) write
431
+ // The evidence gate (v1.9) — the delivery faces (implement/fix task+branch) write
352
432
  // the canonical `{family-prefix}-{key}-test-evidence.json` under the workspace
353
433
  // (§3.7 naming: tasks- for the task families, branch- for the branch fix); the
354
434
  // docs faces (review/docs-fix) carry no evidence file. The read-back is REAL — a
355
435
  // missing/malformed/schema-violating file rewrites the draft to BLOCKED (each
356
436
  // cause reported truly — the tri-state read, D27).
357
- if (face === "work") {
437
+ if (face === "delivery") {
358
438
  const evidenceName = this.#naming.evidenceName(frame);
359
439
  const evidencePath = scene.workspace.resolve(evidenceName);
360
440
  const evidenceRead = scene.workspace.readJson(evidenceName);
@@ -400,7 +480,25 @@ export class CliLifecycle {
400
480
  cause: "contract-violation",
401
481
  termination: null,
402
482
  }) {
403
- this.#io.stderr(`CDD_BLOCKED: ${reason}\n`);
483
+ this.#writeCrash(frame, path, reason, death, false);
484
+ // A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
485
+ // last sample's verdict (the crash record carries the full sample).
486
+ const detail = death.termination === null
487
+ ? ""
488
+ : this.#words.terminationDetail({
489
+ idleMs: death.termination.idleMs,
490
+ verdict: death.termination.lastSample?.verdict ?? "none",
491
+ });
492
+ this.#io.stderr(`CDD_BLOCKED: ${reason}${detail}\n`);
493
+ if (death.termination === null)
494
+ return { status: "BLOCKED" };
495
+ return { status: "TIMEOUT", termination: death.termination };
496
+ }
497
+ /** Write the lane's crash record — the postmortem artifact and same-command
498
+ * resume's decision source. One writer serves both the rejection face
499
+ * (`promoted: false`) and the termination branch's promotion (`promoted: true`):
500
+ * the record shape is identical, only the promotion fact differs. */
501
+ #writeCrash(frame, path, reason, death, promoted) {
404
502
  const op = this.#opOf(frame);
405
503
  this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
406
504
  exitCode: death.exitCode,
@@ -416,8 +514,9 @@ export class CliLifecycle {
416
514
  // The last sample rides WITH the termination (in memory, zero re-read of the
417
515
  // heartbeat file) — null on every non-terminated face.
418
516
  lastSample: death.termination?.lastSample ?? null,
517
+ promoted,
518
+ idleMs: death.termination?.idleMs ?? null,
419
519
  });
420
- return { status: death.termination === null ? "BLOCKED" : "TIMEOUT" };
421
520
  }
422
521
  /** Build the final carrier — the validated writable fields from the draft (the
423
522
  * engine-seated identity rides the canonical file name, never inline: phase/tasks
@@ -439,8 +538,8 @@ export class CliLifecycle {
439
538
  }
440
539
  // The per-face carrier — buildHandoff's typed overloads: the findings face REQUIRES
441
540
  // its findings payload (the schema-required field — cli.test pins the review
442
- // carrier's findings + status), the work face builds a findings-FREE typed carrier
443
- // (the work writable subset declares no findings field — the materialized work
541
+ // carrier's findings + status), the delivery face builds a findings-FREE typed carrier
542
+ // (the delivery writable subset declares no findings field — the materialized delivery
444
543
  // carrier carries zero findings keys). `Record<string, unknown>` local: the round
445
544
  // conclusion (status — a RoundStatus, wider than the carrier's declared union) and
446
545
  // the engine's extended fields ride the caller's set below.
@@ -449,10 +548,10 @@ export class CliLifecycle {
449
548
  artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
450
549
  findings: this.#findingsList(draft.findings),
451
550
  })
452
- : ledger.buildHandoff("work", {
551
+ : ledger.buildHandoff("delivery", {
453
552
  artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
454
553
  });
455
- // The work face ALONE persists the round conclusion — it is the child's own
554
+ // The delivery face ALONE persists the round conclusion — it is the child's own
456
555
  // declared status (the schema enum pinned it to APPROVED | BLOCKED). The findings
457
556
  // face holds NO status field: its conclusion is DERIVED at judgment time
458
557
  // (`HandoffSchema.conclusionOf("findings", carrier)` → rollup(findings)), so the
@@ -460,12 +559,12 @@ export class CliLifecycle {
460
559
  // (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
461
560
  // status-free (the judgment face is perpendicular to the input face · D27).
462
561
  const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
463
- if (face === "work") {
562
+ if (face === "delivery") {
464
563
  carrier.status = status;
465
564
  if (typeof draft.failure_category === "string")
466
565
  carrier.failure_category = draft.failure_category;
467
- // The evidence-contract override (work faces only — the evidence gate reads a
468
- // work round's evidence file) rewrites the persisted conclusion to BLOCKED.
566
+ // The evidence-contract override (delivery faces only — the evidence gate reads a
567
+ // delivery round's evidence file) rewrites the persisted conclusion to BLOCKED.
469
568
  if (reason !== null) {
470
569
  carrier.status = "BLOCKED";
471
570
  carrier.failure_category = "evidence-contract";
@@ -526,13 +625,13 @@ export class CliLifecycle {
526
625
  }
527
626
  /** The `## Handoff schema` section value — the mode's writable-subset fence
528
627
  * (projection ①; byte-fixed per mode so the prompt's fixed prefix stays
529
- * cache-friendly). The family's `schema` field selects the face (§3.6: work →
628
+ * cache-friendly). The family's `schema` field selects the face (§3.6: delivery →
530
629
  * carrier + evidence fence for the implement/fix modes; findings → the review /
531
630
  * docs-fix fence only). */
532
631
  #schemaText(frame) {
533
632
  const op = this.#opOf(frame);
534
- const face = this.#familyOf(op, frame.type).schema ?? "work";
535
- const evidence = face === "work";
633
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
634
+ const evidence = face === "delivery";
536
635
  const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
537
636
  return this.#handoffSchema.schemaText(face, evidence, prefix);
538
637
  }
@@ -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 work faces' test evidence), named by
87
+ * handoff carrier, the round report and the delivery faces' 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) {
@@ -95,6 +95,11 @@ export class StallJudge {
95
95
  this.#idleWindowMs = idleWindowMs;
96
96
  this.#idleSince = spawnedAt;
97
97
  }
98
+ /** The idle time (ms) at `now` — how long since the last progress (the spawn instant
99
+ * until the first one). */
100
+ idleMs(now) {
101
+ return Math.max(0, now - this.#idleSince);
102
+ }
98
103
  /** Judge one tick: feed the tick's sample and the instant it was taken. */
99
104
  observe(sample, now) {
100
105
  const cpuMs = sample.groupCpuMs;
@@ -297,6 +302,10 @@ class SamplingLoop {
297
302
  lastSample() {
298
303
  return this.#last;
299
304
  }
305
+ /** The judge's idle reading (ms) at this instant — the termination fact's idle time. */
306
+ idleMs() {
307
+ return this.#judge.idleMs(Date.now());
308
+ }
300
309
  /** End the loop at the dispatch's terminal state: the cadence stops, and the
301
310
  * heartbeat is removed iff the round ended by itself — a terminated round's file
302
311
  * stays for a human's postmortem. */
@@ -377,10 +386,22 @@ export class Terminator {
377
386
  cwd: run.cwd,
378
387
  reject: false,
379
388
  stripFinalNewline: false,
389
+ // fd 0 on /dev/null: a child that reads stdin sees EOF at once, never a pipe nobody closes.
390
+ stdin: "ignore",
380
391
  killDescendants: true,
381
392
  forceKillAfterDelay: Terminator.FORCE_KILL_AFTER_DELAY_MS,
382
393
  timeout: run.policy.budgetMs,
383
394
  });
395
+ // Reclaim the group the instant the direct child exits: a grandchild holding the stdout
396
+ // / stderr pipes would otherwise keep the `await` open. No execa option does this (its
397
+ // group kill is on-demand only), so execa's own group-aware `kill()` is called once, at
398
+ // the `exit` event, and only on the group the engine created (`killDescendants`). With
399
+ // live members the pgid is still reserved; with none (no grandchild) the kill is a no-op
400
+ // unless the pgid was reused inside a vanishingly small window. Every ordinary child exit in
401
+ // termination.test.ts (no grandchild) passes through this kill.
402
+ subprocess.nodeChildProcess.once("exit", () => {
403
+ subprocess.kill();
404
+ });
384
405
  const sampling = this.#startSampling(run, subprocess.pid, spawnedAt, () => {
385
406
  // The engine's own group kill — execa kills the process group and escalates
386
407
  // SIGTERM → SIGKILL after the grace. No signal logic of the engine's own.
@@ -400,6 +421,7 @@ export class Terminator {
400
421
  killedByStall,
401
422
  signal: result.signal,
402
423
  isTerminated: result.isTerminated,
424
+ idleMs: sampling?.idleMs() ?? 0,
403
425
  lastSample: sampling?.lastSample() ?? null,
404
426
  });
405
427
  endedByItself = termination === null;
@@ -468,15 +490,15 @@ export class Terminator {
468
490
  * signalled and read `stalled` — the idle verdict, not the kill landing, is the
469
491
  * criterion. */
470
492
  static terminationOf(facts) {
471
- const { timedOut, killedByStall, signal, isTerminated, lastSample } = facts;
493
+ const { timedOut, killedByStall, signal, isTerminated, idleMs, lastSample } = facts;
472
494
  if (timedOut)
473
- return { cause: "over-budget", lastSample };
495
+ return { cause: "over-budget", idleMs, lastSample };
474
496
  if (killedByStall)
475
- return { cause: "stalled", lastSample };
497
+ return { cause: "stalled", idleMs, lastSample };
476
498
  if (signal !== undefined)
477
- return { cause: "signal", lastSample };
499
+ return { cause: "signal", idleMs, lastSample };
478
500
  if (isTerminated)
479
- return { cause: "unknown", lastSample };
501
+ return { cause: "unknown", idleMs, lastSample };
480
502
  return null;
481
503
  }
482
504
  }
@@ -32,8 +32,17 @@
32
32
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
33
33
  /** The capsule word rows — every word the capsule face emits, one table. */
34
34
  export const CAPSULE_WORDS = {
35
- /** The capsule emit keys in order (a reorder is a red test — the pinned face). */
36
- keys: ["status", "blocker", "handoff"],
35
+ /** The capsule emit key rows — one declaration per status class (the summary
36
+ * face's key-set single source; a reorder is a red test — the pinned face).
37
+ * A success status renders `status · blocker · handoff`; a failure status renders
38
+ * `status` alone, plus `handoff` only when the round wrote a crash record. */
39
+ keys: {
40
+ success: ["status", "blocker", "handoff"],
41
+ failure: ["status"],
42
+ handoff: "handoff",
43
+ },
44
+ /** The failure status vocabulary — the reduced summary-key class (TIMEOUT / BLOCKED). */
45
+ failureStatuses: ["BLOCKED", "TIMEOUT"],
37
46
  /** The `·`-separator token of the capsule line. */
38
47
  separator: " · ",
39
48
  /** The status vocabulary — the five handoff-conclusion values. */
@@ -67,6 +76,13 @@ export const CAPSULE_WORDS = {
67
76
  graph: "the plan graph has {count} edge violation(s) — fix the **DependsOn** edges first",
68
77
  docContract: "the target document fails the doc-contract — fix its structural findings first",
69
78
  },
79
+ /** The terminated-review promotion warning — the one CDD_WARN wording row the
80
+ * lifecycle emits when a terminated review round's valid findings draft is
81
+ * promoted. The braces are fill slots ({cause} / {idleMs} / {verdict} / {count}). */
82
+ promotionWarning: "terminated review round promoted from its handoff draft — cause: {cause}, idleMs: {idleMs}, last sample verdict: {verdict}, findings recovered: {count}",
83
+ /** The terminated-round diagnostic suffix — appended to the one CDD_BLOCKED reason
84
+ * line of a non-promoted terminated round. Fill slots: {idleMs} / {verdict}. */
85
+ terminationDetail: " — idleMs: {idleMs}, last sample verdict: {verdict}",
70
86
  };
71
87
  /** The guard-ban vocabulary — the STALE / GATE / shape ban rows the guards assert
72
88
  * absent from the live faces (the single-source ban table; the guard scan releases
@@ -153,10 +169,16 @@ export class Words {
153
169
  // -------------------------------------------------------------------------
154
170
  // capsule — the station-word family
155
171
  // -------------------------------------------------------------------------
156
- /** The capsule emit keys in order — status · blocker · handoff (the pinned byte
157
- * order the capsule renders by). */
158
- capsuleKeys() {
159
- return CAPSULE_WORDS.keys;
172
+ /** The capsule emit keys of one status class, in the pinned byte order — the key
173
+ * set's single source. A success status renders `status · blocker · handoff`; a
174
+ * failure status (TIMEOUT / BLOCKED) renders `status`, plus `handoff` only when
175
+ * the round wrote a crash record (`withHandoff`). */
176
+ capsuleKeys(status, withHandoff) {
177
+ const rows = CAPSULE_WORDS.keys;
178
+ const failure = CAPSULE_WORDS.failureStatuses.includes(status);
179
+ if (!failure)
180
+ return rows.success;
181
+ return withHandoff ? [...rows.failure, rows.handoff] : rows.failure;
160
182
  }
161
183
  /** The `·`-separator token of the capsule line. */
162
184
  capsuleSeparator() {
@@ -184,6 +206,22 @@ export class Words {
184
206
  preflightWords() {
185
207
  return CAPSULE_WORDS.preflight;
186
208
  }
209
+ /** The terminated-review promotion warning, rendered from the termination facts —
210
+ * the single source of both the wording row and its slot names. */
211
+ promotionWarning(facts) {
212
+ return CAPSULE_WORDS.promotionWarning
213
+ .replace("{cause}", facts.cause)
214
+ .replace("{idleMs}", String(facts.idleMs))
215
+ .replace("{verdict}", facts.verdict)
216
+ .replace("{count}", String(facts.count));
217
+ }
218
+ /** The terminated-round diagnostic suffix, rendered from the termination facts —
219
+ * idle time plus the last sample's verdict (`none` when no sample was taken). */
220
+ terminationDetail(facts) {
221
+ return CAPSULE_WORDS.terminationDetail
222
+ .replace("{idleMs}", String(facts.idleMs))
223
+ .replace("{verdict}", facts.verdict);
224
+ }
187
225
  // -------------------------------------------------------------------------
188
226
  // locale — the word-table locale face (the langs projection + the label rows)
189
227
  // -------------------------------------------------------------------------
@@ -28,12 +28,12 @@ import { ENGINE_DOC_ROOTS } from "./doc-roots.js";
28
28
  * keyed by `op.type` (implement.wave / review.wave / … — the ledger's single
29
29
  * naming truth, verbatim from the engine-config handoff namespace). The v1.9
30
30
  * reparametrization: `returnFormat` is gone (RETURN_PROSE is the one return
31
- * contract) and the `schema` faces are the handoff-schema selector (work / findings —
32
- * §3.6, session/handoff-schema.ts). */
31
+ * contract) and the `schema` faces are the handoff-schema selector (delivery / findings —
32
+ * session/handoff-schema.ts). */
33
33
  export const HANDOFF_FAMILIES = {
34
34
  "implement.wave": {
35
35
  name: "tasks-{tasks}-implement.json",
36
- schema: "work",
36
+ schema: "delivery",
37
37
  },
38
38
  "review.wave": {
39
39
  name: "tasks-{tasks}-review-{round}.json",
@@ -41,7 +41,7 @@ export const HANDOFF_FAMILIES = {
41
41
  },
42
42
  "fix.wave": {
43
43
  name: "tasks-{tasks}-fix-{round}.json",
44
- schema: "work",
44
+ schema: "delivery",
45
45
  },
46
46
  "review.spec": {
47
47
  name: "spec-review-{round}.json",
@@ -68,7 +68,7 @@ export const HANDOFF_FAMILIES = {
68
68
  },
69
69
  "fix.branch": {
70
70
  name: "branch-fix-{round}.json",
71
- schema: "work",
71
+ schema: "delivery",
72
72
  },
73
73
  };
74
74
  /** The engine runtime — the typed engine-config surface, one constant (the argv
@@ -104,7 +104,7 @@ const FIX_SHELL = [
104
104
  "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the plan/branch lines — the plan document; `INPUT_SPEC` on the spec line — the spec document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
105
105
  EVIDENCE_ITEM,
106
106
  ...LICENSE_ITEMS,
107
- // T5 (v0.3) — The work face's ONE strict-schema sentence: every top-level draft
107
+ // T5 (v0.3) — The delivery face's ONE strict-schema sentence: every top-level draft
108
108
  // field comes from the `## Handoff schema` declared properties (the fields'
109
109
  // single source is the injected fence below — never a second enumeration in the
110
110
  // shell prose; a fix child that mirrors the source review carrier's top-level
@@ -10,7 +10,7 @@
10
10
  // evidenceViolations — the child draft is validated against exactly the same
11
11
  // declared objects the prompt showed it).
12
12
  // · faces: the per-family `schema` field of the handoff families (infra/runtime.ts)
13
- // selects the face — `work` (implement/fix: status+artifacts, plus the separate
13
+ // selects the face — `delivery` (implement/fix: status+artifacts, plus the separate
14
14
  // test-evidence file for task-family rounds) or `findings` (reviews: findings-only
15
15
  // carrier — the engine rolls the status up from the findings, never a
16
16
  // child-authored status).
@@ -41,13 +41,13 @@ const FINDING = {
41
41
  fix: { type: "string" },
42
42
  },
43
43
  };
44
- /** The `work` writable subset — implement/fix carrier. `status` and `artifacts` are
44
+ /** The `delivery` writable subset — implement/fix carrier. `status` and `artifacts` are
45
45
  * the round's required core; notes rides the declared optional field. Reserved
46
46
  * fields (phase · tasks) are NOT declared and are DROPPED by materialize (never a
47
47
  * BLOCK) — the engine stays the carrier's single author.
48
48
  * `as const` preserves the literal property keys — the carrier type family
49
49
  * (`CarrierOf<F>` below) derives its field set FROM these declared keys. */
50
- const CARRIER_WORK = {
50
+ const CARRIER_DELIVERY = {
51
51
  type: "object",
52
52
  required: ["status", "artifacts"],
53
53
  properties: {
@@ -61,7 +61,7 @@ const CARRIER_WORK = {
61
61
  * conclusion is derived from the findings at judgment time
62
62
  * (`conclusionOf("findings", carrier)` → `rollup(findings)`), never a carrier field
63
63
  * the child authors or the engine persists — the declaration plane IS the writable
64
- * plane (one face, one field set). `as const` — see CARRIER_WORK. */
64
+ * plane (one face, one field set). `as const` — see CARRIER_DELIVERY. */
65
65
  const CARRIER_FINDINGS = {
66
66
  type: "object",
67
67
  required: ["findings"],
@@ -100,7 +100,7 @@ const EVIDENCE = {
100
100
  * family's `[K in keyof (typeof BY_FACE)[F]["properties"]]` derives its field set from
101
101
  * exactly these tables, so a schema edit reshapes the carrier types by construction. */
102
102
  const BY_FACE = {
103
- work: CARRIER_WORK,
103
+ delivery: CARRIER_DELIVERY,
104
104
  findings: CARRIER_FINDINGS,
105
105
  };
106
106
  /**
@@ -112,7 +112,7 @@ const BY_FACE = {
112
112
  */
113
113
  export class HandoffSchema {
114
114
  /** Projection ① — the `## Handoff schema` section text: the face's writable
115
- * subset in a ```json fence + (work faces) the evidence file's schema in a second
115
+ * subset in a ```json fence + (delivery faces) the evidence file's schema in a second
116
116
  * fence. The text is byte-stable per (face, evidence, prefix) — the fixed bytes
117
117
  * of the dispatch prompt's contract surface. The evidence prefix is the family
118
118
  * spine (§3.7 naming: `tasks-` for the task families, `branch-` for the branch
@@ -149,14 +149,14 @@ export class HandoffSchema {
149
149
  * single source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
150
150
  * The findings face rolls its conclusion UP from its findings (defined for every
151
151
  * carrier — a review never carries a child-authored status, and the persisted
152
- * findings carrier holds none). The work face reads its DECLARED status, and the
152
+ * findings carrier holds none). The delivery face reads its DECLARED status, and the
153
153
  * absence of a declaration is itself a fact: an ABSENT status → `undefined` (no
154
154
  * conclusion was declared — never an invented approval OR an invented failure ·
155
155
  * D27 present-facts-only), while a PRESENT-but-invalid byte (outside the enum the
156
156
  * schema pinned) degrades to BLOCKED — the conservative reading of a malformed
157
157
  * declaration. `undefined` is DISTINCT from BLOCKED to the caller (the router
158
158
  * treats undefined as "not a failure", a declared BLOCKED as the failure face), so
159
- * a work carrier that predates the status field never reads as a fabricated
159
+ * a delivery carrier that predates the status field never reads as a fabricated
160
160
  * failure. `carrier` is the on-disk carrier (or a freshly built one) — the
161
161
  * conclusion is never a stored field, so any face's carrier derives it the same way. */
162
162
  conclusionOf(face, carrier) {
@@ -164,7 +164,7 @@ export class HandoffSchema {
164
164
  const findings = Array.isArray(carrier.findings) ? carrier.findings : [];
165
165
  return this.rollup(findings);
166
166
  }
167
- // The work face reads its DECLARED status. Absent → undefined (no declaration);
167
+ // The delivery face reads its DECLARED status. Absent → undefined (no declaration);
168
168
  // present-but-invalid → BLOCKED (a declared conclusion that is malformed is a
169
169
  // failure signal, never silently approved). This is the ONE ruling for a work
170
170
  // status: the reconstruct's work leg delegates here, so the read-back and the
@@ -585,10 +585,10 @@ export class Ledger {
585
585
  }
586
586
  /** The handoff FACE of an op/type pair — the family's `schema` selector (work when
587
587
  * the family declares none). The face-aware read/write/bookkeep spine (T2): a
588
- * findings-face round rides the findings writable subset, a work-face round rides
588
+ * findings-face round rides the findings writable subset, a delivery-face round rides
589
589
  * the findings-free work subset — never the caller's guess. */
590
590
  handoffFaceOf(op, type) {
591
- return this.#family(op, type).schema ?? "work";
591
+ return this.#family(op, type).schema ?? "delivery";
592
592
  }
593
593
  /** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
594
594
  handoffName(op, type, params = {}) {
@@ -750,7 +750,7 @@ export class Ledger {
750
750
  return {
751
751
  phase: "fix",
752
752
  // The fix round's conclusion derives from ITS OWN carrier's declared plane (the
753
- // work face reads its status; a docs-fix findings face rolls its findings up) —
753
+ // delivery face reads its status; a docs-fix findings face rolls its findings up) —
754
754
  // the same `conclusionOf` single source (D27).
755
755
  status: this.#handoffSchema.conclusionOf(this.handoffFaceOf("fix", type), fixCarrier),
756
756
  findings: this.#findingsOf(reviewCarrier),
@@ -47,7 +47,7 @@ export class RoundNaming {
47
47
  const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
48
48
  return this.#workspace.resolve(`${family}-${this.op(frame)}${suffix}-report.md`);
49
49
  }
50
- /** The prescribed test-evidence path of a round — "" off the work faces (the doc
50
+ /** The prescribed test-evidence path of a round — "" off the delivery faces (the doc
51
51
  * lines and the review rounds prescribe no evidence file). */
52
52
  evidence(frame) {
53
53
  const name = this.evidenceName(frame);
@@ -55,7 +55,7 @@ export class RoundNaming {
55
55
  }
56
56
  /** The test-evidence file NAME of a work frame — the workspace-relative face the
57
57
  * read-back gate reads it by (`{line}-test-evidence.json`: the task families key
58
- * the line, the branch line names the family alone). "" off the work faces. */
58
+ * the line, the branch line names the family alone). "" off the delivery faces. */
59
59
  evidenceName(frame) {
60
60
  if (frame.type === "spec" || frame.type === "plan")
61
61
  return "";
@@ -131,6 +131,7 @@ export class Lifecycle {
131
131
  round,
132
132
  route,
133
133
  capsuleLines: this.#capsuleLines(frame, outcome, route),
134
+ termination: outcome.termination,
134
135
  };
135
136
  }
136
137
  // -------------------------------------------------------------------------
@@ -287,9 +288,9 @@ export class Lifecycle {
287
288
  // `schema` selector, never the outcome's field presence): a findings-face round
288
289
  // (review / docs-fix) builds the findings carrier — its schema-required findings
289
290
  // key, empty on a conclusion-only round (a fix advances no new findings); a
290
- // work-face round builds the findings-free work carrier — zero findings
291
+ // delivery-face round builds the findings-free delivery carrier — zero findings
291
292
  // injection. The review finding-severity route reads the round carrier's
292
- // findings; the conclusion rides only the work face's declared status (the
293
+ // findings; the conclusion rides only the delivery face's declared status (the
293
294
  // findings face derives its conclusion at judgment time).
294
295
  const face = this.#ledger.handoffFaceOf(op, frame.type);
295
296
  const carrier = outcome.carrier ??
@@ -297,11 +298,11 @@ export class Lifecycle {
297
298
  ? this.#ledger.buildHandoff("findings", {
298
299
  findings: [...(outcome.findings ?? [])],
299
300
  })
300
- : this.#ledger.buildHandoff("work", {}));
301
- // The work face ALONE persists the conclusion (the child's declared status); the
301
+ : this.#ledger.buildHandoff("delivery", {}));
302
+ // The delivery face ALONE persists the conclusion (the child's declared status); the
302
303
  // findings carrier holds no status — its conclusion derives at judgment time
303
304
  // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
304
- if (face === "work" && carrier.status === undefined && outcome.status !== undefined)
305
+ if (face === "delivery" && carrier.status === undefined && outcome.status !== undefined)
305
306
  carrier.status = outcome.status;
306
307
  this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
307
308
  }
@@ -400,7 +401,10 @@ export class Lifecycle {
400
401
  return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
401
402
  }
402
403
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
403
- * interaction point). The blocker cell carries the round's blocker count; the
404
+ * interaction point). A success round carries the real blocker count and the
405
+ * handoff carrier path. A failure round (TIMEOUT / BLOCKED) carries no blocker
406
+ * cell (its count would be a filler); its handoff cell is the crash record and is
407
+ * emitted only when that record exists (a no-host BLOCKED writes none). The
404
408
  * dispatch-ready `next:` literal rides the frame's own RouteTarget identity
405
409
  * (type + id — the v1.25 combination point: frame.type + params.tasks + route
406
410
  * are all present here). */
@@ -408,9 +412,17 @@ export class Lifecycle {
408
412
  if (this.#capsule === null)
409
413
  return [];
410
414
  const op = this.#opOf(frame.phase);
415
+ const failure = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
416
+ const lane = `${op}.${frame.type}`;
417
+ // The failure face's handoff is the crash record — the engine's own postmortem
418
+ // artifact, its existence the emission condition; the success face keeps the
419
+ // round's handoff carrier path.
420
+ const crash = failure ? this.#ledger.readCrash(lane, frame.round) : null;
411
421
  const blockers = (outcome.findings ?? []).filter((finding) => finding.severity === "blocker").length;
412
- const handoff = this.#ledger.handoffPath(op, frame.type, frame.params);
413
- return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame));
422
+ const handoff = crash !== null
423
+ ? this.#ledger.crashPath(lane, frame.round)
424
+ : this.#ledger.handoffPath(op, frame.type, frame.params);
425
+ return this.#capsule.emit(outcome.status, String(blockers), handoff, route, this.#routeTarget(frame), crash !== null);
414
426
  }
415
427
  /** The frame's RouteTarget — the dispatch-ready literal's target identity (the
416
428
  * frame's own facts: the wave task key · the branch line key · the doc path).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "3.0.1",
3
+ "version": "3.1.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {