onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/review/obligation-shardability.js

@@ -0,0 +1,138 @@
+import { reviewMaterialGoals, } from "../target-material-kind.js";
+/**
+ * SEALED authority: obligations whose backing evidence intrinsically spans sections
+ * (cross-section), so independent sharding would destroy it (🔴 ILC-2). Keyed by obligation
+ * identity, decoupled from the shardability declaration. Editing this set is the ONLY way to
+ * change an obligation's relational status — a conspicuous, test-locked change
+ * (obligation-shardability.invariant.test.ts fixes membership), which is exactly what makes the
+ * gate fail-closed against a silent relational→independent weakening.
+ *
+ * `cross_sheet_reference_integrity` is the sole relational spreadsheet obligation: its backing
+ * (formula_patterns[].cross_sheet_refs + cross_sheet_key_overlap) is inherently cross-sheet.
+ * `formula_integrity` is NOT relational — its cross-sheet evidence is owned by the separate
+ * `cross_sheet_reference_integrity` obligation (computeBackedGoals splits them).
+ */
+const RELATIONAL_OBLIGATIONS = new Set([
+    "cross_sheet_reference_integrity",
+]);
+/** True when an obligation carries cross-section evidence (sealed ground truth). Pure. */
+export function isRelationalObligation(obligation) {
+    return RELATIONAL_OBLIGATIONS.has(obligation);
+}
+/** Derived projection: a mandatory cross-section seam is required to shard this obligation.
+ *  Deterministic from `material_shardability` — never stored. */
+export function requiresSeam(declaration) {
+    return declaration.material_shardability === "shardable_with_seam";
+}
+/**
+ * Per-obligation shardability declarations for a material kind, one-to-one with
+ * `reviewMaterialGoals(kind)`. Spreadsheet obligations are distilled from §3 of the design spec
+ * (conservative `whole` unless splitting is proven; `cross_sheet_reference_integrity` is the
+ * sole seam-gated relational obligation). Other kinds return `[]` until their per-material review
+ * adapters land — mirroring `reviewMaterialGoals`.
+ */
+export function reviewObligationShardability(kind) {
+    if (kind === "spreadsheet") {
+        return [
+            { obligation: "formula_integrity", material_shardability: "whole" },
+            {
+                obligation: "cross_sheet_reference_integrity",
+                material_shardability: "shardable_with_seam",
+            },
+            { obligation: "named_range_hygiene", material_shardability: "shardable_independent" },
+            { obligation: "data_validation_coverage", material_shardability: "shardable_independent" },
+            { obligation: "access_and_protection_hygiene", material_shardability: "whole" },
+            { obligation: "structural_risk_signals", material_shardability: "whole" },
+        ];
+    }
+    return [];
+}
+/**
+ * Pure validator core (git-free, injectable — mirrors check-obligation-coverage's
+ * `evaluateObligationCoverage`). Returns every violation; `[]` means the declarations are
+ * exhaustive AND consistent with the sealed relational authority. Relationality is read from the
+ * module's sealed `isRelationalObligation` — NOT from the (injectable) declarations — so a
+ * crafted declaration cannot launder its own relational status. Enforces INV-SHARD-1.
+ */
+export function evaluateObligationShardability(inputs) {
+    const violations = [];
+    const obligationSet = new Set(inputs.obligations);
+    const declarations = inputs.declarations;
+    // (1) exhaustiveness: no orphan / duplicate declarations.
+    const seen = new Set();
+    for (const declaration of declarations) {
+        if (!obligationSet.has(declaration.obligation)) {
+            violations.push({
+                obligation: declaration.obligation,
+                kind: "orphan_declaration",
+                detail: "declaration for an obligation not in the catalog",
+            });
+            continue;
+        }
+        if (seen.has(declaration.obligation)) {
+            violations.push({
+                obligation: declaration.obligation,
+                kind: "duplicate_declaration",
+                detail: "obligation declared more than once",
+            });
+            continue;
+        }
+        seen.add(declaration.obligation);
+        // (2) relational fail-closed: a relational obligation must not be shardable_independent.
+        if (isRelationalObligation(declaration.obligation) &&
+            declaration.material_shardability === "shardable_independent") {
+            violations.push({
+                obligation: declaration.obligation,
+                kind: "relational_independent",
+                detail: "relational obligation declared shardable_independent — would destroy cross-section evidence (ILC-2)",
+            });
+        }
+        // (3) seam is only for relational obligations.
+        if (declaration.material_shardability === "shardable_with_seam" &&
+            !isRelationalObligation(declaration.obligation)) {
+            violations.push({
+                obligation: declaration.obligation,
+                kind: "seam_on_local",
+                detail: "non-relational obligation declared shardable_with_seam — a seam is only for relational evidence",
+            });
+        }
+    }
+    // (1, cont.) every obligation has a declaration.
+    for (const obligation of inputs.obligations) {
+        if (!seen.has(obligation)) {
+            violations.push({
+                obligation,
+                kind: "missing_declaration",
+                detail: "obligation in the catalog has no shardability declaration",
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * fail-closed validator (the immediate consumer of the shardability declarations, so they are
+ * never a consumer-less dead struct). Wraps the pure core with the real per-kind catalog and
+ * declarations. `[]` for every kind is the Stage 2 lock (asserted by the G3 invariant test).
+ */
+export function validateObligationShardability(kind) {
+    return evaluateObligationShardability({
+        obligations: reviewMaterialGoals(kind),
+        declarations: reviewObligationShardability(kind),
+    });
+}
+/**
+ * Pure shardability gate (Stage 3 calls this; no consumer at Stage 2 — a pure function, not a
+ * data struct, so not a dead struct). A shard is permitted only when the obligation is not
+ * `whole`, the proposed shard keeps each element intact, and either it is independently
+ * shardable or its mandatory cross-section seam is actually covered. (design §5.3.)
+ */
+export function isObligationShardable(args) {
+    const { declaration, seam_covered, element_intact } = args;
+    if (declaration.material_shardability === "whole")
+        return false;
+    if (!element_intact)
+        return false;
+    if (declaration.material_shardability === "shardable_independent")
+        return true;
+    return seam_covered; // shardable_with_seam
+}

package/dist/core-runtime/review/pipeline-execution-ledger.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { deliberationResolutionPath, issueDeliberationPromptPacketPath, issueDeliberationResponsePath, } from "./controlled-lens-deliberation.js";
 import { synthesisLedgerPath, synthesisWorkItemsPath, } from "./synthesis-map-reduce.js";
 import { fileExists, readYamlDocument } from "./review-artifact-utils.js";
-import { PIPELINE_EXECUTION_LEDGER_SCHEMA_VERSION, buildLedgerTrust, buildOutputHashes, fileSha256IfPresent, isTrustedLedgerUnit, normalizeLedgerRefs, } from "../pipeline-execution-ledger.js";
+import { PIPELINE_EXECUTION_LEDGER_SCHEMA_VERSION, buildLedgerTrust, buildOutputHashes, fileSha256IfPresent, isResolvedLedgerUnit, normalizeLedgerRefs, } from "../pipeline-execution-ledger.js";
 const PRE_DELIBERATION_ISSUE_ARTIFACT_ORDER = [
     "finding-ledger",
     "finding-relation-graph",
@@ -442,6 +442,32 @@ async function buildUnitEntry(args) {
         downstreamUnitIds: args.downstreamUnitIds,
     };
 }
+/**
+ * 설계 A demotion-disclosure consumer: lenses listed in the persisted stance
+ * matrix's `validation.missing_stances` were demoted complete-with-failure
+ * after bounded resubmit exhaustion; the matrix consumed the gap, so their
+ * per-lens ledger units are terminally resolved (owe no further dispatch).
+ */
+async function demotedStanceUnitIdsFromMatrix(executionPlan) {
+    const matrixPath = executionPlan.issue_stance_matrix_path;
+    if (!matrixPath || !(await fileExists(matrixPath)))
+        return new Set();
+    try {
+        const matrix = await readYamlDocument(matrixPath);
+        return new Set((matrix.validation?.missing_stances ?? [])
+            .map((entry) => entry?.lens_id)
+            .filter((lensId) => typeof lensId === "string")
+            .map((lensId) => `issue-stance:${lensId}`));
+    }
+    catch (error) {
+        // The matrix's `validation.missing_stances` is the only durable authority
+        // for stance demotion. A present-but-unreadable/unparseable matrix (torn
+        // write, out-of-band corruption) must fail loud instead of silently
+        // returning an empty set — a silent empty set would drop the demotion
+        // signal and regress the affected stance unit(s) to unresolved/blocked.
+        throw new Error(`Failed to read demoted stance units from issue-stance matrix at ${matrixPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export async function buildReviewPipelineExecutionLedger(params) {
     const [deliberationDiskUnits, synthesisDiskUnits] = await Promise.all([
         deliberationUnitsFromDisk(params.executionPlan),
@@ -471,6 +497,10 @@ export async function buildReviewPipelineExecutionLedger(params) {
     const workerUnitsByUnitId = firstWinsByUnitId((params.reviewRunManifest?.worker_units ?? []).filter((unit) => typeof unit.unit_id === "string"), (unit) => unit.unit_id);
     const trustedUnitIds = new Set();
     const ledgerUnits = [];
+    // Lazy + memoized: the matrix read matters only when some stance unit is
+    // not completed; a healthy run (frontier loops call this builder per
+    // iteration) never pays the stat+read+parse.
+    let demotedStanceUnitIds = null;
     for (const plannedUnit of units) {
         const entry = await buildUnitEntry({
             plannedUnit,
@@ -484,8 +514,18 @@ export async function buildReviewPipelineExecutionLedger(params) {
             hasReviewRunManifest: params.reviewRunManifest !== null && params.reviewRunManifest !== undefined,
             trustedUnitIds,
         });
+        if (plannedUnit.unitId.startsWith("issue-stance:") &&
+            entry.status !== "completed") {
+            demotedStanceUnitIds ??= await demotedStanceUnitIdsFromMatrix(params.executionPlan);
+            if (demotedStanceUnitIds.has(plannedUnit.unitId)) {
+                entry.resolution = "demoted";
+            }
+        }
         ledgerUnits.push(entry);
-        if (isTrustedLedgerUnit(entry))
+        // Trusted output or terminally resolved — a demoted unit satisfies
+        // downstream upstream-trust because the stage product consumed the
+        // disclosed gap, not the unit's (absent) output.
+        if (isResolvedLedgerUnit(entry))
             trustedUnitIds.add(entry.unitId);
     }
     return {

package/dist/core-runtime/review/review-artifact-utils.js

@@ -2,6 +2,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
 import { atomicWriteFile } from "../artifact-io.js";
+import { isSpreadsheetRef } from "../target-material-kind.js";
+import { DEFAULT_WORKBOOK_INVENTORY_PROMPT_CAPS, observeSpreadsheetSource, projectInventoryForAdmission, projectInventoryForPrompt, } from "../spreadsheet-structure-observer.js";
 export const DEFAULT_EXCLUDED_NAMES = [
     ".git",
     "node_modules",
@@ -174,9 +176,219 @@ export async function collectFilePathsRecursively(rootPath, options, currentDept
     }
     return collected.sort();
 }
-export async function readTextOrDirectoryListing(targetPath, options) {
+/**
+ * Render the workbook inventory as a compact text view for the review prompt
+ * (design §3.2 — the "inventory projection (text view)"). Honesty
+ * (review-target-profile §6): structure is inspected only, cell values and formula
+ * results are not evaluated.
+ *
+ * The view carries bounded DETAIL — not just counts — for every section that backs a
+ * kind-derived review obligation (`reviewMaterialGoals`): formula TEXT + cross-sheet
+ * refs, named-range refers_to, data-validation rule_summary, error-cell tokens, and
+ * external-link targets. Without the detail those obligations would be unverifiable
+ * (the reviewer would be told to audit content that is only an integer in the prompt).
+ * Two projections compose: `projectInventoryForAdmission` drops raw cell values, then
+ * `projectInventoryForPrompt` bounds array SIZE so a large workbook cannot overflow the
+ * prompt. Anything trimmed is surfaced honestly (the "structural sample bounded" line);
+ * the full detail stays in the persisted inventory.
+ */
+function renderSpreadsheetStructuralView(inventory, caps) {
+    const lines = [
+        "[Spreadsheet Structural Inventory — structure inspected only; cell values and formula results are not evaluated]",
+        `workbook_kind: ${inventory.workbook_kind}`,
+        `content_sha256: ${inventory.content_sha256}`,
+    ];
+    if (inventory.unsupported_reason) {
+        lines.push(`unsupported: ${inventory.unsupported_reason}`);
+        return `${lines.join("\n")}\n`;
+    }
+    // Stage 1: when the caller threads window-proportional caps, size the prompt
+    // projection to the lens model's window; otherwise the DEFAULT caps keep the
+    // render byte-identical to today (no regression).
+    const { inventory: inv, sections } = projectInventoryForPrompt(projectInventoryForAdmission(inventory), caps ?? DEFAULT_WORKBOOK_INVENTORY_PROMPT_CAPS);
+    // One rendered formula PATTERN line (Stage 1.1): the deduped formula TEXT + how many
+    // cells carry it (occurrence_count) + a representative cell + the sheets it spans + any
+    // cross-sheet references — the obligation-backing detail for formula_integrity /
+    // cross_sheet_reference_integrity (a count alone is not auditable). A fill-down that was
+    // tens of thousands of per-cell rows now renders as one auditable line.
+    const renderFormulaPatternLine = (pattern) => {
+        const xref = pattern.cross_sheet_refs.length > 0
+            ? `  [cross-sheet → ${pattern.cross_sheet_refs.join(", ")}]`
+            : "";
+        return (`  - ${pattern.pattern}  (×${pattern.occurrence_count}, e.g. ${pattern.sample_cell}` +
+            `; sheets: ${pattern.sheets.join(", ")})${xref}`);
+    };
+    // Friendly labels for the bounded-sample note. A3: count-only sections
+    // (tables/merged_ranges, printed as full counts below) are SUPPRESSED from the note so it
+    // never contradicts them (RC-2); every OTHER projector-recorded trim is disclosed —
+    // friendly label when known, else the raw section key — so a newly-added
+    // projectInventoryForPrompt section can never be silently dropped from disclosure (#4 class).
+    const NOTE_SECTION_LABELS = {
+        per_sheet_data: "sheet bodies",
+        "per_sheet_data.columns": "columns",
+        distinct_value_vocab: "distinct-value columns",
+        formula_patterns: "formula patterns",
+        named_ranges: "named_ranges",
+        data_validations: "data_validations",
+        external_links: "external_links",
+        error_cells: "error_cells",
+        pivot_tables: "pivot_tables",
+        cross_sheet_key_overlap: "cross_sheet_key_overlap",
+        "cross_sheet_key_overlap.pairwise_overlap": "cross-sheet pairwise overlaps",
+        risk_signals: "risk_signals",
+    };
+    const COUNT_ONLY_TRIM_SECTIONS = new Set(["tables", "merged_ranges"]);
+    const trimSectionLabel = (section) => NOTE_SECTION_LABELS[section] ?? section;
+    const renderedTrims = sections.filter((s) => !COUNT_ONLY_TRIM_SECTIONS.has(s.section));
+    // Total sheet count comes from the FULL inventory; the per-sheet layout below renders only
+    // the sheets whose (capped) per_sheet_data body survived projection.
+    // When observation was bounded by the sheet cap, sheet_count_total holds the true total —
+    // render "N of M observed" so the count is not mis-reported as the post-cap number, and a
+    // reviewer knows beyond-cap sheets (and any protection/structure on them) were not observed.
+    const sheetCountLabel = inventory.sheet_count_total !== undefined
+        ? `${inventory.sheets.length} of ${inventory.sheet_count_total} observed`
+        : `${inventory.sheets.length}`;
+    lines.push(`sheets: ${sheetCountLabel}${inv.capture_truncated ? " (capture truncated)" : ""}`);
+    if (renderedTrims.length > 0) {
+        // Honest about WHAT this note means: review renders a bounded PROMPT sample and does not
+        // persist the full WorkbookStructuralInventory, so the trimmed detail is not separately
+        // recoverable — never imply the dropped rows can be retrieved later (R1).
+        lines.push(`structural sample bounded (prompt sample only — review does not persist the full inventory): ${renderedTrims
+            .map((s) => `${trimSectionLabel(s.section)} ${s.kept}/${s.total}`)
+            .join(", ")}`);
+    }
+    const renderedSheetNames = new Set(inv.per_sheet_data.map((d) => d.sheet));
+    // B3: protected/hidden sheets beyond the per_sheet_data render cap keep
+    // access_and_protection_hygiene attached, but their flags are emitted only inside the
+    // per-sheet layout below (rendered-sheet set) — disclose the beyond-cap count so a
+    // reviewer does not read the silence as "the rest are unprotected/visible".
+    const beyondCapAccessFlags = inventory.sheets.filter((sheet) => !renderedSheetNames.has(sheet.name) && (sheet.protected || sheet.hidden));
+    if (beyondCapAccessFlags.length > 0) {
+        lines.push(`${beyondCapAccessFlags.length} protected/hidden sheet(s) beyond the rendered sample (flags not individually shown; access_and_protection_hygiene still applies)`);
+    }
+    // B2: obligation-backing detail is emitted UP FRONT — before the per-sheet bodies — so the
+    // downstream 300-line embed head-cut (truncateForEmbedding) preserves the evidence backing
+    // named_range_hygiene / data_validation_coverage / structural_risk_signals /
+    // cross_sheet_reference_integrity even for a many-sheet workbook. Reordering alone is
+    // zero-sum under a fixed budget, so each obligation class gets a bounded in-band sample
+    // here; the per-sheet layout (columns) follows and may be truncated under heavy load
+    // without dropping any obligation backing.
+    if (inventory.named_ranges.length) {
+        lines.push("", `named_ranges: ${inventory.named_ranges.length}`);
+        for (const nr of inv.named_ranges) {
+            lines.push(`  - ${nr.name} (${nr.scope}) → ${nr.refers_to}`);
+        }
+    }
+    if (inventory.data_validations.length) {
+        lines.push("", `data_validations: ${inventory.data_validations.length}`);
+        for (const dv of inv.data_validations) {
+            // design-C: surface the DECLARED type=list enum members HERE (this loop runs over EVERY
+            // validation, independent of per-sheet column/sheet rendering) so they reach the prompt even
+            // when the column is trimmed by the column cap, the sheet is dropped by the sheet cap, the
+            // sheet has no profiled columns, or one column carries multiple disjoint list validations
+            // (Codex round3 #2/#3/#4/#7). Members are DECLARED labels (bounded), not observed data.
+            const enumLabels = dv.members && dv.members.length > 0 ? ` enum=[${dv.members.join(", ")}]` : "";
+            lines.push(`  - ${dv.sheet}!${dv.range}: ${dv.rule_summary}${enumLabels}`);
+        }
+    }
+    if (inventory.error_cells.length) {
+        lines.push("", `error_cells: ${inventory.error_cells.length}`);
+        for (const ec of inv.error_cells) {
+            lines.push(`  - ${ec.sheet}!${ec.cell}: ${ec.token}`);
+        }
+    }
+    if (inventory.external_links.length) {
+        lines.push("", `external_links: ${inventory.external_links.length}`);
+        for (const el of inv.external_links) {
+            lines.push(`  - ${el.kind}: ${el.target}`);
+        }
+    }
+    // Remaining structural facts that are obligation context but not per-item audit detail.
+    const counts = [];
+    if (inventory.tables.length)
+        counts.push(`tables: ${inventory.tables.length}`);
+    if (inventory.merged_ranges.length)
+        counts.push(`merged_ranges: ${inventory.merged_ranges.length}`);
+    if (inventory.macro_present)
+        counts.push("macro_present: true");
+    if (counts.length)
+        lines.push("", counts.join("; "));
+    if (inventory.pivot_tables.length) {
+        lines.push("", `pivot_tables: ${inventory.pivot_tables.length}`);
+        for (const p of inv.pivot_tables) {
+            const src = p.source_sheet ? ` source=${p.source_sheet}!${p.source_ref ?? ""}` : "";
+            lines.push(`  - ${p.name} @ ${p.sheet}!${p.location}${src}`);
+            lines.push(`    rows=[${p.row_fields.join(", ")}] cols=[${p.column_fields.join(", ")}]` +
+                ` data=[${p.data_fields.join(", ")}] filters=[${p.page_fields.join(", ")}]`);
+        }
+    }
+    if (inventory.cross_sheet_key_overlap.length) {
+        lines.push("", "cross_sheet_key_overlap (shared-column value overlap, counts only):");
+        for (const o of inv.cross_sheet_key_overlap) {
+            const pairs = o.pairwise_overlap.map((p) => `${p.a}∩${p.b}=${p.count}`).join(", ");
+            lines.push(`  - ${o.key_name} across [${o.sheets.join(", ")}]: ${pairs}`);
+        }
+    }
+    if (inventory.risk_signals.length) {
+        lines.push("", "risk_signals:");
+        for (const signal of inv.risk_signals) {
+            lines.push(`  - ${signal.kind} @ ${signal.location}: ${signal.literal}`);
+        }
+    }
+    // formula_integrity / cross_sheet_reference_integrity backing: the deduplicated formula
+    // PATTERNS (Stage 1.1), emitted up front (before the per-sheet bodies) so the formula TEXT
+    // survives the embed cut. A fill-down (one master replicated across N cells) is one pattern
+    // here; formula_cells_total reports the honest cell count (lower-bound when the distinct-
+    // pattern cap dropped a new pattern), so the reviewer sees both the distinct logic and its
+    // true reach. Each pattern carries the sheets it spans, so a workbook whose formulas live
+    // only on a trimmed sheet still shows its formula text.
+    if (inv.formula_patterns.length > 0) {
+        const lowerBound = inv.formula_cells_total_is_lower_bound ? ", lower-bound" : "";
+        lines.push("", `formulas: ${inv.formula_patterns.length} distinct patterns over ${inv.formula_cells_total} cells${lowerBound}:`);
+        for (const pattern of inv.formula_patterns) {
+            lines.push(renderFormulaPatternLine(pattern));
+        }
+    }
+    // Per-sheet LAYOUT (dimensions + columns) — context that follows the obligation backing
+    // above and may be truncated under heavy load without losing any obligation evidence.
+    for (const sheet of inv.sheets.filter((s) => renderedSheetNames.has(s.name))) {
+        const flags = `${sheet.hidden ? " (hidden)" : ""}${sheet.protected ? " (protected)" : ""}`;
+        lines.push("", `## sheet: ${sheet.name}`, `dimensions: ${sheet.dimensions.rows} rows × ${sheet.dimensions.cols} cols${flags}`);
+        const data = inv.per_sheet_data.find((d) => d.sheet === sheet.name);
+        if (data) {
+            const lowConfidence = data.header_confidence === "low" ? "; header_confidence: low (layout uncertain)" : "";
+            lines.push(`layout_kind: ${data.layout_kind}; header_rows: ${data.header_rows ? data.header_rows.join(",") : "none"}${lowConfidence}`);
+            if (data.columns.length > 0) {
+                lines.push("columns:");
+                for (const col of data.columns) {
+                    const vocab = inv.distinct_value_vocab.find((v) => v.sheet === sheet.name && v.column === col.name);
+                    const distinct = vocab
+                        ? `; distinct≈${vocab.distinct_count}${vocab.distinct_count_is_estimate ? "+" : ""}`
+                        : "";
+                    // design-C per-column cardinality: distinct/non_empty COUNT over scanned rows. Declared
+                    // type=list enum members are surfaced in the data_validations section (above), NOT here —
+                    // so they survive column/sheet trimming and multi-validation columns (Codex round3).
+                    const cardinality = `; cardinality=${col.distinct_count}${col.distinct_count_is_estimate ? "+" : ""}/${col.non_empty_count}`;
+                    lines.push(`  - ${col.name} (${col.inferred_type}; non_empty=${col.non_empty_ratio.toFixed(2)}${cardinality}${distinct})`);
+                }
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function readTextOrDirectoryListing(targetPath, options, inventory, inventoryPromptCaps) {
     const stats = await fs.stat(targetPath);
     if (!stats.isDirectory()) {
+        // Spreadsheet targets are rendered as a structural/aggregate inventory view,
+        // not raw bytes (design §3.2). review routes through the SAME shared projection
+        // as reconstruct — raw cell values never enter the prompt, and a binary
+        // workbook is never dumped as garbage utf8. When the orchestrator already
+        // observed this ref (single-observation, design §3.2), reuse that inventory;
+        // otherwise observe here. The render applies the admission + prompt projections,
+        // sized by the optional Stage 1 window-proportional caps (undefined → DEFAULT).
+        if (isSpreadsheetRef(targetPath)) {
+            return renderSpreadsheetStructuralView(inventory ?? (await observeSpreadsheetSource(targetPath)), inventoryPromptCaps);
+        }
         try {
             return await fs.readFile(targetPath, "utf8");
         }
@@ -208,20 +420,20 @@ export async function readTextOrDirectoryListing(targetPath, options) {
         : "";
     return `[Directory Listing]\n${listing}\n${truncationNote}`;
 }
-export async function renderTargetSnapshot(resolvedTargetRefs, options) {
+export async function renderTargetSnapshot(resolvedTargetRefs, options, inventoryByRef, inventoryPromptCaps) {
     const sections = [];
     for (const resolvedTargetRef of resolvedTargetRefs) {
-        sections.push(`## ${resolvedTargetRef}`, "", await readTextOrDirectoryListing(resolvedTargetRef, options), "");
+        sections.push(`## ${resolvedTargetRef}`, "", await readTextOrDirectoryListing(resolvedTargetRef, options, inventoryByRef?.get(path.resolve(resolvedTargetRef)), inventoryPromptCaps), "");
     }
     return `${sections.join("\n").trimEnd()}\n`;
 }
-export async function renderReviewTargetMaterializedInput(materializedKind, materializedRefs, options) {
+export async function renderReviewTargetMaterializedInput(materializedKind, materializedRefs, options, inventoryByRef, inventoryPromptCaps) {
     const sections = [`kind: ${materializedKind}`, ""];
     for (const materializedRef of materializedRefs) {
         sections.push(`## ${path.basename(materializedRef)}`);
         sections.push(`ref: ${materializedRef}`);
         sections.push("");
-        sections.push(await readTextOrDirectoryListing(materializedRef, options));
+        sections.push(await readTextOrDirectoryListing(materializedRef, options, inventoryByRef?.get(path.resolve(materializedRef)), inventoryPromptCaps));
         sections.push("");
     }
     return `${sections.join("\n").trimEnd()}\n`;

package/dist/core-runtime/review/review-execution-steps.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileExists, isoNow, readYamlDocument, writeYamlDocument, } from "./review-artifact-utils.js";
 import { buildReviewPipelineExecutionLedger, } from "./pipeline-execution-ledger.js";
-import { fileSha256IfPresent, isTrustedLedgerUnit, } from "../pipeline-execution-ledger.js";
+import { fileSha256IfPresent, isResolvedLedgerUnit, isTrustedLedgerUnit, } from "../pipeline-execution-ledger.js";
 import { buildReviewContinuationPlan, } from "./continuation-plan.js";
 import { readValidatedLensSidecarArtifact } from "./lens-sidecar-artifact.js";
 import { computeLensCompletionBarrier, resolveRequiredParticipatingLensCount, } from "./lens-completion-policy.js";
@@ -30,6 +30,23 @@ import { renderReviewUnitBoundaryDetailsSection } from "./unit-boundary-details.
  * step calls `completeReviewSession`, which lives in the cli layer, so the
  * core-api wrapper runs it when reviewAdvance signals `ready_to_assemble`.
  */
+/**
+ * Single-source runtime mirror of the closed {@link ReviewUnitKind} union. The
+ * `satisfies Record<ReviewUnitKind, true>` makes adding an enum member a compile
+ * error here, so a new kind cannot be planned/executed until it is wired into the
+ * result buckets ({@link mergeUnitResultIntoExecutionResult}) and the seat gate.
+ * This is the guard against the silent-drop where an unhandled unit_kind would
+ * leave the frontier permanently stalled with no error.
+ */
+const REVIEW_UNIT_KINDS = {
+    lens: true,
+    issue_artifact: true,
+    deliberation: true,
+    synthesize: true,
+};
+function isReviewUnitKind(value) {
+    return Object.prototype.hasOwnProperty.call(REVIEW_UNIT_KINDS, value);
+}
 async function readOptionalYamlArtifact(filePath) {
     if (!(await fileExists(filePath)))
         return null;
@@ -136,6 +153,9 @@ export async function computeReviewFrontier(sessionRoot, targetUnits) {
  */
 export async function validateUnitSeatToResult(args) {
     const { unit } = args;
+    if (!isReviewUnitKind(unit.unitKind)) {
+        throw new Error(`validateUnitSeatToResult: unit ${unit.unitId} has unknown unit_kind "${unit.unitKind}" (not a ReviewUnitKind); a new kind must be wired into the result buckets and frontier routing before it can be executed.`);
+    }
     const executionPlan = args.executionPlan ?? (await loadExecutionPlan(args.sessionRoot));
     const recordedAt = args.recordedAt ?? isoNow();
     const baseResult = (extra) => ({
@@ -251,8 +271,10 @@ export async function mergeUnitResultIntoExecutionResult(args) {
                         ...artifact,
                         synthesis_map_execution_results: upsertUnitResult(artifact.synthesis_map_execution_results ?? [], result),
                     };
-            default:
-                return artifact;
+            default: {
+                const exhaustive = result.unit_kind;
+                throw new Error(`mergeUnitResultIntoExecutionResult: no execution-result bucket for unit_kind "${String(exhaustive)}" (unit ${result.unit_id}); extend this switch when adding a ReviewUnitKind.`);
+            }
         }
     })();
     await writeYamlDocument(resultPath, merged);
@@ -829,7 +851,8 @@ async function ensureDeliberationMarkdownProjection(sessionRoot, plan) {
  */
 async function finalizeHostExecutionResultIfComplete(sessionRoot, plan) {
     const ledger = await buildSessionLedger(sessionRoot, plan);
-    if (!ledger.units.every((unit) => isTrustedLedgerUnit(unit)))
+    // Convergence = no owed work: trusted OR terminally resolved (demoted).
+    if (!ledger.units.every((unit) => isResolvedLedgerUnit(unit)))
         return;
     const resultPath = executionResultPath(sessionRoot);
     const existing = await readOptionalYamlArtifact(resultPath);
@@ -874,10 +897,11 @@ async function finalizeHostExecutionResultIfComplete(sessionRoot, plan) {
  */
 async function computeRoundResult(sessionRoot, plan) {
     const frontier = await computeReviewFrontier(sessionRoot);
-    // Terminal: every ledger unit is trusted, so there is nothing left to run and
-    // the caller assembles. (A continuation plan with no untrusted frontier is
-    // `eligible: false`, so this must precede the ineligibility check.)
-    if (frontier.unitLedger.units.every((unit) => isTrustedLedgerUnit(unit))) {
+    // Terminal: every ledger unit owes no work (trusted or terminally
+    // resolved), so there is nothing left to run and the caller assembles.
+    // (A continuation plan with no untrusted frontier is `eligible: false`,
+    // so this must precede the ineligibility check.)
+    if (frontier.unitLedger.units.every((unit) => isResolvedLedgerUnit(unit))) {
         return { status: "ready_to_assemble" };
     }
     if (!frontier.eligible) {

package/dist/core-runtime/review/review-progress-contract.js

@@ -105,6 +105,10 @@ export function reviewProgressStepIdFromHalt(args) {
     if (args.haltPhase === "lens_completion_barrier") {
         return "lens_completion_barrier";
     }
+    // 설계 B: lens 풀 dispatch breaker 트립은 lens 디스패치 단계에서 멈춘
+    // 것이다 (배리어 판정 이전; halt_unit_kind는 null로 온다).
+    if (args.haltPhase === "lens_dispatch_breaker")
+        return "lens_dispatch";
     if (args.haltPhase === "synthesize")
         return "synthesize";
     if (args.haltPhase === "controlled_lens_deliberation") {
@@ -114,6 +118,10 @@ export function reviewProgressStepIdFromHalt(args) {
     }
     if (args.haltPhase === "issue_artifact") {
         const unitId = args.haltUnitId;
+        // 동적 per-lens stance 유닛(issue-stance:<lens>)은 issue-stance-matrix
+        // 산출 단계에 속한다 — issue_artifact_id 정확 일치로는 매핑되지 않는다.
+        if (unitId?.startsWith("issue-stance:"))
+            return "issue_stance_matrix";
         const step = REVIEW_PROGRESS_STEPS.find((candidate) => candidate.issue_artifact_id === unitId);
         return step?.id ?? "finding_ledger";
     }