@interf/compiler 0.2.5 → 0.3.1

package/skills/interface/compile/SKILL.md

@@ -1,152 +0,0 @@
----
-{
-  "name": "interface/compile",
-  "description": "Interface output contract. Creates or updates local output files from the analysis. Writes knowledge/, briefs/, and home.md with evidence-linked notes. Use when asked to compile outputs, create notes, or run an output stage inside interface compile."
-}
----
-
-# Interface Compile — Output
-
-Read `interf.json` for output definitions and `compile-plan.md` Stage 3 for output specs.
-
-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 creates the actual files that make the interface queryable. All outputs are LOCAL — do not write to the knowledge base. The interface should become a local context shell that future agents can enter and navigate easily.
-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 compiling. 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 a retrieved set size, use it for progress framing
-- do not create or edit `.interf/view-spec.json`; the CLI refreshes it after stage completion
-- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
-- the CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after validation; do not treat those files as stage-owned write targets for compile
-
-## Prerequisites
-
-If `.interf/analysis.json` is missing or unreadable: emit `BLOCKED: missing analysis handoff (.interf/analysis.json)` and stop.
-
-Before compiling, prefer running:
-
-```bash
-interf verify retrieve --json
-```
-
-If it fails, stop and fix the retrieval proof instead of continuing.
-
-Read `.interf/analysis.json` for the extracted entities, claims, and relationships from the preceding analysis stage.
-
-## Steps
-
-```
-Compile:
-- [ ] 1. Read analysis results and output spec
-- [ ] 2. Compile entities
-- [ ] 3. Compile claims
-- [ ] 4. Compile interface-specific outputs
-- [ ] 5. Compile navigation
-- [ ] 6. Validate
-- [ ] 7. Clean up
-```
-
-### 1. Read analysis results and output spec
-
-- `.interf/analysis.json` → extracted entities, claims, relationships, runtime refinements
-- `compile-plan.md` → this stage's section: what files to create, in what format
-- Existing `knowledge/` → what already exists (for delta: update, don't recreate)
-- `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
-- local instruction docs listed by the stage contract
-- if the plan asked for exact values from PDFs, charts, or tables, check whether `.interf/analysis.json` includes a raw extraction ledger or equivalent method notes before treating approximations as closed findings
-
-### 2. Compile entities
-
-Create/update `knowledge/entities/` notes. Each entity gets:
-- Summary, evidence links, related entities
-- Properties for filtering (entity_type, status, confidence)
-- Tags for Obsidian surfacing
-- Clear wikilinks back to supporting parent summaries so an agent can move entity -> evidence -> source trail without guessing
-
-### 3. Compile claims
-
-Create/update `knowledge/claims/` notes. Prose-as-title: filename IS the claim.
-- The claim, why it matters, evidence links
-- 2+ sources required for broad synthesis work
-- single-source claims are allowed for bounded audit or extraction workflows when provenance includes source path/page, extraction method, and precision (`exact`, `approximate`, or `unresolved`)
-- Link claims to related entities, briefs, and parent summaries so backlinks become a real navigation surface
-
-### 4. Compile interface-specific outputs
-
-From `compile-plan.md`: create whatever this output stage defines.
-- Treat `compile-plan.md` Stage 3 as the output contract. Follow the exact filenames and folders named there.
-- briefs/ hero documents
-- summaries/ interface-local temporal views when needed
-- Any other outputs defined in the compile plan
-- if this is a bounded audit, prefer one focused hero brief plus the smallest supporting note set that makes the target answers easy to retrieve
-- do not mirror the whole parent report into the interface unless the compile plan explicitly asks for full-report coverage
-- if the plan includes a target ledger, the hero brief must cover every requested target explicitly and unresolved targets must stay unresolved instead of being replaced by nearby exact figures
-- Preserve `value_display`, `bin_choice`, `precision`, `source_kind`, and page metadata from `.interf/analysis.json`. Compile is a render pass, not a second chart-reading pass.
-- If an approximate chart-derived target includes both `value_display` and `bin_choice`, prefer the conservative answer-grade value for the main hero surface unless the notes explicitly justify a finer display. Keep extra granularity in supporting prose, `scale_band`, or notes rather than upgrading the main answer.
-- Do not invent fixed hero-brief filenames or generic claim-folder patterns unless the compile plan explicitly asks for them.
-
-For delta compiles: update existing files surgically. Do NOT regenerate everything.
-
-When a local output cites evidence from the main knowledge base, use the parent knowledge-base summary path (`../../summaries/...`). Do not point `source:` or evidence links at the interface-local `summaries/` folder unless that interface actually created the cited file.
-When an output depends on exact numbers from PDFs, tables, or charts, say whether the value was text-derived, table-derived, or chart-derived. Do not present chart-extracted values as if they were already explicit in the compiled summaries.
-Do not write `data unavailable` or `gap` when the real state is `not yet extracted from the raw source`.
-If the analysis only opened raw pages but did not log a machine-readable extraction attempt for an exact-value task, keep the result unresolved instead of upgrading it to a verified finding.
-If the analysis logged anchor cross-checks with material drift, keep the finding approximate or unresolved instead of presenting it as settled.
-If the question asked for exact values and you only recovered a visual estimate, say `approximate` explicitly and keep the remaining precision gap in the output.
-Do not substitute a requested `annual`, `quarterly`, `trailing-12-month`, `availability`, `take-up`, or similar target with another metric or period just because the substitute is exact and easier to quote.
-
-### 5. Compile navigation
-
-- `home.md` — links to all key outputs, counts, last compile
-- `knowledge/indexes/` or equivalent local maps when the interface needs better navigation
-- make the order of use obvious: AGENTS.md -> home.md -> local knowledge/briefs/summaries -> knowledge-base summaries -> raw if needed
-- make upward navigation obvious too: local outputs should link out to parent summaries so an agent can follow backlinks and climb toward stronger evidence
-- if Obsidian is mentioned, assume the interface is being browsed from the parent knowledge-base vault rather than as a standalone vault
-- Update every compile run
-
-### 6. Runtime reconciliation
-
-Do not reset retrieve/analyze coverage markers manually. The CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after stage validation so viewers keep a stable presentation contract.
-
-### 7. Validate
-
-- [ ] All outputs from compile-plan.md exist and are non-empty
-- [ ] Entity notes have evidence links
-- [ ] Claims meet the workflow provenance rule: either 2+ sources or a bounded-audit single-source record with explicit provenance
-- [ ] No broken wikilinks
-- [ ] home.md is current
-
-### 8. Clean up
-
-Delete `.interf/analysis.json` — it was temporary between stages.
-
-Report with status-style lines:
-```
-STATUS: loaded compile plan N relevant files.
-STATUS: wrote entities E
-STATUS: wrote claims C
-STATUS: wrote interface outputs
-DONE: compile complete
-```
-
-When the required outputs are 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 compile contract is satisfied.
-
-## Key principle
-
-**Local outputs only.** Everything this skill creates lives in this interface. The connected knowledge base (at `knowledge_base.path`) is read-only. The interface graph is distilled and focused, not a mirror of the knowledge base. The goal is to make future agent navigation easier, not just to dump another layer of summaries.

package/skills/interface/compile/references/output-format.md

@@ -1,48 +0,0 @@
-# Output Format Guide
-
-All outputs are plain markdown. They work standalone for any agent and render well in Obsidian. Obsidian is supported but not required.
-
-## Properties (JSON frontmatter)
-
-Use Obsidian-compatible properties for filtering:
-
-```md
----
-{
-  "entity_type": "person",
-  "status": "active",
-  "confidence": "high",
-  "tags": ["type/entity", "entity/person"]
-}
----
-```
-
-Properties = machine filtering. Tags = human browsing.
-
-## Wikilinks
-
-Use `[[wikilinks]]` for all internal references. Never raw file paths.
-
-## Wiki-link-as-prose
-
-Links read as sentences:
-> This note is where [[readiness assessment language first appears in the knowledge base]]
-
-## home.md
-
-Entry point. Links to key sections, current counts, last compile date. Update every compile.
-
-## .base files
-
-Optional Obsidian-specific JSON files for filterable table/card views. The interface works without them.
-
-## Graph optimization
-
-- Wikilinks consistently (every link = edge)
-- One canonical note per entity (no duplicates)
-- Home.md and indexes as high-connectivity hubs
-- Tags for color-coding in graph view
-
-## Independence
-
-Everything works without Obsidian. Wikilinks are `[[plain text]]`. Properties use JSON frontmatter. Tags are strings. Any agent can read the files directly.

package/skills/interface/create/SKILL.md

@@ -1,87 +0,0 @@
----
-{
-  "name": "interface/create",
-  "description": "Create a new Interf interface. Analyzes a knowledge base to generate an interf.json config and execution plan (compile-plan.md). Use when asked to create an interface, new interface, or build a task-specific view."
-}
----
-
-# Create Interface
-
-This stage drafts the initial interface runtime hypothesis from the parent knowledge base.
-
-## Stage role
-
-- planning only
-- no raw-source inspection
-- no chart/table extraction
-- no registry edits
-
-Read `.interf/stage-contract.json` first and treat it as authoritative.
-
-## Minimal completion target
-
-For automated runs, the primary deliverable is a correct `compile-plan.md`.
-
-- If scaffolded `interf.json` already matches the stage contract, leave it unchanged.
-- If scaffolded `AGENTS.md` already preserves the router, checklist, and parent handoff, leave it unchanged.
-- Do not spend the run rewriting scaffold files that already validate.
-- After the knowledge-base review, the next action should usually be to rewrite `compile-plan.md` in one full write and stop.
-
-## Bounded analysis
-
-Build the plan from the parent knowledge-base surface only:
-
-- `../../home.md`
-- `../../knowledge/`
-- `../../summaries/`
-
-Read only enough to plan the interface:
-
-- the primary summary or summaries that anchor the task
-- the highest-signal parent knowledge notes that clarify scope
-- the local scaffold files you may update
-
-Do not widen into broad research. If later stages need raw/chart work, encode that in `compile-plan.md` and leave the actual extraction to retrieve/analyze.
-
-## Plan requirements
-
-`compile-plan.md` must:
-
-- preserve the exact requested use case line in `## Interface Goal`
-- keep the existing workflow stage headings and required subsection labels
-- translate the task into a concrete target ledger when the task names specific values, periods, entities, metrics, units, or chart/table families
-- keep different time cuts and metric families separate, and say when later stages must inspect raw visuals
-- require a concrete local extraction path plus exact/approximate/unresolved labeling when precision matters
-- require a durable output surface, usually one focused hero brief for bounded audits
-
-## AGENTS handling
-
-`AGENTS.md` is a scaffold router for later agents, not the main output of this stage.
-
-- Preserve the scaffold router and checklist.
-- preserve the `## Manual access checklist`, raw-source gate, and parent knowledge-base handoff
-- preserve the router to `workflow/use/query/` and later compile-stage docs
-- do not execute those instructions during create
-- only rewrite `AGENTS.md` if the existing scaffold is materially wrong for this interface
-
-## Finish rule
-
-Once `compile-plan.md` is correct and the scaffold still validates:
-
-1. update `interf.json` only if needed
-2. update `AGENTS.md` only if needed
-3. emit the required status lines
-4. stop
-
-Do not keep researching after the durable plan is written.
-
-## Status contract
-
-For automated runs, these canonical `STATUS:` lines are mandatory and must appear verbatim on their own lines:
-
-- `STATUS: loaded interface creation contract.`
-- `STATUS: analyzed knowledge-base.`
-- `STATUS: wrote compile plan.`
-
-You may emit `DONE: interface create complete.` as a final progress line, but the CLI validates completion from the scaffold files rather than trusting that line.
-Additional `STATUS:` lines are allowed between them, but do not replace or rewrite these canonical markers.

package/skills/interface/create/references/compile-plan-format.md

@@ -1,109 +0,0 @@
-# Interface Compile Plan Format
-
-When creating an interface, generate a `compile-plan.md` that follows the selected workflow's stage graph. The examples below show the built-in `Retrieve -> Analyze -> Compile` shape. For custom workflows, repeat the same section pattern for each workflow-defined stage label and contract type. This file lives in the interface root and is git-tracked.
-
-## Format
-
-```markdown
-# {Interface Name} — Compile Plan
-
-## Stage 1: Retrieve
-
-Filter criteria for knowledge-base summaries/:
-- Categories: {list of relevant categories}
-- Priority evidence tiers: {which source/evidence tiers matter most}
-- Truth modes to prioritize or downweight: {fact vs proposal vs brainstorm etc.}
-- Key entities: {people/companies to prioritize}
-- Date range: {if relevant}
-
-Expected relevant file count: ~{estimate}
-Coverage loop:
-- scan all summary frontmatter
-- read abstracts for every candidate file
-- expand through links until the selected set is stable
-- persist selected and rejected files with reasons
-
-## Stage 2: Analyze
-
-For each relevant summary, extract:
-- {entity type 1}: {what to look for}
-- {entity type 2}: {what to look for}
-- Claims: {what patterns/decisions/risks to detect}
-- Runtime refinements: {when to add missing ontology/taxonomy/relationship structure}
-
-Working-set budget: ~{fraction or token budget} of model context window per batch.
-Subagent instruction: "{what each subagent should return}"
-
-## Stage 3: Compile
-
-Output files to create/update:
-
-### {Output 1, e.g., briefs/Company.md}
-Purpose: {what question this answers}
-Sections: {structure}
-Evidence: {what sources to cite}
-
-### {Output 2, e.g., knowledge/entities/*.md}
-{same format}
-
-### home.md
-Links to: {key outputs}
-Status: {counts, last compile}
-Agent navigation: {how an agent should move from AGENTS.md into the rest of this interface}
-```
-
-## Example: Task-Specific interface
-
-```markdown
-# {Interface Name} — Compile Plan
-
-## Stage 1: Retrieve
-
-Filter criteria for knowledge-base summaries/:
-- Categories: {documents, notes, datasets, reports, experiments, or other relevant categories}
-- Priority evidence tiers: {which evidence tiers matter most for this task}
-- Truth modes to prioritize or downweight: {which truth modes to favor or downweight}
-- Key entities: {entities, systems, products, markets, or themes to prioritize}
-- Date range: {all time, a recent window, or another task-specific cutoff}
-
-Expected relevant file count: ~{estimate} of {knowledge_base_summary_total}
-Coverage loop:
-- scan all {knowledge_base_summary_total} summary frontmatter blocks
-- read abstracts for the full candidate set
-- follow adjacency links for the relevant clusters until retrieval closure
-- persist selected and rejected files with reasons in coverage proof
-
-## Stage 2: Analyze
-
-For each relevant summary, extract:
-- {Entity type 1}: {what to extract}
-- {Entity type 2}: {what to extract}
-- Claims: {what is being asserted and with what level of support}
-- Contradictions: {what disagreements matter}
-- Open questions: {what remains unresolved}
-- Runtime refinements: {what missing structure to add when evidence supports it}
-
-Working-set budget: ~{fraction} of model context window per batch.
-Subagent instruction: "{what each subagent should extract and return}"
-
-## Stage 3: Compile
-
-### briefs/{Primary Brief}.md
-Purpose: "{what question this brief answers}"
-Sections: {section structure}
-Evidence: {what evidence to prefer}
-
-### briefs/{Secondary Brief}.md
-Purpose: "{what this note clarifies}"
-Sections: {section structure}
-Evidence: {what evidence to cite}
-
-### briefs/{Follow-up Brief}.md
-Purpose: "{what should be checked next}"
-Sections: {section structure}
-Evidence: {how to link back to gaps or follow-up needs}
-
-### home.md
-Links to: {key briefs and local outputs}
-Agent navigation: AGENTS.md -> home.md -> briefs/ -> knowledge/ -> knowledge-base summaries
-```

package/skills/interface/create/references/workflows.md

@@ -1,35 +0,0 @@
-# Interface Workflows
-
-Interf now ships one built-in interface workflow: `interf`.
-
-Use it as the default task-specific method on top of a knowledge base. If you need a different bias, create a reusable local workflow under `interf/workflows/interface/` and benchmark it.
-
-## interf
-
-Task-specific evidence distillation. Best when the agent needs a bounded workspace that:
-- proves what was scanned and selected
-- preserves the exact task nouns the user cares about
-- compiles minimal answer-ready artifacts for later retrieval
-
-**Questions it answers:**
-- What exactly is this interface trying to help an agent do?
-- Which entities, periods, metrics, comparators, or source families matter?
-- What compiled brief or notes should a weaker model rely on instead of rediscovering the raw data?
-
-**Default bias:**
-- narrow retrieval to the requested task before widening scope
-- turn the request into a target ledger when the task is bounded
-- preserve time periods, units, metric families, and provenance
-- when exact values matter, inspect the raw source and classify the result as text-derived, table-derived, or chart-derived
-- compile one concise hero brief plus the minimum supporting notes needed for reliable retrieval
-
-## Create new workflow
-
-Create a reusable local interface workflow when the built-in `interf` method is not enough.
-
-The wizard asks:
-1. What questions should this interface answer?
-2. What categories or entities matter?
-3. What output documents should it maintain?
-
-Then it saves a named local workflow under `interf/workflows/interface/` and generates `interf.json` plus `compile-plan.md` from knowledge-base analysis.

package/skills/interface/query/SKILL.md

@@ -1,48 +0,0 @@
----
-{
-  "name": "interface/query",
-  "description": "Manual-use skill for answering questions from inside an interface. Navigates AGENTS.md, home.md, local knowledge/briefs/summaries, parent knowledge-base summaries, backlinks, and raw sources only when reachable. Use when a user opens an agent inside an interface and asks questions against it."
-}
----
-
-# Interface Query
-
-Use this skill in manual agent sessions inside a compiled interface.
-
-Start with:
-- `AGENTS.md`
-- `home.md`
-- local `knowledge/`
-- `briefs/`
-- local `summaries/`
-
-Default loop:
-- answer from local interface outputs first
-- follow wikilinks and backlinks outward before treating one note as complete
-- climb to parent knowledge-base summaries in `../../summaries/` when you need stronger evidence
-- use raw source files only when needed for verification, direct quotes, ambiguity, or missing context
-- if the user asks for exact chart or table values from a named report, use local outputs only to locate the source and relevant pages, then go straight to the raw PDF and a concrete local extraction path
-- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record local `workflow/use/query/SKILL.md` after you inspect it
-- when you climb to the parent knowledge-base query loop, record `../../workflow/use/query/SKILL.md` after you inspect it
-
-Raw-source gate:
-- inspect `../../.interf/source-access.json`
-- actually open and inspect at least one `suggested_checks` path before claiming raw-file verification; a plain existence check is not enough
-- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record `../../.interf/source-access.json` after you inspect it
-- if the path is not reachable or permission is not granted, say the answer is based on interface and parent knowledge-base artifacts only
-- when the question depends on exact figures, direct quotes, chart values, table values, or image-derived evidence, raw inspection is required before answering confidently
-
-PDF / chart rule:
-- if the parent source is a PDF, deck, or report and the needed evidence may live in charts, tables, or figures, do not assume the default text layer or existing notes captured everything
-- if local outputs and parent summaries do not preserve the needed numeric detail, inspect the raw source and say whether the value was text-derived, table-derived, or chart-derived
-- opening the PDF with `Read` is not enough for an exact-value chart question; you must take a machine-readable extraction path before answering
-- if the first local extraction method misses the number, continue down another local recovery path instead of settling early for a visual estimate
-- if the default local extraction path still cannot reach the value, switch methods before stopping early; a temporary scratch helper outside the workspace is allowed when needed
-- if the chart does not expose exact numbers as text, say that clearly instead of pretending the interface already captured them
-- if you can only estimate from the chart after exhausting the local extraction path, label the answer `approximate` and keep the precision gap explicit
-
-When confidence is low:
-- expand outward through linked briefs, claims, entities, and parent summaries
-- do not stop at the first local note if linked evidence exists above it
-
-This skill is for manual question-answering behavior. It does not change retrieve, analyze, or compile runtime contracts.

package/skills/interface/retrieve/SKILL.md

@@ -1,133 +0,0 @@
----
-{
-  "name": "interface/retrieve",
-  "description": "Interface retrieval contract. Identifies relevant files from the connected knowledge base. Scans knowledge-base summaries metadata, applies filters from compile-plan.md, computes delta since last compile. Use when asked to retrieve from the knowledge base, find relevant files, or run a retrieval stage inside interface compile."
-}
----
-
-# Interface Compile — Retrieve
-
-Read `interf.json` (must have `type: interface`) and `compile-plan.md` for filter criteria.
-
-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 identifies which files in the knowledge base are relevant to this interface and which are new since last compile.
-
-Retrieve is coverage-gated. The goal is not to guess a relevant set quickly. The goal is to prove that the routing layer scanned the full summary set, reviewed the candidate abstracts, and persisted both selected and rejected files before analysis begins.
-The runtime in `compile-plan.md` is an initial hypothesis. Retrieve may discover missing entities, categories, or relationship clusters that should shape later interface refinement.
-
-Important proof semantics:
-- `proof.scanned` is the full summary set scanned at the frontmatter-routing layer
-- `proof.reviewed` is the narrower candidate set whose abstracts were reviewed
-- `proof.retrieved` plus `proof.excluded` should partition the scanned summary set
-
-The knowledge base is located at `knowledge_base.path` from `interf.json` (typically `../..`). Knowledge-base summaries are at `{knowledge_base.path}/summaries/`.
-If a coding agent is sandboxed to its current working tree, prefer launching it from the source folder or another root that can reach both the knowledge base and the source folder.
-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 retrieving. 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 summary-set size, use it as the source of truth for progress reporting
-- if the prompt requires `.interf/relevant.json`, write it
-- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
-- when updating `.interf/relevant.json` or `.interf/coverage.json`, read the current file first and then rewrite the full JSON document; do not depend on anchored patch edits against stale runtime files
-- the CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation; do not treat those files as stage-owned write targets for retrieve
-- once the selected set is final, write the proof artifacts immediately, emit the `DONE:` line, and stop; do not reopen manual query docs or raw files after selection is settled
-
-## Steps
-
-```
-Retrieve:
-- [ ] 1. Read config and plan
-- [ ] 2. Scan knowledge-base frontmatter
-- [ ] 3. Review candidate abstracts
-- [ ] 4. Expand through links if needed
-- [ ] 5. Compute delta
-- [ ] 6. Write retrieval proof
-```
-
-### 1. Read config and plan
-
-- `interf.json` → `knowledge_base.path` to locate the knowledge base
-- `compile-plan.md` → this stage's section: categories, priority evidence tiers, truth modes, key entities, date range
-- if the plan depends on exact figures from PDFs, charts, or tables, keep that modality requirement visible during retrieval
-- `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
-- local instruction docs listed by the stage contract
-
-Resolve `knowledge_base.path` from config and verify the knowledge base exists (has `summaries/`).
-
-### 2. Scan knowledge-base frontmatter
-
-Read all files in `{knowledge_base.path}/summaries/` frontmatter (fast — no full file reads):
-- source
-- source_kind
-- evidence tier / truth mode / state
-- abstract
-
-Build a summary-set map: total files, source-kind distribution, evidence distribution.
-
-### 3. Review candidate abstracts
-
-From compile-plan.md filter criteria, identify a candidate set. Then read the abstract block for every candidate file before final selection.
-If the use case depends on exact numeric comparisons from charts or tables, do not exclude a candidate just because the summary abstract is coarse. Keep files whose key evidence may still live in raw visuals.
-
-### 4. Expand through links if needed
-
-If candidate abstracts point to adjacent summaries that may materially change the answer, follow those links, review their abstracts, and repeat until the retrieved set is coverage-complete for the interface question.
-Track emergent clusters that suggest the initial interface runtime is missing concepts, relationships, or taxonomy branches.
-When chart-heavy PDFs or report pages are likely to hold the decisive evidence, preserve that signal for later stages instead of routing the interface toward prose-only summaries.
-If exact numbers will require a local extraction path against the raw PDF, carry that requirement forward explicitly instead of assuming the analysis stage can infer it from a coarse abstract.
-
-### 5. Compute delta
-
-- If the current workspace already makes the delta obvious, keep `delta_files` limited to the newly relevant or newly changed files.
-- If the prior compile boundary is not obvious from the current workspace, use the conservative fallback: set `delta_files` equal to the selected relevant set for this run.
-
-### 6. Write retrieval proof
-
-Write the full retrieved set to `.interf/relevant.json` in the current runtime shape. At minimum include:
-- `generated_at`
-- `knowledge_base_summary_count` derived from the current knowledge-base summary total
-- `relevant_files` with the actual knowledge-base-relative summary paths selected in this run
-- `delta_files` with the actual knowledge-base-relative summary paths that are new or changed for this run
-
-Do not paste placeholder filenames, canned totals, or copied sample counters into the runtime artifact.
-If `.interf/relevant.json` does not exist yet, create it in one complete write rather than trying to patch a missing file.
-
-Write retrieval proof to `.interf/coverage.json` in the current verifier shape. Include:
-- top-level `generated_at`
-- top-level counts derived from this run: `knowledge_base_summary_total`, `frontmatter_scanned`, `candidates_after_frontmatter`, `abstracts_reviewed`, `expansion_passes`, `relevant_selected`, `rejected`, `coverage_complete`
-- `proof.scanned` for the full scanned summary set
-- `proof.reviewed` for the candidate abstracts actually reviewed
-- `proof.retrieved` for the selected relevant set
-- `proof.excluded` for the excluded set
-
-`proof.retrieved` plus `proof.excluded` must partition the scanned set for this run.
-
-If `.interf/coverage.json` already exists, read it and then rewrite the complete JSON document. Do not patch old counters or timestamps line-by-line.
-If the retrieve stage reveals clear runtime gaps, preserve that signal for later stages via `.interf/analysis.json` or the next stage handoff rather than silently discarding it.
-
-Report to user with status-style lines:
-```
-STATUS: loaded retrieve plan N summary files.
-STATUS: scanned N/N
-STATUS: reviewed M abstracts, P expansion passes
-STATUS: selected R relevant, X rejected, D delta
-DONE: retrieve complete
-```
-
-When the retrieval proof and relevant set are 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 once retrieval closure is recorded.