@oscaner-skills/cdd-engine 4.6.0 → 4.8.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.
@@ -1,7 +1,8 @@
1
1
  // packages/cdd-engine/src-next/contract/completion-criterion.ts
2
2
  // P22 T4/T6 — "is this round done?" as criteria behind ONE verb-keyed registry
3
3
  // (design spec §8 · the completion-criterion row): `implement` is done when the
4
- // group's baseline carries at least one commit, `review` (branch review included —
4
+ // group's baseline carries at least one commit OR the round is a zero-diff
5
+ // verification wave with green evidence (P30 §2.4), `review` (branch review included —
5
6
  // branch-review folds to the review op) is done when its carrier is schema-shaped,
6
7
  // and `fix` is done when its work carrier's `dispositions` cover every finding of
7
8
  // the REQUESTING review carrier (design spec §3.4).
@@ -9,9 +10,9 @@
9
10
  // The criterion judges a CompletionContext the dispatch side assembles (Task 7):
10
11
  // the round's verdict-free identity, its ledger row, the row's in-register records,
11
12
  // the persisted carrier bytes, the requester's review path, the git read face and the
12
- // repoRoot path basis. The two cells with a provider seam (`records`, `reviewsPath`) are
13
- // filled by `CliLifecycle` — this module pins the context SHAPE only and imports
14
- // neither `face/` nor the lifecycle.
13
+ // repoRoot path basis. The four cells with a provider seam (`records`, `reviewsPath`,
14
+ // `emptyFileTasks`, `evidenceOk`) are filled by `CliLifecycle` — this module pins the
15
+ // context SHAPE only and imports neither `face/` nor the lifecycle.
15
16
  //
16
17
  // The registry is deliberately PARTIAL while the verbs are ported one at a time: a
17
18
  // verb with no criterion throws at lookup (`CompletionCriteria.of`), so a dispatch of
@@ -21,19 +22,26 @@
21
22
  //
22
23
  // Module-level exports are types / the declared registry / the class — zero
23
24
  // behavior-carrying bare functions.
24
- var _a;
25
+ var _a, _b;
25
26
  import { readFileSync } from "node:fs";
26
27
  import path from "node:path";
27
28
  import { RoundViolation, } from "../session/ledger.js";
28
29
  /**
29
30
  * CommitsSinceGroupBase — the implement criterion: the round is done when the GROUP
30
- * has at least one commit since the group's baseline (design spec §8).
31
+ * has at least one commit since the group's baseline (design spec §8), OR when the
32
+ * round is a VERIFICATION wave with green evidence (P30 §2.4).
31
33
  *
32
34
  * The baseline is the EARLIEST record's `dispatchBase` of the group — not the round's
33
35
  * own. A group re-dispatched after a failed attempt carries a newer per-attempt base,
34
36
  * so comparing against the round's own base would read "attempt 1 committed, attempt 2
35
37
  * committed nothing" as an empty round (the cross-attempt false negative the group
36
38
  * baseline exists to prevent).
39
+ *
40
+ * The second leg is a strictly additive OR branch: a wave whose EVERY task declares an
41
+ * empty `Files` (a verification wave — it changes no file by design) commits nothing,
42
+ * so its green evidence is the round's completion. The commit test itself is
43
+ * untouched — a wave with any non-empty `Files` row keeps the `committed nothing`
44
+ * refusal on a zero diff.
37
45
  */
38
46
  export class CommitsSinceGroupBase {
39
47
  /** The group baseline — the first record (ledger order = cycle/attempt order) that
@@ -46,27 +54,70 @@ export class CommitsSinceGroupBase {
46
54
  }
47
55
  return null;
48
56
  }
57
+ /** Whether the wave is a VERIFICATION wave: EVERY task id the wave key declares has
58
+ * an empty `Files` declaration. The id set is read from the row's `wave` key (the
59
+ * wave-unitary model's group identity, `"1,2"` = `{1, 2}`) — the empty-`Files` cell
60
+ * carries membership only, so a set that is a mere subset of the wave must not read
61
+ * as "the whole wave changes nothing". A wave key declaring no id is never a
62
+ * verification wave: an empty member set would satisfy "every member" vacuously. */
63
+ static isVerificationWave(row, emptyFileTasks) {
64
+ const ids = _a.waveIdsOf(row.wave);
65
+ if (ids.length === 0)
66
+ return false;
67
+ return ids.every((id) => emptyFileTasks.has(id));
68
+ }
69
+ /** The task ids one wave key declares — the comma-separated digits of `row.wave`,
70
+ * deduped. A non-numeric token carries no task identity and is dropped. */
71
+ static waveIdsOf(wave) {
72
+ const ids = new Set();
73
+ for (const token of wave.split(",")) {
74
+ const trimmed = token.trim();
75
+ if (/^\d+$/.test(trimmed))
76
+ ids.add(Number(trimmed));
77
+ }
78
+ return [...ids];
79
+ }
49
80
  async judge(ctx) {
50
81
  // The round under judgment is APPENDED to the group's recorded history: on a
51
82
  // group's FIRST dispatch the ledger holds no record yet (the round is recorded at
52
83
  // bookkeep, after this judgment), and the round's own `dispatchBase` IS the group
53
84
  // baseline. An earlier record always wins — the group's start, never a retry's.
54
- const base = CommitsSinceGroupBase.groupBaseOf([...ctx.records, ctx.record]);
85
+ const base = _a.groupBaseOf([...ctx.records, ctx.record]);
55
86
  if (base === null) {
56
87
  return this.#hard("the round's group carries no dispatch baseline — a completion judgment needs the HEAD the group started from");
57
88
  }
58
89
  const commits = await ctx.git.commitsSince(ctx.repoRoot, base);
59
- if (commits.length === 0) {
60
- return this.#hard(`the group committed nothing since its baseline ${base}`);
61
- }
62
- // An implement round is judged by its COMMITS, never by its handoff draft: the
63
- // absent carrier is a bookkeeping observation (design spec §3.3), so the round
64
- // still concludes.
90
+ if (commits.length > 0)
91
+ return this.#committed(ctx);
92
+ return this.#zeroCommit(ctx, base);
93
+ }
94
+ /** A round with commits concludes. An implement round is judged by its COMMITS, never
95
+ * by its handoff draft: the absent carrier is a bookkeeping observation (design spec
96
+ * §3.3), so the round still concludes. */
97
+ #committed(ctx) {
65
98
  if (ctx.carrier === null) {
66
99
  return { fulfilled: true, violation: null, observations: [this.#observation()] };
67
100
  }
68
101
  return { fulfilled: true, violation: null };
69
102
  }
103
+ /** A zero-commit round: a verification wave with green evidence concludes (its empty
104
+ * diff is the plan's declaration, not an empty round), every other zero-commit round
105
+ * keeps the `committed nothing` refusal. The two refusals name DIFFERENT gaps — a
106
+ * wave that declares no file changes and owes evidence is not the same defect as a
107
+ * wave that simply produced nothing. */
108
+ #zeroCommit(ctx, base) {
109
+ const verification = _a.isVerificationWave(ctx.row, ctx.emptyFileTasks);
110
+ if (!verification) {
111
+ return this.#hard(`the group committed nothing since its baseline ${base}`);
112
+ }
113
+ if (!ctx.evidenceOk) {
114
+ return this.#hard("the wave declares no file changes on every task, but this round's test evidence is not green — a verification wave still owes green evidence");
115
+ }
116
+ const observations = [this.#verificationObservation()];
117
+ if (ctx.carrier === null)
118
+ observations.push(this.#observation());
119
+ return { fulfilled: true, violation: null, observations };
120
+ }
70
121
  /** The hard verdict of this criterion — the ledger's existing `contract-violation`
71
122
  * cause, never a new violation enum row. */
72
123
  #hard(message) {
@@ -77,7 +128,13 @@ export class CommitsSinceGroupBase {
77
128
  #observation() {
78
129
  return RoundViolation.soft(IMPLEMENT_CARRIER_ABSENT);
79
130
  }
131
+ /** The verification-wave observation — the round passed on its plan declaration plus
132
+ * green evidence rather than on a diff; booked soft, it never gates. */
133
+ #verificationObservation() {
134
+ return RoundViolation.soft(IMPLEMENT_VERIFICATION_WAVE);
135
+ }
80
136
  }
137
+ _a = CommitsSinceGroupBase;
81
138
  /**
82
139
  * JudgeCarrier — the review criterion: a review round is done exactly when its
83
140
  * carrier is a schema-shaped judge payload — a JSON object whose `findings` is an
@@ -105,6 +162,12 @@ export class JudgeCarrier {
105
162
  * round is judged by its COMMITS, so a round that committed its work but wrote no
106
163
  * handoff draft still concludes; the missing carrier is booked, never gated. */
107
164
  export const IMPLEMENT_CARRIER_ABSENT = "the implement round wrote no handoff carrier — the round is judged by its commits, not by its draft";
165
+ /** The zero-diff verification-wave observation (P30 §2.4) — the wave's every task
166
+ * declares an empty `Files`, so its empty diff IS the plan's declaration and its
167
+ * green evidence is the round's completion. Booked soft: the round concluded on the
168
+ * declaration, and the ledger says so instead of reading it as an ordinary commit
169
+ * round that happened to leave nothing. */
170
+ export const IMPLEMENT_VERIFICATION_WAVE = "the implement round committed nothing — every task of this wave declares an empty `Files`, so the round concluded on its green evidence as a verification wave";
108
171
  /** The zero-commit observation of a fix round — a NEW literal (the engine had no
109
172
  * reusable zero-commit warning; `commitsSince` fed the crash postmortem alone).
110
173
  * The yardstick is THIS round's own `dispatchBase`: the implement criterion asks
@@ -116,6 +179,11 @@ export const FIX_DISPOSITIONS_ZERO_COMMIT = "the fix round committed nothing sin
116
179
  /** The empty-input observation — an empty requesting carrier is legal input, so it
117
180
  * is reported, never refused. */
118
181
  export const FIX_DISPOSITIONS_EMPTY_INPUT = "the requesting review carrier carries no findings — the fix round owes no dispositions";
182
+ /** The legacy-key-set observation (P30 §2.5) — the requesting carrier carries no
183
+ * finding `id` (it predates the engine-written key), so the dispositions were matched
184
+ * by summary text. Booked soft: the round is judged, and the ledger says the key it
185
+ * used. No carrier migration — present facts only. */
186
+ export const FIX_DISPOSITIONS_LEGACY_KEYS = "the requesting review carrier carries no finding `id` — the dispositions were matched by summary text, the legacy key";
119
187
  /** The legacy-record observation — no requesting carrier is locatable, so the
120
188
  * judgment is skipped visibly (reading the gap as an empty input set would restore
121
189
  * an always-passing criterion). */
@@ -123,14 +191,24 @@ export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records
123
191
  /**
124
192
  * FixDispositions — the fix criterion: the round is done when its work carrier's
125
193
  * `dispositions` cover every finding of the requesting review carrier (design spec
126
- * §3.4). The input set is the REQUESTING side's carrier — the same-key same-cycle
127
- * completed review record's `carrierPath`, falling back to the fix route's
194
+ * §3.4, P30 §2.5). The input set is the REQUESTING side's carrier — the same-key
195
+ * same-cycle completed review record's `carrierPath`, falling back to the fix route's
128
196
  * `--reviews` path; the round's own `carrierPath` is never the input set.
129
197
  *
130
- * Keys are the findings' `summary` strings VERBATIM (no normalization, no
131
- * fingerprint); repeated summaries collapse to one key (one defect owes one
132
- * disposition). Values are `{ status: "fixed" | "rejected", reason?: string }` —
133
- * `rejected` without a reason is a shape violation, hard like the missing slot.
198
+ * Keys are the findings' engine-written `id`s (`F1`, `F2` … in carrier order) — the
199
+ * primary key the engine authors, so rewriting a summary no longer produces an unknown
200
+ * key. `summary` is description text: it labels the failure message (its first
201
+ * sentence) and nothing else. A LEGACY carrier that predates the `id` column carries
202
+ * none, so its `summary` stands in as the key and the round books one soft observation
203
+ * (present facts only — no carrier migration).
204
+ *
205
+ * The key-set refusal prints BOTH diffs in ONE message: the missing side (a carrier
206
+ * finding with no disposition — `id` + summary first sentence, carrier order) and the
207
+ * unknown side (a disposition no finding raised — its bare key, marked `unknown`). One
208
+ * failure therefore names everything the child has to fix.
209
+ *
210
+ * Values are `{ status: "fixed" | "rejected", reason?: string }` — `rejected` without a
211
+ * reason is a shape violation, hard like the missing slot.
134
212
  *
135
213
  * The fix round's zero-commit fact is an OBSERVATION, not a refusal: this criterion
136
214
  * answers from the carrier, never from the diff.
@@ -149,16 +227,17 @@ export class FixDispositions {
149
227
  }
150
228
  return reviewsPath;
151
229
  }
152
- /** Read the requesting carrier's input set (the summaries, deduped in order). The
153
- * read is synchronous on purpose: the input is ONE small carrier, and the dispatch
154
- * face already reads its small inputs synchronously at the same seam.
230
+ /** Read the requesting carrier's input set (the findings, deduped by disposition
231
+ * key in carrier order). The read is synchronous on purpose: the input is ONE small
232
+ * carrier, and the dispatch face already reads its small inputs synchronously at
233
+ * the same seam.
155
234
  *
156
235
  * Every path resolves against `repoRoot`, never `process.cwd()`: the engine runs
157
236
  * from a subdirectory too, `--reviews` arrives repoRoot-relative and a record's
158
237
  * `carrierPath` arrives absolute — both must land on the one basis (`RepoRoot`'s
159
238
  * rule). The reported `path` is the resolved one, so a failure names a real file. */
160
239
  static requesterInputOf(records, cycle, reviewsPath, repoRoot) {
161
- const declared = _a.requesterPathOf(records, cycle, reviewsPath);
240
+ const declared = _b.requesterPathOf(records, cycle, reviewsPath);
162
241
  if (declared === null)
163
242
  return { kind: "unrecorded" };
164
243
  const target = path.resolve(repoRoot, declared);
@@ -177,7 +256,7 @@ export class FixDispositions {
177
256
  detail: "the carrier declares no `findings` array",
178
257
  };
179
258
  }
180
- const set = _a.#summariesOf(findings);
259
+ const set = _b.#findingsOf(findings);
181
260
  if ("index" in set) {
182
261
  return {
183
262
  kind: "unreadable",
@@ -185,7 +264,7 @@ export class FixDispositions {
185
264
  detail: `finding #${set.index} carries no string \`summary\``,
186
265
  };
187
266
  }
188
- return { kind: "read", path: target, summaries: set.summaries };
267
+ return { kind: "read", path: target, findings: set.findings };
189
268
  }
190
269
  /** The carrier's `dispositions` map — null when the slot is absent or not an
191
270
  * object (the criterion's own shape refusal; the schema only pins the slot type). */
@@ -201,32 +280,32 @@ export class FixDispositions {
201
280
  const own = this.#ownRefusal(ctx);
202
281
  if (own !== null)
203
282
  return own;
204
- const requester = _a.requesterInputOf(ctx.records, ctx.record.cycle, ctx.reviewsPath, ctx.repoRoot);
283
+ const requester = _b.requesterInputOf(ctx.records, ctx.record.cycle, ctx.reviewsPath, ctx.repoRoot);
205
284
  if (requester.kind === "unrecorded")
206
285
  return this.#complete([this.#soft(FIX_DISPOSITIONS_UNRECORDED)]);
207
286
  if (requester.kind === "unreadable") {
208
287
  return this.#hard(`the requesting review carrier is missing or unreadable at ${requester.path} — ${requester.detail}`);
209
288
  }
210
- const dispositions = _a.dispositionsOf(ctx.carrier) ?? {};
211
- const refusal = _a.#keyRefusal(dispositions, requester.summaries);
289
+ const dispositions = _b.dispositionsOf(ctx.carrier) ?? {};
290
+ const refusal = _b.#keyRefusal(dispositions, requester.findings);
212
291
  if (refusal !== null)
213
292
  return this.#hard(refusal);
214
- const shape = _a.#valueRefusal(dispositions);
293
+ const shape = _b.#valueRefusal(dispositions);
215
294
  if (shape !== null)
216
295
  return this.#hard(shape);
217
- return this.#complete(await this.#observationsOf(ctx, requester.summaries));
296
+ return this.#complete(await this.#observationsOf(ctx, requester.findings));
218
297
  }
219
298
  /** The round's two summary counts — `fixed` / `rejected`, counted over the SAME
220
- * pair the judgment reads (dispositions ∩ the input set). Counts only: the
299
+ * pair the judgment reads (dispositions ∩ the input key set). Counts only: the
221
300
  * `fixed N · rejected M` line is rendered by the presentation plane
222
301
  * (`face/words.ts` template). A face fact: never stored, never a capsule key,
223
302
  * never a second read face. */
224
303
  summaryOf(carrier, input) {
225
- const wanted = new Set(input);
304
+ const wanted = new Set(input.map((finding) => _b.keyOf(finding)));
226
305
  let fixed = 0;
227
306
  let rejected = 0;
228
- for (const [summary, value] of Object.entries(_a.dispositionsOf(carrier) ?? {})) {
229
- if (!wanted.has(summary))
307
+ for (const [key, value] of Object.entries(_b.dispositionsOf(carrier) ?? {})) {
308
+ if (!wanted.has(key))
230
309
  continue;
231
310
  const status = value?.status;
232
311
  if (status === "fixed")
@@ -236,6 +315,12 @@ export class FixDispositions {
236
315
  }
237
316
  return { fixed, rejected };
238
317
  }
318
+ /** One finding's disposition key — the engine-written `id`, or the summary on a
319
+ * LEGACY carrier that carries none (`keyOf` is the ONE fallback ruling: the read,
320
+ * the judgment and the counts all derive the key here). */
321
+ static keyOf(finding) {
322
+ return finding.id ?? finding.summary;
323
+ }
239
324
  /** The round's own carrier refusals (① missing carrier, ② missing slot). */
240
325
  #ownRefusal(ctx) {
241
326
  const carrier = ctx.carrier;
@@ -245,24 +330,49 @@ export class FixDispositions {
245
330
  ? "the fix round persisted no work carrier and recorded no carrier path"
246
331
  : `the fix round persisted no work carrier at ${at}`);
247
332
  }
248
- if (_a.dispositionsOf(carrier) === null) {
333
+ if (_b.dispositionsOf(carrier) === null) {
249
334
  return this.#hard("the fix carrier declares no `dispositions` object — every requesting finding owes a fixed/rejected row");
250
335
  }
251
336
  return null;
252
337
  }
253
- /** The key-set refusals (③ missing entries, ④ unknown entries) — exact matching,
254
- * one defect one disposition. */
338
+ /** The key-set refusal — BOTH diffs in one message (P30 §2.5), each entry carrying
339
+ * what makes it actionable: the missing side names the finding by `id` + the summary's
340
+ * first sentence (carrier order), the unknown side names the bare key and marks it
341
+ * `unknown` (the carrier raised no such finding, so there is no summary to quote —
342
+ * inventing one would be worse than saying `unknown`). */
255
343
  static #keyRefusal(dispositions, input) {
256
- const wanted = new Set(input);
344
+ const wanted = new Set(input.map((finding) => _b.keyOf(finding)));
257
345
  const unknown = Object.keys(dispositions).filter((key) => !wanted.has(key));
258
- if (unknown.length > 0) {
259
- return `disposition(s) for finding(s) the requesting carrier never raised: ${unknown.join(", ")}`;
260
- }
261
- const missing = input.filter((summary) => !Object.hasOwn(dispositions, summary));
346
+ const missing = input.filter((finding) => !Object.hasOwn(dispositions, _b.keyOf(finding)));
347
+ if (unknown.length === 0 && missing.length === 0)
348
+ return null;
349
+ const parts = [];
262
350
  if (missing.length > 0) {
263
- return `no disposition for finding(s) of the requesting carrier: ${missing.join(", ")}`;
351
+ parts.push(`no disposition for finding(s) of the requesting carrier: ${missing
352
+ .map((finding) => _b.#labelOf(finding))
353
+ .join(", ")}`);
264
354
  }
265
- return null;
355
+ if (unknown.length > 0) {
356
+ parts.push(`disposition(s) for finding(s) the requesting carrier never raised: ${unknown
357
+ .map((key) => `${key} (unknown)`)
358
+ .join(", ")}`);
359
+ }
360
+ return parts.join(" · ");
361
+ }
362
+ /** One finding's failure label — an id-bearing finding reads `F2 "<summary first
363
+ * sentence>"`; a legacy finding's key IS its summary, so the sentence alone is the
364
+ * whole label. */
365
+ static #labelOf(finding) {
366
+ const sentence = _b.#firstSentence(finding.summary);
367
+ return finding.id === null ? `"${sentence}"` : `${finding.id} "${sentence}"`;
368
+ }
369
+ /** The summary's first sentence — the message's actionable excerpt (the whole summary
370
+ * is a paragraph in practice). A summary with no terminator is its own sentence; a
371
+ * leading terminator falls back to the whole line rather than an empty quote. */
372
+ static #firstSentence(summary) {
373
+ const text = summary.trim();
374
+ const cut = text.search(/[.!?。!?]/);
375
+ return cut <= 0 ? text : text.slice(0, cut + 1);
266
376
  }
267
377
  /** The value-shape refusal (⑥ `rejected` without a reason; a status outside the
268
378
  * two declared words is the same shape family). */
@@ -279,12 +389,15 @@ export class FixDispositions {
279
389
  }
280
390
  return null;
281
391
  }
282
- /** The two soft observations of a completed fix round — the empty input set and the
283
- * zero-commit round (both bookkeeping, neither a gate). */
392
+ /** The soft observations of a completed fix round — the empty input set, the legacy
393
+ * (id-less) key set and the zero-commit round (all bookkeeping, none a gate). */
284
394
  async #observationsOf(ctx, input) {
285
395
  const observations = [];
286
396
  if (input.length === 0)
287
397
  observations.push(this.#soft(FIX_DISPOSITIONS_EMPTY_INPUT));
398
+ if (input.some((finding) => finding.id === null)) {
399
+ observations.push(this.#soft(FIX_DISPOSITIONS_LEGACY_KEYS));
400
+ }
288
401
  // THIS round's own baseline — a null one (legacy fold, non-git tree) carries no
289
402
  // present fact, so the observation is simply unmeasurable, never invented.
290
403
  const base = ctx.record.dispatchBase;
@@ -295,23 +408,32 @@ export class FixDispositions {
295
408
  }
296
409
  return observations;
297
410
  }
298
- /** The deduped input set — repeated summaries collapse to one key. A finding
299
- * without a string `summary` is NOT skipped (a silently dropped finding owes no
300
- * disposition and passes forever): the caller grades it `unreadable`.
301
- * `index` is the first offending entry. */
302
- static #summariesOf(findings) {
303
- const summaries = [];
411
+ /** The deduped input set — repeated disposition KEYS collapse to one entry (a legacy
412
+ * carrier with the same summary twice owes one disposition; id-bearing findings keep
413
+ * their own keys, so distinct findings never collapse). A finding without a string
414
+ * `summary` is NOT skipped (a silently dropped finding owes no disposition and passes
415
+ * forever): the caller grades it `unreadable`. `index` is the first offending entry.
416
+ * An `id` that is absent or not a non-empty string is `null` — the legacy key, never
417
+ * an invented one. */
418
+ static #findingsOf(findings) {
419
+ const rows = [];
304
420
  const seen = new Set();
305
421
  for (const [index, finding] of findings.entries()) {
306
422
  const summary = finding?.summary;
307
423
  if (typeof summary !== "string")
308
424
  return { index };
309
- if (seen.has(summary))
425
+ const raw = finding?.id;
426
+ const row = {
427
+ id: typeof raw === "string" && raw.length > 0 ? raw : null,
428
+ summary,
429
+ };
430
+ const key = _b.keyOf(row);
431
+ if (seen.has(key))
310
432
  continue;
311
- seen.add(summary);
312
- summaries.push(summary);
433
+ seen.add(key);
434
+ rows.push(row);
313
435
  }
314
- return { summaries };
436
+ return { findings: rows };
315
437
  }
316
438
  #complete(observations) {
317
439
  return { fulfilled: true, violation: null, observations };
@@ -327,7 +449,7 @@ export class FixDispositions {
327
449
  return RoundViolation.soft(message);
328
450
  }
329
451
  }
330
- _a = FixDispositions;
452
+ _b = FixDispositions;
331
453
  /** The verb-keyed criterion registry — one criterion per op verb. A verb is
332
454
  * registered when its criterion lands (branch review folds to `review`, so it needs
333
455
  * no own row); an UNREGISTERED verb still throws at lookup, so a future verb can
@@ -458,7 +458,10 @@ const OVERALL_ELEMENTS = [
458
458
  home: "table",
459
459
  selector: SelectorSpec.table(SelectorSpec.heading("## File paths"), /^\| [^|]+ \| `[^`]+` \|$/),
460
460
  },
461
- // Change history — the version-lineage surface.
461
+ // Change history — the version-lineage surface. Both the row selector and the
462
+ // version-cell read are anchored at the FIRST column: a row's identity is a cell
463
+ // that IS `v<n>.<m>`, never prose carrying a version token. The judgment plane's
464
+ // `lineageRows` / `lineageVersion` reads hold the same anchor (`invariants.ts`).
462
465
  {
463
466
  anchor: "Change history row",
464
467
  presence: "required",
@@ -9,6 +9,8 @@
9
9
  // cross-doc-chain · section-scoped-domain ·
10
10
  // phase-design-spec-is-phase-spec;
11
11
  // the change-history family — change-history-version-unique ·
12
+ // change-history-row-shape ·
13
+ // change-history-latest-matches-front-matter ·
12
14
  // front-matter-version-in-lineage ·
13
15
  // change-history-row-not-in-other-table · list-marker-not-doubled;
14
16
  // the identity legs — task-id-unique · phase-id-unique;
@@ -153,21 +155,56 @@ export class Invariant extends MarkdownPrimitives {
153
155
  }
154
156
  /** The doc's `## Change history` table — the ONE lineage read face all four doc
155
157
  * types expose (each parse record carries it, filled by the same table-section
156
- * read). The change-history strategies read ONLY through this accessor. */
158
+ * read). The change-history strategies read ONLY through this accessor. The
159
+ * record keeps the header and the body rows verbatim: a row whose cell count
160
+ * disagrees with the header is judged by `change-history-row-shape`, never
161
+ * repaired or dropped here. */
157
162
  changeHistory(ctx) {
158
163
  return ctx.parsed.tables["Change history"];
159
164
  }
160
- /** The first `vX.Y` version token on a line — the lineage row's identity read. */
161
- firstVersion(text) {
162
- const match = text.match(/v\d+\.\d+/);
163
- return match === null ? null : match[0];
165
+ /** The version token of a lineage row — the FIRST cell read ANCHORED: the cell must
166
+ * BE the version, never merely carry one (an in-cell prose mention of `spec v0.4`
167
+ * is not an identity). */
168
+ lineageVersion(row) {
169
+ const cell = (row[0] ?? "").trim();
170
+ return /^v\d+\.\d+$/.test(cell) ? cell : null;
171
+ }
172
+ /** The change-history rows that ARE lineage rows — the ones whose cell count matches
173
+ * the table's column header. A row whose cells disagree with the header (a
174
+ * hard-wrapped cell) is a SHAPE fact — reported by `change-history-row-shape`,
175
+ * never silently read as a lineage identity. Duplicate detection and the
176
+ * newest-row leg read ONLY this set. */
177
+ lineageRows(ctx) {
178
+ const table = this.changeHistory(ctx);
179
+ const width = table.headerRow?.length ?? 0;
180
+ if (width === 0)
181
+ return [];
182
+ return table.rows.filter((row) => row.length === width);
183
+ }
184
+ /** The anchored cell-0 versions of EVERY change-history body row, whatever its width.
185
+ * Membership is the one read a shape-ragged row must not starve: when the header
186
+ * version lives only on the newest row and that row hard-wraps, the version is still
187
+ * the document's own lineage (its shape is a separate defect).
188
+ * `front-matter-version-in-lineage` reads this set; the duplicate and newest-row legs
189
+ * keep `historyVersions`. */
190
+ membershipVersions(ctx) {
191
+ return this.changeHistory(ctx)
192
+ .rows.map((row) => this.lineageVersion(row))
193
+ .filter((version) => version !== null);
194
+ }
195
+ /** The numeric comparison rank of a version token — the lineage's newest row is a
196
+ * NUMERIC read (`v0.10` outranks `v0.9`), never a lexical one. */
197
+ versionRank(version) {
198
+ const [major, minor] = version.replace(/^v/, "").split(".");
199
+ return Number(major) * 1_000_000 + Number(minor);
164
200
  }
165
201
  /** The doc's Change-history row versions, in row order — the ONE lineage identity
166
- * read every lineage strategy shares (one copy on the base, zero per-strategy
167
- * private duplicates). */
202
+ * read the duplicate and newest-row strategies share (one copy on the base, zero
203
+ * per-strategy private duplicates). Header-width rows only: a shape-ragged row is
204
+ * no lineage identity (membership's wider read is `membershipVersions`). */
168
205
  historyVersions(ctx) {
169
- return this.changeHistory(ctx)
170
- .rows.map((row) => this.firstVersion(row[0] ?? ""))
206
+ return this.lineageRows(ctx)
207
+ .map((row) => this.lineageVersion(row))
171
208
  .filter((version) => version !== null);
172
209
  }
173
210
  /** The identity index every slug-keyed strategy looks up through — the caller's
@@ -382,17 +419,54 @@ export class ChangeHistoryVersionUniqueInvariant extends Invariant {
382
419
  evaluate(ctx) {
383
420
  const findings = [];
384
421
  const seenVersions = new Set();
385
- for (const row of this.changeHistory(ctx).rows) {
386
- const version = this.firstVersion(row[0] ?? "");
387
- if (version !== null && seenVersions.has(version)) {
422
+ for (const version of this.historyVersions(ctx)) {
423
+ if (seenVersions.has(version)) {
388
424
  findings.push(this.finding(ctx, "Change history", `duplicate change-history version: ${version} registers more than once`, "keep each lineage version in exactly one Change-history row"));
389
425
  }
390
- if (version !== null)
391
- seenVersions.add(version);
426
+ seenVersions.add(version);
392
427
  }
393
428
  return findings;
394
429
  }
395
430
  }
431
+ /** change-history-row-shape — a Change-history body row whose cell count disagrees with
432
+ * the table's column header is a rendering defect (a hard-wrapped cell parsed as its
433
+ * own row). The row is REPORTED, never silently dropped from the lineage read. */
434
+ export class ChangeHistoryRowShapeInvariant extends Invariant {
435
+ name = "change-history-row-shape";
436
+ evaluate(ctx) {
437
+ const table = this.changeHistory(ctx);
438
+ const width = table.headerRow?.length ?? 0;
439
+ if (width === 0)
440
+ return [];
441
+ const findings = [];
442
+ for (const row of table.rows) {
443
+ if (row.length === width)
444
+ continue;
445
+ findings.push(this.finding(ctx, "Change history", `a Change-history row carries ${row.length} cells against the ${width}-column header`, "keep the row on one line — a hard-wrapped cell parses as a row of its own"));
446
+ }
447
+ return findings;
448
+ }
449
+ }
450
+ /** change-history-latest-matches-front-matter — the front-matter `version:` IS the
451
+ * lineage's newest numeric version: appending a row lifts both in the same edit, so
452
+ * the two sides can never disagree. */
453
+ export class ChangeHistoryLatestMatchesFrontMatterInvariant extends Invariant {
454
+ name = "change-history-latest-matches-front-matter";
455
+ evaluate(ctx) {
456
+ const headerVersion = ctx.head.version;
457
+ if (headerVersion === null)
458
+ return [];
459
+ const versions = this.historyVersions(ctx);
460
+ if (versions.length === 0)
461
+ return [];
462
+ const latest = versions.reduce((newest, version) => this.versionRank(version) > this.versionRank(newest) ? version : newest);
463
+ if (latest === headerVersion)
464
+ return [];
465
+ return [
466
+ this.finding(ctx, "version", `the header version ${headerVersion} is not the newest lineage version ${latest}`, `align the two in one edit — bump the version front-matter key to ${latest}, or add the row that reaches ${headerVersion}`),
467
+ ];
468
+ }
469
+ }
396
470
  /** task-id-unique — every `### Task N:` id registers exactly once (plan). */
397
471
  export class TaskIdUniqueInvariant extends Invariant {
398
472
  name = "task-id-unique";
@@ -762,20 +836,22 @@ export class HollowInvariant extends Invariant {
762
836
  * the endpoints and the age of the row carrying the value are the author's
763
837
  * presentation choice, never a judgment input (a newest-first lineage, a
764
838
  * non-monotone frozen history and an ascending one all judge the same). The fix
765
- * names the header key, never a row to reorder. */
839
+ * names the header key, never a row to reorder. Membership reads EVERY body row's
840
+ * anchored cell 0 (`membershipVersions`), so a version carried only by a
841
+ * shape-ragged row still counts as lineage. */
766
842
  export class FrontMatterVersionInLineageInvariant extends Invariant {
767
843
  name = "front-matter-version-in-lineage";
768
844
  evaluate(ctx) {
769
845
  const headerVersion = ctx.head.version;
770
846
  if (headerVersion === null)
771
847
  return [];
772
- const historyVersions = this.historyVersions(ctx);
773
- if (historyVersions.length === 0)
848
+ const membership = this.membershipVersions(ctx);
849
+ if (membership.length === 0)
774
850
  return [];
775
- if (historyVersions.includes(headerVersion))
851
+ if (membership.includes(headerVersion))
776
852
  return [];
777
853
  return [
778
- this.finding(ctx, "version", `the header version ${headerVersion} is outside the document's own lineage`, `the version front-matter key must belong to the Change-history row versions: ${historyVersions.join(", ")}`),
854
+ this.finding(ctx, "version", `the header version ${headerVersion} is outside the document's own lineage`, `the version front-matter key must belong to the Change-history row versions: ${membership.join(", ")}`),
779
855
  ];
780
856
  }
781
857
  }
@@ -17,14 +17,16 @@
17
17
  // list — these declarations are the rule surface. One rule = one strategy: the
18
18
  // multi-surface strategies of the old family were split per leg (uniqueness → three,
19
19
  // order → one section-order row, selfBounded → one lineage row), so a declaration row
20
- // never hides a second rule. The version-order leg and the header-equals-last-row leg
21
- // are not declared at all: ordering is presentation, not data integrity, and the
22
- // lineage judgment is membership-only.
20
+ // never hides a second rule. Version ORDER stays presentation, not data integrity; the
21
+ // header-to-newest-row agreement and the row's cell shape are declared legs of their
22
+ // own (`change-history-latest-matches-front-matter` · `change-history-row-shape`), and
23
+ // the lineage identity read is membership-plus-anchor (the first cell must BE a
24
+ // version).
23
25
  //
24
26
  // Module-level exports are types / the declared data — zero behavior-carrying bare
25
27
  // functions.
26
- import { ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
27
- /** The rule registry — doc scope 21 rows + ledger scope 2 rows = 23. */
28
+ import { ChangeHistoryLatestMatchesFrontMatterInvariant, ChangeHistoryRowShapeInvariant, ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
29
+ /** The rule registry — doc scope 23 rows + ledger scope 2 rows = 25. */
28
30
  export const RULE_REGISTRY = [
29
31
  { scope: "doc", id: "presence", docKeys: "all", create: () => new PresenceInvariant() },
30
32
  {
@@ -33,6 +35,18 @@ export const RULE_REGISTRY = [
33
35
  docKeys: "all",
34
36
  create: () => new ChangeHistoryVersionUniqueInvariant(),
35
37
  },
38
+ {
39
+ scope: "doc",
40
+ id: "change-history-row-shape",
41
+ docKeys: "all",
42
+ create: () => new ChangeHistoryRowShapeInvariant(),
43
+ },
44
+ {
45
+ scope: "doc",
46
+ id: "change-history-latest-matches-front-matter",
47
+ docKeys: "all",
48
+ create: () => new ChangeHistoryLatestMatchesFrontMatterInvariant(),
49
+ },
36
50
  { scope: "doc", id: "task-id-unique", docKeys: "all", create: () => new TaskIdUniqueInvariant() },
37
51
  {
38
52
  scope: "doc",