@oscaner-skills/cdd-engine 4.12.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.
@@ -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();
@@ -31,6 +31,9 @@ export class CliArtifacts {
31
31
  #projector;
32
32
  #issue;
33
33
  #stdinRead;
34
+ /** The composition root's artifact matrix — the ONE home of the `base` row's
35
+ * spelling; every read/write in this class asks it, never a memoized literal. */
36
+ #matrix;
34
37
  /** The composition-root usage throw — commander's OWN CommanderError (the root's
35
38
  * exit-normalization face; the split never re-implements the usage byte). */
36
39
  #usage;
@@ -42,6 +45,7 @@ export class CliArtifacts {
42
45
  this.#projector = opts.projector ?? new Projector(declaredRegistries);
43
46
  this.#issue = opts.issue;
44
47
  this.#stdinRead = opts.stdinRead;
48
+ this.#matrix = opts.matrix;
45
49
  this.#usage = opts.usage;
46
50
  }
47
51
  /** `cdd schema get <type> --output skeleton <target>` — the derived doc skeleton
@@ -114,8 +118,8 @@ export class CliArtifacts {
114
118
  plan: planPath,
115
119
  recordedAt: new Date().toISOString(),
116
120
  };
117
- workspace.writeJson("base.json", artifact);
118
- this.#io.stdout(`${root.relativize(workspace.resolve("base.json"))}\n`);
121
+ workspace.writeJson(this.#baseName(), artifact);
122
+ this.#io.stdout(`${root.relativize(workspace.resolve(this.#baseName()))}\n`);
119
123
  return 0;
120
124
  }
121
125
  /** The `get` body — read + validate + print the artifact JSON (exit 2 when the
@@ -126,7 +130,7 @@ export class CliArtifacts {
126
130
  baseGet(workspace, root) {
127
131
  const artifact = this.#readBase(workspace);
128
132
  if (artifact === null) {
129
- const path = root.relativize(workspace.resolve("base.json"));
133
+ const path = root.relativize(workspace.resolve(this.#baseName()));
130
134
  this.#io.stderr(`cdd base get: missing or corrupt base artifact at ${path}\n`);
131
135
  return 2;
132
136
  }
@@ -157,6 +161,11 @@ export class CliArtifacts {
157
161
  const day = String(now.getDate()).padStart(2, "0");
158
162
  return `${now.getFullYear()}-${month}-${day}`;
159
163
  }
164
+ /** The base artifact's workspace-relative name — the matrix's `base` row renders it
165
+ * (one spelling, one home; this class never carries a copy). */
166
+ #baseName() {
167
+ return this.#matrix.render({ domain: "workspace", tasks: null }, "base");
168
+ }
160
169
  /** Read + validate the base artifact; null when missing or malformed — a total
161
170
  * read (never a throw). The read rides `Workspace.readJson` (P11 · §4.2) — the
162
171
  * read/write single normalization path, so a legacy absolute `plan` field reads
@@ -166,7 +175,7 @@ export class CliArtifacts {
166
175
  * narrowed to the declared enum domain (a value outside the four-value set is a
167
176
  * schema-invalid artifact → null, never a fabricated source). */
168
177
  #readBase(workspace) {
169
- const read = workspace.readJson("base.json");
178
+ const read = workspace.readJson(this.#baseName());
170
179
  if (read.kind !== "ok")
171
180
  return null;
172
181
  const parsed = read.value;