@oscaner-skills/cdd-engine 4.7.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.
- package/dist/contract/completion-criterion.js +179 -57
- package/dist/contract/declare.js +4 -1
- package/dist/contract/invariants.js +95 -19
- package/dist/contract/rules.js +19 -5
- package/dist/contract/task-blocks.js +46 -0
- package/dist/face/cli.js +92 -7
- package/dist/face/declare.js +5 -9
- package/dist/face/lifecycle.js +122 -14
- package/dist/face/preview.js +1 -1
- package/dist/face/words.js +4 -4
- package/dist/render/templates.js +13 -4
- package/dist/session/dispatch-authority.js +58 -10
- package/dist/session/handoff-schema.js +8 -1
- package/dist/session/inflight.js +44 -18
- package/dist/session/ledger.js +50 -3
- package/dist/session/preflight.js +5 -5
- package/package.json +1 -1
|
@@ -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
|
|
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
|
|
13
|
-
// filled by `CliLifecycle` — this module pins the
|
|
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 =
|
|
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
|
|
60
|
-
return this.#
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
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' `
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
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
|
|
153
|
-
* read is synchronous on purpose: the input is ONE small
|
|
154
|
-
* face already reads its small inputs synchronously at
|
|
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 =
|
|
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 =
|
|
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,
|
|
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 =
|
|
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 =
|
|
211
|
-
const refusal =
|
|
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 =
|
|
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.
|
|
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 [
|
|
229
|
-
if (!wanted.has(
|
|
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 (
|
|
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
|
|
254
|
-
*
|
|
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
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
const
|
|
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
|
-
|
|
351
|
+
parts.push(`no disposition for finding(s) of the requesting carrier: ${missing
|
|
352
|
+
.map((finding) => _b.#labelOf(finding))
|
|
353
|
+
.join(", ")}`);
|
|
264
354
|
}
|
|
265
|
-
|
|
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
|
|
283
|
-
* zero-commit round (
|
|
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
|
|
299
|
-
*
|
|
300
|
-
*
|
|
301
|
-
* `
|
|
302
|
-
|
|
303
|
-
|
|
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
|
-
|
|
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(
|
|
312
|
-
|
|
433
|
+
seen.add(key);
|
|
434
|
+
rows.push(row);
|
|
313
435
|
}
|
|
314
|
-
return {
|
|
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
|
-
|
|
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
|
package/dist/contract/declare.js
CHANGED
|
@@ -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
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
|
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.
|
|
170
|
-
.
|
|
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
|
|
386
|
-
|
|
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
|
-
|
|
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
|
|
773
|
-
if (
|
|
848
|
+
const membership = this.membershipVersions(ctx);
|
|
849
|
+
if (membership.length === 0)
|
|
774
850
|
return [];
|
|
775
|
-
if (
|
|
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: ${
|
|
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
|
}
|
package/dist/contract/rules.js
CHANGED
|
@@ -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.
|
|
21
|
-
//
|
|
22
|
-
//
|
|
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
|
|
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",
|