@interf/compiler 0.1.8

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

@@ -0,0 +1,220 @@
+---
+{
+  "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 N/N` after the inventory pass is complete
+- `STATUS: read X/N` after each deep-read batch or every 25 files, whichever comes first
+- `STATUS: wrote graph outputs` after `knowledge/` and `home.md` are updated
+- `DONE: compiled N/N` when `.interf/state.json` is updated successfully
+
+If you are blocked or hit an unrecoverable issue, emit `BLOCKED:` or `ERROR:` once with the concrete reason.
+
+## Prerequisites check
+
+Read `.interf/state.json`. Compare `summarized` vs `compiled`.
+
+- If `summarized == compiled` and both are current: "Knowledge base is up to date. Nothing to do." Stop.
+- If `summarized == 0` or source folder has unprocessed files: "File-evidence stage not ready yet." Stop.
+- Otherwise: proceed.
+
+## Execution checklist
+
+```
+Knowledge-base compile:
+- [ ] 1. Read interf.json
+- [ ] 2a. Inventory — scan ALL frontmatter, write .interf/inventory.json
+- [ ] 2b. Local evidence reading — batch-read abstracts/overviews, update inventory per file
+- [ ] 3. Canonicalize entities, threads, and aliases
+- [ ] 4. Extract cross-file claims and relationships
+- [ ] 5. Build retrieval indexes and navigation
+- [ ] 6. Update state (.interf/state.json)
+- [ ] 7. 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.
+
+### 2. Scan summaries and create inventory
+
+This step has two phases — inventory (deterministic, must be complete) then analysis (can span sessions).
+
+**Phase A: Inventory (MUST be complete before any analysis)**
+
+Scan ALL summaries/ frontmatter. Every file. Write `.interf/inventory.json`:
+
+```json
+{
+  "total": 2460,
+  "files": [
+    {
+      "file": "summaries/readiness assessment language.md",
+      "source": "notes/readiness.md",
+      "source_kind": "note",
+      "evidence_tier": "primary",
+      "truth_mode": "stated",
+      "state": "active",
+      "frontmatter_scanned": true,
+      "abstract_read": false,
+      "full_read": false
+    }
+  ],
+  "summary_map": {
+    "source_kind": {"note": 340, "plan": 280},
+    "evidence_tier": {"primary": 600, "secondary": 400},
+    "truth_mode": {"stated": 700, "reported": 120},
+    "state": {"active": 640, "draft": 80}
+  }
+}
+```
+
+Verify: `total` in inventory MUST equal actual summaries/ file count. If not, stop.
+
+This is deterministic — read frontmatter from every file, write the inventory. No analysis, no interpretation. Fast.
+
+**Phase B: Deep read (batched, resumable across sessions)**
+
+Work through inventory.json. For each file where `abstract_read: false`:
+- Read the abstract section
+- Update inventory: `abstract_read: true`
+- Extract entity mentions, thread markers, and potential claims
+
+For higher-weight files (`tier_1_authoritative`, `tier_2_direct_record`, or otherwise critical) where `full_read: false`:
+- Read the full overview
+- Update inventory: `full_read: true`
+- Extract deeper evidence
+
+**Batching:** Process ~200 files per batch. After each batch:
+- Write updated inventory.json
+- Report progress: "Abstract read: 400/2460 (16%)"
+
+If the session ends mid-batch, the next run reads inventory.json and continues from where it left off. No work is lost.
+
+### 3. Canonicalize entities, threads, and aliases
+
+**Prerequisite:** inventory.json must have ALL files scanned (frontmatter_scanned: true). Deep reads (abstract_read) should be substantially complete — at least 80% of files. If not, continue Phase B first.
+
+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
+- 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
+
+### 4. Extract cross-file claims and relationships
+
+**Prerequisite:** Same as entities — inventory must be complete.
+
+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
+
+### 5. Build retrieval indexes and navigation
+
+Create aggregate navigation in knowledge/indexes/:
+- People.md, Companies.md, Timeline.md, Themes.md, Projects.md, Threads.md
+- 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
+
+Update `home.md` every compile run so it becomes the knowledge-base landing layer for agents.
+
+### 6. Update state
+
+Update `.interf/state.json` with proof of work:
+
+```json
+{
+  "compiled": 2460,
+  "last_compile": "2026-03-30T18:10:00Z",
+  "entity_count": 85,
+  "claim_count": 142,
+  "inventory_complete": true,
+  "abstracts_read": 2460,
+  "full_reads": 400
+}
+```
+
+The inventory at `.interf/inventory.json` has per-file detail. State.json has the summary. Both must be consistent. If `abstracts_read` < total, the compile is incomplete — next run continues.
+
+Refresh `.interf/health.json` after state is updated. The CLI refreshes `.interf/view-spec.json` after stage completion so viewers keep a stable knowledge-base-level presentation contract.
+
+### 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
+
+## 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
+
+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: 85, Claims: 142
+home.md updated.
+```
+
+When the required outputs, state, and health files 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

@@ -0,0 +1,48 @@
+# 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

@@ -0,0 +1,60 @@
+# 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: `GATHR and Aon act as paid R&D for the product thesis.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

@@ -0,0 +1,46 @@
+# Stage: Discover Entities
+
+Create canonical notes in knowledge/entities/ for recurring actors in the knowledge base.
+
+## Process
+
+1. Scan all summaries/ `people:` frontmatter fields → build frequency map
+2. Scan abstracts and overviews for company names, product names, concepts
+3. For each actor appearing 3+ times:
+   - Create a canonical entity note
+   - Resolve aliases (e.g., "Matt" and "Matteo" → 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., "Matteo Cassese" not "Matt")
+- Mention aliases in the summary
+- All evidence links point to the one canonical note

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

@@ -0,0 +1,33 @@
+---
+{
+  "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
+
+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 compiled knowledge-base artifacts only
+
+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

@@ -0,0 +1,122 @@
+---
+{
+  "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.
+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. Update `.interf/state.json`.
+8. Refresh `.interf/health.json`.
+9. 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, inventory, and state were actually written
+- emit `DONE: summarized N/N` when the required writes are complete
+- do not emit per-file progress
+
+## 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.
+
+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
+
+This is a per-file evidence stage only. Cross-file synthesis belongs to `knowledge-base/compile`.
+
+## Inventory and state
+
+Write `.interf/inventory.json` so every source file is accounted for.
+
+Minimum shape:
+
+```json
+{
+  "total": 3,
+  "files": [
+    {
+      "raw": "company-overview.md",
+      "summary": "summaries/company overview.md",
+      "status": "summarized"
+    }
+  ]
+}
+```
+
+Update `.interf/state.json` with:
+- `pending`
+- `summarized`
+- `last_summarize`
+
+Refresh `.interf/health.json` after state is updated.
+
+## Guardrails
+
+- Do not modify source files.
+- Do not emit `STATUS: batch committed` before files exist on disk.
+- 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.

package/skills/workflow/create/SKILL.md

@@ -0,0 +1,126 @@
+---
+{
+  "name": "workflow/create",
+  "description": "Create or refine an Interf workflow package. Use when asked to define a KB or interface workflow, author workflow.json, shape compile stages, or add declarative stage acceptance criteria."
+}
+---
+
+# Create Workflow
+
+Use this skill when shaping a reusable Interf workflow package.
+
+Prefer the CLI first:
+
+```bash
+interf create workflow
+```
+
+That wizard should create the initial package under:
+
+```text
+interf/workflows/<type>/<workflow-id>/
+```
+
+Then refine the package in place.
+
+## What a workflow is
+
+A workflow is a package, not just a JSON file.
+
+It has two layers:
+
+- `workflow.json` = machine-readable stage graph and contract mapping
+- local docs = human/agent method layer
+
+Typical shape:
+
+```text
+interf/workflows/knowledge-base/<workflow-id>/
+  workflow.json
+  README.md
+  create/
+    SKILL.md
+  compile/
+    stages/
+      <stage-id>/
+        SKILL.md
+  use/
+    query/
+      SKILL.md
+```
+
+## What `workflow.json` should define
+
+Keep it declarative.
+
+- `id`
+- `type`
+- `label`
+- `hint`
+- optional `extends`
+- optional `placeholder`
+- optional `stages`
+- optional `stage_policy_notes`
+
+Each stage can define:
+
+- `id`
+- `label`
+- `contract_type`
+- optional `skill_dir`
+- optional `description`
+- optional `acceptance`
+
+## Contract kinds
+
+Use the shipped contract families only.
+
+Knowledge-base stages:
+- `kb-file-evidence`
+- `kb-knowledge-layer`
+
+Interface stages:
+- `interface-retrieval`
+- `interface-analysis`
+- `interface-output`
+
+Do not invent new engine contract kinds in a local workflow package.
+
+## Declarative acceptance
+
+Use stage `acceptance` for deterministic stage checks that the CLI can compare against runtime state.
+
+Current acceptance fields:
+
+- `artifacts_exist`
+- `state_truthy`
+- `state_equals_counts`
+- `state_at_least`
+- `state_at_least_counts`
+
+Use dynamic counts when possible.
+
+Good:
+- `"summarized": "target_files"`
+- `"frontmatter_scanned": "knowledge_base_summary_total"`
+
+Avoid hardcoding fixed file counts unless the workflow really requires them.
+
+## Builder rules
+
+- keep `workflow.json` readable and declarative
+- put execution guidance in `SKILL.md` files, not in dense JSON prose
+- let the CLI own runtime state, verification, and pass/fail
+- use `AGENTS.md` as the workspace router after scaffolding, not as the reusable workflow spec
+- prefer extending shipped workflows before inventing a new stage graph
+
+## Outcome
+
+A good workflow package gives Interf:
+
+- a compile pipeline
+- stage-to-contract mapping
+- readable local docs for executors
+- optional declarative acceptance checks
+
+The goal is not to write code inside the workflow. The goal is to define a stage pipeline that Interf can enforce.