@interf/compiler 0.3.4 → 0.4.0

package/README.md

@@ -2,9 +2,72 @@
 
 Prepare local datasets for accurate agent use.
 
-Interf Compiler runs local data-processing workflows over your dataset to build a compiled workspace: a folder of agent-readable files that helps agents navigate evidence, verify facts, and answer accurately.
+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.
 
-Use truth checks to test the raw dataset, compile the workspace, and compare the result on the same task.
+Define truth checks to measure how accurately agents answer from your dataset.
+
+Start with a baseline on your files as-is.
+
+Then compile the workspace and retest it on the same checks so you can measure whether it actually helps.
+
+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.
+
+## Why Use It
+
+Interf Compiler is built around a few simple principles:
+
+- `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.
+
+## Example: Truth Checks
+
+Truth checks are just question-and-answer pairs you already know how to verify from the dataset.
+
+A maintained public test run in this repo uses checks like this:
+
+<!-- PUBLIC_TEST_CHECKS:START -->
+```jsonc
+{
+  "workspaces": [
+    {
+      "name": "cbre-chart-sanity",
+      "about": "Bristol historical take-up and availability chart lookup.",
+      "checks": [
+        {
+          "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": "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 -->
+
+## Example: `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.
+
+<!-- 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 -->
+
+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.
+
+Use `interf test` on your own dataset to measure files as-is versus the compiled workspace on the same checks.
+
+Each run saves one comparison record under `.interf/tests/runs/`. Detailed target-specific runs and preserved sandboxes stay under `.interf/tests/targets/`.
 
 ## Quick Start
 
@@ -31,45 +94,36 @@ interf test
 The first run can:
 
 - save a few truth checks for the dataset
-- test the raw dataset as a baseline
+- test your files as-is first on those same checks
 - build the compiled workspace
 - test the compiled workspace on the same truth checks
 
 ## What Interf Compiler Creates
 
-Interf Compiler adds three things beside your dataset:
+After setup, the main persistent object is the compiled workspace:
 
-- `interf.config.json` with your saved truth checks and workspace setup
 - `interf/workspaces/<name>/` with the compiled workspace
-- `interf/benchmarks/runs/...` with saved test runs
+- `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
+
+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:
 
 - 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
-- runtime state under `.interf/`
+- workspace method, test, and runtime state under `.interf/`
 
 The compiled workspace is the folder your agent should work from.
 
-## Why Use It
-
-Raw dataset folders are hard for agents.
-
-Common failure modes:
-
-- missed evidence
-- weak cross-file understanding
-- bad comparisons
-- answers that sound confident but are wrong
+## How It Works
 
-Interf Compiler keeps the raw dataset as the source of truth, builds a compiled workspace on top of it, and tests whether that workspace actually helps.
-
-## The Loop
-
-1. Define truth checks for the dataset.
-2. Build the compiled workspace.
-3. Test raw vs compiled on the same truth checks.
+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.
 
 Truth checks are simple:
 
@@ -82,115 +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
 
-If you want to see the config shape first, this is what Interf Compiler writes:
-
-```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
-      "checks": [
-        {
-          "question": "What full-year revenue range did the company maintain?",
-          "answer": "$4.8B to $5.0B in revenue."
-        },
-        {
-          "question": "Did gross margin improve or decline year over year?",
-          "answer": "Gross margin declined year over year."
-        }
-      ]
-    }
-  ]
-}
-```
-
 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 doctor
 ```
 
-Sample run:
-
-```bash
-cp -r examples/benchmark-demo /tmp/interf-demo
-cd /tmp/interf-demo
-interf
-interf compile
-interf test
-```
-
 ## What `interf test` Does
 
-`interf test` scores either the raw files, a compiled workspace, or both on the same saved truth checks.
-
-It answers a simple question:
-
-- does the compiled workspace help on this dataset or not?
-
-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:
-
-- whether the run tested `raw`, `workspace`, or both
-- 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.
-
-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 over a dataset.
-
-The built-in workflow:
+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.
 
-- 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`
-
-If you want a different method, you can define your own workflow and test it on the same dataset.
-
-Under the hood, each workflow defines:
-
-- `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
-
-The compiler then projects that workflow 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>`, the compiler can keep compiling, testing, and retrying until that workspace passes or reaches the attempt limit. If several attempts fail, it 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
+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
 
@@ -209,53 +177,62 @@ 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 Compiler 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. The compiler 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:
+Each loop can:
 
-- it reruns the same workflow 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 Compiler 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
 
@@ -277,6 +254,12 @@ Tell me whether the compiled workspace passes the truth checks, and only recomme
 
 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 runs on your dataset, this is the part you customize:
 
 ```bash
@@ -293,20 +276,19 @@ Workflow docs live in [docs/workflow-spec.md](./docs/workflow-spec.md).
 - `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

package/builtin-workflows/interf/use/query/SKILL.md

@@ -0,0 +1,28 @@
+# Manual Query Loop
+
+This file is the editable authoring source for the generated native local `interf-query` skill.
+
+Default loop:
+1. Read `home.md` first.
+2. Browse `knowledge/` before `raw/`.
+3. Use `summaries/` for source-grounded evidence.
+4. Use `raw/` for direct quotes, verification, exact table lookups, and chart-derived values.
+
+Answering rule:
+- do not modify files under `raw/`
+- when a number is chart-derived, say that explicitly
+- if the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first
+- use `raw/` to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a second incompatible range
+- when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
+- match the granularity of the visible axis labels or bands and do not invent finer precision than the chart supports
+- when reading charts, verify you are on the correct metric family and year before answering
+- keep historical annual charts separate from current-quarter snapshots, sector splits, or nearby lookalike panels
+- when a chart-derived value is approximate, use a bounded range instead of a pseudo-exact number.
+- 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.
+- if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused workspace note rather than synthesizing a new midpoint or shifted band
+- when the compiled layer is insufficient, verify in `raw/` and then answer
+
+You can edit this file to bias manual question-answering behavior for this workspace.

package/builtin-workflows/interf/workflow.json

@@ -0,0 +1,120 @@
+{
+  "id": "interf",
+  "type": "workspace",
+  "compiler_api": {
+    "kind": "workspace",
+    "version": 1
+  },
+  "label": "Interf Compiler (Recommended)",
+  "hint": "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.",
+  "stages": [
+    {
+      "id": "summarize",
+      "label": "Summarize",
+      "description": "Turn source files into per-file summaries.",
+      "contract_type": "workspace-file-evidence",
+      "skill_dir": "summarize",
+      "reads": [
+        "raw",
+        "runtime"
+      ],
+      "writes": [
+        "summaries"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          ".interf/runtime/inventory.json"
+        ],
+        "state_truthy": [
+          "last_summarize",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "summarized": "expected_summary_total"
+        }
+      }
+    },
+    {
+      "id": "structure",
+      "label": "Structure",
+      "description": "Build the cross-file knowledge structure from the summaries.",
+      "contract_type": "workspace-knowledge-structure",
+      "skill_dir": "structure",
+      "reads": [
+        "summaries",
+        "runtime"
+      ],
+      "writes": [
+        "knowledge-entities",
+        "knowledge-claims",
+        "knowledge-indexes"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          "knowledge/indexes"
+        ],
+        "state_truthy": [
+          "last_structure",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "structured": "summary_total"
+        }
+      }
+    },
+    {
+      "id": "shape",
+      "label": "Shape",
+      "description": "Shape the final workspace around the saved focus and truth checks.",
+      "contract_type": "workspace-query-shape",
+      "skill_dir": "shape",
+      "reads": [
+        "raw",
+        "summaries",
+        "knowledge-entities",
+        "knowledge-claims",
+        "knowledge-indexes",
+        "runtime"
+      ],
+      "writes": [
+        "knowledge-indexes",
+        "home"
+      ],
+      "acceptance": {
+        "artifacts_exist": [
+          "home.md"
+        ],
+        "state_truthy": [
+          "last_shape",
+          "inventory_complete"
+        ],
+        "state_at_least_counts": {
+          "shaped": "summary_total",
+          "compiled": "summary_total"
+        }
+      }
+    }
+  ],
+  "stage_policy_notes": {
+    "summarize": [
+      "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."
+    ],
+    "structure": [
+      "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/`."
+    ],
+    "shape": [
+      "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.",
+      "If a saved truth check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
+      "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."
+    ]
+  }
+}