@interf/compiler 0.2.5 → 0.3.1

package/dist/lib/workflows-kb.js

@@ -1,306 +0,0 @@
-import { join } from "node:path";
-import { countFilesRecursive } from "./filesystem.js";
-import { readInterfConfig, refreshWorkspaceBootstrapGuidance, resolveKnowledgeBaseSourcePath, } from "./interf.js";
-import { buildSummarizePlan, writeSummarizePlan } from "./summarize-plan.js";
-import { reconcileKnowledgeBaseCompileRun, reconcileKnowledgeBaseSummarizeRun, } from "./runtime-reconcile.js";
-import { loadState, refreshKnowledgeBaseArtifacts, } from "./state.js";
-import { buildKnowledgeBaseSummarizeContract, validateStageContractAcceptance, } from "./runtime.js";
-import { readJsonFileUnchecked } from "./parse.js";
-import { formatKnowledgeBaseWorkflowStageStep, getKnowledgeBaseWorkflow, getWorkflowStagePolicyNotes, resolveKnowledgeBaseWorkflowFromConfig, } from "./workflow-definitions.js";
-import { validateKnowledgeBaseSummarize, validateKnowledgeBaseCompile, } from "./validate.js";
-import { reportLine, reportBlankLine, reportValidationFailure, buildLocalSkillContractExtension, buildStageInstructions, bundledSkillForContractType, resolveStageAcceptance, workflowCompileStageDirectory, } from "./workflow-helpers.js";
-import { executeValidatedStage, executeValidatedSummarizeStage, findStageByContractType, } from "./workflow-stage-runner.js";
-// ---------------------------------------------------------------------------
-// KB-specific helpers
-// ---------------------------------------------------------------------------
-export function resolveKnowledgeBaseContext(knowledgeBasePath) {
-    const config = readInterfConfig(knowledgeBasePath);
-    const workflowId = resolveKnowledgeBaseWorkflowFromConfig(config);
-    return {
-        knowledgeBaseName: config?.name ?? "knowledge-base",
-        sourcePath: resolveKnowledgeBaseSourcePath(knowledgeBasePath, config),
-        workflowId,
-    };
-}
-export function knowledgeBaseExecutionStages(workflowId, knowledgeBasePath) {
-    return getKnowledgeBaseWorkflow(workflowId, { workspacePath: knowledgeBasePath }).stages;
-}
-function readKnowledgeBaseInventoryTotal(knowledgeBasePath) {
-    const inventory = readJsonFileUnchecked(join(knowledgeBasePath, ".interf", "inventory.json"), "knowledge-base inventory");
-    if (!inventory)
-        return 0;
-    if (typeof inventory.total === "number")
-        return inventory.total;
-    if (typeof inventory.summary_total === "number")
-        return inventory.summary_total;
-    if (Array.isArray(inventory.entries))
-        return inventory.entries.length;
-    if (Array.isArray(inventory.summaries))
-        return inventory.summaries.length;
-    if (Array.isArray(inventory.files))
-        return inventory.files.length;
-    return 0;
-}
-function isKnowledgeBaseSummarizeStageComplete(knowledgeBasePath, expectedSummaryTotal) {
-    const validation = validateKnowledgeBaseSummarize(knowledgeBasePath);
-    const acceptance = validateStageContractAcceptance(knowledgeBasePath);
-    const state = loadState(knowledgeBasePath);
-    const inventoryTotal = readKnowledgeBaseInventoryTotal(knowledgeBasePath);
-    return Boolean(validation.ok &&
-        acceptance.ok &&
-        state?.inventory_complete === true &&
-        typeof state.last_summarize === "string" &&
-        state.last_summarize.length > 0 &&
-        (state.summarized ?? 0) >= expectedSummaryTotal &&
-        inventoryTotal >= expectedSummaryTotal);
-}
-// ---------------------------------------------------------------------------
-// KB compile contract builder
-// ---------------------------------------------------------------------------
-export function buildKnowledgeBaseCompileContract(knowledgeBasePath, workflowId, summaryCount, instructions, stageId = "compile", stageSkillDir = "compile") {
-    const sourcePath = resolveKnowledgeBaseSourcePath(knowledgeBasePath);
-    const acceptance = resolveStageAcceptance("knowledge-base", workflowId, stageId, sourcePath, knowledgeBasePath);
-    const localSkills = buildLocalSkillContractExtension(knowledgeBasePath, [workflowCompileStageDirectory(stageSkillDir)], "Use them to refine knowledge-base compile behavior, entity/claim extraction, and retrieval structure.");
-    return {
-        instructions,
-        counts: {
-            summary_total: summaryCount,
-            local_skill_docs: localSkills.count,
-        },
-        ...(acceptance ? { acceptance } : {}),
-        artifacts: {
-            reads: [
-                "interf.json",
-                "summaries/",
-                ...localSkills.reads,
-            ],
-            writes: [
-                ".interf/inventory.json",
-                "knowledge/entities/",
-                "knowledge/claims/",
-                "knowledge/indexes/",
-                "home.md",
-            ],
-            verifies: [
-                "interf verify compile --json",
-            ],
-        },
-        policies: {
-            execution_mode: "deterministic",
-            status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
-            notes: [
-                "Build or refresh `.interf/inventory.json` first, then use it as the progress ledger for the rest of the run.",
-                "Prefer the current inventory runtime shape: `.interf/inventory.json` should use `entries` plus `total`, and each entry should carry `source`, `summary`, `frontmatter_scanned: true`, and the abstract/overview-read proof needed for compile verification.",
-                "This stage is the knowledge-base compile pass. Treat synthesis outputs as evidence objects, not final truth.",
-                "Use a multi-pass approach: inventory -> local evidence reading -> canonicalization -> retrieval optimization.",
-                "Build retrieval-oriented outputs: canonical entities, cross-file claims, timelines, themes, and navigation indexes that make interface retrieval easier later.",
-                "Write structured knowledge outputs under `knowledge/entities/`, `knowledge/claims/`, and `knowledge/indexes/`.",
-                "Do not collapse the knowledge-base knowledge layer into flat files like `knowledge/entities.md` or `knowledge/claims.md`.",
-                "Do not start compile by deleting prior outputs with `rm`, wildcard cleanup, `;`, or `&&` chains. Rewrite the required files directly and remove stale artifacts only with narrow, explicit path writes when truly needed.",
-                ...(summaryCount <= 3
-                    ? [
-                        `This run has ${summaryCount} summary file${summaryCount === 1 ? "" : "s"}. Treat it as a tiny compile: read every summary overview, write the smallest truthful substrate immediately, then stop.`,
-                        "For a tiny compile, do not spend time designing a broad ontology or rereading the same evidence loop. A compact landing layer plus a small grounded retrieval surface is enough.",
-                        "For a tiny compile, finish as soon as `home.md`, the stable core indexes, and at least one grounded entity or claim note exist together with a valid inventory.",
-                    ]
-                    : []),
-                ...getWorkflowStagePolicyNotes("knowledge-base", workflowId, stageId, sourcePath, knowledgeBasePath),
-                ...localSkills.notes,
-            ],
-            evidence_weighting: {
-                required_fields: ["source_kind", "evidence_tier", "truth_mode", "state"],
-                preserve_tiers: true,
-            },
-            working_set: {
-                target_context_fraction: 0.4,
-                strategy: "Batch summary reads into bounded working sets, then canonicalize and optimize retrieval in multiple passes.",
-            },
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// KB orchestration functions
-// ---------------------------------------------------------------------------
-export async function runKnowledgeBaseSummarize(options) {
-    const context = resolveKnowledgeBaseContext(options.knowledgeBasePath);
-    const sourcePath = options.sourcePath ?? context.sourcePath;
-    const workflowId = context.workflowId;
-    const stageDefinition = options.stageDefinition ?? findStageByContractType(knowledgeBaseExecutionStages(workflowId, options.knowledgeBasePath), "kb-file-evidence");
-    const stageStatusLabel = stageDefinition.label.toLowerCase();
-    const plan = buildSummarizePlan(sourcePath, options.knowledgeBasePath, options.fullPass ? "all" : "pending");
-    const expectedSummaryTotal = plan.summaryCount + plan.targetCount;
-    const planPath = writeSummarizePlan(options.knowledgeBasePath, plan);
-    const localSkills = buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine summary structure, evidence grouping, and summarization heuristics.");
-    const instructions = buildStageInstructions(bundledSkillForContractType(stageDefinition.contractType), localSkills);
-    if (options.reportSummary !== false) {
-        reportLine(options.reporter, `${plan.sourceCount} source files, ${plan.summaryCount} summarized, ${plan.targetCount} to summarize`);
-    }
-    if (plan.targetCount === 0) {
-        refreshKnowledgeBaseArtifacts(options.knowledgeBasePath, { ensureViewSpec: true });
-        const validation = validateKnowledgeBaseSummarize(options.knowledgeBasePath);
-        if (options.reportStep !== false) {
-            reportLine(options.reporter, `${formatKnowledgeBaseWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath })} skipped (no work required)`);
-        }
-        if (!validation.ok) {
-            reportValidationFailure(options.reporter, validation.summary);
-        }
-        return {
-            ok: validation.ok,
-            code: validation.ok ? 0 : 1,
-            skipped: true,
-            plan,
-        };
-    }
-    if (options.reportStep !== false) {
-        reportLine(options.reporter, `${formatKnowledgeBaseWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath })} (${plan.targetCount} files)`);
-    }
-    const stageResult = await executeValidatedSummarizeStage({
-        executor: options.executor,
-        workspacePath: options.knowledgeBasePath,
-        targetType: "knowledge-base",
-        targetName: context.knowledgeBaseName,
-        workflow: workflowId,
-        workflowSourcePath: sourcePath,
-        stageDefinition,
-        instructions,
-        summary: `Preparing ${stageDefinition.label.toLowerCase()} for ${plan.targetCount} source files.`,
-        contract: buildKnowledgeBaseSummarizeContract({
-            knowledgeBaseName: context.knowledgeBaseName,
-            targetCount: plan.targetCount,
-            expectedSummaryTotal,
-            sourcePath,
-            planPath,
-            workflowNotes: getWorkflowStagePolicyNotes("knowledge-base", workflowId, stageDefinition.id, sourcePath, options.knowledgeBasePath),
-            localSkillDocs: localSkills.reads,
-            instructions,
-            acceptance: resolveStageAcceptance("knowledge-base", workflowId, stageDefinition.id, sourcePath, options.knowledgeBasePath),
-        }),
-        statusLines: [
-            `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${plan.targetCount} files.`,
-            "The CLI owns live file-count progress. Do not emit per-file progress.",
-            "If `.interf/inventory.json` already exists, overwrite it completely instead of patching prior contents.",
-            "Emit STATUS: batch committed after a completed batch has been merged into summaries/ and inventory.",
-            `Emit DONE: ${stageStatusLabel} complete ${plan.targetCount}/${plan.targetCount} when finished.`,
-        ],
-        reporter: options.reporter,
-        completionCheck: () => isKnowledgeBaseSummarizeStageComplete(options.knowledgeBasePath, expectedSummaryTotal),
-        reconcile: () => reconcileKnowledgeBaseSummarizeRun(options.knowledgeBasePath, expectedSummaryTotal),
-        refreshArtifacts: () => refreshKnowledgeBaseArtifacts(options.knowledgeBasePath, { ensureViewSpec: true }),
-        validate: () => validateKnowledgeBaseSummarize(options.knowledgeBasePath),
-        startingSummaryCount: plan.summaryCount,
-        targetCount: plan.targetCount,
-    });
-    if (!stageResult.ok) {
-        return {
-            ok: false,
-            code: stageResult.code,
-            skipped: false,
-            plan,
-        };
-    }
-    return {
-        ok: true,
-        code: 0,
-        skipped: false,
-        plan,
-    };
-}
-export async function runKnowledgeBaseCompile(options) {
-    const knowledgeBaseConfig = readInterfConfig(options.knowledgeBasePath);
-    const knowledgeBaseName = knowledgeBaseConfig?.name ?? "knowledge-base";
-    const workflowId = resolveKnowledgeBaseWorkflowFromConfig(knowledgeBaseConfig);
-    const sourcePath = options.sourcePath ?? resolveKnowledgeBaseSourcePath(options.knowledgeBasePath, knowledgeBaseConfig);
-    const stageDefinition = options.stageDefinition ?? findStageByContractType(knowledgeBaseExecutionStages(workflowId, options.knowledgeBasePath), "kb-knowledge-layer");
-    const stageStatusLabel = stageDefinition.label.toLowerCase();
-    const summaryCount = countFilesRecursive(join(options.knowledgeBasePath, "summaries"));
-    if (options.reportStep !== false) {
-        reportBlankLine(options.reporter);
-        reportLine(options.reporter, `${formatKnowledgeBaseWorkflowStageStep(workflowId, stageDefinition.id, { sourcePath })} (building graph)`);
-    }
-    const instructions = buildStageInstructions(bundledSkillForContractType(stageDefinition.contractType), buildLocalSkillContractExtension(options.knowledgeBasePath, [workflowCompileStageDirectory(stageDefinition.skillDir)], "Use them to refine knowledge-base compile behavior, entity/claim extraction, and retrieval structure."));
-    return executeValidatedStage({
-        executor: options.executor,
-        workspacePath: options.knowledgeBasePath,
-        targetType: "knowledge-base",
-        targetName: knowledgeBaseName,
-        workflow: workflowId,
-        workflowSourcePath: sourcePath,
-        stageDefinition,
-        instructions,
-        summary: `Preparing ${stageDefinition.label.toLowerCase()} for ${summaryCount} summary files.`,
-        contract: buildKnowledgeBaseCompileContract(options.knowledgeBasePath, workflowId, summaryCount, instructions, stageDefinition.id, stageDefinition.skillDir),
-        statusLines: [
-            `Emit exactly one startup line: STATUS: loaded ${stageStatusLabel} plan ${summaryCount} summary files.`,
-            `Emit STATUS: inventoried summaries ${summaryCount}/${summaryCount} after the inventory pass completes.`,
-            `Emit STATUS: read summary files X/${summaryCount} after each deep-read batch or every 25 files, whichever comes first.`,
-            `Emit STATUS: wrote ${stageStatusLabel} outputs after knowledge/ and home.md are updated.`,
-            `Emit DONE: ${stageStatusLabel} complete ${summaryCount}/${summaryCount} when the required outputs are on disk.`,
-        ],
-        reporter: options.reporter,
-        completionCheck: () => validateKnowledgeBaseCompile(options.knowledgeBasePath).ok &&
-            validateStageContractAcceptance(options.knowledgeBasePath).ok,
-        reconcile: () => reconcileKnowledgeBaseCompileRun(options.knowledgeBasePath),
-        refreshArtifacts: () => refreshKnowledgeBaseArtifacts(options.knowledgeBasePath, { ensureViewSpec: true }),
-        validate: () => validateKnowledgeBaseCompile(options.knowledgeBasePath),
-    });
-}
-export async function compileKnowledgeBase(options) {
-    refreshWorkspaceBootstrapGuidance(options.knowledgeBasePath);
-    const { sourcePath, workflowId } = resolveKnowledgeBaseContext(options.knowledgeBasePath);
-    const stages = knowledgeBaseExecutionStages(workflowId, options.knowledgeBasePath);
-    let summarize = {
-        ok: true,
-        code: 0,
-        skipped: true,
-        plan: buildSummarizePlan(sourcePath, options.knowledgeBasePath),
-    };
-    let compile = null;
-    let evidencePassCount = 0;
-    for (const stageDefinition of stages) {
-        if (stageDefinition.contractType === "kb-file-evidence") {
-            summarize = await runKnowledgeBaseSummarize({
-                executor: options.executor,
-                knowledgeBasePath: options.knowledgeBasePath,
-                sourcePath,
-                reporter: options.reporter,
-                reportSummary: evidencePassCount === 0,
-                reportStep: true,
-                stageDefinition,
-                fullPass: evidencePassCount > 0,
-            });
-            evidencePassCount += 1;
-            if (!summarize.ok) {
-                return {
-                    ok: false,
-                    summarize,
-                    compile: null,
-                    failedStage: stageDefinition.id,
-                };
-            }
-            continue;
-        }
-        compile = await runKnowledgeBaseCompile({
-            executor: options.executor,
-            knowledgeBasePath: options.knowledgeBasePath,
-            sourcePath,
-            reporter: options.reporter,
-            reportStep: true,
-            stageDefinition,
-        });
-        if (!compile.ok) {
-            return {
-                ok: false,
-                summarize,
-                compile,
-                failedStage: stageDefinition.id,
-            };
-        }
-    }
-    return {
-        ok: compile?.ok ?? summarize.ok,
-        summarize,
-        compile,
-        failedStage: null,
-    };
-}
-//# sourceMappingURL=workflows-kb.js.map

package/dist/lib/workflows-kb.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"workflows-kb.js","sourceRoot":"","sources":["../../src/lib/workflows-kb.ts"],"names":[],"mappings":"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"}

package/skills/interface/analyze/SKILL.md

@@ -1,191 +0,0 @@
----
-{
-  "name": "interface/analyze",
-  "description": "Interface analysis contract. Deep analysis of relevant summaries from the knowledge base. Reads delta files from state, batches them, and extracts entities and claims for this interface's ontology. Use when asked to analyze, extract, or run an analysis stage inside interface compile."
-}
----
-
-# Interface Compile — Analyze
-
-Read `interf.json`, `compile-plan.md`, and `.interf/relevant.json` for the current target set from the preceding retrieval stage.
-
-Local runtime reference:
-- active stage contract: `.interf/stage-contract.json`
-- active run ledger: `.interf/run.json`
-- local config: `interf.json`
-- local plan: `compile-plan.md`
-- local instruction docs: the files listed by `.interf/stage-contract.json`
-
-When this skill is embedded into a generated interface, do not try to open SDK repo docs or source files outside the current workspace. The local contract and local docs are the source of truth for this run.
-
-This skill does the deep analysis — reading summaries and extracting what matters for this interface. It may refine the interface runtime after the requested target set is classified, but bounded audits should close the named task before widening scope.
-If `../../.interf/source-access.json` exists, use it as the quick check for whether raw paths are actually reachable from this session before assuming raw fallback will work.
-If local docs are listed by the stage contract, read them before analyzing. They may `extend` or `override` the bundled workflow instructions for this stage, but they do not bypass coverage proof or the stage contract.
-
-Harness role:
-- This skill is an internal harness step normally invoked by `interf compile` from inside an interface.
-- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
-
-## Runtime contract
-
-When invoked by the CLI, honor any explicit execution instructions in the prompt. In particular:
-- if `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run
-- if the prompt gives an expected analysis set size, use it for progress reporting
-- use `.interf/relevant.json` as the source of truth for `relevant_files` and `delta_files`
-- require `.interf/coverage.json` and `coverage_complete: true` as proof that retrieve reached retrieval closure
-- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
-- the CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation; do not treat those files as stage-owned write targets for analyze
-- before any long-running raw inspection, PDF/chart extraction, OCR, or shell-based helper step, emit a `STATUS:` line naming the current subtask
-- do not stay silent for more than about one minute while extraction work is still in progress
-- when you switch page groups, markets, chart families, or extraction methods, emit another `STATUS:` line first
-- do not keep reopening the same large raw PDF once the relevant pages are known; switch to a narrower page-bounded extraction step instead
-- avoid long inline Bash heredocs for extraction helpers; prefer one page-bounded command per step, or write a short scratch script file and run it explicitly
-
-## Prerequisites
-
-`.interf/relevant.json` and `.interf/coverage.json` must exist. If not: "Run the retrieval stage first." Stop.
-
-Before analyzing, prefer running:
-
-```bash
-interf verify retrieve --json
-```
-
-If it fails, stop and fix the retrieval proof instead of continuing.
-
-## Steps
-
-```
-Analyze:
-- [ ] 1. Read retrieve proof and plan
-- [ ] 2. Load summaries in bounded working sets
-- [ ] 3. Extract entities, claims, and relationships
-- [ ] 4. Refine runtime where evidence demands it
-- [ ] 5. Merge results
-- [ ] 6. Write analysis handoff
-```
-
-### 1. Read retrieve proof and plan
-
-- `.interf/relevant.json` → `delta_files[]` (or all `relevant_files[]` when delta is conservative)
-- `.interf/coverage.json` → proof of scanned summary set, abstract review, and expansion passes
-- `compile-plan.md` → this stage's section: what to extract (entity types, claim types, relationships)
-- `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
-- local instruction docs listed by the stage contract
-- treat the plan as the starting ontology
-- if the plan names a bounded audit target set, treat that set as the hard default scope until every requested value is classified as exact, approximate, or unresolved
-- if the plan includes a target ledger, use it as the primary checklist and record one result per target
-- if the plan depends on exact figures from PDFs, charts, or tables, raw inspection is part of analysis for those items, not an optional afterthought
-- for exact-value PDF work, reading raw pages with `Read` confirms location and context, but it does not by itself satisfy the extraction requirement
-- choose the local extraction path from whatever the current environment actually supports; do not assume a specific binary or hardcode shell recipes into the answer
-- before locking in a machine-readable path, verify that the local method is actually available in this environment; if it is missing or blocked, count that as one failed path and switch to another available local method
-
-### 2. Load summaries in bounded working sets
-
-Read full abstract + overview for each delta file.
-Summaries are the default evidence surface, but if the plan requires exact chart/table values and the summaries do not preserve them, inspect the raw source for those specific items and record how the values were derived.
-Do not treat `the summary was coarse` as proof that the source lacks the number.
-When exact chart values matter, the analysis is not complete until you either recover the value more precisely or record why the local environment blocked a machine-readable attempt.
-Keep raw probing focused. Do not dump large SVG, PDF, or OCR bodies into the run log. Extract the needed values, calibration anchors, and method notes only.
-If the plan names a bounded target set, keep the extraction bounded to that set. Do not widen to every market, page, or entity in the report unless one extra comparator or calibration anchor is required to answer the task correctly.
-For bounded audits, do not widen the ontology, taxonomy, or target set until the requested values are classified or a concrete blocker has been recorded.
-Treat metric plus period as part of the target identity. A nearby exact figure with the wrong period, wrong unit, or wrong chart family does not satisfy the target and must remain separate supporting context.
-As soon as each target row is classified as exact, approximate, or unresolved, stop extraction and move directly to the required file writes. Do not spend extra turns polishing, re-reading, or chasing more precision after the ledger is complete.
-
-### Exact-value escalation for PDFs and charts
-
-If the task asks for exact chart or table values:
-- opening the PDF with `Read` is only the first step; it does not count as the machine-readable extraction attempt
-- a concrete local extraction path is the default path rather than an optional enhancement
-- before each new page group, market batch, or extraction method, emit a short `STATUS:` line so the run ledger shows where extraction is currently focused
-- use `Read` on the raw PDF to confirm location, context, or a narrow page group only; once the page map is known, do not keep reopening the full PDF
-- after the page map is known, switch to a page-bounded local extraction helper or scratch file workflow for that page group instead of rereading the whole PDF
-- keep helper commands single-purpose and short. Avoid long inline Bash heredocs; if you need multiple steps, write a short scratch script file first or run separate bounded commands
-- use this ladder in order and do not stop after a single failed extractor:
-  1. confirm the relevant pages, chart titles, axes, units, time cuts, and left-to-right target order from the raw PDF
-  1a. before locking in values, build a page-level chart map for each target chart: page, chart title, visible axis range/ticks, legend or component series, and whether the chart is stacked
-  2. attempt text or table extraction with a local machine-readable method that you have already verified is available in this environment
-  3. if the text layer still misses the values, switch to another machine-readable path that fits the source structure and is already available in the environment
-  4. if the chart still has no explicit labels, attempt another recoverable extraction path before giving up on exactness
-  4a. try at most two machine-readable extraction paths per target or tightly related page group; if both fail, record the blocker and mark the value unresolved instead of escalating indefinitely
-  5. when the report contains known anchor values elsewhere (for example Key Stats or Q1/YTD tables), use them to validate calibration before finalizing historical chart values
-  6. if the anchor check is materially off, recalibrate or change method instead of locking in a coarse approximation
-  7. only then fall back to a visual estimate
-- if the chart is stacked, recover the total stacked height or area unless the request explicitly names one component series; do not treat one colored segment as the requested total
-- if multiple charts share a page, keep a separate chart map and scale for each chart family; never reuse one chart's scale for another chart on the same page
-- when you use shell commands for scratch extraction, keep them single-purpose and non-destructive. Do not start with `rm`, wildcard cleanup, or chained helpers like `;` and `&&`. Prefer fresh temp filenames or directories instead.
-- if a local extraction path is unavailable, blocked, or missing a dependency, record that explicitly, do not retry the same missing path, and either switch once to another available local path or record the blocker
-- do not call a value approximate or unavailable until you have exhausted the extraction ladder or documented a concrete blocker on the local extraction path
-- if you only have an approximation, keep that precision gap visible in the analysis instead of presenting it as final truth
-- if the task only needs a rounded bin, one-decimal chart read, or other answer-grade approximation, and the rendered chart plus visible axis labels already support that answer, stop there instead of drilling deeper into SVG or PDF internals for pseudo-precision
-- if you record an approximate chart value, also record the scale band that supports it, such as `between 0.5 and 0.6, closer to 0.5`, plus any nearby labeled anchors used to choose the rounded value or `bin_choice`
-- if a chart-derived value sits between adjacent one-decimal bins, set `bin_choice` to the closer supported bin and explain that choice in `scale_band` or the notes; do not default to rounding an uncertain midpoint up
-- for approximate chart reads, make `value_display` the answer-grade value a later weak model should quote; keep any finer-grained midpoint guess in `scale_band` or `notes` instead of promoting it into the main display value
-- if the visible chart scale is coarser than the requested display precision, prefer the nearest clearly supported bin or anchor rather than interpolating a prettier in-between tenth that the chart does not really justify
-- if you cannot state which chart title, scale, and total-vs-component interpretation produced the number, keep the target unresolved instead of emitting a confident approximate answer
-- if you widen beyond the named target set, record why in the extraction ledger and stop once that reason is satisfied
-- once every requested value is classified as exact, approximate, or unresolved, stop exploring. Write `.interf/analysis.json`, emit the required status line, and finish the stage.
-- when using scratch extraction files, keep the command output minimal. Write bulk SVG/OCR/PDF output to temp files and inspect only the relevant slices for the target chart rather than streaming whole blobs into the run log.
-
-Batching strategy:
-- Prefer a working set budget of roughly 35-45% of the model context window per batch
-- For 100+ files: spawn subagents per batch
-
-### 3. Extract entities, claims, and relationships
-
-Each batch (or subagent) extracts:
-- Entities relevant to this interface's ontology goals
-- Claims (patterns, decisions, risks, metrics)
-- Relationships between entities
-- Modality notes when it matters: whether a key numeric claim came from prose, tables, or chart/figure extraction
-- Time-cut notes when it matters: whether a value is annual, quarterly, trailing-twelve-month, or another window
-- Precision notes when it matters: exact, approximate, or unresolved
-- For bounded audits, only extract the entities and claims needed for the named targets plus any narrowly justified comparators or calibration anchors
-- For bounded target ledgers, emit one result per requested item with metric, entity, period, source kind, derivation, value, and precision
-
-Subagent instruction:
-```
-Analyze these summaries for the {interface-name} interface.
-Ontology goals: {from compile-plan.md}
-Return: entities, claims, relationships as structured list.
-Include summary title as evidence reference.
-```
-
-### 4. Refine runtime where evidence demands it
-
-If repeated evidence shows the interface needs better local structure, propose or record:
-- new ontology branches
-- refined taxonomy labels
-- emergent thread clusters
-- stronger relationship groupings
-
-Do not rewrite the runtime gratuitously. Refine only when it helps the interface become a better local context layer for future agents.
-For bounded audit or exact-value tasks, do not widen the runtime before the requested values are classified and the main brief can be written.
-
-### 5. Merge results
-
-Combine all batch/subagent outputs:
-- Deduplicate entities (same person/company from different batches)
-- Merge evidence for existing entities/claims
-- merge runtime refinements
-- Flag conflicts for manual review
-
-### 6. Write analysis handoff
-
-Store the merged extraction results in `.interf/analysis.json` (temporary, consumed by the next output stage). Include runtime refinements when present.
-When exact-value PDF or chart work happened, include a raw extraction ledger in `.interf/analysis.json` with enough detail for the compile stage to judge confidence: source path, pages inspected, methods attempted, result, whether a scratch helper was used, and whether each reported value is exact, approximate, or unresolved.
-For chart-derived approximate values, include enough structure in `.interf/analysis.json` for a later reviewer to reconstruct the judgment without reopening the raw file: chart title, whether the chart was stacked, scale band or nearest labeled anchors, and the reason the chosen `bin_choice` is closer than the neighboring bins.
-For bounded target audits, the final write sequence is strict: write `.interf/analysis.json`, emit `STATUS: wrote analyze outputs`, emit `DONE: analyze complete`, and stop.
-
-The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation.
-
-Report with status-style lines:
-```
-STATUS: loaded analyze plan N files.
-STATUS: inspecting <current subtask>
-STATUS: analyzed N/N
-STATUS: wrote analysis
-DONE: analyze complete
-```
-
-When the analysis artifact is written, emit the required `DONE:` line and stop. The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation. Do not keep exploring after the analyze contract is satisfied.