@interf/compiler 0.3.3 → 0.4.0

package/README.md

@@ -1,155 +1,134 @@
-# Interf
+# Interf Compiler
 
-Open-source toolkit for preparing local files for agents.
+Prepare local datasets for accurate agent use.
 
-Turn PDFs, docs, spreadsheets, and notes into a local workspace your agent can navigate, verify, and answer from.
+Interf Compiler runs a local data-processing workflow over your dataset to build a compiled workspace: a file-based layer on top of your raw files that gives agents the full picture of the dataset they need to answer questions accurately.
 
-If you use Claude Code, Codex, OpenClaw, Hermes, or your own local agent setup on folders full of PDFs, docs, spreadsheets, and notes, the failure often shows up late: missed evidence, shallow analysis, bad comparisons, or answers that sound confident but are wrong.
+Define truth checks to measure how accurately agents answer from your dataset.
 
-Interf lets you set a few truth checks on a dataset, measure the raw baseline first if you want it, compile a workspace on top of that dataset, and see whether the result actually passes.
+Start with a baseline on your files as-is.
 
-- your dataset stays on your machine
-- BYOAI: use Claude Code, Codex, OpenClaw, Hermes, or your own local setup
-- your raw files stay the source of truth
-- the workflow package is the reusable method
-- the compiler runtime executes that workflow package and builds a file-based layer on top
+Then compile the workspace and retest it on the same checks so you can measure whether it actually helps.
 
-`interf compile` runs a workflow package with your agents as executors and produces a compiled workspace: a file-based layer on top of your raw files that agents can navigate, inspect, and work from.
+Then run self-improving loops that revise the workflow, rebuild the workspace, and rerun the same truth checks until the workspace passes or reaches the loop limit.
 
-Each compiled workspace carries its own `raw/` snapshot, so agents can work from one self-contained folder instead of reaching back into the source-folder control plane.
+## Why Use It
 
-Interf also projects native agent shells from that workspace:
+Interf Compiler is built around a few simple principles:
 
-- the compiled workspace itself is the folder your agent works from
-- each compile stage runs inside its own ephemeral execution shell with stage-specific instructions and mounted zone aliases under `inputs/` and `outputs/`
+- `Local`: the dataset, workflow, workspace, and test runs stay on your machine.
+- `File-based`: the compiled workspace is normal folders and files you can inspect, review, and version.
+- `Source-backed`: your raw files stay the source of truth; the compiled workspace is a layer on top, not a replacement database.
+- `Interoperable`: the same workspace can be used with different local agents and tools.
+- `Self-improving`: when truth checks fail, Interf can retry the workflow or revise it, rebuild the workspace, and rerun the same checks.
 
-The main reusable artifact is the workflow package. In the advanced looped mode, Interf can keep rerunning that workflow package against the same dataset and truth checks until it either passes or exhausts the attempt budget.
+## Example: Truth Checks
 
-## Quick Start
-
-Requirements:
-
-- Node.js 20+
-- a local coding agent: Claude Code or Codex
-
-Install:
-
-```bash
-npm install -g @interf/compiler
-```
+Truth checks are just question-and-answer pairs you already know how to verify from the dataset.
 
-The quickest start is the wizard:
-
-```bash
-cd ~/my-folder
-interf
-```
-
-If you want to see the config shape first, this is what Interf writes:
+A maintained public test run in this repo uses checks like this:
 
+<!-- PUBLIC_TEST_CHECKS:START -->
 ```jsonc
 {
   "workspaces": [
     {
-      "name": "my-workspace",
-      "about": "General compiled workspace for the quarterly results folder.",
-      "max_attempts": 3, // rerun compile + test until this workspace passes the saved truth checks or hits this limit
+      "name": "cbre-chart-sanity",
+      "about": "Bristol historical take-up and availability chart lookup.",
       "checks": [
         {
-          "question": "What full-year revenue range did the company maintain?",
-          "answer": "$4.8B to $5.0B in revenue."
+          "question": "What were Bristol's annual take-up values in 2018 and 2016?",
+          "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
         },
         {
-          "question": "Did gross margin improve or decline year over year?",
-          "answer": "Gross margin declined year over year."
+          "question": "What were Bristol's availability values in 2018 and 2016?",
+          "answer": "About 0.55 to 0.6 million sq ft in 2018 and about 1.2 to 1.3 million sq ft in 2016. These are approximate chart-derived reads."
         }
       ]
     }
   ]
 }
 ```
+<!-- PUBLIC_TEST_CHECKS:END -->
 
-The root-level flow is:
+## Example: `interf test`
 
-```bash
-interf
-interf compile
-interf test
-```
+`interf test` compares the raw files and the compiled workspace on the same saved truth checks.
+The table below is synced from a real public test run in this repo.
 
-The first guided run can:
+<!-- PUBLIC_TEST_TABLE:START -->
+| Runner | Files as-is | Compiled workspace |
+| --- | --- | --- |
+| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
+| Claude Code (Claude Opus 4.6 1M, max) | `0/2` | `2/2` |
+<!-- PUBLIC_TEST_TABLE:END -->
 
-- save a few truth checks for the dataset in this folder
-- run a baseline test on the raw files
-- compile the workspace
-- optionally keep compiling and retesting until it passes or reaches the attempt limit
-- run the same test against the compiled workspace
+That is the point of `interf test`: measure the same checks on both sides and keep the result honest, even when a compiled workspace helps one model more than another.
 
-That gives you three concrete things:
+Use `interf test` on your own dataset to measure files as-is versus the compiled workspace on the same checks.
 
-- `interf/workspaces/my-workspace/` with the compiled workspace for your dataset
-- `interf/benchmarks/runs/...` with the saved test result
-- a pass/fail score on the same truth checks you wrote
+Each run saves one comparison record under `.interf/tests/runs/`. Detailed target-specific runs and preserved sandboxes stay under `.interf/tests/targets/`.
 
-Saved test runs keep the details you need later:
+## Quick Start
 
-- whether the run tested `raw`, `workspace`, or both
-- per-question pass/fail results
-- the saved run path under `interf/benchmarks/runs/...`
-- the preserved sandbox path when a failed run is kept for review or you use `interf test --keep-sandboxes`
-- executor metadata such as agent, command, model, effort, and profile when available
+Requirements:
 
-If `interf.config.json` is missing, `interf` or `interf init` can draft it with you before the first compile. If Interf cannot find your local agent or compile setup, run:
+- Node.js 20+
+- a local coding agent such as Claude Code or Codex
+
+Install:
 
 ```bash
-interf doctor
+npm install -g @interf/compiler
 ```
 
-The first flow is:
+Start from the folder that already contains your dataset:
 
-- write down a few truth checks your agent should be able to pass on the dataset
-- let `interf` or `interf init` save those checks in `interf.config.json`
-- optionally run a baseline test on the raw files
-- run `interf compile` to build the compiled workspace
-- run `interf test` to test the raw files, the compiled workspace, or both
-- only create another workspace if you want a separate compiled setup with its own checks
-- if needed, rerun compile or use the advanced retry path until it is good enough
+```bash
+cd ~/my-dataset
+interf
+interf compile
+interf test
+```
 
-## Why This Approach
+The first run can:
 
-Interf is built around a few simple design principles:
+- save a few truth checks for the dataset
+- test your files as-is first on those same checks
+- build the compiled workspace
+- test the compiled workspace on the same truth checks
 
-- `Explicit`: the output is visible and inspectable, not hidden memory
-- `Local`: your dataset stays on your machine
-- `File over app`: the output is just files, so you can use your editor, Unix tools, Obsidian, or your own software on top
-- `BYOAI`: use Claude Code, Codex, OpenClaw, Hermes, or your own model
+## What Interf Compiler Creates
 
-Interf does not replace your data with an opaque store. It keeps the raw files in place and adds a file-based layer on top for agents.
+After setup, the main persistent object is the compiled workspace:
 
-Sample flow:
+- `interf/workspaces/<name>/` with the compiled workspace
+- `interf/workspaces/<name>/.interf/interf.json` with the workspace-local runtime contract
+- `interf/workspaces/<name>/.interf/tests/runs/...` with saved raw-vs-compiled test comparisons
 
-```bash
-cp -r examples/benchmark-demo /tmp/interf-demo
-cd /tmp/interf-demo
-interf
-interf compile
-interf test
-```
+The dataset root can also keep `interf.config.json` as bootstrap/setup for workspace names, truth checks, and compile defaults.
+
+A compiled workspace is a folder on top of your dataset. It includes:
 
-## Start With Your Own Truth Checks
+- a workspace-local `raw/` snapshot for direct evidence and verification
+- agent-readable summaries and cross-file notes
+- `AGENTS.md`, `CLAUDE.md`, and generated local query skills
+- workspace method, test, and runtime state under `.interf/`
 
-Start with your own truth checks: questions where you already know the correct answer from the dataset.
+The compiled workspace is the folder your agent should work from.
 
-`interf.config.json` is where you save those truth checks for a dataset folder.
+## How It Works
 
-That file uses one `workspaces` array:
+1. Save a few truth checks for the dataset.
+2. Optionally test your files as-is for a baseline.
+3. Build the compiled workspace.
+4. Test the compiled workspace on the same truth checks.
+5. Optionally let Interf retry or improve the workflow until it passes or hits the configured limit.
 
-- most folders only need one workspace
-- add another workspace only if you want a separate compiled setup with different truth checks
-- each workspace carries its own `checks`
-- each workspace can optionally carry `max_attempts` for the self-improving compile loop
+Truth checks are simple:
 
-If the file is missing, `interf init` can draft it with you before the first compile. You can edit it any time.
+- one question
+- one expected answer
 
 Good first truth checks are small and practical:
 
@@ -157,128 +136,29 @@ Good first truth checks are small and practical:
 - one short statement that should be true or false
 - one simple comparison across years, files, or sections
 
-Then run:
+If `interf.config.json` is missing, `interf` or `interf init` can draft it with you before the first compile. If the compiler cannot find your local agent or compile setup, run:
 
 ```bash
-interf compile
-interf test
+interf doctor
 ```
 
 ## What `interf test` Does
 
-`interf test` scores either the raw files, a compiled workspace, or both on the same saved truth checks.
-
-It lets you answer a simple question:
-
-- what is the current baseline on the raw files?
-- does this compiled workspace improve on that baseline?
-- which compiled workspace or workflow performs better on the same dataset?
-- does a separate workspace with different truth checks work better for that job?
-
-By default it loads truth checks from `interf.config.json`, can run a raw baseline in an isolated raw-files sandbox, can test eligible compiled workspaces under `interf/workspaces/`, and saves the run under `interf/benchmarks/runs/`.
+By default, if a compiled workspace exists, it runs both sides and saves one comparison under that workspace's `.interf/tests/runs/`.
 
 For live runs:
 
-- raw tests execute from a sanitized raw-only sandbox
+- raw tests execute from a sanitized raw-only shell built from `raw/`
 - compiled-workspace tests execute from a copied workspace sandbox with embedded sanitized `raw/`
-- neither sandbox includes `interf.config.json` or the source-folder `interf/` control plane
-- failed test sandboxes are kept automatically for review
+- both sides use the same saved truth checks from that workspace's `.interf/interf.json`
+- neither sandbox includes the dataset control plane
+- detailed raw/workspace target runs are kept under `.interf/tests/targets/runs/`
+- failed test sandboxes are kept automatically under `.interf/tests/targets/sandboxes/`
 - `interf test --keep-sandboxes` keeps every sandbox, even successful ones
 
-Each saved run includes:
-
-- the benchmark target and mode
-- per-question results and traces
-- the preserved sandbox path when one was kept
-- the executor metadata for that run
-
-If you run `interf test` from inside a workspace, it uses that workspace's truth checks and tests that workspace. If you run it from the source folder, it lets you choose a saved workspace and then choose raw files, the compiled workspace, or both.
-
-Live test runs use an isolated sandbox. For raw baselines, Interf gives the agent sanitized raw files only. For compiled-workspace tests, it gives the agent a copied workspace with its own embedded sanitized `raw/` fallback via `source.path`. The source-folder control plane, `interf.config.json`, and saved test runs are not part of those sandboxes.
-
-If you need repeated isolated experiments across workflows or models, use the advanced eval-pack runner in [docs/eval-loop.md](./docs/eval-loop.md).
-
-## What `interf compile` Does
-
-`interf compile` runs the selected workflow package over a dataset.
-
-By default, that means:
-
-- summarize the source files into per-file evidence notes
-- structure the cross-file knowledge layer into entities, claims, and indexes
-- shape the final workspace around its saved focus and truth checks
-
-In other words, the built-in workflow is:
-
-1. `summarize`
-2. `structure`
-3. `shape`
-
-The default workflow is built in. If you want a different method, you can define your own workflow package and test it on the same dataset.
-
-Each workflow package combines:
-
-- `workflow.json` for stage order, compiler API target, and deterministic contract mapping
-- `workspace.schema.json` for the deterministic output shape of the compiled workspace
-- stage `reads` / `writes` declarations that reference schema-defined zone ids
-- local `SKILL.md` files as the authoring source for query and stage-execution behavior
-
-Interf then projects that package into the native agent surfaces it actually runs:
-
-- the compiled workspace gets a generated native query shell
-- each compile stage gets a generated native execution shell
-- that shell keeps its own `AGENTS.md`, `CLAUDE.md`, and native local skills
-- schema-declared workspace zones are mounted both at their workflow-relative paths and as shell-local `inputs/<zone-id>` / `outputs/<zone-id>` aliases
-- the workspace root itself is not linked into the shell
-
-If a workspace has `max_attempts`, or if you run `interf compile --max-attempts <n>`, Interf can keep compiling, testing, and retrying until that workspace passes or reaches the attempt limit. If several attempts fail, Interf keeps the best-performing compiled workspace from that run.
-
-For stage-level review:
-
-- successful stage shells are pruned by default
-- failed stage shells stay under `.interf/execution-shells/`
-- `interf compile --keep-stage-shells` keeps every stage shell so you can inspect the exact native instruction surface, mounted inputs, and mounted outputs for each stage
-
-## What Gets Created
+From inside a workspace, `interf test` uses that workspace's `.interf/interf.json` directly. From the dataset root, `interf.config.json` only bootstraps workspace selection before the workspace-local runtime contract takes over.
 
-After compile, Interf writes into `./interf/` beside your source files.
-
-- `interf/workspaces/<name>/` is a compiled workspace over the folder
-- `interf/benchmarks/runs/...` stores saved test runs
-
-Inside those workspaces you will see things like:
-
-- a workspace-local `raw/` snapshot for direct evidence and verification
-- `workflow/workspace.schema.json` describing the deterministic output shape
-- `AGENTS.md`, `CLAUDE.md`, and generated local query skills for manual agent use
-- summaries of source files
-- navigation notes and entrypoints for agents
-- cross-file knowledge notes
-- workspace-specific outputs when you define a separate job-focused workspace
-
-The compiled workspace is just a normal folder. Open it in your editor, in your agent, or in Obsidian if you want the graph view.
-
-For manual use, the workspace is the native agent shell. The editable authoring source for that shell lives under `workflow/use/query/`, and Interf generates native local query skills from it inside the workspace.
-
-If you use Obsidian, open `interf/workspaces/<name>/` as the vault for the compiled workspace.
-
-## Terminology
-
-Public terms:
-
-- `dataset` = the collection of files Interf prepares
-- `truth check` = one question plus the expected correct answer
-- `checks` = the config field that stores those truth checks
-- `test` = run the saved truth checks and get a score
-- `compiled workspace` = the output Interf produces on top of a folder
-- `workspace` = one compiled setup with its own checks
-
-Technical terms:
-
-- `source folder` = the dataset root Interf reads from
-- `benchmark` = the technical alias and saved-run layer behind `interf test`
-- `workflow package` = the saved method that defines or customizes how compile runs
-- `.interf/` = runtime state, proofs, and health artifacts
+Maintainers can use the internal repeated-test matrix runner in [docs/test-matrix.md](./docs/test-matrix.md) for controlled workflow or model comparisons. Normal users should stay on `interf test`.
 
 ## Advanced: Separate Workspaces
 
@@ -297,57 +177,66 @@ Why create another one:
 - it gives that job its own compiled output under `interf/workspaces/<name>/`
 - it lets you test that job separately
 
-## Advanced: Keep Improving Until It Passes
+## Advanced: Compile Loops
+
+`max_attempts` is a retry budget for the same workflow variation.
+
+Retries keep the target fixed:
 
-Interf also supports a deeper loop above the normal compile + test flow.
+- same dataset
+- same workflow variation
+- same truth checks
+- same measurement
 
-The normal workspace flow already supports `max_attempts` inside `interf.config.json` or `interf compile --max-attempts <n>`.
+`max_loops` enables the self-improving workflow loop in the normal `interf compile` path.
 
-Give it the same dataset and the same truth checks. Interf can keep rerunning compile + test attempts until the test passes or the attempt budget runs out.
+In that loop, the thing that changes is the workflow itself.
 
-That loop is the self-improving part of the product:
+Each loop can:
 
-- it reruns the same workflow package over the same dataset
-- it keeps the truth checks fixed, so the target does not move
-- it keeps the measurement fixed, so attempts stay comparable
-- it can vary the compile profile and follow-up diagnostics
-- it records which attempt performed best on the same saved test
+- run the current workflow variation on the dataset
+- test it on the same truth checks
+- inspect the failed traces, preserved stage shells, and test artifacts
+- review the workflow and stage docs
+- create a new workflow variation for that dataset
+- test the new variation on the same truth checks
 
-In practice:
+- `max_attempts` retries the same workflow variation
+- a self-improving loop creates and tests workflow variations
 
-- `max_attempts` controls how many total attempts a normal workspace compile gets
-- `retry_policy.max_attempts_per_profile` controls how many attempts each compile profile gets in eval packs
-- stronger diagnostic profiles can be used only after the default ones fail
-- the truth checks stay the same across every attempt
-- each attempt records what changed and which attempt performed best
+The workflow is the right surface for that kind of improvement because it is:
 
-Example eval-pack shape:
+- the reusable artifact
+- the human-reviewable method
+- the thing a future workflow-editing agent should inspect and change
+
+Interf Compiler preserves the workflow-improvement shell, the workflow-before / workflow-after snapshots, the failed stage shells, and the saved test runs from each loop so you can inspect exactly what the loop reviewed and changed.
+
+Example workspace config:
 
 ```jsonc
 {
   "workspaces": [
     {
-      "name": "my-workspace",
-      "max_attempts": 3, // rerun compile + test until this workspace passes the saved truth checks or hits this limit
+      "name": "cbre-chart-sanity",
+      "max_attempts": 3, // retry compile + test for the same workflow until this workspace passes or hits this limit
+      "max_loops": 2, // workflow-editing loops after retries fail
       "checks": [
         {
-          "question": "What full-year revenue range did the company maintain?",
-          "answer": "$4.8B to $5.0B in revenue."
+          "question": "What were Bristol's annual take-up values in 2018 and 2016?",
+          "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
         }
       ]
     }
-  ],
-  "retry_policy": {
-    "max_attempts_per_profile": 3
-  }
+  ]
 }
 ```
 
-Use the normal workspace retry loop first. Use the eval-pack path when you want Interf to compare multiple compile profiles, add diagnostics, or keep iterating in a more controlled experiment loop. It spends more tokens, so use it when that extra spend is worth the accuracy target.
+Use the normal workspace retry and loop controls first. Maintainers can use the internal repeated-test runner when they want controlled comparisons across workflows, compile profiles, or models.
 
 ## Use It With Your Agent
 
-If you already work through Claude Code, Codex, OpenClaw, or Hermes, the agent can run this process for you.
+If you already work through a local coding agent, it can run this process for you.
 
 Paste something like this into your agent:
 
@@ -363,9 +252,15 @@ Tell me whether the compiled workspace passes the truth checks, and only recomme
 
 ## Custom Workflows
 
-Interf ships with a default workflow.
+Interf Compiler ships with a default workflow.
+
+The built-in `interf` workflow runs three stages:
+
+1. `summarize`
+2. `structure`
+3. `shape`
 
-If you want to change how the workflow package runs on your dataset, this is the part you customize:
+If you want to change how the workflow runs on your dataset, this is the part you customize:
 
 ```bash
 interf create workflow
@@ -374,27 +269,26 @@ interf verify workflow --path <path>
 
 Then test that workflow on the same dataset and the same truth checks.
 
-Workflow package docs live in [docs/workflow-spec.md](./docs/workflow-spec.md).
+Workflow docs live in [docs/workflow-spec.md](./docs/workflow-spec.md).
 
 ## Core Commands
 
 - `interf` = open the root-folder wizard
 - `interf init` = alias for the root-folder wizard
 - `interf create workspace` = create another compiled workspace when you need one
-- `interf create workflow` = create a reusable local workflow package
+- `interf create workflow` = create a reusable local seed workflow
 - `interf compile` = build a selected workspace for the current folder
-- `interf test` = test the raw files, a compiled workspace, or both on saved truth checks
-- `interf benchmark` = alias for `interf test`
+- `interf test` = compare the raw files and a compiled workspace on saved truth checks
 - `interf doctor` = check local executor setup
 - `interf verify <check>` = run deterministic checks on major workflow steps
 - `interf reset <scope>` = remove generated state while keeping source files
 
 ## More Docs
 
-- [docs/workflow-spec.md](./docs/workflow-spec.md) for custom workflow packages
+- [docs/workflow-spec.md](./docs/workflow-spec.md) for custom workflows
 - [docs/runtime-contract.md](./docs/runtime-contract.md) for the exact on-disk contract
 - [docs/architecture.md](./docs/architecture.md) for the deeper system model
-- [docs/eval-loop.md](./docs/eval-loop.md) for advanced eval-pack experiments across workflows and models
+- [docs/test-matrix.md](./docs/test-matrix.md) for the internal repeated-test matrix runner used in maintainer model/workflow comparisons
 
 Maintainers should use [CONTRIBUTING.md](./CONTRIBUTING.md) for test and release gates.
 

package/builtin-workflows/interf/README.md

@@ -0,0 +1,19 @@
+# Interf Compiler (Recommended)
+
+Interf Compiler's default methodology: summarize source-grounded evidence, structure the cross-file layer, then shape the final workspace around its focus and saved truth checks.
+
+## Package
+
+- `workflow.json` = stage graph, compiler API target, and compile contract mapping
+- `workspace.schema.json` = deterministic workspace output shape
+- `improve/`, `compile/stages/`, and `use/query/` = human-readable authoring docs
+- Portable workflow packages are standalone: explicit stages, schema, and docs live together in this folder
+- Interf Compiler projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops
+
+## Stages
+
+- `summarize` — Turn source files into per-file summaries. (workspace-file-evidence; reads: raw, runtime; writes: summaries)
+- `structure` — Build the cross-file knowledge structure from the summaries. (workspace-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
+- `shape` — Shape the final workspace around the saved focus and truth checks. (workspace-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+
+This package is the built-in seed for `interf`. Interf Compiler copies or materializes it into `.interf/workflow/` and runs that workspace-local package directly.

package/builtin-workflows/interf/compile/stages/shape/SKILL.md

@@ -0,0 +1,28 @@
+# Shape
+
+Shape the final workspace around the saved focus and truth checks.
+
+Contract type: `workspace-query-shape`
+
+## Requirements
+
+- Use the workspace focus plus saved truth-check question text to shape `home.md` and retrieval routes.
+- Rewrite `home.md` into a real entrypoint note. Do not leave the scaffold `Not yet compiled.` placeholder in place.
+- When a chart-derived value is approximate, use a bounded range instead of a pseudo-exact number.
+- Match the granularity of the visible axis labels or bands. Do not invent finer precision than the chart supports.
+- Keep the answer inside the visible tick band unless the chart supports a tighter bound.
+- Use an upper-half or lower-half band only when the mark clearly sits there.
+- If a mark touches or nearly touches a labeled gridline, anchor the answer at that gridline or the immediately adjacent half-band.
+- Do not widen a chart-derived range across multiple visible bands unless the chart genuinely supports that uncertainty.
+- When you settle on a bounded chart read, keep that same band consistent across `home.md`, focused indexes, and claim/entity notes for that metric and year.
+- Do not copy expected answers into the workspace.
+
+## Notes
+
+- Use the workspace focus and saved truth checks to bias the final workspace toward the job it should be especially good at.
+- Do not copy expected answers into the final workspace just because the checks imply them.
+- Prefer the saved summary evidence and structured notes when they already preserve the bounded chart/table reads plus provenance you need.
+- Reopen `raw/` during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.
+- If a saved truth check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from raw.
+- Prefer better routing, prioritization, and focused navigation over speculative synthesis.
+- Any wikilinks you add to `home.md` or indexes must resolve to real workspace note basenames or explicit relative paths.

package/builtin-workflows/interf/compile/stages/structure/SKILL.md

@@ -0,0 +1,18 @@
+# Structure
+
+Build the cross-file knowledge structure from the summaries.
+
+Contract type: `workspace-knowledge-structure`
+
+## Requirements
+
+- Treat the knowledge layer as retrieval structure, not final truth.
+- Prefer durable entity, claim, and index notes over one giant catch-all file.
+
+## Notes
+
+- Bias structure toward canonical entities, claims, timelines, and stable indexes.
+- Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.
+- For small datasets, prefer a minimal stable substrate over exhaustive graph sprawl.
+- When you add wikilinks, target real workspace notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.
+- For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`.

package/builtin-workflows/interf/compile/stages/summarize/SKILL.md

@@ -0,0 +1,18 @@
+# Summarize
+
+Turn source files into per-file summaries.
+
+Contract type: `workspace-file-evidence`
+
+## Requirements
+
+- Each summary must use JSON frontmatter and include `source`, `source_kind`, `evidence_tier`, `truth_mode`, `state`, and a non-empty `abstract`.
+- Include a clear abstract block in the body so a human can skim the summary quickly.
+- Do not skip the abstract just because the overview section is present.
+
+## Notes
+
+- Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.
+- For large reports or decks, capture scope, headline evidence, and chart/table routing in one light pass.
+- As soon as one report summary can state scope, headline metrics, and chart/table routing, stop reading and write the summary batch plus runtime artifacts immediately.
+- Keep scratch extraction commands single-purpose and non-destructive.

package/builtin-workflows/interf/improve/SKILL.md

@@ -0,0 +1,18 @@
+# Workflow Improvement
+
+Workflow: interf
+
+This file is the editable authoring source for Interf Compiler's generated native workflow-improver shell.
+The improver edits this workspace-local package directly.
+
+Default loop:
+1. Read the loop context first.
+2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.
+3. Edit only the local workflow package for this workspace to create a better workflow variation for this dataset.
+4. Keep `workflow.json`, `workspace.schema.json`, and any changed stage docs aligned.
+
+Guardrails:
+- do not edit truth checks, test specs, or raw dataset files
+- do not hardcode expected answers into workflow docs
+- keep this package standalone; do not add or rely on runtime `extends` or fallback behavior
+- prefer small, defensible workflow changes over random churn