@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.
@@ -48,6 +48,25 @@ const FINDING = {
48
48
  line: { type: "integer" },
49
49
  summary: { type: "string" },
50
50
  fix: { type: "string" },
51
+ // P37 §2.1 — the blocker evidence slot. Declared OPTIONAL on the schema face by
52
+ // design: warn / nit findings owe no scenario, so a required `impact` would BLOCK
53
+ // legal drafts. A blocker's obligation is judged by `gradingViolations` (the
54
+ // grading gate), never by the shape walk — the shape only pins what a scenario IS.
55
+ impact: {
56
+ type: "object",
57
+ required: ["scenario"],
58
+ properties: { scenario: { type: "string" }, test: { type: "string" } },
59
+ },
60
+ // P37 §5 — the cross-round downgrade reason. Optional at the schema layer: only
61
+ // the cross-round identity + scenario identity judgment requests it.
62
+ regrade: { type: "string" },
63
+ // P37 §2.3 — the repair anchor a fix round locates the finding by. Never read by
64
+ // `rollup`; its `path` is a pin judged on the handoff read-back corpus.
65
+ contract: {
66
+ type: "object",
67
+ required: ["path", "anchor"],
68
+ properties: { path: { type: "string" }, anchor: { type: "string" } },
69
+ },
51
70
  },
52
71
  };
53
72
  /** The ONE carrier declaration — the five child-writable slots. DECLARATION ORDER IS
@@ -204,29 +223,142 @@ export class HandoffSchema {
204
223
  }
205
224
  /** The review conclusion rollup — status derived from the findings severities
206
225
  * (the rollup the retired JSON-return channel performed; a review never carries
207
- * a child-authored status). */
226
+ * a child-authored status). Unchanged by the grading gate: `rollup` counts
227
+ * blockers and nothing else, so the refusal is never a fourth conclusion. */
208
228
  rollup(findings) {
209
229
  const blockers = findings.filter((finding) => finding?.severity === "blocker").length;
210
230
  return blockers > 0 ? "CHANGES_REQUESTED" : findings.length > 0 ? "REVIEW_FIX" : "APPROVED";
211
231
  }
232
+ /** P37 §2.2 — the blocker evidence gate, a PURE predicate colocated with `rollup`.
233
+ * A finding graded `blocker` owes a non-blank `impact.scenario`; every blocker that
234
+ * lacks one is returned so the failure face can list them all (never one of two).
235
+ * Warn / nit findings owe nothing here, and the predicate never judges severity —
236
+ * the tier is the child's call, this gate only asks whether a blocker paid its
237
+ * evidence. `rollup` deliberately does not call it: a review conclusion is not a
238
+ * place to refuse a round, and `rollup`'s return type stays `RoundStatus`. */
239
+ gradingViolations(findings) {
240
+ if (!Array.isArray(findings))
241
+ return [];
242
+ const violations = [];
243
+ for (const entry of findings) {
244
+ const row = entry;
245
+ if (row?.severity !== "blocker")
246
+ continue;
247
+ const scenario = row.impact?.scenario;
248
+ if (typeof scenario === "string" && scenario.trim().length > 0)
249
+ continue;
250
+ violations.push({
251
+ ...(typeof row.id === "string" && row.id.length > 0 ? { id: row.id } : {}),
252
+ ...(typeof row.summary === "string" ? { summary: row.summary } : {}),
253
+ });
254
+ }
255
+ return violations;
256
+ }
212
257
  /** The draft findings presented as round findings — unknown severities dropped
213
- * (the capsule's blocker count + the outcome's face, never the judgment domain). */
258
+ * (the capsule's blocker count + the outcome's face, never the judgment domain).
259
+ * The three cells the cross-round regrade judgment reads ride along (P37 §2.1 ·
260
+ * §5.1): the engine-written `id`, the blocker's `impact` and the round's own
261
+ * `regrade`. Each cell is projected only when it keeps its declared shape — a
262
+ * malformed cell reads as absent, never as a fabricated value. */
214
263
  findingsOf(findings) {
215
264
  if (!Array.isArray(findings))
216
265
  return [];
217
266
  const rows = [];
218
267
  for (const entry of findings) {
219
- const severity = entry?.severity;
268
+ const row = entry;
269
+ const severity = row?.severity;
220
270
  if (severity !== "blocker" && severity !== "warn" && severity !== "nit")
221
271
  continue;
222
- const summary = entry?.summary;
272
+ const id = _a.#textOf(row?.id);
273
+ const impact = _a.#impactOf(row?.impact);
274
+ const regrade = _a.#textOf(row?.regrade);
223
275
  rows.push({
224
276
  severity: severity,
225
- summary: typeof summary === "string" ? summary : undefined,
277
+ summary: _a.#textOf(row?.summary),
278
+ ...(id === undefined ? {} : { id }),
279
+ ...(impact === undefined ? {} : { impact }),
280
+ ...(regrade === undefined ? {} : { regrade }),
226
281
  });
227
282
  }
228
283
  return rows;
229
284
  }
285
+ /** P37 §5.1 — the cross-round downgrade judgment, a PURE predicate over the two
286
+ * rounds' findings projections. Returns the current rows that were graded BELOW a
287
+ * matching earlier row, whose earlier `impact.scenario` was non-empty, and that
288
+ * carry no `regrade` reason: exactly the rows the display face marks.
289
+ *
290
+ * The four steps, in order: (1) locate the matching earlier row on EITHER of two
291
+ * keys — the `summary` text (the defect's description, which survives a reworded
292
+ * scenario), or the earlier row's `impact.scenario` verbatim (the scenario did not
293
+ * change, so the defect did not either — the key §5.1 registers alongside the first
294
+ * one, not instead of it); a multi-row hit is narrowed by the engine-written `id`,
295
+ * never keyed on `id` (it is a row number, so a re-numbered carrier would pair
296
+ * unrelated defects); (2) an unchanged or raised grade is no downgrade; (3) a
297
+ * lowered grade against a non-empty scenario owes a `regrade` reason; (4) a lowered
298
+ * grade whose earlier scenario was empty has no reference, so the defect is read as
299
+ * changed. Omission or rewriting of THIS round's scenario never retires the duty once
300
+ * a pair is made — only the earlier row's scenario is read for the reference. */
301
+ static downgrades(prior, current) {
302
+ return current.filter((row) => _a.#downgradeReference(prior, row) !== undefined &&
303
+ _a.#textOf(row.regrade) === undefined);
304
+ }
305
+ /** P37 §5.1 · §5.2 — the reasons the round DID state, in carrier row order. The
306
+ * counterpart of `downgrades`: the same downgrade judgment, read on the rows that
307
+ * carry their `regrade` cell. The two sets partition one judgment, so a display face
308
+ * can print the mark and the reasons from ONE criterion instead of re-deciding which
309
+ * row was downgraded. */
310
+ static regradeReasons(prior, current) {
311
+ // Rule zero (class-size limit): this file is well past the limit and predates it —
312
+ // splitting it is P39's work (design spec D95 ②), not this round's.
313
+ const reasons = [];
314
+ for (const row of current) {
315
+ if (_a.#downgradeReference(prior, row) === undefined)
316
+ continue;
317
+ const reason = _a.#textOf(row.regrade);
318
+ if (reason !== undefined)
319
+ reasons.push(reason);
320
+ }
321
+ return reasons;
322
+ }
323
+ /** The earlier row a current row was graded below — §5.1's steps 1 → 4, absent for
324
+ * every row that is not a downgrade. Step 1 compares TWO keys: the `summary` text and
325
+ * the earlier row's `impact.scenario` verbatim. Either hit pairs; a multi-row hit is
326
+ * narrowed by `id`. Rewriting BOTH the summary and this round's scenario is the only
327
+ * way to cut a pair, and that is a declaration that the defect changed. */
328
+ static #downgradeReference(prior, row) {
329
+ const matches = prior.filter((candidate) => (candidate.summary !== undefined && candidate.summary === row.summary) ||
330
+ (candidate.impact?.scenario !== undefined &&
331
+ candidate.impact.scenario === row.impact?.scenario));
332
+ if (matches.length === 0)
333
+ return undefined;
334
+ const narrowed = matches.filter((candidate) => row.id !== undefined && candidate.id === row.id);
335
+ const reference = (narrowed.length > 0 ? narrowed : matches)[0];
336
+ if (reference === undefined)
337
+ return undefined;
338
+ if (_a.#tierRankOf(row.severity) >= _a.#tierRankOf(reference.severity)) {
339
+ return undefined;
340
+ }
341
+ if (_a.#textOf(reference.impact?.scenario) === undefined)
342
+ return undefined;
343
+ return reference;
344
+ }
345
+ /** The tier ladder's rank — higher is more severe (blocker 2 · warn 1 · nit 0). */
346
+ static #tierRankOf(severity) {
347
+ return severity === "blocker" ? 2 : severity === "warn" ? 1 : 0;
348
+ }
349
+ /** A non-blank string cell, else undefined — the projection's ONE blank test. */
350
+ static #textOf(value) {
351
+ return typeof value === "string" && value.trim().length > 0 ? value : undefined;
352
+ }
353
+ /** The blocker's scenario cell when it keeps its declared shape — a scenario-less
354
+ * impact is absent, never a row carrying an empty reference. */
355
+ static #impactOf(value) {
356
+ const scenario = _a.#textOf(value?.scenario);
357
+ if (scenario === undefined)
358
+ return undefined;
359
+ const test = _a.#textOf(value?.test);
360
+ return test === undefined ? { scenario } : { scenario, test };
361
+ }
230
362
  /** The plane's writable subset — the ONE projection every consumer reads (prompt
231
363
  * fence · read-back validator · dropped-key walk). The properties are CARRIER's
232
364
  * own slot declarations filtered in declaration order; the required set comes from
@@ -35,6 +35,7 @@ import path from "node:path";
35
35
  import lockfile from "proper-lockfile";
36
36
  import { AtomicWriter } from "../infra/atomic.js";
37
37
  import { ProcessFacts } from "../infra/proc.js";
38
+ import { ArtifactRegistry } from "./round-artifacts.js";
38
39
  /** The acquire refusal — another dispatch holds the record (or the lock) already. The
39
40
  * carrier keeps the holder's facts so the CLI renders the held BLOCK from them; a
40
41
  * corrupt record yields a null `record`. */
@@ -54,8 +55,10 @@ export class HoldingError extends Error {
54
55
  */
55
56
  export class InFlight {
56
57
  /** The record's file name inside the workspace-root namespace — the tree-level
57
- * `.kairos/cdd/in-flight.json` under the default configuration. */
58
- static FILE = "in-flight.json";
58
+ * `.kairos/cdd/in-flight.json` under the default configuration. The spelling lives
59
+ * in the artifact matrix (`WorkspaceDomain`'s `in-flight` row); this constant is the
60
+ * read face's answer, never a second home. */
61
+ static FILE = ArtifactRegistry.nameOf("in-flight", null);
59
62
  /** The lock's stale window (ms) — a FINITE value larger than the longest dispatch
60
63
  * budget (implement, 6 h). Finiteness is deliberate: `stale: Infinity` pushes the
61
64
  * default `update` to `Infinity`, which Node clamps to 1 ms of lock-touch churn