@oscaner-skills/cdd-engine 4.10.0 → 4.12.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.
@@ -14,7 +14,7 @@
14
14
  var _a;
15
15
  // The module exports the shared seams + the lifecycle class — zero behavior-carrying
16
16
  // bare functions.
17
- import { existsSync, readFileSync } from "node:fs";
17
+ import { readFileSync } from "node:fs";
18
18
  import path from "node:path";
19
19
  import process from "node:process";
20
20
  import { printParseErrorCode } from "jsonc-parser";
@@ -31,7 +31,7 @@ import { CarrierRulings } from "../session/carrier-rulings.js";
31
31
  import { TargetFaceTable } from "../session/faces.js";
32
32
  import { HandoffSchema } from "../session/handoff-schema.js";
33
33
  import { InFlight } from "../session/inflight.js";
34
- import { Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
34
+ import { CONCLUDED_BLOCKED_CAUSE, Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
35
35
  import { RoundNaming } from "../session/round-naming.js";
36
36
  import { PlanStructure } from "../session/run.js";
37
37
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
@@ -202,20 +202,19 @@ export class CliLifecycle {
202
202
  dispatchBase: record.dispatchBase,
203
203
  verdict: { treeClean: true, targetAction: false },
204
204
  violations: [ABORT_INTERRUPTED],
205
- carrierPath: null,
206
205
  }, "wave");
207
206
  // P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
208
207
  // draft the dead child may have left writable and the final it never materialized.
209
- // The identity is the record's OWN (the same op/cycle the abort booked), never a
210
- // re-derivation from the current frontier.
211
- this.#sealRoundCarriersOf(op, "wave", _a.#waveParams(key, cycle, op));
208
+ // The identity is the record's OWN (op / cycle / attempt), never a re-derivation
209
+ // from the current frontier.
210
+ this.#sealRoundCarriersOf(op, "wave", _a.#waveParams(key, cycle, attempt));
212
211
  return true;
213
212
  }
214
213
  /** The handoff params of a wave round, replayed from a dead holder's record — the
215
- * same shaping the frame builder applies (the implement family is round-less, the
216
- * review / fix families carry the cycle). */
217
- static #waveParams(key, cycle, op) {
218
- return op === "implement" ? { tasks: key } : { tasks: key, round: cycle };
214
+ * same shaping the frame builder applies: every family carries its cycle and its
215
+ * attempt, so the abort record seals exactly the pair the round itself owned. */
216
+ static #waveParams(key, cycle, attempt) {
217
+ return { tasks: key, round: cycle, attempt };
219
218
  }
220
219
  /** One dispatch — the round's work, the observation facts every record carries (the
221
220
  * dispatch baseline HEAD captured before the spawn, the dispatch-after
@@ -320,16 +319,20 @@ export class CliLifecycle {
320
319
  const logEntries = this.#logUnavailable === null ? [] : [this.#logUnavailable];
321
320
  if (outcome.status === "BLOCKED" || outcome.status === "TIMEOUT") {
322
321
  const authored = outcome.violations ?? [];
322
+ // The failure itself is the HARD fact — but only for the round that authored NO
323
+ // entry at all (the no-host / silent route). A round that DECLARED its own
324
+ // BLOCKED / TIMEOUT and paid with soft entries alone (the read-back's dropped
325
+ // decorative fields, a write-back nothing measured) declared its failure itself:
326
+ // the board's crashed row and the failure reason read hard entries alone (§3.3),
327
+ // so an invented one would report an outcome the round never had (P34 T5 — such a
328
+ // round is ABSENT from `crashed:`). The synthesized entry carries its OWN cause,
329
+ // never `contract-violation`: a declared conclusion is not a broken contract.
330
+ const synthesized = authored.length === 0
331
+ ? [RoundViolation.hard(`the round concluded ${outcome.status}`, CONCLUDED_BLOCKED_CAUSE)]
332
+ : [];
323
333
  return {
324
334
  verdict: { treeClean, targetAction: false },
325
- // A failure is never a silent absence (§3.3): a concluded BLOCKED round that
326
- // authored no entry books one here (`contract-violation`, the existing cause).
327
- violations: [
328
- ...(authored.length > 0
329
- ? authored
330
- : [RoundViolation.hard(`the round concluded ${outcome.status}`)]),
331
- ...logEntries,
332
- ],
335
+ violations: [...authored, ...synthesized, ...logEntries],
333
336
  };
334
337
  }
335
338
  // The evidence gate is judged ONCE: its graded entries ride the verdict AND its
@@ -379,40 +382,39 @@ export class CliLifecycle {
379
382
  /** The plan tasks whose `Files` declaration names no path — the verification-wave
380
383
  * cell. The PLAN document is the only source (never the diff): an absent plan, a
381
384
  * plan path pointing at no document or an unreadable one declares no empty row, so
382
- * a wave can never read as verification on a plan this dispatch could not see. */
385
+ * a wave can never read as verification on a plan this dispatch could not see. A
386
+ * document the grammar refuses is the same shape: it declares no row either (the
387
+ * refusal leg speaks before the dispatch, and this cell never becomes a second,
388
+ * louder reporter of a broken plan). */
383
389
  #emptyFileTasks() {
384
390
  const planPath = this.#scene.planPath;
385
391
  if (planPath === null)
386
392
  return new Set();
387
- let content;
388
393
  try {
389
- content = readFileSync(planPath, "utf8");
394
+ const empty = new Set();
395
+ for (const block of this.#blocks.parse(readFileSync(planPath, "utf8"))) {
396
+ if (this.#blocks.filePathsOf(block).length === 0)
397
+ empty.add(block.id);
398
+ }
399
+ return empty;
390
400
  }
391
401
  catch {
392
402
  return new Set();
393
403
  }
394
- const empty = new Set();
395
- for (const block of this.#blocks.parse(content)) {
396
- if (this.#blocks.filePathsOf(block).length === 0)
397
- empty.add(block.id);
398
- }
399
- return empty;
400
404
  }
401
- /** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
402
- * group baseline and the carrier path the round writes. Deliberately verdict-free:
403
- * this judgment PRODUCES the verdict, so a verdict cell here would be a
404
- * self-fulfilling input. The group's already-recorded verdicts arrive through
405
- * `CompletionContext.records`, never through this cell. */
405
+ /** The round IDENTITY the criterion judges from — its op / cycle / attempt and the
406
+ * group baseline. Deliberately verdict-free AND path-free: the carrier a round
407
+ * wrote is DERIVED from that identity (the ledger's accessor), never a cell the
408
+ * frame hands over. Deliberately verdict-free: this judgment PRODUCES the verdict,
409
+ * so a verdict cell here would be a self-fulfilling input. The group's
410
+ * already-recorded verdicts arrive through `CompletionContext.records`, never
411
+ * through this cell. */
406
412
  #judgedRecordOf(frame, outcome) {
407
- const op = this.#opOf(frame);
408
413
  return {
409
- op,
414
+ op: this.#opOf(frame),
410
415
  cycle: frame.round,
411
416
  attempt: frame.attempt ?? 1,
412
417
  dispatchBase: outcome.dispatchBase ?? null,
413
- carrierPath: outcome.carrier === undefined
414
- ? null
415
- : this.#scene.ledger.handoffPath(op, frame.type, frame.params),
416
418
  };
417
419
  }
418
420
  /** The progress row the round belongs to (the criterion's context cell) — the key's
@@ -424,9 +426,11 @@ export class CliLifecycle {
424
426
  ledger.entryFor(frame.key));
425
427
  }
426
428
  /** The evidence gate as a graded entry (design spec §3.3) — the work plane's wave /
427
- * branch rounds write the canonical `{family-prefix}-{key}-test-evidence.json`; a
428
- * missing / malformed / schema-violating file is HARD. The tri-state read reports
429
- * each cause truly (D27): a corrupt file is never misreported as absent. */
429
+ * branch rounds write the evidence file at the round identity's own name
430
+ * (`RoundNaming#renderName(…, "evidence")`, resolved by `#naming.evidenceName`); a
431
+ * missing / malformed / schema-violating file is HARD. The name is never spelled
432
+ * here — the naming face stays its single source. The tri-state read reports each
433
+ * cause truly (D27): a corrupt file is never misreported as absent. */
430
434
  #evidenceViolations(frame) {
431
435
  if (HandoffSchema.planeOf(this.#opOf(frame)) !== "work")
432
436
  return [];
@@ -702,14 +706,23 @@ export class CliLifecycle {
702
706
  * plan-less scene and when the plan is unreadable. */
703
707
  #briefHashOf(frame) {
704
708
  const scene = this.#scene;
705
- if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
709
+ const plan = scene.plan;
710
+ if (frame.type !== "wave" || frame.target.kind !== "wave")
711
+ return null;
712
+ const text = plan.text();
713
+ const doc = plan.doc();
714
+ const planPath = plan.stationPath();
715
+ if (text === null || doc === null || planPath === null)
706
716
  return null;
707
717
  try {
708
- const plan = readFileSync(scene.planPath, "utf8");
709
- const body = this.#brief.taskBody(plan, frame.target.tasks);
710
- return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
718
+ const body = this.#brief.taskBody(text, doc, frame.target.tasks);
719
+ return scene.ledger.refs().briefRevision(this.#rel(planPath), body).brief_hash;
711
720
  }
712
721
  catch {
722
+ // The ONLY throw point left is the brief's own out-of-bounds gate
723
+ // (`task N not found in the plan` — a legal scene when the plan was amended
724
+ // after the wave compiled): the round then records no hash, the same failure
725
+ // face `Ledger#briefRevision` keeps.
713
726
  return null;
714
727
  }
715
728
  }
@@ -800,13 +813,16 @@ export class CliLifecycle {
800
813
  // empty, so the assembler drops the line entirely.
801
814
  INPUT_RULINGS: this.#rulingsInputOf(frame),
802
815
  // The kind-named judged-doc anchors (the semantic retirement of the generic
803
- // INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
804
- // doc path on a plan line, the plan path on a branch line, whose review/fix
805
- // judges the plan document) AND its design-spec reference (INPUT_SPEC — the
806
- // `spec:` front-matter link target, so the plan/branch reviewer judges plan→
807
- // spec conformance); the spec line carries its spec document (INPUT_SPEC; the
808
- // judged doc IS the spec, no plan anchor). Empty off the off-faces (the slots
809
- // are dropped by the assembler).
816
+ // INPUT_DOC): the plan line carries the plan document as its judged doc
817
+ // (INPUT_PLAN) AND its design-spec reference (INPUT_SPEC — the `spec:`
818
+ // front-matter link target, the plan→spec conformance anchor); the branch line
819
+ // carries the plan document (its plan-conformance reference) plus the same
820
+ // design-spec reference, while the live tree against BASE_BRANCH is the judged
821
+ // object; the spec-shaped doc targets (phase-spec · single-spec) carry their
822
+ // spec document (INPUT_SPEC, the judged doc); the overall line's ONE charter
823
+ // anchor is INPUT_OVERALL, so its INPUT_SPEC stays empty (C2 — the charter is
824
+ // never its own spec). Empty off the off-faces (the slots are dropped by the
825
+ // assembler).
810
826
  INPUT_PLAN: frame.type === "plan"
811
827
  ? this.#rel(docPath ?? "")
812
828
  : frame.type === "branch"
@@ -814,16 +830,16 @@ export class CliLifecycle {
814
830
  : "",
815
831
  INPUT_SPEC: frame.type === "plan" || frame.type === "branch"
816
832
  ? this.#rel(scene.specLink ?? "")
817
- : frame.type === "wave"
833
+ : frame.type === "wave" || frame.type === "overall"
818
834
  ? ""
819
- : // the doc shapes (phase-spec · overall · single-spec) carry the judged
820
- // document — the charter line's own charter is its spec anchor.
835
+ : // the spec-shaped doc targets (phase-spec · single-spec) carry the judged
836
+ // document; the overall line's charter anchor is INPUT_OVERALL below.
821
837
  this.#rel(docPath ?? ""),
822
- // The parent charter of the spec the face reads (INPUT_OVERALL) — the same
823
- // value condition as INPUT_SPEC, one face (the phase-spec line = its own
824
- // `program:`; plan/branch = the same-slug identity doc's `program:`; the
825
- // overall line itself = the judged charter); empty off those faces and when
826
- // the named program is absent (the assembler drops the empty slot).
838
+ // The parent charter of the spec the face reads (INPUT_OVERALL) — the overall
839
+ // line's ONE charter anchor (the judged charter itself); the phase-spec line
840
+ // carries its own `program:`; plan/branch carry the same-slug identity doc's
841
+ // `program:`; empty off those faces and when the named program is absent (the
842
+ // assembler drops the empty slot).
827
843
  INPUT_OVERALL: frame.type === "overall"
828
844
  ? this.#rel(docPath ?? "")
829
845
  : frame.type === "phase-spec" || frame.type === "plan" || frame.type === "branch"
@@ -844,7 +860,10 @@ export class CliLifecycle {
844
860
  OUTPUT_REPORT: this.#rel(this.#naming.report(frame)),
845
861
  OUTPUT_EVIDENCE: this.#rel(this.#naming.evidence(frame)),
846
862
  OUTPUT_HANDOFF: this.#rel(scene.ledger.handoffPath(op, frame.type, params)),
847
- REVIEW_TYPE: isReview ? frame.type : "",
863
+ // P33 T1 — the target discriminant the child reads (the CLI's `--type` word).
864
+ // It renders right below ROLE on every face that has a target; implement is the
865
+ // one role without one, so the slot stays empty and the assembler drops the line.
866
+ TARGET_TYPE: role === "implement" ? "" : frame.type,
848
867
  WORKSPACE_DIR: this.#rel(scene.workspace.path),
849
868
  WORKSPACE_ID: scene.workspace.slug,
850
869
  // v1.9 — the injected writable-subset schema (projection ①): the `## Handoff
@@ -906,22 +925,18 @@ export class CliLifecycle {
906
925
  for (const name of this.#roundCarrierNamesOf(op, type, params))
907
926
  CarrierSeal.seal(name);
908
927
  }
909
- /** A frame's own carrier paths — the child's draft (`Ledger#handoffPath`, the family
910
- * table's fill) and the engine's final (`RoundNaming#finalPath`, `.c{N}` suffixed).
911
- * A round-less family (implement) resolves both to the same path — one name, sealed
912
- * once. */
928
+ /** A frame's own carrier paths — the child's draft and the engine's final, both
929
+ * rendered by the one naming rule (`RoundNaming#renderName`), the final carrying the
930
+ * `.c{N}` cycle suffix. A cycle-less identity resolves both to the same path — one
931
+ * name, sealed once. */
913
932
  #roundCarrierNames(frame) {
914
933
  return this.#roundCarrierNamesOf(this.#opOf(frame), frame.type, frame.params);
915
934
  }
916
935
  /** `#roundCarrierNames` over an identity — the abort fold's entry (it holds a dead
917
936
  * holder's op/cycle, never a frame). */
918
937
  #roundCarrierNamesOf(op, type, params) {
919
- const ledger = this.#scene.ledger;
920
- const draftName = ledger.handoffName(op, type, params);
921
- return [
922
- this.#scene.workspace.resolve(draftName),
923
- this.#naming.finalPath(draftName, params.round),
924
- ];
938
+ const artifact = RoundNaming.artifactOf(op, type, params);
939
+ return [this.#naming.renderPath(artifact, "draft"), this.#naming.renderPath(artifact, "final")];
925
940
  }
926
941
  // -------------------------------------------------------------------------
927
942
  // the read-back reconstruct (§3.6) — the draft is the round's content
@@ -934,12 +949,14 @@ export class CliLifecycle {
934
949
  return this.#scene.workspace.readJsonLenient(this.#scene.ledger.handoffName(op, frame.type, frame.params));
935
950
  }
936
951
  /** The non-rejecting draft probe of the termination branch — a terminated REVIEW
937
- * round's draft is promotable iff it exists, parses, passes the judge plane's schema,
938
- * and carries at least one finding. Returns the validated draft (the promotion
939
- * then rides the reconstruct's existing validation/persistence/conclusion path) or
940
- * null (the round keeps the TIMEOUT failure face). It calls no `#reject` and
941
- * produces no outcome — a probe is a question, never a verdict. Implement/fix
942
- * rounds are outside the promotion domain (their `op` is not the review family). */
952
+ * round's draft is promotable iff it exists, parses, passes the judge plane's TIERED
953
+ * read-back (a required slot's violation refuses; a decorative column is only the
954
+ * reconstruct's cue to drop it), and carries at least one finding. Returns the
955
+ * draft (the promotion then rides the reconstruct's existing
956
+ * validation/persistence/conclusion path) or null (the round keeps the TIMEOUT
957
+ * failure face). It calls no `#reject` and produces no outcome — a probe is a
958
+ * question, never a verdict. Implement/fix rounds are outside the promotion domain
959
+ * (their `op` is not the review family). */
943
960
  #probeDraft(frame) {
944
961
  const op = this.#opOf(frame);
945
962
  if (op !== "review")
@@ -948,8 +965,12 @@ export class CliLifecycle {
948
965
  const read = this.#readDraft(frame);
949
966
  if (read.kind !== "ok")
950
967
  return null;
968
+ // The SAME tier the reconstruct later applies — one read-back ruling, so the probe
969
+ // and the materialize step can never disagree about a draft's validity (a
970
+ // decorative column's mistake is a drop, not a failure). The read-back is a pure
971
+ // ruling; the shallow copy keeps the probe's draft independent of it either way.
951
972
  const draft = read.value;
952
- if (this.#handoffSchema.violations(plane, draft).length > 0)
973
+ if (this.#handoffSchema.readBack(plane, { ...draft }).problems.length > 0)
953
974
  return null;
954
975
  const findings = Array.isArray(draft.findings) ? draft.findings : [];
955
976
  return findings.length >= 1 ? draft : null;
@@ -1026,9 +1047,12 @@ export class CliLifecycle {
1026
1047
  }
1027
1048
  draft = draftRead.value;
1028
1049
  }
1029
- const problems = schema.violations(plane, draft);
1030
- if (problems.length > 0) {
1031
- return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${problems.join("; ")}`);
1050
+ // The TIERED read-back (spec §2.1): a required slot's violation refuses the round,
1051
+ // a decorative slot's violation is DROPPED from the draft in place (surfaced once on
1052
+ // the carrier's notes by materialize) — a wrong optional column never costs a round.
1053
+ const readBack = schema.readBack(plane, draft);
1054
+ if (readBack.problems.length > 0) {
1055
+ return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${readBack.problems.join("; ")}`);
1032
1056
  }
1033
1057
  // T2 — the plane-aware read: the judge plane ALONE reads `draft.findings` (its
1034
1058
  // own declared required field — rolled up to the conclusion); the work plane
@@ -1043,13 +1067,13 @@ export class CliLifecycle {
1043
1067
  // reaches this line; the absent→undefined case exists only for on-disk legacy
1044
1068
  // carriers the ledger reads back, never a schema-validated draft).
1045
1069
  const status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
1046
- const carrier = this.#materialize(frame, plane, draft, status);
1070
+ const materialized = this.#materialize(frame, plane, draft, status, readBack.dropped);
1047
1071
  // P31 §2.2 — the disposition summary reads the REQUESTING carrier. A mismatch
1048
1072
  // found here (the bytes moved inside the round) is a BLOCKED outcome: the read-back
1049
1073
  // is the FALLBACK behind the pre-dispatch gate, never the gate itself.
1050
1074
  let summary;
1051
1075
  try {
1052
- summary = this.#dispositionsSummary(frame, plane, carrier);
1076
+ summary = this.#dispositionsSummary(frame, plane, materialized.carrier);
1053
1077
  }
1054
1078
  catch (raw) {
1055
1079
  if (!(raw instanceof CarrierMismatchError))
@@ -1060,8 +1084,11 @@ export class CliLifecycle {
1060
1084
  return {
1061
1085
  status,
1062
1086
  findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
1063
- carrier,
1087
+ carrier: materialized.carrier,
1064
1088
  dispositionsSummary: summary,
1089
+ // The read-back's drops are the round's OWN soft observations (spec §2.14) — a
1090
+ // wrong decorative field is a loss the record must show, never a silent rewrite.
1091
+ violations: materialized.violations,
1065
1092
  };
1066
1093
  }
1067
1094
  /** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
@@ -1081,34 +1108,33 @@ export class CliLifecycle {
1081
1108
  return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
1082
1109
  }
1083
1110
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
1084
- * ledger's resolved review handoff path when the route carried none (the ONE
1085
- * resolution the round context's INPUT_REVIEWS and the disposition summary share).
1086
- * Four layers, ONE identity (P31 §2.3): the explicit `--reviews` flag → the
1087
- * same-cycle review record's own `carrierPath` (the FINAL carrier the round wrote) →
1088
- * the ledger's resolved family name (a draft, or a migrated line's retired twin —
1089
- * the carrier that EXISTS, never the never-minted canonical spelling) → the legacy
1090
- * `null`. Record-present means final-wins: a draft sitting beside the final never
1091
- * becomes the judged input.
1092
- *
1093
- * A same-cycle review record that RECORDED no carrier path, with no carrier at
1094
- * either spelling on disk, leaves the requester input UNRECORDED: the answer is
1095
- * null, and the fix criterion books its visible skip (design spec §3.4's legacy
1096
- * row) instead of failing the round on a hard absent-carrier refusal. An absent
1097
- * record is a different fact — it keeps the resolved path, so the criterion reports
1098
- * the missing requesting carrier it truly is. */
1111
+ * same-cycle review record's carrier identity through the ledger's ONE accessor
1112
+ * (the recorded path, then the read ladder a pre-P31 row needs), or the ledger's
1113
+ * resolved family name when the line records no review for this cycle. A record
1114
+ * that resolves no carrier reads `null` — the UNRECORDED face, which the criterion
1115
+ * books as a visible skip instead of failing the round on a hard absent-carrier
1116
+ * refusal. Record-present means the record's own final wins: a draft sitting beside
1117
+ * it never becomes the judged input. */
1099
1118
  #reviewsPath(frame) {
1100
1119
  if (this.#reviews !== null)
1101
1120
  return this.#reviews;
1102
- const recorded = this.#requesterRecord(frame)?.carrierPath;
1103
- if (typeof recorded === "string" && recorded !== "")
1104
- return recorded;
1105
- const resolved = this.#scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
1106
- if (existsSync(resolved))
1107
- return resolved;
1108
- const legacy = this.#scene.ledger
1109
- .recordsOf(frame.key, frame.type)
1110
- .some((record) => record.op === "review" && record.cycle === frame.round && record.carrierPath === null);
1111
- return legacy ? null : resolved;
1121
+ const record = this.#requesterRecord(frame);
1122
+ if (record !== null) {
1123
+ const recorded = this.#scene.ledger.carrierPathOf(frame.type, String(frame.key), record);
1124
+ return recorded === "" ? null : recorded;
1125
+ }
1126
+ return this.#reviewFamilyPath(frame);
1127
+ }
1128
+ /** The review family's name for this frame's CYCLE — the one home of the
1129
+ * "fall back with the cycle only" rule (§2.10). It never carries the frame's
1130
+ * `attempt`: the review family's attempt is its own recorded one, resolved by the
1131
+ * central `#attemptAware` default. A re-dispatched fix frame would otherwise ask
1132
+ * for a `-a2` name the cycle's review never wrote. */
1133
+ #reviewFamilyPath(frame) {
1134
+ return this.#scene.ledger.resolveHandoffPath("review", frame.type, {
1135
+ tasks: frame.params.tasks,
1136
+ round: frame.round,
1137
+ });
1112
1138
  }
1113
1139
  /** The same-cycle review record this fix round answers — its LATEST attempt (a
1114
1140
  * re-dispatched review supersedes its predecessor, the same rule the round-read gate
@@ -1344,32 +1370,48 @@ export class CliLifecycle {
1344
1370
  * separate fact (`#verdictOf`): a hard round fails on its record + exit code, while
1345
1371
  * the carrier keeps the child's own declared status (the engine never rewrites a
1346
1372
  * declaration to encode a judgment). */
1347
- #materialize(frame, plane, draft, status) {
1373
+ // Rule zero — five params: the first four ARE the carrier (frame · plane · draft ·
1374
+ // status), and `droppedDecorative` is the read-back ruling the call already owns; a
1375
+ // parameter object would only rename the call site, not remove the coupling.
1376
+ #materialize(frame, plane, draft, status, droppedDecorative = []) {
1348
1377
  const ledger = this.#scene.ledger;
1349
- const notes = [];
1350
1378
  // The §8.7 classification ruling — the SAME judgment the read-back validator makes
1351
1379
  // (non-declared keys are dropped, never a BLOCK): materialize drops them and books
1352
1380
  // AT MOST ONE WARN on the carrier's notes (auditable, non-interrupting — replacing
1353
1381
  // the retired "BLOCK + crash-resume + reopen" chain). The engine stays the carrier's
1354
1382
  // single author; a child's stray key is surfaced, not obeyed.
1355
1383
  const dropped = this.#handoffSchema.droppedKeys(plane, draft);
1384
+ // TWO loss families, two landings. A DECLARATIVE loss (a declared slot outside its
1385
+ // declared shape) is ONE carrier note AND ONE `RoundViolation.soft` on the record —
1386
+ // spec §2.14's soft landing, the child owed the field and lost it. A non-declared
1387
+ // key is §8.7's own face: ONE note and nothing else (the drop is silent on the warn
1388
+ // channel — it cost the child no declared obligation).
1389
+ const observations = [];
1390
+ if (droppedDecorative.length > 0) {
1391
+ observations.push(`dropped decorative draft field(s) outside their declared shape: ${droppedDecorative.join(", ")} — never written`);
1392
+ }
1393
+ const reserved = [];
1356
1394
  if (dropped.length > 0) {
1357
- notes.push(`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`);
1395
+ reserved.push(`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`);
1358
1396
  }
1397
+ const notes = [...observations, ...reserved];
1359
1398
  // The per-plane carrier — buildHandoff's typed overloads: the judge plane REQUIRES
1360
1399
  // its findings payload (the schema-required field — cli.test pins the review
1361
1400
  // carrier's findings + status), the work plane builds a findings-FREE typed carrier
1362
1401
  // (the work writable subset declares no findings field — a docs-fix draft's residual
1363
1402
  // findings are dropped, never materialized). `Record<string, unknown>` local: the
1364
1403
  // round conclusion (status — a RoundStatus, wider than the carrier's declared union)
1365
- // and the engine's extended fields ride the caller's set below.
1404
+ // and the engine's extended fields ride the caller's set below. A dropped slot is
1405
+ // read as absent here — the copy points are where the drop must land, never a
1406
+ // second pass over the raw draft.
1407
+ const artifacts = droppedDecorative.includes("artifacts") ? undefined : draft.artifacts;
1366
1408
  const carrier = plane === "judge"
1367
1409
  ? ledger.buildHandoff("judge", {
1368
- artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
1369
- findings: this.#findingsList(draft.findings),
1410
+ artifacts: this.#canonicalArtifacts(frame, artifacts, notes),
1411
+ findings: this.#findingsList(draft.findings, droppedDecorative),
1370
1412
  })
1371
1413
  : ledger.buildHandoff("work", {
1372
- artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
1414
+ artifacts: this.#canonicalArtifacts(frame, artifacts, notes),
1373
1415
  });
1374
1416
  // The work plane ALONE persists the round conclusion — it is the child's own
1375
1417
  // declared status (the schema enum pinned it to APPROVED | BLOCKED). The judge
@@ -1378,17 +1420,22 @@ export class CliLifecycle {
1378
1420
  // persisted judge carrier stays the pure declaration plane
1379
1421
  // (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
1380
1422
  // status-free (the judgment plane is perpendicular to the input plane · D27).
1381
- const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
1423
+ const draftNotes = droppedDecorative.includes("notes")
1424
+ ? []
1425
+ : Array.isArray(draft.notes)
1426
+ ? [...draft.notes]
1427
+ : [];
1382
1428
  if (plane === "work") {
1383
1429
  carrier.status = status;
1384
1430
  // The fix dispositions ride the carrier VERBATIM (the child's declaration, never
1385
1431
  // an engine rewrite) — the schema pinned the slot's object shape.
1386
- if (draft.dispositions !== undefined)
1432
+ if (draft.dispositions !== undefined && !droppedDecorative.includes("dispositions")) {
1387
1433
  carrier.dispositions = draft.dispositions;
1434
+ }
1388
1435
  }
1389
1436
  if (notes.length > 0 || draftNotes.length > 0)
1390
1437
  carrier.notes = [...notes, ...draftNotes];
1391
- return carrier;
1438
+ return { carrier, violations: observations.map((text) => RoundViolation.soft(text)) };
1392
1439
  }
1393
1440
  /** The carrier's artifacts map (find #5 — the engine self-derives, never trusts a
1394
1441
  * child-reported path for the canonical slots): a declared PRESCRIBED slot
@@ -1445,8 +1492,7 @@ export class CliLifecycle {
1445
1492
  #schemaText(frame) {
1446
1493
  const plane = HandoffSchema.planeOf(this.#opOf(frame));
1447
1494
  const evidence = plane === "work" && (frame.type === "wave" || frame.type === "branch");
1448
- const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
1449
- return this.#handoffSchema.schemaText(plane, evidence, prefix);
1495
+ return this.#handoffSchema.schemaText(plane, evidence);
1450
1496
  }
1451
1497
  /** The artifacts field as a string-map (only string values land — non-string rows
1452
1498
  * are dropped, never coerced). */
@@ -1464,12 +1510,28 @@ export class CliLifecycle {
1464
1510
  * for the ONE engine-owned column: `id`, stamped from the carrier position (`F1`,
1465
1511
  * `F2` …) and overwriting whatever the child wrote (P30 §2.5 — the disposition
1466
1512
  * primary key belongs to the engine, never to the audited prose). This is the only
1467
- * write point of a finding id in the engine. */
1468
- #findingsList(findings) {
1513
+ * write point of a finding id in the engine, and it runs AFTER the decorative
1514
+ * deletions: a draft `id` outside its declared shape drops the CHILD's value only,
1515
+ * never the key the engine owns (a non-string id must still land as `F1`).
1516
+ *
1517
+ * `dropped` is the tiered read-back's decorative paths — the finding row's own
1518
+ * out-of-tier columns (`findings[i].line` and friends) are removed HERE, the copy
1519
+ * point for a nested drop (spec §2.14), so the carrier never re-acquires a column
1520
+ * the read-back refused. */
1521
+ #findingsList(findings, dropped = []) {
1469
1522
  const rows = Array.isArray(findings) ? findings : [];
1470
- return rows.map((row, index) => typeof row === "object" && row !== null && !Array.isArray(row)
1471
- ? { ...row, id: `F${index + 1}` }
1472
- : row);
1523
+ return rows.map((row, index) => {
1524
+ if (typeof row !== "object" || row === null || Array.isArray(row))
1525
+ return row;
1526
+ const copy = { ...row };
1527
+ for (const path of dropped) {
1528
+ const column = HandoffSchema.findingColumnOf(path, index);
1529
+ if (column !== null)
1530
+ delete copy[column];
1531
+ }
1532
+ copy.id = `F${index + 1}`;
1533
+ return copy;
1534
+ });
1473
1535
  }
1474
1536
  /** The same-command resume string — the crash record's `next`, mirroring the
1475
1537
  * CLI's dispatchable form of this frame (re-run the same command per the BLOCKED
@@ -1499,9 +1561,10 @@ export class CliLifecycle {
1499
1561
  // The `--reviews` input is the SAME carrier the fix prompt names (P31 §2.3): one
1500
1562
  // four-layer resolution, never a second family spelling spliced here. The
1501
1563
  // fallback fires only when the recorded face resolves to `null` (a legacy record
1502
- // with no carrier on disk) — the never-null guard keeps a command shape.
1503
- const findings = this.#reviewsPath(frame) ??
1504
- scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
1564
+ // with no carrier on disk) — the never-null guard keeps a command shape, and
1565
+ // `#reviewFamilyPath` is the one home of the cycle-only rule (§2.10): a fix
1566
+ // retried at attempt 2 would otherwise ask for a `-a2` name review never wrote.
1567
+ const findings = this.#reviewsPath(frame) ?? this.#reviewFamilyPath(frame);
1505
1568
  const target = frame.target.kind === "plan"
1506
1569
  ? `--plan ${frame.target.doc}`
1507
1570
  : frame.target.kind === "spec"
@@ -145,6 +145,21 @@ export const CAPSULE_WORDS = {
145
145
  "discard the ones that are broken",
146
146
  ],
147
147
  },
148
+ /** The plan-read rows (spec §2.1 · §2.4 · §2.7) — the vocabulary the `PlanRead`
149
+ * value emits: the two read-failure marks, the healthy-but-empty mark, the
150
+ * orphan mark, the program face's undeclared cell and the two orphan
151
+ * diagnostics.
152
+ * `planReadWord(cause)` reads only `io` / `syntax`; the remaining rows are
153
+ * peers, never members of the failure vocabulary. */
154
+ planRead: {
155
+ io: "! unreadable",
156
+ syntax: "! unparseable",
157
+ empty: "(empty plan)",
158
+ orphan: "! no-spec",
159
+ orphanSpec: "the plan's slug \"{slug}\" names no design spec — {specPath} is absent (every plan is written for one phase; add that phase spec or fix the plan's `slug:`)",
160
+ slugMissing: "the plan declares no `slug:` key — add `slug: <workspace-key>` to the plan's front-matter and re-run",
161
+ cellEmpty: "",
162
+ },
148
163
  /** The cut-short round's late-landing hint — every kill / timeout / crash message
149
164
  * carries it: the child may have written more after the engine stopped watching. */
150
165
  lateLanding: "a late write may land after the round was cut short — check the working tree before starting the review",
@@ -376,6 +391,42 @@ export class Words {
376
391
  return CAPSULE_WORDS.lateLanding;
377
392
  }
378
393
  // -------------------------------------------------------------------------
394
+ // plan-read — the `PlanRead` value's word port
395
+ // -------------------------------------------------------------------------
396
+ /** One read-failure mark (`io` / `syntax`) — the failure vocabulary, and only it. */
397
+ planReadWord(cause) {
398
+ return CAPSULE_WORDS.planRead[cause];
399
+ }
400
+ /** The healthy plan carrying no task block yet — never folded into the failure
401
+ * vocabulary (a healthy empty state is not a read failure). */
402
+ planEmptyWord() {
403
+ return CAPSULE_WORDS.planRead.empty;
404
+ }
405
+ /** The orphan mark the doc face, the program cell and the plan row fold into. */
406
+ planOrphanWord() {
407
+ return CAPSULE_WORDS.planRead.orphan;
408
+ }
409
+ /** The `spec-absent` orphan diagnostic — the plan's slug and the derived spec path,
410
+ * both filled here (the row lives in the table only). */
411
+ planOrphanSpec(slug, specPath) {
412
+ return CAPSULE_WORDS.planRead.orphanSpec
413
+ .replace("{slug}", slug)
414
+ .replace("{specPath}", specPath);
415
+ }
416
+ /** The `slug-absent` diagnostic — the plan parses but declares no identity key. */
417
+ planSlugMissing() {
418
+ return CAPSULE_WORDS.planRead.slugMissing;
419
+ }
420
+ /** The program face's undeclared cell — `""` belongs to that one semantic. */
421
+ get cellEmpty() {
422
+ return CAPSULE_WORDS.planRead.cellEmpty;
423
+ }
424
+ /** The stderr diagnostic prefix — delegated to the `warn` station row (one
425
+ * source, no second `CDD_WARN:` literal). */
426
+ get warnPrefix() {
427
+ return CAPSULE_WORDS.stations.warn;
428
+ }
429
+ // -------------------------------------------------------------------------
379
430
  // locale — the word-table locale face (the langs projection + the label rows)
380
431
  // -------------------------------------------------------------------------
381
432
  /** The locale key set — the word table's declared languages (the `langs`