@oscaner-skills/cdd-engine 4.12.0 → 4.13.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.
@@ -36,6 +36,7 @@
36
36
  // Module-level exports are types / constants / the class — zero behavior-carrying
37
37
  // bare functions (the plan's zero-bare-function discipline).
38
38
  var _a;
39
+ import path from "node:path";
39
40
  /** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
40
41
  * defers the next hop to user adjudication (soft by nature: a default suggestion,
41
42
  * never a hard stop — the user / the plan write authority override it). */
@@ -133,17 +134,20 @@ export const NEXT_HOP_REASON = {
133
134
  };
134
135
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
135
136
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
136
- /** The fix-route readback suffix — appended verbatim to the fix findings path on the
137
- * route's `next:` render (`(confirm the reviews handoff · if a finding needs a ruling,
138
- * record it beside that handoff — same path with .json replaced by .rulings.json)`), a
139
- * pure wording prompt: the anti-blind-fix mechanical guard is the ledger round / C5-1,
140
- * the suffix only reminds the orchestrator to confirm the captured findings and, when a
141
- * finding needs a user ruling, to record it in the SIDECAR beside the reviews handoff
142
- * (the carrier's bytes are frozen — the ruling never edits them; P31 §2.1/§2.5).
143
- * `annotate` names the carrier action alone — distinct from `backfill` (a durable fact
144
- * landed into its owning doc), which stays the ruling's destination when it asserts a
145
- * project-level fact. */
146
- export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record it beside that handoff — same path with .json replaced by .rulings.json)";
137
+ /** The value slot of the fix readback sentence — the rendered sidecar path the route
138
+ * carries (`Route.rulings`). The sentence is FIXED bytes and the path is a VALUE, so
139
+ * the render face fills a slot instead of deriving a name (§2.10 · §2.6's "the render
140
+ * plane holds no name rule"). */
141
+ export const FIX_READBACK_SLOT = "<rendered sidecar path>";
142
+ /** The fix-route readback suffix — appended to the fix findings path on the route's
143
+ * `next:` render, with the sidecar path filled into `FIX_READBACK_SLOT`:
144
+ * `(confirm the reviews handoff · if a finding needs a ruling, record it at
145
+ * <rendered sidecar path>)`. A RESULT sentence, never a naming rule: the old wording
146
+ * taught the `.json` → `.rulings.json` transformation, which is the very second
147
+ * expression this phase retires (§2.8 · issue ④). The path arrives from the route (the
148
+ * router renders it from the CARRIER's identity), so no reader of this constant derives
149
+ * a name from it. A carrier with no round identity renders no suffix at all. */
150
+ export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record it at <rendered sidecar path>)";
147
151
  /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
148
152
  * produces no `next:` line on any op. Exported as the ONE failure-status set: the
149
153
  * skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
@@ -155,6 +159,21 @@ export const FAILED_STATUS = new Set(["BLOCKED", "TIMEOUT"]);
155
159
  * no hidden state: every judgment reads the execution state + the round carrier.
156
160
  */
157
161
  export class NextStepRouter {
162
+ /** The artifact matrix this router holds — the composition root's single instance,
163
+ * handed down so the readback face renders the SAME name the dispatch gate judges
164
+ * (the router itself derives no name). `null` — a hermetic caller — means the fix
165
+ * hop carries no `rulings` value: a router without a matrix cannot render a name and
166
+ * must not invent one. */
167
+ #artifacts;
168
+ /** `artifacts` is the composition root's matrix, OPTIONAL here — unlike
169
+ * `CliLifecycle#artifacts`, which is required because a wiring bug there would read as
170
+ * a legal `absent` carrier. A hermetic caller passing `null` loses exactly one
171
+ * decorative cell (the fix hop's read-back hint, omitted whole — never printed empty),
172
+ * and no judgment becomes a visible `absent` through it. Production passes the single
173
+ * instance. */
174
+ constructor(artifacts) {
175
+ this.#artifacts = artifacts ?? null;
176
+ }
158
177
  /** next(state, ref) — the C5 derivation: the next-hop Route, or null when the round
159
178
  * produces no next line (the BLOCKED/TIMEOUT failure-mode face). */
160
179
  next(state, ref) {
@@ -171,7 +190,7 @@ export class NextStepRouter {
171
190
  // what the fix will do (C5-1). Zero findings (approved) → the unified closure: the
172
191
  // ready batch decides whether the next wave continues or the run is exhausted.
173
192
  if (ref.findings.length > 0)
174
- return { kind: "fix", reviews: ref.reviewsPath };
193
+ return this.#fixRoute(ref);
175
194
  return this.#close(state);
176
195
  case "fix": {
177
196
  // C5-1: the fix face is the re-review / closure decision point. The soft cap
@@ -191,11 +210,39 @@ export class NextStepRouter {
191
210
  case "branch-review":
192
211
  // The branch terminal face — findings route the fix; zero findings close the line
193
212
  // through the same unified closure terminal.
194
- return ref.findings.length > 0
195
- ? { kind: "fix", reviews: ref.reviewsPath }
196
- : this.#close(state);
213
+ return ref.findings.length > 0 ? this.#fixRoute(ref) : this.#close(state);
197
214
  }
198
215
  }
216
+ /** The one-way fix hop — the carrier the fix reads plus the ruling sidecar's RESOLVED
217
+ * path beside it. The path's name comes from the CARRIER's identity
218
+ * (`attribute(basename(carrier))` with `op` fixed to `review`), never from this fix
219
+ * round's `(line, op)` and never from a tail replacement on the handoff's own
220
+ * spelling: `plan-review-1-a1.json` renders `plan-review-1.c1.rulings.json`. A carrier
221
+ * the matrix cannot place (a P34-era legacy spelling) leaves the value absent, and the
222
+ * render face then omits the readback sentence whole. */
223
+ #fixRoute(ref) {
224
+ const reviews = ref.reviewsPath;
225
+ const rulings = this.#rulingsOf(reviews);
226
+ return {
227
+ kind: "fix",
228
+ ...(reviews === undefined ? {} : { reviews }),
229
+ ...(rulings === null ? {} : { rulings }),
230
+ };
231
+ }
232
+ /** The sidecar path beside one carrier — the matrix's `rulings` render of the carrier's
233
+ * own round identity, resolved in the carrier's OWN directory (the same coordinate the
234
+ * dispatch gate prints as `derived:`). The identity itself comes from the matrix's ONE
235
+ * entry (`ArtifactRegistry#reviewedIdentityOf`), so the `op: "review"` construction
236
+ * this router used to spell has one home. Null when the router holds no matrix or the
237
+ * name attributes to no round identity. */
238
+ #rulingsOf(carrier) {
239
+ if (this.#artifacts === null || carrier === undefined)
240
+ return null;
241
+ const identity = this.#artifacts.reviewedIdentityOf(carrier);
242
+ if (identity === null)
243
+ return null;
244
+ return path.join(path.dirname(carrier), this.#artifacts.render(identity, "rulings"));
245
+ }
199
246
  /** The unified closure terminal (v1.20) — the single way a review/fix closure renders
200
247
  * its next hop: the ready batch decides `next-wave` vs `done` (a closing review with
201
248
  * another wave ready continues the run; an exhausted run reports `done`). */