@interf/compiler 0.1.8

package/skills/interface/create/SKILL.md

@@ -0,0 +1,264 @@
+---
+{
+  "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, build a view, or set up a briefing, research, or audit interface."
+}
+---
+
+# Create Interface
+
+Creates a new interface connected to an existing knowledge base. The LLM analyzes the knowledge base to draft the initial runtime hypothesis for the use case: ontology, taxonomy, retrieval strategy, and output shape.
+
+Local runtime reference:
+- active stage contract: `.interf/stage-contract.json`
+- active run ledger: `.interf/run.json`
+- local config: `interf.json`
+- local plan target: `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.
+
+Harness role:
+- This skill is an internal harness step normally invoked by `interf create interface`.
+- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
+
+If `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run. It defines the interface use case, knowledge-base connection, and which files the harness expects this step to update.
+
+## Wizard checklist
+
+```
+Create interface:
+- [ ] 1. Select knowledge base
+- [ ] 2. Define use case
+- [ ] 3. Analyze knowledge base
+- [ ] 4. Update interf.json
+- [ ] 5. Generate compile-plan.md
+- [ ] 6. Update interface structure
+- [ ] 7. Register
+- [ ] 8. Show next steps
+```
+
+### 1. Select knowledge base
+
+Ask: which knowledge base should this interface read from?
+
+Read `~/.interf/registry.json` for available knowledge bases. If only one knowledge base exists, confirm it.
+
+### 2. Define use case
+
+If the caller already provided `Selected workflow: ...`, treat that as the chosen workflow and do not re-decide it.
+
+If a known workflow exists: use it as the starting point and adapt it to the actual knowledge base.
+If no known workflow fits: ask the user:
+- What questions should this interface answer?
+- What's the use case? (briefing, research, audit, etc.)
+
+### 3. Analyze knowledge base
+
+Read the knowledge base's `summaries/` frontmatter and high-level `knowledge/` layer to understand available data:
+- Category distribution
+- People mentioned
+- Date range
+- Evidence-tier / truth-mode distribution
+- Entity and claim coverage in knowledge/
+
+The knowledge base is 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.
+
+This analysis informs the config and compile plan.
+
+### 4. Update interf.json
+
+`interf.json` is minimal. It stores only `type`, `name`, `workflow`, and the knowledge-base path (`knowledge_base.path`). No filter criteria, no output specs, no validation rules — all of that belongs in `compile-plan.md`.
+
+If the CLI already created the scaffold, confirm the existing `interf.json` is correct:
+
+```json
+{
+  "type": "interface",
+  "name": "{name}",
+  "workflow": "{workflow}",
+  "knowledge_base": {
+    "path": "../.."
+  }
+}
+```
+
+Do not add `filter:`, `outputs:`, or `validation:` sections to `interf.json`. Those belong in `compile-plan.md`.
+
+### 5. Generate compile-plan.md
+
+This is the execution plan for compiling THIS interface. The LLM writes it based on the knowledge-base analysis and use case.
+
+The plan defines the initial runtime hypothesis for the selected workflow stage graph.
+Start from the existing scaffolded `compile-plan.md`. Preserve the workflow stage headings and required subsection labels already present in that starter plan, then refine the bullet contents and wording for the actual use case.
+For each workflow stage:
+- name the stage exactly as the workflow labels it
+- explain what that stage must accomplish for this use case
+- include contract-appropriate detail for retrieval, analysis, or output stages
+
+### 6. Update interface structure
+
+The CLI creates the scaffold before invoking this skill. The expected structure is:
+
+```
+{name}/
+├── interf.json
+├── compile-plan.md              execution plan (git-tracked)
+├── AGENTS.md
+├── CLAUDE.md
+├── workflow/
+│   ├── workflow.json
+│   ├── README.md
+│   ├── create/
+│   │   └── SKILL.md
+│   ├── use/
+│   │   └── query/
+│   │       └── SKILL.md
+│   └── compile/
+│       └── stages/
+│           └── {workflow stage folders}/
+├── .gitignore
+├── .interf/state.json        runtime only (gitignored)
+└── home.md
+```
+
+**AGENTS.md:**
+```markdown
+# {Name}
+
+{One-line description: what this interface is for and what questions it answers.}
+
+## How this interface works
+
+This is an Interf interface — a focused local context shell built on top of a knowledge base.
+
+- `interf.json` — minimal config. Defines type, name, and knowledge-base path only.
+- `compile-plan.md` — execution plan. Defines the selected workflow's compile stages. Generated by LLM, customized for this specific interface. This is the initial runtime hypothesis, not the final word.
+- `knowledge/` — this interface's local entities, claims, and indexes. Built during compile.
+- `briefs/` — hero documents for this use case.
+- `summaries/` — periodic summaries.
+- `workflow/` — local workflow package for create, query, and compile-stage docs.
+- `workflow/use/query/` — interface-local manual query rules. If local artifacts are insufficient, this should defer to the parent KB query loop at `../../workflow/use/query/SKILL.md`.
+- `home.md` — start here. Overview of what's built.
+- The knowledge base is at `../../`. Knowledge-base summaries are at `../../summaries/`.
+- The knowledge-base raw-file quick check is at `../../.interf/source-access.json`.
+- Agent access hierarchy for this interface is: local interface artifacts -> parent knowledge-base artifacts -> raw source files only when needed.
+- If your coding agent is sandboxed, prefer opening the source folder as the session root, then navigate to this interface from there.
+- In Obsidian, browse this interface from the parent knowledge-base vault. Do not assume a standalone interface vault can resolve parent links.
+
+## Manual access checklist
+
+Use this checklist on the first substantive manual question so you do not get stuck later in the session:
+
+1. Read this `AGENTS.md` and then local `workflow/use/query/SKILL.md`.
+2. Confirm the local interface surface is reachable: `home.md`, `knowledge/`, `briefs/`, and any local `summaries/`.
+3. Confirm the parent knowledge base is reachable: `../../AGENTS.md`, `../../home.md`, and parent summaries.
+4. Run the raw-source preflight through `../../.interf/source-access.json` immediately. If the environment asks for permission, request it right away.
+5. After that preflight, start the answer with exactly `Raw access: confirmed` or `Raw access: unavailable`.
+
+## Preferred operation
+
+Use the Interf CLI:
+```
+interf verify interface-plan --json   # immediately after scaffold creation
+interf compile
+interf verify retrieve --json        # after retrieve before analyze/compile
+```
+
+## Raw skills (fallback / internal harness)
+
+Run the compile chain:
+```
+interface/retrieve      retrieval contract: prove coverage and select relevant files
+interface/analyze       analysis contract: extract entities, claims, and refinements
+interface/compile       output contract: create local outputs and validate them
+```
+
+## For agents without bundled skills
+
+Read `AGENTS.md` first. Then read `workflow/use/query/SKILL.md` for manual questions or the relevant `workflow/compile/stages/<stage>/SKILL.md` when doing compile work. `interf.json` and `compile-plan.md` provide the config and execution plan.
+
+To answer questions: start with `home.md`, follow wikilinks to local entities, claims, and indexes in `knowledge/`, then use `briefs/` and local `summaries/` for high-level entry points. If you need deeper evidence, follow links into knowledge-base summaries at `../../summaries/`, then raw files only when necessary.
+Preserve the scaffold router and checklist. Do not replace this file with a shorter template that drops the manual access checklist, raw-source gate, or parent knowledge-base handoff.
+If local docs are listed by the stage contract, read them before creating the interface. They may `extend` or `override` the bundled workflow instructions for later stages, but they do not bypass the stage contract.
+Do not answer from the knowledge base until retrieval coverage is proved via `.interf/coverage.json` and `.interf/relevant.json`.
+
+## Rules
+
+- Do not modify anything in the knowledge base — it is read-only.
+- All outputs are local to this interface.
+- Follow prose-as-title: filenames are claims, not slugs.
+- Follow wiki-link-as-prose: links read as sentences.
+```
+
+When updating `AGENTS.md`, edit the existing scaffold in place. Keep the manual access checklist, router guidance, and parent knowledge-base handoff sections. Only refine the interface-specific description and lines that need to reflect this use case.
+
+**.gitignore:**
+```
+knowledge/
+briefs/
+summaries/
+.interf/
+```
+Add any output directories from compile-plan.md.
+
+**CLAUDE.md:**
+- Generate it from the final `AGENTS.md` content so Claude Code picks up the same interface instructions automatically.
+- Add a short header telling users to edit `AGENTS.md`, not `CLAUDE.md`.
+
+**.interf/state.json:**
+```json
+{
+  "version": 1,
+  "retrieve_complete": false,
+  "analyze_complete": false,
+  "compile_complete": false,
+  "coverage_complete": false,
+  "frontmatter_scanned": 0,
+  "candidate_count": 0,
+  "abstracts_read": 0,
+  "expansion_passes": 0,
+  "relevant_count": 0,
+  "rejected_count": 0,
+  "delta_count": 0,
+  "delta_files": [],
+  "last_retrieve": null,
+  "last_analyze": null,
+  "last_compile": null,
+  "knowledge_base_summary_count_at_last_compile": 0,
+  "extracted_entities": 0,
+  "extracted_claims": 0,
+  "entity_count": 0,
+  "claim_count": 0,
+  "output_count": 0,
+  "warning_count": 0,
+  "error_count": 0
+}
+```
+
+**home.md:**
+```markdown
+# {Name} — Home
+
+Not yet compiled. Run `interf compile` to start interface compilation.
+```
+
+### 7. Register
+
+Add to `~/.interf/registry.json` interfaces[]. Create registry if it doesn't exist.
+
+### 8. Show next steps
+
+```
+Done — interface "{name}" created at {path}
+Connected to knowledge base "{knowledge-base-name}"
+
+Next: cd {path} && interf compile
+```
+
+## What this skill does NOT do
+
+- Does not compile the interface (use `interf compile` from inside the interface, or the raw stage skills)
+- Does not create knowledge bases (use CLI `interf create knowledge-base`)

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

@@ -0,0 +1,109 @@
+# 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: Research Briefing interface
+
+```markdown
+# Research Briefing — Compile Plan
+
+## Stage 1: Retrieve
+
+Filter criteria for knowledge-base summaries/:
+- Categories: papers, notes, repos, datasets, experiments
+- Priority evidence tiers: tier_1_authoritative, tier_2_direct_record, tier_3_working_material
+- Truth modes to prioritize or downweight: prioritize fact/reported_fact/measurement, downweight brainstorm and speculation
+- Key entities: methods, datasets, benchmarks, authors, projects
+- Date range: all (for landscape), last 90 days (for recent developments)
+
+Expected relevant file count: ~220 of 900
+Coverage loop:
+- scan all 900 summary frontmatter blocks
+- read abstracts for the full candidate set
+- follow adjacency links for methods, datasets, and benchmark clusters until retrieval closure
+- persist selected and rejected files with reasons in coverage proof
+
+## Stage 2: Analyze
+
+For each relevant summary, extract:
+- Methods: goals, assumptions, strengths, weaknesses
+- Datasets: scope, quality issues, benchmark relevance
+- Claims: what is being asserted and with what level of support
+- Contradictions: disagreements across sources, benchmarks, or interpretations
+- Open questions: what the knowledge base still does not explain well
+- Runtime refinements: add missing method families, benchmark clusters, and claim groupings when evidence supports them
+
+Working-set budget: ~40% of model context window per batch.
+Subagent instruction: "Extract entities, claims, contradictions, and open questions relevant to this research briefing. Return structured JSON."
+
+## Stage 3: Compile
+
+### briefs/Themes.md
+Purpose: "What themes define this knowledge base right now?"
+Sections: major themes, strongest evidence, changes over time
+Evidence: prefer primary and direct-record sources
+
+### briefs/Contradictions.md
+Purpose: "Where do sources disagree or look unresolved?"
+Sections: contradiction, supporting evidence, counterevidence, next check
+Evidence: cite both sides explicitly
+
+### briefs/Open-Questions.md
+Purpose: "What should we read or verify next?"
+Sections: question, why it matters, missing evidence, suggested next sources
+Evidence: link back to the gaps in the reviewed set
+
+### home.md
+Links to: all briefs notes, latest summary, entity/claim counts
+Agent navigation: AGENTS.md -> home.md -> briefs/ -> knowledge/ -> knowledge-base summaries
+```

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

@@ -0,0 +1,50 @@
+# Interface Workflows
+
+Pre-designed interface methodologies. Use them as starting points and adapt them to the actual knowledge-base data.
+
+## briefing
+
+Current-state briefing. Best when the agent needs the latest truth, recent changes, and immediate next steps.
+
+**Questions it answers:**
+- What is true right now?
+- What changed recently?
+- What should happen next?
+
+**Filter:** current-state docs, changelogs, decisions, updates
+**Outputs:** Current-State.md, Changes.md, Next-Steps.md
+
+## research
+
+Research synthesis. Best when the agent needs themes, claims, contradictions, and open questions from a dense knowledge base.
+
+**Questions it answers:**
+- What are the strongest recurring themes?
+- Where do sources agree or disagree?
+- What questions still need more evidence?
+
+**Filter:** primary sources, papers, notes, datasets, experiments, repos
+**Outputs:** Themes.md, Contradictions.md, Open-Questions.md
+
+## audit
+
+Audit and gap-finding. Best when the agent needs to improve knowledge-base quality, surface contradictions, and plan follow-up work.
+
+**Questions it answers:**
+- What is missing or weakly covered?
+- Which facts or claims look inconsistent?
+- What should be verified or added next?
+
+**Filter:** canonical records, requirements, policies, status docs, recent changes
+**Outputs:** Gaps.md, Contradictions.md, Follow-Ups.md
+
+## Create new workflow
+
+Create a new reusable local workflow from the wizard when the shipped workflows are 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

@@ -0,0 +1,34 @@
+---
+{
+  "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
+
+Raw-source gate:
+- inspect `../../.interf/source-access.json`
+- verify one `suggested_checks` path is actually readable from this session before claiming raw-file verification
+- 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 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

@@ -0,0 +1,166 @@
+---
+{
+  "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
+- keep `.interf/health.json` consistent with the latest `.interf/state.json` if you update state directly
+- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
+
+## 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. Update state
+```
+
+### 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
+- `.interf/state.json` → `last_compile`, `knowledge_base_summary_count_at_last_compile`
+- `../../.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.
+
+### 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.
+
+### 5. Compute delta
+
+- First run (`last_compile` is null): ALL relevant files are new
+- Subsequent runs: compare `knowledge_base_summary_count_at_last_compile` vs current count, identify new files by date
+
+### 6. Update state
+
+Write the full retrieved set to `.interf/relevant.json`:
+
+```json
+{
+  "version": 1,
+  "generated_at": "2026-03-30T20:00:00Z",
+  "knowledge_base_summary_count": 2500,
+  "relevant_files": ["summaries/file1.md", "summaries/file2.md"],
+  "delta_files": ["summaries/file1.md", "summaries/file2.md"]
+}
+```
+
+File paths in `relevant_files` and `delta_files` are relative to the knowledge base.
+
+Write retrieval proof to `.interf/coverage.json`:
+
+```json
+{
+  "version": 1,
+  "run_id": "run_abc123",
+  "interface": "briefing",
+  "generated_at": "2026-03-30T20:00:00Z",
+  "knowledge_base_summary_total": 3,
+  "frontmatter_scanned": 3,
+  "candidates_after_frontmatter": 2,
+  "abstracts_reviewed": 2,
+  "expansion_passes": 2,
+  "relevant_selected": 1,
+  "rejected": 2,
+  "coverage_complete": true,
+  "proof": {
+    "scanned": ["summaries/file1.md", "summaries/file2.md", "summaries/file3.md"],
+    "reviewed": ["summaries/file1.md", "summaries/file2.md"],
+    "retrieved": ["summaries/file1.md"],
+    "excluded": ["summaries/file2.md", "summaries/file3.md"]
+  }
+}
+```
+
+Write retrieve results to `.interf/state.json`:
+
+```json
+{
+  "retrieve_complete": true,
+  "coverage_complete": true,
+  "frontmatter_scanned": 2500,
+  "candidate_count": 1200,
+  "abstracts_read": 1200,
+  "expansion_passes": 2,
+  "relevant_count": 1200,
+  "rejected_count": 1300,
+  "delta_count": 12,
+  "delta_files": ["summaries/file1.md", "summaries/file2.md"],
+  "last_retrieve": "2026-03-30T20:00:00Z"
+}
+```
+
+Refresh `.interf/health.json` after state is updated. The health file is a computed verification surface for compile status and key metrics, not a prose summary.
+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 2500 summary files.
+STATUS: scanned 2500/2500
+STATUS: reviewed 1200 abstracts, 2 expansion passes
+STATUS: selected 1200 relevant, 1300 rejected, 12 delta
+DONE: retrieve complete
+```
+
+When the retrieval proof, relevant set, state, and health files are written, emit the required `DONE:` line and stop. Do not keep exploring once retrieval closure is recorded.