clearotron 0.2.4 → 0.3.0-beta.1

package/driver/findings-model.mjs

@@ -2441,7 +2441,7 @@ export function knockoutFindingViews(mark, { manifest = null } = {}) {
  * Derived through knockoutFindingViews rather than re-deriving that fallback here — one projection
  * decides what a finding's number is, and this cell cannot disagree with the sheet it points into.
  */
-// ── THE REVIEWER'S NOTES: WHAT EACH ONE IS ABOUT (tracker issues 331 A.4, 333 rule 5) ───────────────
+// ── THE REVIEWER'S NOTES: WHAT EACH ONE IS ABOUT (A.4, rule 5) ──────────────────────────────────────
 //
 // The knockout page prints a note about the REQUEST at the top, above the conflicts, and a note about
 // the NAME under that name's cards. A note saying the screen may have been scoped to the wrong market
@@ -2454,7 +2454,7 @@ export function knockoutFindingViews(mark, { manifest = null } = {}) {
 //
 // IT SORTS ON WHAT THE NOTE TALKS ABOUT, and the doctrine is written to match: a note about the request
 // NAMES the request. The word set spans both vocabularies deliberately — "dispatch" and "instructed"
-// are what runs written before tracker issue 333 say, "the request" and "was asked" are what runs
+// are what earlier runs say, "the request" and "was asked" are what runs
 // written after it say — so one reader serves the archive and the new doctrine at once.
 export const REQUEST_NOTE_WORDS = /\b(?:dispatch|the request|the requester|instructed|was asked)\b/i;
 

package/driver/flag-snapshot.mjs

@@ -277,7 +277,7 @@ export function postureDelta(snapshot, expected = PRODUCTION_POSTURE) {
  * hardcoded expectation. This answers how it differs from the box it is being read on, which is the
  * question a staff member actually has in front of the capability page.
  *
- * WHY AN AGE IS NOT THE GUARD IT LOOKS LIKE (tracker issue 170). The snapshot's only writers were a run
+ * WHY AN AGE IS NOT THE GUARD IT LOOKS LIKE. The snapshot's only writers were a run
  * and the launcher, so a deployment being CONFIGURED — which runs nothing by definition — holds a
  * capture that is stale for exactly as long as somebody is working on it, which is exactly when they
  * are looking at the page. Found live: the register provider was moved from signa to clarivate and every
@@ -526,7 +526,7 @@ export function isStale(snapshot, { now, maxAgeMs = 24 * 60 * 60 * 1000 }) {
  * the class of defect the snapshot exists to remove rather than to add to.
  *
  * Callable from the portal because the portal HAS the engine environment: one configuration per server
- * box, owner ruling 2026-08-26, `EnvironmentFile=%h/.env` on every unit. Its result is for COMPARISON
+ * box, ruling 2026-08-26, `EnvironmentFile=%h/.env` on every unit. Its result is for COMPARISON
  * only — see portal-config-view.mjs on why the page still renders the capture and never this.
  */
 export async function livePosture({ env = process.env } = {}) {

package/driver/floor-duty.mjs

@@ -14,7 +14,7 @@
 // WHY THIS READS THE FORM AND NOT THE PROSE. The obligation used to read "placed or explicitly reasoned
 // away", and *reasoned away* is prose — unfalsifiable by machine. On the first of those runs 39 of the 45
 // missing marks ARE discussed somewhere in the recommendations and 0 of the 45 record ids are named, so
-// "discussed" and "reasoned away" cannot be told apart from the text. The owner ruling of 2026-08-20
+// "discussed" and "reasoned away" cannot be told apart from the text. The ruling of 2026-08-20
 // settled it: the duty survives, narrowed to the must-check list, discharged by NAMING THE RECORD ID
 // with a one-line ground. That is a row on a form, and a row is checkable.
 //
@@ -65,7 +65,7 @@ export function armFloorDuty(runDir, { now = () => new Date().toISOString() } =
     ensureDriverDir(String(runDir ?? ""));
     writeFileSync(driverDir(String(runDir ?? ""), FLOOR_DUTY_STAMP), JSON.stringify({
       _provenance: "the placement pass on this run ran under code that orders the floors by record id "
-        + "(#1117), so its floor account may be held to that order (tracker issue 1955)",
+        + "(#1117), so its floor account may be held to that order",
       ts: now(),
     }, null, 2) + "\n");
     return true;

package/driver/frame-diff-model.mjs

@@ -436,7 +436,7 @@ export function effectiveInScope(hit, scopeJurisdictions = []) {
 // does a SEARCHED token mechanically cover a scoped jurisdiction j? (exact, or an EU search covering EU-scope).
 // A member scoped but only EU searched is NOT covered (national rights need a national search) → stays a gap.
 //
-// EXPORTED for the delivered-narrative coverage check (predelivery-lint.mjs, tracker issue 134), which asks
+// EXPORTED for the delivered-narrative coverage check (predelivery-lint.mjs), which asks
 // the same question of a different claimant: not "did the plan cover the scope" but "does the prose claim
 // coverage of a territory the run did not search". One copy of the EU-reach rule, because two copies drifting
 // apart would be a worse defect than the disagreement this is being exported to catch. Callers pass

package/driver/framework-preflight.mjs

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// THE FRAMEWORK PRE-FLIGHT — read a deck and its manifest and say what they declare, before either
+// rates a real matter.
+//
+// A customer's counsel writes a risk framework as two files: a prose deck they can argue with, and a
+// small manifest that gives code the band words. Until now the only way to find out whether the pair
+// worked was to point a company at it and run a matter. Three things went wrong in that order, and each
+// of them looked like something else:
+//
+//   the manifest is refused          — the run fails by a token, hours in, naming a JSON key
+//   the deck and the manifest differ — nothing fails; the profile screen renders the framework's title
+//                                      and its coloured band pills and silently omits the box saying what
+//                                      the bands mean, so the page looks built and is missing half of it
+//   the deck resolves somewhere else — nothing fails; another framework rates the matter
+//
+// IT REPORTS AND DOES NOT GRADE. The pre-flight says what the framework declares — the ladder in its own
+// order, the entity the deck names, the shape it is, which file answered — and where the two files
+// disagree it says which band and what the deck did not do. It has no opinion on whether the rubric is a
+// good one: a rubric is a legal document, and a check that scored one would be a content lint in a
+// different costume. Nothing here reads what a band MEANS, only that the deck defines it.
+//
+// AGREEMENT IS THE RENDERER'S OWN READ, not a second one. `bandMeaningRows` in profile-service.mjs is the
+// walk the profile screen makes; this calls it. A pre-flight with its own matcher would pass a deck the
+// page then drops, which is the defect it exists to remove rather than a smaller version of it.
+
+import { readFileSync } from "node:fs";
+import { config } from "./driver.config.mjs";
+import { loadFrameworkManifest, manifestPathFor, DEFAULT_FRAMEWORK } from "./framework.mjs";
+import { bandMeaningRows } from "./profile-service.mjs";
+
+/**
+ * WHY A DECK SERVED FROM THE REPO IS WORTH A SENTENCE, and why only sometimes.
+ *
+ * Skill resolution is layered: the config store wins, the repo answers when the store is silent. That
+ * fallback is the migration design and every generic methodology file relies on it. For a FRAMEWORK it is
+ * different in kind, because the shipped tree carries decks under the same filenames customers use for
+ * their own — `risk-framework.md`, `risk-framework-demo.md`, `risk-framework-triage.md`, which are the
+ * three `files[]` re-includes after excluding `risk-framework-*`. Take a customer's deck out of the
+ * config store and the repo's copy answers: readable, valid, and not theirs. Nothing throws and the
+ * matter is rated under another company's rubric.
+ *
+ * So: reported when an overlay is configured and did not hold the file. Silent on a single-tree install,
+ * where there is no other copy for it to have been.
+ */
+export const SUBSTITUTION_SAY = (r) =>
+  `served from the shipped tree, not the configured store — the store has no ${r.rel}, so ${r.basePath} answered. `
+  + `A customer deck removed from the store is replaced by the shipped file of the same name rather than missed.`;
+
+const layerSay = {
+  overlay: "the configured store",
+  base: "the shipped tree (the configured store does not hold it)",
+  "base-only": "the shipped tree",
+  missing: "nowhere — neither the configured store nor the shipped tree holds it",
+};
+
+/**
+ * Everything the pre-flight found about one framework, as data. `ok` is the whole verdict; `refusals`
+ * says why when it is false, in sentences written for the person who wrote the files.
+ *
+ * `resolve` and `read` are injected so the lint can drive a planted tree — the CLI passes neither and
+ * gets the engine's own resolution, which is the point of the check.
+ */
+export function preflightFramework(fwPath, { resolve, read } = {}) {
+  const resolveOne = resolve ?? ((rel) => config.resolveSkillPathReport(rel));
+  const readOne = read ?? ((p) => readFileSync(p, "utf8"));
+  const manifestRel = manifestPathFor(fwPath);
+  const out = {
+    fwPath, manifestRel, ok: false, refusals: [], substitutions: [],
+    deck: null, manifest: null, declares: null, bands: null,
+  };
+
+  for (const [name, rel] of [["deck", fwPath], ["manifest", manifestRel]]) {
+    let r;
+    try { r = resolveOne(rel); }
+    catch (e) { out.refusals.push({ code: "skills_overlay_unreadable", say: String(e?.message ?? e) }); return out; }
+    out[name] = { rel, path: r.path, layer: r.layer, from: layerSay[r.layer] ?? r.layer };
+    if (r.layer === "base") out.substitutions.push({ ...r, say: SUBSTITUTION_SAY(r) });
+  }
+
+  let manifest;
+  try { manifest = loadFrameworkManifest((rel) => resolveOne(rel).path, fwPath); }
+  catch (e) {
+    out.refusals.push({ code: "manifest", say: String(e?.message ?? e) });
+    return out;
+  }
+  out.declares = {
+    key: manifest.framework_key, title: manifest.title, entity: manifest.entity_label,
+    sourceDeck: manifest.source_deck, shape: manifest.structure.kind,
+    ladder: manifest.bands.map((b) => ({ label: b.label, tone: b.tone })),
+  };
+
+  let deckText;
+  try { deckText = readOne(out.deck.path); }
+  catch (e) {
+    out.refusals.push({ code: "deck_unreadable", say: `the deck could not be read at ${out.deck.path}: ${String(e?.message ?? e)}` });
+    return out;
+  }
+
+  // The entity label has to appear in the prose, because the deck speaks about the company by name and a
+  // manifest naming a company the deck never mentions is a pair from two different frameworks.
+  if (!deckText.toLowerCase().includes(String(manifest.entity_label).toLowerCase()))
+    out.refusals.push({ code: "entity_absent",
+      say: `the manifest names "${manifest.entity_label}" as the company, and the deck prose never uses that name.` });
+
+  out.bands = bandMeaningRows(deckText, manifest) ?? [];
+  const missed = out.bands.filter((b) => b.miss);
+  if (missed.length)
+    out.refusals.push({ code: "bands_disagree",
+      say: `${missed.length} of ${out.bands.length} bands are named in the manifest and not defined in the deck. `
+        + "The profile screen shows what the bands mean only when EVERY band is defined, so one miss empties the whole box.",
+      bands: missed.map((b) => ({ band: b.band, miss: b.miss })) });
+
+  out.ok = out.refusals.length === 0;
+  return out;
+}
+
+/** The report as lines for a reader. No colour, no verdict word the caller has not earned. */
+export function formatPreflight(r) {
+  const L = [];
+  L.push(`Framework: ${r.fwPath}${r.fwPath === DEFAULT_FRAMEWORK ? "  (this installation's default)" : ""}`);
+  if (r.deck) L.push(`  deck      ${r.deck.path}`, `            read from ${r.deck.from}`);
+  if (r.manifest) L.push(`  manifest  ${r.manifest.path}`, `            read from ${r.manifest.from}`);
+  if (r.declares) {
+    const d = r.declares;
+    L.push("", `It declares itself "${d.title}" (${d.key}), a ${d.shape}-shaped framework rating ${d.entity}.`,
+      `Transcribed from: ${d.sourceDeck}`, "", "The ladder, highest risk first:");
+    for (const [i, b] of d.ladder.entries()) L.push(`  ${i + 1}. ${b.label.padEnd(16)} ${b.tone}`);
+  }
+  if (r.bands?.length) {
+    L.push("", "What the deck defines:");
+    for (const b of r.bands) L.push(b.miss ? `  ✗ ${b.band.padEnd(16)} ${b.miss}` : `  ✓ ${b.band.padEnd(16)} ${b.meaning}`);
+  }
+  for (const s of r.substitutions) L.push("", `WARNING  ${s.rel}: ${s.say}`);
+  if (r.refusals.length) {
+    L.push("", "Not ready:");
+    for (const f of r.refusals) L.push(`  ${f.say}`);
+  } else {
+    L.push("", "The deck and the manifest agree. Nothing was created and nothing was rated.");
+  }
+  return L.join("\n");
+}

package/driver/gateway.mjs

@@ -65,6 +65,13 @@ export const TOOL_WRITTEN_ARTIFACTS = new Map([
     refusals: (runDir) => frameRefusalsFor(runDir) }],
   ["knockout-frame.md", { tool: "record_knockout_frame", what: "the batch scope note",
     refusals: (runDir) => frameRefusalsFor(runDir) }],
+  // The knockout lane's reviewing pass. ONE EXACT BASENAME, and it sits under `_driver/` rather than the
+  // run root because the artifact is the pass's account of what it rewrote, not a surface a client is
+  // shown — the lookup keys on the basename either way. The row is what makes a repair on this stage a
+  // CALL: the seat's grant carries no Write, so a ladder handing it the write form would order a
+  // hand-write it cannot perform, on a stage whose failure is deliberately quiet.
+  ["knockout-review.json", { tool: "record_knockout_review", what: "your rewrites of the lines a reader sees first",
+    refusals: (runDir) => knockoutReviewRefusalsFor(runDir) }],
   [BLIND_FRAME_MODEL_FILE, { tool: "record_blind_frame", what: "the threat model" }],
   [SKEPTIC_FLAGS_FILE, { tool: "record_skeptic", what: "your flags and escalation decisions" }],
   ["senior-eye-review.md", { tool: "record_narrative_refutation", what: "your verdict and typed flags" }],
@@ -227,6 +234,7 @@ import { KNOCKOUT_ASSESS_CHUNK_RE, knockoutAssessChunkFile } from "./knockout-as
 // The frame transport's refusal reader, so a missing plan or note can be told apart from a stage that
 // never called its tool — the distinction, which its sibling stage still lacks.
 import { frameRefusalsFor } from "./knockout-frame-record.mjs";
+import { knockoutReviewRefusalsFor } from "./knockout-review-record.mjs";
 import { profilesStoreDir } from "./profiles.mjs";
 // The supplemental lane's single source (stages.mjs). The import is acyclic — stages.mjs reads
 // verify/coverage-ledger/config/framework and never reaches back here.
@@ -577,7 +585,7 @@ export function selectEngine() {
 //      name: an enrolled-token veto is an enumerated check, and a fifth token forgetting to enrol is the
 //      move-blindness this repo has counted seven instances of.
 //
-// What died here with the form path (2026-08-17 owner ruling, delete-not-gate): reading the seat's file
+// What died here with the form path (2026-08-17 ruling, delete-not-gate): reading the seat's file
 // as a SUBMISSION, preserving it, refereeing whose bytes it held (the isDriverOwnBytes machinery) and
 // rewriting the seat-facing copy. The seat writes no file, so there is no submission to read, no bytes
 // to referee, and no seat-facing copy to keep in step. The capture duty moved to the receiver

package/driver/hit-list.mjs

@@ -178,7 +178,7 @@ export function slimLine(rec, reading = null) {
   return line;
 }
 
-// ── CROWDS RIDE THE LIST AS A SIBLING ARRAY (Option A, ruled on tracker issue 95, 2026-08-31) ──────
+// ── CROWDS RIDE THE LIST AS A SIBLING ARRAY (Option A, ruled 2026-08-31) ──────────────────────────
 //
 // WHY THEY HAVE TO RIDE AT ALL. The locked body's acceptance 4 is that no stage reads the fat band or
 // an unpicked record. `band_lookup` answers from the list — but a lookup into a zone that was CROWDED

package/driver/jx-lanes.mjs

@@ -256,7 +256,7 @@ export { romanizationRefusal, romanizationSpellings };
 // The jx model calls (fold completions, serp-judge, nativeread) are the ONLY dispatches in the driver
 // that produce a per-token provider invoice. This comment used to name their executor as a
 // `@anthropic-ai/sdk` Messages call; that has not been true since the lane lost its own destination
-// and credential, and the SDK is no longer a dependency of this product at all (tracker issue 99).
+// and credential, and the SDK is no longer a dependency of this product at all.
 // The lane goes wherever the run's resolved program goes — the CLI opens every connection, and no
 // driver code calls a provider — so one run never mixes a subscription login with an API key. What
 // survives unchanged is the BILLING distinction this block is about: these calls land on a per-token

package/driver/jx.mjs

@@ -164,7 +164,7 @@ export function deriveJxSliceStatement({ sidecar, units = null, env = process.en
 // A reader concludes the deep lane ran. It does not follow: a profile set to `full` on an unarmed
 // deployment and one set to `candidates` on an armed deployment execute identically.
 //
-// OWNER RULING (2026-08-17): flag, do not gate. "If we can't run deep dive on serpAPI we need to flag
+// RULING (2026-08-17): flag, do not gate. "If we can't run deep dive on serpAPI we need to flag
 // it." So `depth` is not deleted and it does not start gating anything — the run derives what the lane
 // ACTUALLY got from the same durable record `executes` already comes from, and says so beside the ask.
 // Gating would change what a run executes and therefore what it bills; a flag changes only what the

package/driver/knockout-assess-record.mjs

@@ -164,7 +164,7 @@ const DECLARED = Object.freeze({
 
 /**
  * Refuse an undeclared key by path. THE SHARED IMPLEMENTATION (preserve-merge.mjs), which six transports
- * now use — reused rather than rebuilt, per this issue's own owner ruling.
+ * now use — reused rather than rebuilt, per this issue's own ruling.
  *
  * THE HAND-ROLLED FIRST CUT OF THIS WAS A PRODUCT-FAILURE RISK, and the shared module is why it did not
  * ship. Mine refused undeclared keys at the TOP LEVEL as well as inside typed sub-objects. The shared one