@interf/compiler 0.2.5 → 0.3.1

package/skills/knowledge-base/compile/SKILL.md

@@ -1,196 +0,0 @@
----
-{
-  "name": "knowledge-base/compile",
-  "description": "Compile the cross-file knowledge layer from summaries in a knowledge base. Discovers entities, claims, relationships, and navigation outputs. Builds knowledge/ and home.md layers. Use when asked to compile a knowledge base, build graph, update knowledge, or connect the dots."
-}
----
-
-# Compile Knowledge Base
-
-Read `interf.json` for the config. Must have `type: knowledge-base`.
-
-Local runtime reference:
-- active stage contract: `.interf/stage-contract.json`
-- active run ledger: `.interf/run.json`
-- local config: `interf.json`
-- local instruction docs: the files listed by `.interf/stage-contract.json`
-
-When this skill is embedded into a generated knowledge base, 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 builds the cross-file intelligence layer from existing summaries. This is the knowledge-layer contract for a knowledge base. For per-file evidence generation, use the bundled file-evidence stage first.
-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 the stage contract.
-
-Harness role:
-- This skill is an internal harness step normally invoked by `interf compile`.
-- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
-
-## CLI status contract
-
-When this skill is launched by the Interf CLI, do not narrate intent or planning. Only emit user-visible updates that begin with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`.
-
-If `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run. It defines required artifacts, counts, and execution notes. Follow it instead of improvising a different workflow.
-
-Use this sequence:
-- `STATUS: loaded compile plan N summary files`
-- `STATUS: inventoried summaries N/N` after the inventory pass is complete
-- `STATUS: read summary files X/N` after each deep-read batch or every 25 files, whichever comes first
-- `STATUS: wrote compile outputs` after `knowledge/` and `home.md` are updated
-- `DONE: compile complete N/N` when the required outputs are on disk
-
-If you are blocked or hit an unrecoverable issue, emit `BLOCKED:` or `ERROR:` once with the concrete reason.
-Keep scratch commands single-purpose and non-destructive. Do not start by deleting old outputs with `rm`, wildcard cleanup, `;`, or `&&` chains.
-
-## Prerequisites check
-
-Read the stage contract, inventory, and summaries.
-
-- If `summaries/` is missing or empty: "File-evidence stage not ready yet." Stop.
-- Otherwise: proceed.
-
-## Execution bias
-
-This stage builds a reusable substrate, not a full task-specific intelligence layer.
-
-- for small knowledge bases, prefer the smallest useful retrieval surface over graph sprawl
-- for a single report or small folder, do not invent dozens of entities or claims just because the source is rich
-- create only the entities, claims, and indexes that materially help later interface retrieval
-- if `.interf/stage-contract.json` says `summary_total <= 3`, treat the run as a tiny compile: read every summary overview, write the smallest truthful substrate, and stop
-- for a tiny compile, do not spend time designing an elaborate ontology or widening into raw-source exploration
-- a tiny compile is successful when it leaves a grounded home page plus a compact retrieval surface in `knowledge/` that later interfaces can build on
-- stop once the stable substrate exists; do not keep expanding the ontology out of curiosity
-
-## Execution checklist
-
-```
-Knowledge-base compile:
-- [ ] 1. Read interf.json
-- [ ] 2. Scan ALL summary frontmatter and write .interf/inventory.json
-- [ ] 3. Read the summary overviews needed for a minimal compile
-- [ ] 4. Write canonical entities, claims, indexes, and home.md
-- [ ] 5. Validate
-```
-
-### 1. Read interf.json + local stage docs
-
-Read `interf.json` for knowledge-base identity and paths. Read `.interf/stage-contract.json` for the active stage contract. Then read any local docs listed by the contract. The summaries in `summaries/` have this structure:
-
-- **Frontmatter fields**: source, source_kind, evidence_tier, truth_mode, state, abstract
-- **Sections**: overview, key claims, references when needed
-
-This is what you're working with. Every summary has:
-- `source` → the exact source file path
-- `source_kind`, `evidence_tier`, `truth_mode`, `state` → use these to weight evidence and avoid flattening weak material into strong claims
-- `abstract` → quick routing summary for inventory and interface retrieve
-- `overview` / `key claims` → source-grounded detail for deeper reads
-
-The compile job is to turn these file-level evidence objects into a retrieval-ready knowledge base. Use the active stage contract plus any local docs listed by it for entity discovery rules, claim derivation logic, and quality requirements.
-Prefer source-domain entities over document-shell entities. A report PDF is evidence, not the main ontology. If a market report summary names covered markets, segments, publishers, or themes, compile those as the primary retrieval surface instead of centering the document title alone.
-
-### 2. Scan summaries and create inventory
-
-Scan ALL summaries/ frontmatter once. This step is deterministic and must complete before synthesis.
-
-Write `.interf/inventory.json`:
-
-Write a full inventory ledger in the current runtime shape. At minimum:
-- `total` must equal the actual `summaries/` file count for this run
-- every summary must have a corresponding inventory entry
-- prefer the current `entries[]` runtime shape over legacy `files[]`
-- for current `entries[]` inventory entries, include at least `source`, `summary`, `frontmatter_scanned: true`, and the overview-read proof the validators use (`abstract`, `abstract_read: true`, or an equivalent current-state field)
-- per-summary entries should preserve the fields the runtime and validators use, such as file path, source path, source metadata, and whether frontmatter or deeper reads were completed
-- for legacy `files[]` inventory entries, use `frontmatter_scanned: true` after the frontmatter pass and `abstract_read: true` after the summary overview read
-- do not invent alternate flag names for those validator-facing fields
-- if you include `summary_map`, derive it from the current inventory instead of copying sample aggregates from docs
-
-Verify: `total` in inventory MUST equal the actual summaries/ file count. If not, stop.
-
-Then read the summary overviews needed for synthesis:
-
-- if `N <= 25`, read every summary overview
-- if `N > 25`, read all high-signal summaries plus enough additional summaries to build a stable substrate
-- if `N <= 3`, move directly from those overview reads into the smallest honest compile outputs; do not turn a tiny knowledge base into an open-ended graph-design pass
-
-Do not turn this into an open-ended archival pass. The compile stage should finish in one run for normal small knowledge bases.
-
-### 3. Canonicalize entities, threads, and aliases
-
-**Prerequisite:** inventory.json must cover all summaries, and the overview reads above must be complete for the working set.
-
-Use the inventory summary_map plus deep-read evidence to identify canonical entities and recurring threads. Create canonical notes in knowledge/entities/ for recurring actors:
-- people, companies, products, concepts, projects, and durable threads
-- for reports, datasets, and decks, create entities for the covered domain objects when the summary makes them explicit (for example markets, publishers, regions, products, or benchmark topics)
-- Resolve aliases to one canonical note
-- Include: summary, evidence links, related entities, first/last seen
-- Prefer explicit wikilinks to related summaries, entities, and claims so future agents can climb outward through backlinks instead of rereading from scratch
-- For a single report or other small KB, prefer a compact set of 2-6 high-signal entities over exhaustive decomposition.
-
-### 4. Extract cross-file claims and relationships
-
-**Prerequisite:** Same as entities.
-
-Use inventory data plus deep reads to identify patterns across files. Create notes in knowledge/claims/ for cross-file observations:
-- Must have 2+ supporting sources unless explicitly marked unresolved or exploratory
-- Use prose-as-title: filename IS the claim
-- Include: the claim, why it matters, evidence links, and a clear sense of evidence strength
-- Link claims back to the supporting summaries and related entities so navigation can move claim -> evidence -> source trail cleanly
-- For a single report or small KB, 1-4 strong claims are enough when they capture the main retrieval surface.
-
-### 5. Build retrieval indexes and navigation
-
-Create aggregate navigation in knowledge/indexes/:
-- Keep a stable core set first: Companies.md, Markets.md, Themes.md
-- Add extra indexes only when the source base clearly supports them and they do not replace the stable core set
-- For a single report or dataset, prefer report-shaped indexes over generic People/Projects/Timeline scaffolding
-- Link to canonical entities, high-signal summaries, and major claims
-- Make the result useful for interface creation and retrieve, not just for human browsing
-- Treat backlinks as part of the retrieval surface: notes should make it obvious how to move from a high-level concept to the supporting summaries and back again
-- If the KB is very small, keep the indexes short and direct instead of expanding them into standalone essays.
-- For a tiny compile, it is enough for the stable core indexes to be short landing notes that route later interface stages toward the real evidence.
-
-Update `home.md` every compile run so it becomes the knowledge-base landing layer for agents.
-Include the source count, the high-signal scope of the knowledge base, and links to the stable core indexes.
-
-### 6. Runtime reconciliation
-
-The CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after stage validation so viewers keep a stable knowledge-base-level presentation contract.
-Rewrite outputs directly instead of clearing `knowledge/` or `.interf/` first. If a stale artifact truly must go away, remove only that explicit path after the replacement files are already written.
-
-### 7. Validate
-
-- [ ] All output files exist and are non-empty
-- [ ] Entity notes have evidence links
-- [ ] Claims preserve evidence strength and do not overstate exploratory material
-- [ ] No wikilinks to nonexistent files
-- [ ] home.md is current
-- [ ] The result is compact enough that an interface stage can reuse it without re-reading a bloated local graph
-
-## Graph quality rules
-
-- Canonicalize aliases to one entity note
-- Remove stale duplicates
-- Repair broken wikilinks
-- Prefer explicit wikilinks over vague prose
-- Use properties for machine filtering, tags for Obsidian surfacing
-- Prefer a small stable graph over speculative expansion
-
-After compile, prefer running:
-
-```bash
-interf verify compile --json
-```
-
-If it fails, fix inventory/state/output consistency before treating the knowledge base as ready for interface creation or retrieval.
-
-Report:
-```
-Step 2/2 complete — Knowledge-base compile
-Entities: <entity_count>, Claims: <claim_count>
-home.md updated.
-```
-
-When the required outputs and inventory are written, emit the required `DONE:` line and stop. Do not keep browsing or auditing after the compile contract is satisfied.
-
-## What this skill does NOT do
-
-- Does not generate per-file summaries (use `knowledge-base/summarize`)
-- Does not work on interfaces (use `interface/retrieve` to start interface compile)

package/skills/knowledge-base/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 knowledge base 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/knowledge-base/compile/references/stage-claims.md

@@ -1,60 +0,0 @@
-# Stage: Extract Claims
-
-Create notes in knowledge/claims/ for cross-file observations backed by evidence.
-
-## Process
-
-1. Read summaries/ overviews looking for patterns that appear across 2+ files
-2. Group related observations into claims
-3. For each claim: create a note with evidence links
-
-## What qualifies as a claim
-
-- A pattern observed in 2+ sources
-- A decision or pivot with supporting evidence
-- A risk identified from multiple signals
-- A relationship between entities backed by evidence
-- A metric or milestone confirmed by locked/confirmed sources
-
-Do NOT create claims from single observations unless marked as unresolved/hypothesis.
-
-## Claim note format
-
-Use prose-as-title: the filename IS the claim.
-
-Example filename: `{subject} acts as {relationship} for {entity}.md`
-
-```markdown
----
-{
-  "claim_type": "pattern | decision | risk | milestone | relationship | metric",
-  "status": "active | historical | unresolved",
-  "evidence_count": "N",
-  "confidence": "high | medium | low",
-  "tags": ["type/claim", "claim/{claim_type}"]
-}
----
-
-## Claim
-
-{The observation in one tight paragraph.}
-
-## Why it matters
-
-{Why this matters for future querying and decision-making.}
-
-## Evidence
-
-- [[{summary title}]]: {one-line evidence}
-- [[{summary title}]]: {one-line evidence}
-
-## Related
-
-- [[{related entity or claim}]]
-```
-
-## Confidence levels
-
-- **high**: 3+ locked/confirmed sources agree
-- **medium**: 2+ sources, at least one confirmed
-- **low**: 2+ draft sources, or sources partially conflict

package/skills/knowledge-base/compile/references/stage-entities.md

@@ -1,46 +0,0 @@
-# Stage: Discover Entities
-
-Create canonical notes in knowledge/entities/ for recurring actors in the knowledge base.
-
-## Process
-
-1. Scan all summaries/ abstracts and frontmatter → build frequency map of recurring actors
-2. Scan overviews for company names, product names, concepts
-3. For each actor appearing 3+ times:
-   - Create a canonical entity note
-   - Resolve aliases (e.g., "{Short name}" and "{Full name}" -> one note)
-   - Link to all supporting summaries/ files via wikilinks
-
-## Entity note format
-
-```markdown
----
-{
-  "entity_type": "person | company | product | concept",
-  "status": "active | historical",
-  "first_seen": "YYYY-MM-DD",
-  "last_seen": "YYYY-MM-DD",
-  "evidence_count": "N",
-  "tags": ["type/entity", "entity/{entity_type}"]
-}
----
-
-## Summary
-
-{Who/what this is and why it matters. 2-3 sentences.}
-
-## Evidence
-
-- [[{summary title}]]: {one-line context}
-
-## Related
-
-- [[{related entity or claim}]]
-```
-
-## Alias resolution
-
-When multiple names refer to the same actor:
-- Pick the most complete name as canonical (e.g., "{Full Name}" not "{Nickname}")
-- Mention aliases in the summary
-- All evidence links point to the one canonical note

package/skills/knowledge-base/query/SKILL.md

@@ -1,45 +0,0 @@
----
-{
-  "name": "knowledge-base/query",
-  "description": "Manual-use skill for answering questions from inside a compiled knowledge base. Navigates AGENTS.md, home.md, knowledge/, summaries/, backlinks, and raw sources only when reachable. Use when a user opens an agent inside a knowledge base and asks questions against it."
-}
----
-
-# Knowledge Base Query
-
-Use this skill in manual agent sessions inside a compiled knowledge base.
-
-Start with:
-- `AGENTS.md`
-- `home.md`
-- `knowledge/`
-- `summaries/`
-
-Default loop:
-- use `knowledge/` indexes, entities, and claims first
-- follow wikilinks and backlinks outward before treating one note as complete
-- use `summaries/` for deeper evidence
-- use raw source files only when needed for verification, direct quotes, ambiguity, or missing context
-- when a caller asks for a trace, audit log, or `artifacts_consulted` list, 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 compiled 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 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 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; take a machine-readable extraction path before answering
-- if the first local extraction method misses the number, attempt another local recovery path before settling 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 compiled notes were sufficient
-- if you can only estimate from the chart, label the answer `approximate` and keep the precision gap explicit
-
-When confidence is low:
-- expand outward through linked claims, entities, indexes, and summaries
-- do not over-read a single summary title as final truth
-
-This skill is for manual question-answering behavior. It does not change summarize or compile runtime contracts.

package/skills/knowledge-base/summarize/SKILL.md

@@ -1,152 +0,0 @@
----
-{
-  "name": "knowledge-base/summarize",
-  "description": "Generate summaries for unprocessed source files in a knowledge base. Reads interf.json for format rules. Creates one summaries/ file per source file with abstract, overview, metadata, and wikilinks. Use when asked to summarize, process files, generate summaries, or after adding new files to a knowledge base."
-}
----
-
-# Summarize Source Files into Summaries
-
-Read `interf.json`, `.interf/stage-contract.json`, and `.interf/run.json` first.
-
-Use only local workspace files for this run:
-- `interf.json`
-- `.interf/stage-contract.json`
-- `.interf/summarize-targets.json` when present
-- `.interf/source-access.json` when raw-file access needs a quick check
-- local instruction docs explicitly listed by `.interf/stage-contract.json`
-
-Do not open SDK repo docs or source files outside the current workspace. The local contract and local docs are the source of truth.
-
-Harness role:
-- This skill is normally invoked as one of the file-evidence stages inside `interf compile`.
-- When launched by the CLI, follow the stage contract exactly and keep user-visible output to `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:` lines only.
-
-## Required sequence
-
-1. Read `interf.json` and confirm `type: knowledge-base`.
-2. Read `.interf/stage-contract.json` and treat it as authoritative.
-3. Read `.interf/summarize-targets.json` when present and treat `targets[]` as the source of truth for which files to summarize.
-   If a target includes `output`, write the summary to that exact relative path.
-4. Read any local docs listed by the stage contract.
-5. Create one summary file in `summaries/` for each target source file.
-6. Write `.interf/inventory.json`.
-7. Emit `DONE:` and stop.
-
-If the CLI provided a summarize plan, do not re-audit the whole knowledge base before writing summaries.
-
-## Status contract
-
-When launched by the Interf CLI:
-- emit exactly one startup line: `STATUS: loaded summarize plan N files`
-- emit `STATUS: batch committed` only after summary files and inventory were actually written
-- emit `DONE: summarize complete N/N` when the required writes are complete
-- do not emit per-file progress
-
-## Execution bias
-
-This stage is a light per-file evidence pass, not a mini research project.
-
-- process only the files listed in `.interf/summarize-targets.json`
-- for a single large PDF, deck, or report, do one lightweight evidence pass and then stop
-- for a single large PDF, deck, or report, do at most one routing pass across the document plus one focused follow-up read that covers no more than 3 routed pages or sections
-- capture the file's scope, headline facts that are directly exposed, and whether important evidence also lives in charts or tables
-- if the document repeats the same template across many pages or entities, sample only enough pages to describe that repeated structure and preserve routing for later interfaces
-- do not chase every page, every market, every appendix, or every historical chart in this stage
-- leave narrow task-specific extraction to interface workflows
-- once you can state the document scope, the exposed headline metrics, and where deeper chart/table evidence lives, write the summary immediately
-- once the summary file and inventory are written, stop immediately
-- keep bulk PDF/OCR extraction output out of the run log. Save scratch output to temp files and inspect only the routed slices you need for the summary.
-- keep scratch extraction commands single-purpose and non-destructive. Do not use `rm`, wildcard cleanup, `;`, or `&&` chains during summarize.
-- if a shell pattern is blocked, do not retry the same chained command with minor edits. Switch to a simpler local read path and keep moving.
-- if you have already checked whether the summary file exists and it does not, the next step is to write it rather than doing another exploratory read
-- do not precreate `.interf/inventory.json` with `touch`; write the final JSON document directly
-- when updating `.interf/inventory.json`, rewrite the full JSON document in one whole-file write instead of appending or patching partial lines
-- do not use `apply_patch` or line-matched diffs on `.interf/inventory.json`; replace the file in one complete write
-- when you are ready to write, prefer a direct whole-file shell write such as `cat > path <<'EOF' ... EOF` for summary markdown and the inventory artifact
-- whole-file shell writes for stage artifacts are allowed and preferred here; do not stall deciding between patch-based editing and direct writes
-
-## Summary output format
-
-Create one markdown file per source file under `summaries/`.
-Every summary filename must end in `.md`, even when the source file is `.txt`, `.pdf`, or another format.
-If the source file already ends in `.md`, keep a single `.md` suffix instead of appending another one.
-When `.interf/summarize-targets.json` provides `targets[].output`, use that exact path instead of inferring a filename.
-
-Each summary must include JSON frontmatter with:
-- `source`
-- `source_kind`
-- `evidence_tier`
-- `truth_mode`
-- `state`
-- `abstract`
-
-Use JSON frontmatter wrapped in `---` markers. Do not use YAML `key: value` frontmatter.
-
-Example:
-
-```markdown
----
-{
-  "source": "go-to-market-notes.txt",
-  "source_kind": "note",
-  "evidence_tier": "primary",
-  "truth_mode": "proposed",
-  "state": "draft",
-  "abstract": "Short source-grounded description."
-}
----
-```
-
-Each summary must include these sections:
-- `## Overview`
-- `## Key Takeaways`
-
-`## References` is optional.
-
-Keep summaries source-grounded:
-- do not overstate certainty
-- keep titles descriptive and conservative
-- preserve evidence tiers and truth modes
-- keep links sparse and obvious
-- for PDFs, decks, and reports, capture material table/chart/figure evidence when it affects the source's meaning
-- preserve the main headline metrics for the top-level sections or market groups when they are present in extractable text
-- preserve easy headline values from prose or clearly exposed tables when they are central to the source
-- for market reports and dashboards, preserve the main peer groups that are trivial to recover from prose or headline tables, but do not turn summarize into a full market-by-market extraction pass
-- if important evidence appears to live in charts or other visuals, say that clearly in the summary and preserve enough routing detail for a later interface or manual query step
-- do not turn the knowledge-base summarize stage into an exhaustive visual extraction pass across the whole report
-- if exact chart numbers are not directly recoverable from the same page with light local extraction, say so explicitly in the summary instead of flattening the evidence into vague prose
-- when useful, note whether important evidence came from prose, tables, or charts so later interface stages know when raw visual inspection may still be needed
-- distinguish `chart present and relevant` from `exact chart values not yet extracted`
-
-This is a per-file evidence stage only. Cross-file synthesis belongs to `knowledge-base/compile`.
-
-## Inventory output
-
-Write `.interf/inventory.json` so every source file is accounted for.
-
-Minimum shape:
-- prefer the current runtime shape: top-level `entries` plus `total`
-- `total` equal to the actual current source-file count
-- one `entries[]` object per source file
-- each entry should preserve at least `source`, `summary`, and a conservative summarize `status` or `state`
-- per-file routing must let the runtime and validators see which raw file maps to which summary
-
-Do not copy canned totals or filenames into the runtime inventory.
-Do not invent new top-level inventory keys when `entries` already fits the run.
-
-The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after stage validation.
-For a one-file summarize run, the finish sequence is strict: write the summary file, rewrite `.interf/inventory.json`, emit `STATUS: batch committed`, emit the standard summarize `DONE:` line using the current run counts, and stop.
-
-## Guardrails
-
-- Do not modify source files.
-- Do not emit `STATUS: batch committed` before files exist on disk.
-- Do not create placeholder JSON files with `touch` before writing the final documents.
-- Do not append a second JSON object to `.interf/inventory.json`. Rewrite the whole file once.
-- Do not use `apply_patch` or line-matched diffs to edit `.interf/inventory.json`.
-- Use a single whole-file write for each required artifact as soon as the summary text is ready.
-- If you check whether a required summary or inventory artifact exists and it is missing, create it next instead of doing another exploratory read.
-- Do not keep mining the source after a usable conservative summary already exists.
-- Do not keep browsing after the required writes are complete.
-- If a required path is missing or unreadable, emit one `BLOCKED:` or `ERROR:` line with the concrete reason and stop.