@interf/compiler 0.2.5 → 0.3.0

package/templates/knowledge-base/registry.md

@@ -1,118 +0,0 @@
-# Interf Registry
-
-The registry at `~/.interf/registry.json` tracks all knowledge bases and interfaces on this machine. The CLI and skills read it to list knowledge bases, show status, and navigate between them.
-
-## Format
-
-```json
-{
-  "version": 5,
-  "knowledgeBases": [
-    {
-      "name": "market-intel",
-      "path": "/path/to/market-intel",
-      "workflow": "interf",
-      "created": "2026-03-30T14:00:00Z"
-    },
-    {
-      "name": "ops",
-      "path": "/path/to/ops",
-      "workflow": "karpathy",
-      "created": "2026-03-30T15:00:00Z"
-    }
-  ],
-  "interfaces": [
-    {
-      "name": "q2-launch-brief",
-      "path": "/path/to/q2-launch-brief",
-      "knowledgeBase": "ops",
-      "knowledgeBasePath": "/path/to/ops",
-      "workflow": "interf",
-      "created": "2026-03-30T16:00:00Z"
-    },
-    {
-      "name": "pricing-gap-review",
-      "path": "/path/to/pricing-gap-review",
-      "knowledgeBase": "market-intel",
-      "knowledgeBasePath": "/path/to/market-intel",
-      "workflow": "interf",
-      "created": "2026-03-30T16:30:00Z"
-    }
-  ]
-}
-```
-
-## Fields
-
-**Knowledge-base entry:**
-- `name` — short identifier
-- `path` — absolute path to knowledge-base root
-- `workflow` — selected methodology
-- `created` — ISO timestamp
-
-**Interface entry:**
-- `name` — short identifier
-- `path` — absolute path to interface root
-- `knowledgeBase` — name of the connected knowledge base
-- `knowledgeBasePath` — absolute path to the connected knowledge base
-- `workflow` — selected methodology (`interf` for the shipped default, or a local workflow id)
-- `created` — ISO timestamp
-
-## When it's updated
-
-| Action | Registry change |
-|---|---|
-| `interf create knowledge-base` | Adds a knowledge-base entry |
-| `interf create interface` | Adds an interface entry |
-| `interf compile` | Does NOT update registry |
-| manual cleanup / future remove command | Removes entry (does not delete files) |
-
-The registry stores static info only: names, paths, connections. It never stores processing status.
-
-## How status is computed (live, not stored)
-
-Processing status is always computed on demand from the filesystem:
-
-```
-For each knowledge base:
-  source_count = discover source files from source.path
-  summary_count  = count files in {path}/summaries/
-  pending      = source_count - summary_count
-  status       = pending > 0 ? "pending" : "compiled"
-
-For each interface:
-  state       = read {path}/.interf/state.json
-  knowledge_base_summary = count files in {knowledgeBasePath}/summaries/
-  stale           = knowledge_base_summary > state.knowledge_base_summary_count_at_last_compile
-  status      = stale ? "stale" : "compiled"
-```
-
-This avoids cached status going stale. Always compute fresh.
-
-## CLI output
-
-```
-$ interf list
-
-  Knowledge Bases
-  ─────────────────────────────────
-  market-intel  1,240 files    compiled
-  ops             892 files    3 pending
-
-  Interfaces
-  ─────────────────────────────────
-  q2-launch-brief      → ops            compiled
-  pricing-gap-review   → market-intel   stale (12 new)
-```
-
-## Creation
-
-`interf create knowledge-base` or `interf create interface` creates `~/.interf/` and `registry.json` if they don't exist yet. The initial registry:
-
-```json
-{
-  "version": 5,
-  "knowledgeBases": [],
-  "interfaces": []
-}
-```

package/templates/workflow-package/README.md

@@ -1,16 +0,0 @@
-# {{workflow_label}}
-
-This is the local {{target_type}} workflow package. Interf uses it when you run `interf compile`.
-
-- `workflow.json` defines the stage graph and contract kinds for this workspace.
-- `create/` explains what the scaffold/setup step produces.
-- `compile/stages/` contains one stage folder per compile stage.
-- `use/query/` explains how to use the compiled knowledge base or interface in manual agent sessions.
-
-Workflow id: `{{workflow_id}}`
-Method: {{workflow_hint}}
-
-Compile stages:
-{{stage_lines}}
-
-Interf CLI remains the referee for contracts, proofs, validators, and runtime state under `.interf/`.

package/templates/workflow-package/create/SKILL.md

@@ -1,8 +0,0 @@
-# Create
-
-This doc explains what Interf scaffolded for the selected {{target_type}} workflow.
-
-- selected workflow: `{{workflow_id}}`
-- method: {{workflow_hint}}
-- the CLI owns create-time validation, folder creation, config writing, and bootstrap docs
-- edit this workflow package after scaffold if you want to refine how later compile/query behavior works

package/templates/workflow-package/interface-query/SKILL.md

@@ -1,29 +0,0 @@
-# Interface Query
-
-{{top_preflight}}
-Use this skill when answering questions from inside this interface in a manual agent session.
-AGENTS.md should route manual questions here before an agent starts browsing notes on its own.
-Treat this as the interface-local query layer, not a replacement for the parent knowledge-base query loop.
-This is a workspace-local query doc, not a required globally installed slash-command skill.
-
-Default loop:
-- start with `AGENTS.md`, then `home.md`
-- browse local `knowledge/`, `briefs/`, and local `summaries/` first
-- answer direct target questions from the hero brief before widening scope
-- follow wikilinks and backlinks outward before treating one note as complete
-- if local interface artifacts are insufficient, load and follow the parent knowledge-base query guidance at `../../workflow/use/query/SKILL.md` before going raw
-- use parent knowledge-base artifacts in this order: `../../home.md`, then `../../knowledge/`, then `../../summaries/`
-- 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
-
-First-reply rule:
-{{first_reply_rule}}
-
-Task bias:
-- reuse the exact metric and period words from the question
-- if the target ledger marks a value approximate, say the literal word `approximate`
-- if the target ledger marks a value chart-derived or table-derived, say that literally
-- prefer the target ledger's `bin_choice` when the question is bin-shaped, and the `value_display` when the question asks for the approximate reading itself
-- do not add raw-access commentary unless the question asks about raw access
-
-Keep the interface-specific routing here. Keep raw-source, PDF/chart, and general fallback policy in `../../workflow/use/query/SKILL.md`.

package/templates/workflow-package/interface-stage/SKILL.md

@@ -1,13 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# {{stage_label}}
-
-This workflow stage customizes the built-in {{contract_type}} contract for the `{{workflow_id}}` interface workflow.
-
-- purpose: {{stage_description}}
-{{stage_notes}}
-
-Interf still enforces the same contract reads, writes, coverage proof rules, validators, and runtime reconciliation for this stage.

package/templates/workflow-package/knowledge-base-query/SKILL.md

@@ -1,36 +0,0 @@
-# Knowledge Base Query
-
-{{top_preflight}}
-Use this skill when answering questions from inside this knowledge base in a manual agent session.
-AGENTS.md should route manual questions here before an agent starts browsing notes on its own.
-This is the canonical parent-knowledge-base query loop that attached interfaces can inherit before raw fallback.
-This is a workspace-local query doc, not a required globally installed slash-command skill.
-
-Default loop:
-- start with `AGENTS.md`, then `home.md`
-- browse `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` before depending on raw files
-- actually open and inspect at least one `suggested_checks` path before claiming raw-file verification; a plain existence check is not enough
-- if raw files are not reachable, 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
-- choose that extraction path from the local environment you actually have instead of assuming specific tools
-- verify the chosen local extraction path is actually available before depending on it; if it is missing, switch once to another available local path
-- if the first local extraction method misses the number, attempt another local recovery path before settling for a visual estimate
-- 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
-
-First-reply rule:
-{{first_reply_rule}}
-
-You can edit this file to bias manual question-answering behavior without changing workflow stage logic.

package/templates/workflow-package/knowledge-base-stage/SKILL.md

@@ -1,13 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# {{stage_label}}
-
-This workflow stage customizes the built-in {{contract_type}} contract for the `{{workflow_id}}` knowledge-base workflow.
-
-- purpose: {{stage_description}}
-{{stage_notes}}
-
-Interf still enforces the same contract reads, writes, proof rules, validators, and runtime reconciliation for this stage.

package/templates/workflow-starters/interface/interf/README.md

@@ -1,13 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# Interf Interface Workflow
-
-Bias this interface toward the concrete user task, durable evidence routing, and answer-ready outputs.
-
-- turn the requested task into a bounded target set before broadening scope
-- preserve named entities, periods, metrics, units, and comparators instead of collapsing them into generic prose
-- when exact values matter, keep text-derived, table-derived, and chart-derived evidence distinct
-- prefer one concise hero brief and the smallest supporting note set that lets weaker agents answer reliably

package/templates/workflow-starters/interface/interf/create/SKILL.md

@@ -1,15 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# Interf Create Bias
-
-Turn the user's requested task into a concrete compile plan the later stages can actually execute.
-
-- treat `compile-plan.md` as the primary durable output of create; leave scaffolded `AGENTS.md` alone unless it is materially wrong
-- preserve the exact requested use-case line in `compile-plan.md` instead of leaving the generic workflow placeholder
-- carry named markets, years, metrics, units, comparators, and source families verbatim into the target ledger
-- if the task depends on exact values from reports, PDFs, charts, or tables, require a concrete local extraction path instead of vague raw-reading language
-- keep the interface bounded; do not widen into a general report summary unless a comparator or calibration anchor is genuinely needed
-- for automated runs, emit these canonical status markers verbatim and on their own lines: `STATUS: loaded interface creation contract.`, `STATUS: analyzed knowledge-base.`, `STATUS: wrote compile plan.`

package/templates/workflow-starters/knowledge-base/interf/README.md

@@ -1,13 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# Interf Knowledge Base Workflow
-
-Bias this knowledge base toward source-grounded summaries, explicit evidence tiers, and retrieval-ready compile outputs.
-
-- keep summary titles and abstracts conservative and source-grounded
-- preserve evidence tiers, truth modes, and draft-vs-final distinctions
-- compile durable entities, claims, indexes, and navigation that make later interfaces easier to retrieve from
-- prefer structures that help agents prove what they scanned, selected, and excluded before synthesis

package/templates/workflow-starters/knowledge-base/karpathy/README.md

@@ -1,13 +0,0 @@
----
-{
-  "mode": "extend"
-}
----
-# Karpathy Knowledge Base Workflow
-
-Bias this knowledge base toward the source folder -> summaries -> compiled markdown knowledge-base loop.
-
-- keep per-source summaries legible and source-grounded
-- prefer markdown-native knowledge artifacts an agent can browse and file back into the base
-- preserve backlinks and local browseability across the knowledge layer
-- treat the compiled base as a maintained working surface for later questions, not just a one-shot export