@oscaner-skills/cdd-engine 4.13.0 → 4.14.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/census.js +134 -0
- package/dist/contract/pins.js +893 -0
- package/dist/contract/review-criteria.js +332 -0
- package/dist/face/board-view.js +88 -13
- package/dist/face/capsule.js +7 -5
- package/dist/face/cli.js +14 -2
- package/dist/face/lifecycle.js +184 -12
- package/dist/render/templates.js +73 -14
- package/dist/session/handoff-schema.js +137 -5
- package/dist/session/ledger.js +7 -9
- package/dist/session/round-artifacts.js +10 -0
- package/dist/session/run.js +5 -3
- package/package.json +1 -1
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/contract/review-criteria.ts
|
|
2
|
+
// P37 T1 — the grading criteria registry (design spec §1, §6.1): the three tier
|
|
3
|
+
// boundaries with their evidence duty and their counterexample live as ROWS, and
|
|
4
|
+
// `SEVERITY_RUBRIC` is assembled from them. The prose is therefore no longer a
|
|
5
|
+
// second copy of the criteria — the registry is the only corpus that reaches the
|
|
6
|
+
// rubric's tier body.
|
|
7
|
+
//
|
|
8
|
+
// One row carries three executable cells: `body` (the boundary), `duty` (what the
|
|
9
|
+
// grader owes that tier) and `counterExample` (the neighbouring tier's edge, stated
|
|
10
|
+
// as a sentence a reviewer can match a finding against). Assembly reads all three:
|
|
11
|
+
// a cell that renders nothing would retire either the evidence duty or the
|
|
12
|
+
// counterexample, which is exactly the long-prose failure this registry replaces.
|
|
13
|
+
//
|
|
14
|
+
// Two distinct validation contracts, both required (design spec §6.1):
|
|
15
|
+
// · the row SHAPE is the type — every row is a `readonly` literal with all six
|
|
16
|
+
// cells (`id` / `tier` / `body` / `duty` / `counterExample` / `face`), so
|
|
17
|
+
// deleting a key is a `tsc` error, not a runtime throw;
|
|
18
|
+
// · the CELL CONTENT is judged at assembly — a cell that is blank after `trim()`,
|
|
19
|
+
// or a tier with no row at all, throws out of `renderRubric()`.
|
|
20
|
+
//
|
|
21
|
+
// `face` declares the extra execution surface a row is wired to (design spec §6.2):
|
|
22
|
+
// `numbered` rows appear in the rendered rubric itself, a `gate` row's `id` is the
|
|
23
|
+
// word its mechanical gate prints, and a `test` row's `id` is named by a test title.
|
|
24
|
+
// The face is a declaration about wiring; the three prose cells reach the rubric
|
|
25
|
+
// bytes for EVERY row regardless of face.
|
|
26
|
+
//
|
|
27
|
+
// Display wording is NOT a rubric cell. The downgrade mark (design spec §5.2) is a
|
|
28
|
+
// token the board and the capsule print, not a sentence a grader calibrates against:
|
|
29
|
+
// it rides `REGRADE_MARK` below, so the nit tier's prose stays a run of sentences and
|
|
30
|
+
// a display fragment can never splice into it.
|
|
31
|
+
//
|
|
32
|
+
// P37 T2 — the SECOND table (design spec §3.1, §6.1): the lens question rows. One row
|
|
33
|
+
// asks what counts as crossing into functional impact under one lens; the row carries
|
|
34
|
+
// no `tier`, no `duty` and no `counterExample`, because a question never grades — the
|
|
35
|
+
// reviewer answers it along the tier ladder above. `wave` and `branch` share their four
|
|
36
|
+
// questions by declaring both kinds on ONE row (`reviewKinds`), so the shared text is
|
|
37
|
+
// stored once: 15 physical rows cover 19 (review kind, lens) cells.
|
|
38
|
+
//
|
|
39
|
+
// `face` is `numbered` on every row: the question's only execution surface is the
|
|
40
|
+
// rendered review prompt. `LENS_QUESTIONS.forReviewKind` expands each shared row per
|
|
41
|
+
// declared kind in declaration order, and `render/templates.ts` folds that projection
|
|
42
|
+
// into the review's `**Criteria —` line as a `1. …` list.
|
|
43
|
+
//
|
|
44
|
+
// The two tables never merge: a question carries no verdict columns, and a criteria row
|
|
45
|
+
// carries no question — asking one table for the other's row is an unregistered lookup
|
|
46
|
+
// and throws.
|
|
47
|
+
//
|
|
48
|
+
// Module-level exports are types / the declared tables / the registry instances — zero
|
|
49
|
+
// behavior-carrying bare functions.
|
|
50
|
+
/** The tier order the rubric assembles in — the ladder a grader answers in order. */
|
|
51
|
+
export const TIER_ORDER = ["blocker", "warn", "nit"];
|
|
52
|
+
/** The cell names, in assembly order — the message names the blank cell. */
|
|
53
|
+
const CELLS = ["body", "duty", "counterExample"];
|
|
54
|
+
/** The downgrade mark's ONE spelling (design spec §5.2) — the display wording the
|
|
55
|
+
* board's verb token and the capsule summary line print. It is declared here beside
|
|
56
|
+
* the criteria table because the mark has exactly one source (never a second copy at
|
|
57
|
+
* a render site), and it is deliberately NOT a rubric cell: a display token has no
|
|
58
|
+
* place in the tier prose a grader calibrates against. */
|
|
59
|
+
export const REGRADE_MARK = "downgraded without a regrade reason";
|
|
60
|
+
/** The separator between two downgrade notes on ONE face — the mark and a stated
|
|
61
|
+
* reason are two sentences, never one spliced phrase. */
|
|
62
|
+
export const REGRADE_NOTE_SEPARATOR = "; ";
|
|
63
|
+
/** The board's ` · ` cell shape — a reason carrying it would read as two cells on the
|
|
64
|
+
* ONE token §5.2 pins as one row. */
|
|
65
|
+
const BOARD_CELL_SHAPE = / *· */g;
|
|
66
|
+
/** Whitespace runs and control characters — a reason carrying a line break would split
|
|
67
|
+
* the capsule's one line and the board's one token into two. */
|
|
68
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: the control-character range IS the rule here — a display token may not carry a line break or a raw C0 byte.
|
|
69
|
+
const DISPLAY_BREAKS = /[\s\u0000-\u001f\u007f]+/g;
|
|
70
|
+
/** One stated reason folded to its display form: the author's bytes stay on the carrier,
|
|
71
|
+
* only the printed wording is collapsed so neither face can split on it. */
|
|
72
|
+
const displayReason = (reason) => reason.replace(BOARD_CELL_SHAPE, "; ").replace(DISPLAY_BREAKS, " ").trim();
|
|
73
|
+
/** The downgrade note's ONE composition (design spec §5.2) — both display faces take
|
|
74
|
+
* their bytes from here, so the mark and the stated reason cannot drift apart: a row
|
|
75
|
+
* that owes its reason prints the mark, a row that states one prints the reason, and
|
|
76
|
+
* a round with neither prints nothing at all. A stated reason is folded first, so a
|
|
77
|
+
* line break or the board's own ` · ` never splits the one line / one token it rides. */
|
|
78
|
+
export const regradeNote = (owing, reasons) => {
|
|
79
|
+
const stated = reasons.map(displayReason).filter((reason) => reason.length > 0);
|
|
80
|
+
const parts = [...(owing > 0 ? [REGRADE_MARK] : []), ...stated];
|
|
81
|
+
return parts.length === 0 ? undefined : parts.join(REGRADE_NOTE_SEPARATOR);
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* The declared criteria table. Every tier owes at least one row; the `warn` tier
|
|
85
|
+
* carries two (the debt boundary and the pin parseability gate of §7.4), and the
|
|
86
|
+
* `nit` tier carries two (the expression boundary and the downgrade mark of §5.2).
|
|
87
|
+
*/
|
|
88
|
+
export const CRITERIA_ROWS = [
|
|
89
|
+
{
|
|
90
|
+
id: "grading-impact-missing",
|
|
91
|
+
tier: "blocker",
|
|
92
|
+
body: "A finding is a blocker when the functional result departs from expectation or sows a functional defect: the bytes, exit code or rendering a consumer receives contradict the declared contract, or a legal input reaches an undeclared outcome. The four typical instances: a declared acceptance gate, contract or prompt is violated where the consumer can see it; a legal input escapes the declared failure face (a blank input returns 500, an unknown id is not a 404); the gate fails or the suite can never go red (an inert grep · a dead guard · an unconditional skip); a security or privacy defect. Violating a written sentence while the bytes a consumer receives stay unchanged is a warn, not a blocker — citing a clause is not the same as affecting behaviour.",
|
|
93
|
+
duty: "A blocker owes a reproducible scenario: the legal input or condition → what actually happens → what was expected, one sentence the next reviewer can refute on the spot.",
|
|
94
|
+
counterExample: "A deviation you can describe but cannot back with a scenario (which legal input → what actually happens → what was expected) is a warn, not a blocker: an unrefutable deviation is not yet a functional impact, so the finding is graded by the consequence its own description states.",
|
|
95
|
+
face: "gate",
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
id: "debt-consequence",
|
|
99
|
+
tier: "warn",
|
|
100
|
+
body: "A finding is a warn when it leaves this round's functional result unchanged but makes the next person do the wrong thing: debt (a duplicated policy · a stale docstring · a missing coverage case), a misleading claim no consumer is hurt by, a gap nobody verifies, or dead code that tempts a later reader to believe it still runs.",
|
|
101
|
+
duty: "A warn owes the consequence: not a failure today, but who will take which step wrongly, and when.",
|
|
102
|
+
counterExample: "Dead code that nothing calls today and no output depends on is a warn, not a nit: it changes what the next reader believes, which is the warn / nit boundary itself.",
|
|
103
|
+
face: "numbered",
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
id: "pin-parseability",
|
|
107
|
+
tier: "warn",
|
|
108
|
+
body: "A pin that resolves nowhere is a warn: an unresolvable path, symbol or test title leaves a claim nobody can re-check, while the bytes a consumer receives stay unchanged.",
|
|
109
|
+
duty: "A pin finding owes the consequence: the next reader either trusts the claim blindly or drops it, and either way the document loses a coordinate.",
|
|
110
|
+
counterExample: "P28 withdrew the old docs-validation gate as too heavy and left legality to the dispatch gate, which judges document structure and never pin coordinates; this gate returns in its narrow form, so a pin is judged on its own three shapes (a path segment, a symbol, a test title) only — never document structure, never semantics, never the whole docs corpus — and a `contract.path` belongs to the handoff read-back corpus, which `PinAudit` never carries.",
|
|
111
|
+
face: "test",
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
id: "expression-only",
|
|
115
|
+
tier: "nit",
|
|
116
|
+
body: "A finding is a nit when it is pure expression: naming, line-wrapping, comment wording, ordering inside one file — it changes neither behaviour nor anyone's judgment.",
|
|
117
|
+
duty: "A nit owes why it is not a warn: one sentence saying which judgment it leaves untouched.",
|
|
118
|
+
counterExample: "A naming inconsistency that stays self-consistent inside one file is a nit, not a warn: no cross-surface reader is misled.",
|
|
119
|
+
face: "numbered",
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
id: "regrade-mark",
|
|
123
|
+
tier: "nit",
|
|
124
|
+
body: "A finding is downgraded without a regrade reason when the same defect returns one tier lower and the new round states no reason for the change: the reader can no longer tell a re-grade from a changed defect, while the round's own conclusion stays what it was.",
|
|
125
|
+
duty: "The mark is a display fact: it rides the board's verb token after its `+N` count and the capsule summary line, never a finding row, never a carrier entry, and never the round's conclusion.",
|
|
126
|
+
counterExample: "A downgrade whose previous round carried no scenario has no reference to hold it against, so the finding is read as a changed defect and carries no mark.",
|
|
127
|
+
face: "numbered",
|
|
128
|
+
},
|
|
129
|
+
];
|
|
130
|
+
/**
|
|
131
|
+
* The criteria registry — the lookup face (`of`, an unregistered id throws) and the
|
|
132
|
+
* rubric assembly (`renderRubric`). Both preserve the declared order: same-tier rows
|
|
133
|
+
* sit adjacent, and the tiers run blocker → warn → nit.
|
|
134
|
+
*/
|
|
135
|
+
export class CriteriaRegistry {
|
|
136
|
+
#rows;
|
|
137
|
+
constructor(rows = CRITERIA_ROWS) {
|
|
138
|
+
this.#rows = rows;
|
|
139
|
+
}
|
|
140
|
+
/** The declared rows, in declaration order — the structural test's row census. */
|
|
141
|
+
get rows() {
|
|
142
|
+
return this.#rows;
|
|
143
|
+
}
|
|
144
|
+
/** One row by id — an unregistered id throws, so a gate or a test that names a
|
|
145
|
+
* criterion can never quietly read nothing. */
|
|
146
|
+
of(id) {
|
|
147
|
+
const row = this.#rows.find((candidate) => candidate.id === id);
|
|
148
|
+
if (row === undefined) {
|
|
149
|
+
throw new Error(`no grading criterion is registered under "${id}"`);
|
|
150
|
+
}
|
|
151
|
+
return row;
|
|
152
|
+
}
|
|
153
|
+
/** The tier body the rubric is assembled from: each row contributes its three
|
|
154
|
+
* cells in the fixed order `body` → `duty` → `counterExample`, one space apart;
|
|
155
|
+
* same-tier rows join in declaration order, and the tiers run blocker → warn →
|
|
156
|
+
* nit. A blank cell or an empty tier throws — no tier fragment ever renders
|
|
157
|
+
* short of a sentence. */
|
|
158
|
+
renderRubric() {
|
|
159
|
+
const tiers = [];
|
|
160
|
+
for (const tier of TIER_ORDER) {
|
|
161
|
+
const rows = this.#rows.filter((row) => row.tier === tier);
|
|
162
|
+
if (rows.length === 0) {
|
|
163
|
+
throw new Error(`the criteria registry declares no "${tier}" row — every tier owes one`);
|
|
164
|
+
}
|
|
165
|
+
tiers.push(rows
|
|
166
|
+
.map((row) => this.#fragmentOf(row))
|
|
167
|
+
.join(" ")
|
|
168
|
+
.trim());
|
|
169
|
+
}
|
|
170
|
+
return tiers.join(" ");
|
|
171
|
+
}
|
|
172
|
+
/** One row's rubric fragment — its three cells, each trimmed, each required. */
|
|
173
|
+
#fragmentOf(row) {
|
|
174
|
+
const cells = [row.body, row.duty, row.counterExample].map((cell) => cell.trim());
|
|
175
|
+
for (const [index, cell] of cells.entries()) {
|
|
176
|
+
if (cell.length === 0) {
|
|
177
|
+
throw new Error(`criteria row "${row.id}" leaves its ${CELLS[index]} cell blank — every cell reaches the rubric`);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
return cells.join(" ");
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
/** The process-wide registry — the one table every consumer reads. */
|
|
184
|
+
export const CRITERIA = new CriteriaRegistry();
|
|
185
|
+
/** The declared lens question table (§3.1's nineteen cells). The four wave / branch
|
|
186
|
+
* rows lead (shared text, one copy), then plan, spec and the charter's five. */
|
|
187
|
+
export const LENS_QUESTION_ROWS = [
|
|
188
|
+
{
|
|
189
|
+
id: "standards-lens",
|
|
190
|
+
reviewKinds: ["wave", "branch"],
|
|
191
|
+
lens: "standards",
|
|
192
|
+
question: "Does the change break the repository's own standard on a surface a consumer reads — a public shape, prompt bytes, a documented command, or a contract an existing test pins?",
|
|
193
|
+
face: "numbered",
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
id: "spec-lens",
|
|
197
|
+
reviewKinds: ["wave", "branch"],
|
|
198
|
+
lens: "spec",
|
|
199
|
+
question: "Does the change depart from the reviewed contract (the wave brief / plan / design spec) while the behaviour a consumer receives changes with it?",
|
|
200
|
+
face: "numbered",
|
|
201
|
+
},
|
|
202
|
+
{
|
|
203
|
+
id: "buildability-lens",
|
|
204
|
+
reviewKinds: ["wave", "branch"],
|
|
205
|
+
lens: "buildability",
|
|
206
|
+
question: "Is the reviewer's own typecheck / test run red, or would it go red on a path the plan declares?",
|
|
207
|
+
face: "numbered",
|
|
208
|
+
},
|
|
209
|
+
{
|
|
210
|
+
id: "scope-lens",
|
|
211
|
+
reviewKinds: ["wave", "branch"],
|
|
212
|
+
lens: "scope",
|
|
213
|
+
question: "Does the change land outside the wave brief's `**Files:**` surface and the plan's intent, and is that out-of-scope change consumed?",
|
|
214
|
+
face: "numbered",
|
|
215
|
+
},
|
|
216
|
+
{
|
|
217
|
+
id: "plan-completeness",
|
|
218
|
+
reviewKinds: ["plan"],
|
|
219
|
+
lens: "completeness",
|
|
220
|
+
question: "Is a spec requirement owned by no task, so implementation skips it silently and the requirement never ships?",
|
|
221
|
+
face: "numbered",
|
|
222
|
+
},
|
|
223
|
+
{
|
|
224
|
+
id: "plan-decomposition",
|
|
225
|
+
reviewKinds: ["plan"],
|
|
226
|
+
lens: "decomposition",
|
|
227
|
+
question: "Does the task granularity make a step impossible to verify on its own, so a defect crosses steps with nobody noticing?",
|
|
228
|
+
face: "numbered",
|
|
229
|
+
},
|
|
230
|
+
{
|
|
231
|
+
id: "plan-buildability",
|
|
232
|
+
reviewKinds: ["plan"],
|
|
233
|
+
lens: "buildability",
|
|
234
|
+
question: "Is a step of the plan not executable against the tree as it stands — a missing prerequisite, a command that does not exist, an order no edge permits?",
|
|
235
|
+
face: "numbered",
|
|
236
|
+
},
|
|
237
|
+
{
|
|
238
|
+
id: "spec-completeness",
|
|
239
|
+
reviewKinds: ["spec"],
|
|
240
|
+
lens: "completeness",
|
|
241
|
+
question: "Is a condition that must hold left unwritten, so the downstream author can only guess — and guessing wrong changes behaviour?",
|
|
242
|
+
face: "numbered",
|
|
243
|
+
},
|
|
244
|
+
{
|
|
245
|
+
id: "spec-consistency",
|
|
246
|
+
reviewKinds: ["spec"],
|
|
247
|
+
lens: "consistency",
|
|
248
|
+
question: "Do two places state the same fact differently, so the downstream reader goes wrong whichever one is taken?",
|
|
249
|
+
face: "numbered",
|
|
250
|
+
},
|
|
251
|
+
{
|
|
252
|
+
id: "spec-clarity",
|
|
253
|
+
reviewKinds: ["spec"],
|
|
254
|
+
lens: "clarity",
|
|
255
|
+
question: "Can a statement be read two reasonable ways, and do the two readings derive different implementations?",
|
|
256
|
+
face: "numbered",
|
|
257
|
+
},
|
|
258
|
+
{
|
|
259
|
+
id: "overall-scope",
|
|
260
|
+
reviewKinds: ["overall"],
|
|
261
|
+
lens: "scope",
|
|
262
|
+
question: "Does the phase's scope descend to implementation detail, leaving the increment that phase delivers undecidable?",
|
|
263
|
+
face: "numbered",
|
|
264
|
+
},
|
|
265
|
+
{
|
|
266
|
+
id: "overall-inventory",
|
|
267
|
+
reviewKinds: ["overall"],
|
|
268
|
+
lens: "inventory",
|
|
269
|
+
question: 'Does the registry disagree with the tree, so "delivered" stops being credible?',
|
|
270
|
+
face: "numbered",
|
|
271
|
+
},
|
|
272
|
+
{
|
|
273
|
+
id: "overall-dependency",
|
|
274
|
+
reviewKinds: ["overall"],
|
|
275
|
+
lens: "dependency",
|
|
276
|
+
question: "Does a dependency edge disagree with the actual serial order, so the schedule collides?",
|
|
277
|
+
face: "numbered",
|
|
278
|
+
},
|
|
279
|
+
{
|
|
280
|
+
id: "overall-acceptance",
|
|
281
|
+
reviewKinds: ["overall"],
|
|
282
|
+
lens: "acceptance",
|
|
283
|
+
question: "Is an acceptance cell undecidable when the phase closes?",
|
|
284
|
+
face: "numbered",
|
|
285
|
+
},
|
|
286
|
+
{
|
|
287
|
+
id: "overall-boundary",
|
|
288
|
+
reviewKinds: ["overall"],
|
|
289
|
+
lens: "boundary",
|
|
290
|
+
question: "Is a non-goal drawn so loosely that it filters nothing?",
|
|
291
|
+
face: "numbered",
|
|
292
|
+
},
|
|
293
|
+
];
|
|
294
|
+
/**
|
|
295
|
+
* The lens question registry — the lookup face (`of`, unregistered throws) and the
|
|
296
|
+
* per-kind projection (`forReviewKind`, a shared row expanded once per declared kind).
|
|
297
|
+
* Both preserve declaration order, and a blank question throws on projection rather
|
|
298
|
+
* than rendering an empty list item.
|
|
299
|
+
*/
|
|
300
|
+
export class LensQuestionRegistry {
|
|
301
|
+
#rows;
|
|
302
|
+
constructor(rows = LENS_QUESTION_ROWS) {
|
|
303
|
+
this.#rows = rows;
|
|
304
|
+
}
|
|
305
|
+
/** The declared rows, in declaration order — the structural test's row census. */
|
|
306
|
+
get rows() {
|
|
307
|
+
return this.#rows;
|
|
308
|
+
}
|
|
309
|
+
/** One cell by (review kind, lens) — an unregistered pair throws, so a review’s
|
|
310
|
+
* criteria line can never read a question that was never declared. */
|
|
311
|
+
of(reviewKind, lens) {
|
|
312
|
+
const row = this.#rows.find((candidate) => candidate.reviewKinds.includes(reviewKind) && candidate.lens === lens);
|
|
313
|
+
if (row === undefined) {
|
|
314
|
+
throw new Error(`no lens question is registered for ${reviewKind} · ${lens}`);
|
|
315
|
+
}
|
|
316
|
+
return row;
|
|
317
|
+
}
|
|
318
|
+
/** One review kind's questions in rendering order — every row whose `reviewKinds`
|
|
319
|
+
* names the kind, in declaration order, a shared row expanded once per kind. A
|
|
320
|
+
* blank question throws: the list is prompt bytes, never an empty item. */
|
|
321
|
+
forReviewKind(reviewKind) {
|
|
322
|
+
const rows = this.#rows.filter((row) => row.reviewKinds.includes(reviewKind));
|
|
323
|
+
for (const row of rows) {
|
|
324
|
+
if (row.question.trim().length === 0) {
|
|
325
|
+
throw new Error(`lens question "${row.id}" is blank — every row reaches the prompt`);
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
return rows;
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
/** The process-wide lens question registry — the one table the prompt plane reads. */
|
|
332
|
+
export const LENS_QUESTIONS = new LensQuestionRegistry();
|
package/dist/face/board-view.js
CHANGED
|
@@ -34,10 +34,12 @@
|
|
|
34
34
|
//
|
|
35
35
|
// Module-level exports are types / constants / the classes — zero behavior-carrying
|
|
36
36
|
// bare functions (the plan's zero-bare-function discipline).
|
|
37
|
+
var _a;
|
|
37
38
|
import { readFileSync } from "node:fs";
|
|
38
39
|
import path from "node:path";
|
|
39
40
|
import { FrontMatterExtractor } from "../contract/frontmatter.js";
|
|
40
41
|
import { DOC_KEYS } from "../contract/project.js";
|
|
42
|
+
import { REGRADE_NOTE_SEPARATOR, regradeNote } from "../contract/review-criteria.js";
|
|
41
43
|
import { ConfigLoader } from "../infra/config.js";
|
|
42
44
|
import { RepoRoot } from "../infra/root.js";
|
|
43
45
|
import { ENGINE_RUNTIME } from "../infra/runtime.js";
|
|
@@ -45,7 +47,8 @@ import { SlugIndex } from "../infra/slug-index.js";
|
|
|
45
47
|
import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
|
|
46
48
|
import { ArtifactReads } from "../session/artifact-reads.js";
|
|
47
49
|
import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
|
|
48
|
-
import {
|
|
50
|
+
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
51
|
+
import { Ledger, RoundRecords, } from "../session/ledger.js";
|
|
49
52
|
import { PipelineFrontier } from "../session/pipeline.js";
|
|
50
53
|
import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
|
|
51
54
|
import { RouteRenderer } from "./route-render.js";
|
|
@@ -99,6 +102,13 @@ const ARTIFACT_FACT_LABELS = {
|
|
|
99
102
|
export class LineCarriers {
|
|
100
103
|
#records;
|
|
101
104
|
#pathOf;
|
|
105
|
+
/** The ONE per-record read's cache — the carrier bytes are read (and parsed) once
|
|
106
|
+
* per record, then both projections (`countOf` / `findingsOf`) take their cell from
|
|
107
|
+
* the same value (P37 §5.2). */
|
|
108
|
+
#content = new Map();
|
|
109
|
+
/** The findings projection's schema face — the SAME `HandoffSchema.findingsOf` the
|
|
110
|
+
* round read-back uses (one projection, two consumers). */
|
|
111
|
+
#schema = new HandoffSchema();
|
|
102
112
|
constructor(records, pathOf) {
|
|
103
113
|
this.#records = records;
|
|
104
114
|
this.#pathOf = pathOf;
|
|
@@ -106,35 +116,92 @@ export class LineCarriers {
|
|
|
106
116
|
/** The judgment over one line's records, with the caller supplying each record's
|
|
107
117
|
* carrier path — the board's own derivation is `ofLedger` below. */
|
|
108
118
|
static of(records, pathOf) {
|
|
109
|
-
return new
|
|
119
|
+
return new _a(records, pathOf);
|
|
110
120
|
}
|
|
111
121
|
/** The board's derivation — the ledger's ONE accessor, bound to this line's type +
|
|
112
122
|
* key. No ledger (no workspace to observe) resolves no path for every record. */
|
|
113
123
|
static ofLedger(ledger, type, key, records) {
|
|
114
|
-
return
|
|
124
|
+
return _a.of(records, (record) => ledger?.carrierPathOf(type, key, record) ?? "");
|
|
115
125
|
}
|
|
116
126
|
/** One record's graded findings count — zero for a record that resolves no path or
|
|
117
127
|
* whose path a later round overwrote; a tampered carrier THROWS (the checked read). */
|
|
118
128
|
countOf(record) {
|
|
129
|
+
return this.#contentOf(record).count;
|
|
130
|
+
}
|
|
131
|
+
/** One record's findings as the round-finding projection (P37 §5.2) — the board's
|
|
132
|
+
* per-record read face, sharing `countOf`'s ONE carrier read and ONE parse. The
|
|
133
|
+
* projection is `HandoffSchema.findingsOf` (unknown severities still dropped), so
|
|
134
|
+
* the count's native array length and this filtered row set are two cells of the
|
|
135
|
+
* same read, never two reads. */
|
|
136
|
+
findingsOf(record) {
|
|
137
|
+
return this.#contentOf(record).findings;
|
|
138
|
+
}
|
|
139
|
+
/** One record's downgrade note (P37 §5.1 · §5.2) — its findings judged against the
|
|
140
|
+
* nearest EARLIER record on this line whose findings projection is non-empty (an
|
|
141
|
+
* implement / fix record with no findings never resets the reference, so a downgrade
|
|
142
|
+
* cannot slip through a clean neighbour). `undefined` when nothing was downgraded,
|
|
143
|
+
* the mark when a row owes its reason, the stated reason when the row carries one. */
|
|
144
|
+
regradeNoteOf(record) {
|
|
145
|
+
const prior = this.#priorOf(record);
|
|
146
|
+
const current = this.findingsOf(record);
|
|
147
|
+
return regradeNote(HandoffSchema.downgrades(prior, current).length, HandoffSchema.regradeReasons(prior, current));
|
|
148
|
+
}
|
|
149
|
+
/** The earlier records of this line, newest first — the "previous round" walk's
|
|
150
|
+
* candidate list (the nearest one with a non-empty findings projection wins). */
|
|
151
|
+
#priorOf(record) {
|
|
152
|
+
const earlier = this.#records
|
|
153
|
+
.filter((other) => _a.#earlierRound(other, record))
|
|
154
|
+
.sort((left, right) => left.cycle === right.cycle ? right.attempt - left.attempt : right.cycle - left.cycle);
|
|
155
|
+
for (const other of earlier) {
|
|
156
|
+
const findings = this.findingsOf(other);
|
|
157
|
+
if (findings.length > 0)
|
|
158
|
+
return findings;
|
|
159
|
+
}
|
|
160
|
+
return [];
|
|
161
|
+
}
|
|
162
|
+
/** Whether `other` precedes `record` on the line — the `(cycle, attempt)` order. */
|
|
163
|
+
static #earlierRound(other, record) {
|
|
164
|
+
return other.cycle === record.cycle
|
|
165
|
+
? other.attempt < record.attempt
|
|
166
|
+
: other.cycle < record.cycle;
|
|
167
|
+
}
|
|
168
|
+
/** One record's carrier content, read ONCE — the path guard, the ownership judgment,
|
|
169
|
+
* the digest-checked read and the JSON parse all live here, so a second projection
|
|
170
|
+
* can never become a second read. */
|
|
171
|
+
#contentOf(record) {
|
|
172
|
+
const cached = this.#content.get(record);
|
|
173
|
+
if (cached !== undefined)
|
|
174
|
+
return cached;
|
|
175
|
+
const content = this.#readFresh(record);
|
|
176
|
+
this.#content.set(record, content);
|
|
177
|
+
return content;
|
|
178
|
+
}
|
|
179
|
+
/** The read behind `#contentOf` — zeroes for a record with no path or an overwritten
|
|
180
|
+
* one, and for bytes that hold no findings array or are not JSON. */
|
|
181
|
+
#readFresh(record) {
|
|
119
182
|
const path = this.#pathOf(record);
|
|
120
|
-
if (path === "" || !RoundRecords.ownerOf(this.#records, record, this.#pathOf))
|
|
121
|
-
return
|
|
183
|
+
if (path === "" || !RoundRecords.ownerOf(this.#records, record, this.#pathOf)) {
|
|
184
|
+
return EMPTY_CARRIER_CONTENT;
|
|
185
|
+
}
|
|
122
186
|
const text = CarrierIntegrity.read(path, record.carrierDigest ?? null);
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
/** The `findings` array length of one carrier's bytes — zero when the payload holds
|
|
126
|
-
* none (a work-plane carrier declares no findings) or is not JSON. */
|
|
127
|
-
static #findingsCountOf(text) {
|
|
187
|
+
if (text === null)
|
|
188
|
+
return EMPTY_CARRIER_CONTENT;
|
|
128
189
|
try {
|
|
129
190
|
const value = JSON.parse(text);
|
|
130
191
|
const findings = value?.findings;
|
|
131
|
-
|
|
192
|
+
if (!Array.isArray(findings))
|
|
193
|
+
return EMPTY_CARRIER_CONTENT;
|
|
194
|
+
return { count: findings.length, findings: this.#schema.findingsOf(findings) };
|
|
132
195
|
}
|
|
133
196
|
catch {
|
|
134
|
-
return
|
|
197
|
+
return EMPTY_CARRIER_CONTENT;
|
|
135
198
|
}
|
|
136
199
|
}
|
|
137
200
|
}
|
|
201
|
+
_a = LineCarriers;
|
|
202
|
+
/** The unreadable / findings-free content — a shared frozen value (no allocation per
|
|
203
|
+
* empty record). */
|
|
204
|
+
const EMPTY_CARRIER_CONTENT = { count: 0, findings: [] };
|
|
138
205
|
/**
|
|
139
206
|
* BoardView — the entry-document → board face. The identity index (`SlugIndex`)
|
|
140
207
|
* is the ONLY node source: the entry document's declared `doc-type:` picks the
|
|
@@ -373,9 +440,17 @@ export class BoardView {
|
|
|
373
440
|
* fact. A record that resolves no carrier (a legacy row, or a work-plane round whose
|
|
374
441
|
* carrier declares no findings) contributes zero. */
|
|
375
442
|
static #summaryToken(verb, body, mark, run, carriers) {
|
|
443
|
+
// Rule zero (class-size limit): this file is well past the limit and predates it —
|
|
444
|
+
// splitting it is P39's work (design spec D95 ②), not this round's.
|
|
376
445
|
const findings = run.reduce((total, record) => total + carriers.countOf(record), 0);
|
|
377
446
|
const suffix = findings === 0 ? "" : `+${findings}`;
|
|
378
|
-
|
|
447
|
+
// P37 §5.2 — the downgrade note rides the SAME token, after its `+N`: the mark when
|
|
448
|
+
// a row owes its reason, the stated reason when the row carries one (both composed
|
|
449
|
+
// by the criteria module's ONE note). One token, one line, no new entry — the note is
|
|
450
|
+
// display, never a finding.
|
|
451
|
+
const notes = run.flatMap((record) => carriers.regradeNoteOf(record) ?? []);
|
|
452
|
+
const note = notes.length === 0 ? "" : ` ${notes.join(REGRADE_NOTE_SEPARATOR)}`;
|
|
453
|
+
return `${verb} ${body} ${mark}${suffix}${note}`;
|
|
379
454
|
}
|
|
380
455
|
/** attemptSuffix(record) — the re-dispatch superscript: `attempt === 1` renders
|
|
381
456
|
* nothing (an `a1` never appears), otherwise `a{attempt}`. */
|
package/dist/face/capsule.js
CHANGED
|
@@ -17,9 +17,9 @@
|
|
|
17
17
|
// count is exactly the number the review criterion rules undisplayed. The key set is
|
|
18
18
|
// still the word table's single source (`Words.capsuleKeys(status, withHandoff)`) —
|
|
19
19
|
// a failure status keeps the handoff cell only when the round wrote a crash record.
|
|
20
|
-
// The fix round's disposition summary
|
|
21
|
-
//
|
|
22
|
-
// `reason:`.
|
|
20
|
+
// The `summary` slot — the fix round's disposition summary, or the review round's
|
|
21
|
+
// downgrade note — rides the SAME render, placed so the dispatchable `next:` literal
|
|
22
|
+
// keeps its line: `status` → summary → `next:` → `reason:`.
|
|
23
23
|
//
|
|
24
24
|
// The byte face is v1-pinned: the key words (status · handoff) are pin-enforced by
|
|
25
25
|
// the CapsuleKey type and the emit signature — a data-only change cannot reshape
|
|
@@ -85,8 +85,10 @@ export class Capsule {
|
|
|
85
85
|
/** emit(status, handoff, hop, withHandoff, summary) → the capsule stdout lines:
|
|
86
86
|
* the status-class key set from the word table (a success status renders
|
|
87
87
|
* `status · handoff`; a failure status renders `status`, plus `handoff` only when
|
|
88
|
-
* the round wrote a crash record), then the
|
|
89
|
-
*
|
|
88
|
+
* the round wrote a crash record), then the optional `summary` line — the fix
|
|
89
|
+
* round's disposition summary, or the review round's downgrade note (both fill the
|
|
90
|
+
* ONE slot; there is no second render path for either), then the optional `next:`
|
|
91
|
+
* row followed by its `reason:` row — the dispatchable
|
|
90
92
|
* literal keeps its exact bytes and the diagnostic fact lands on the line after
|
|
91
93
|
* it. `hop` is the ONE injected `NextHop` object — its ABSENCE (null: the
|
|
92
94
|
* BLOCKED / TIMEOUT failure face) prints neither row, while a present object
|
package/dist/face/cli.js
CHANGED
|
@@ -1238,10 +1238,22 @@ export class Cli {
|
|
|
1238
1238
|
const identityPath = identityRead?.kind === "ok" ? identityRead.path : null;
|
|
1239
1239
|
// The spec link is the SAME read's path rebased to repoRoot-relative (D46 · T3), so
|
|
1240
1240
|
// every round-context path token speaks ONE basis (the child spawns at cwd = the
|
|
1241
|
-
// repo root) and the anchor and the frontier can never name two documents.
|
|
1242
|
-
|
|
1241
|
+
// repo root) and the anchor and the frontier can never name two documents. The wave
|
|
1242
|
+
// line reads it on the same rule as the plan / branch lines (P37 §4.1): a code
|
|
1243
|
+
// review that cannot open the phase contract is the constructive blind spot the
|
|
1244
|
+
// phase closes.
|
|
1245
|
+
if (type === "plan" || type === "branch" || type === "wave") {
|
|
1243
1246
|
specLink = identityPath === null ? null : root.relativize(identityPath);
|
|
1244
1247
|
}
|
|
1248
|
+
// P37 §4.1 — the wave line's charter anchor. The two anchors are judged
|
|
1249
|
+
// INDEPENDENTLY: the spec anchor follows the identity document's own resolution
|
|
1250
|
+
// (a single-spec resolves fine and owns no `program:` by design), the charter
|
|
1251
|
+
// anchor follows that document's `program:` alone. Coupling them would strip a
|
|
1252
|
+
// single-spec phase's spec anchor — the blind spot this phase closes.
|
|
1253
|
+
if (type === "wave" && identityPath !== null && specDoc?.program != null) {
|
|
1254
|
+
const overallEntry = index.overallOf(specDoc.program);
|
|
1255
|
+
overallLink = overallEntry === null ? null : root.relativize(overallEntry.path);
|
|
1256
|
+
}
|
|
1245
1257
|
// The pipeline frontier's four declared cells (§11) — the composition root's ONE
|
|
1246
1258
|
// collection point. The identity word + path come from the document index's read
|
|
1247
1259
|
// (never the argv `--type` spelling): every non-plan declared document owns the
|