@interf/compiler 0.5.0 → 0.6.1

package/README.md

@@ -1,71 +1,71 @@
-# Interf Compiler
+# Interf
 
-Prepare local datasets for accurate agent use.
+Interf helps make data ready for agent work.
 
-Interf Compiler runs a local data-processing workflow over your dataset to build a file-based layer on top of your raw files that gives agents the full picture they need to answer questions accurately.
+Measure how well your agent can answer the questions your task depends on. If raw files are not enough, Interf can prepare a compiled dataset and test it again on the same saved checks.
 
-Define truth checks for your dataset, measure a baseline on the raw files, then compile and retest the compiled dataset on the same checks.
+Start with checks. Give Interf the files behind a task and a few saved checks. It shows how well local agents do on the raw files first, so you can see what already works and which agent performs best.
 
-If it still fails, self-improving loops can revise the workflow, rebuild the compiled dataset, and rerun the same checks until it passes or reaches the loop limit.
+The compiled dataset is a real folder your agent can open and work from. If the first workflow still fails, Interf can retry the same workflow variation or edit the workflow across self-improving loops within the configured budgets and test each new variation on the same saved checks.
 
-## Why Use It
+Interf runs local workflows that prepare and structure the files for the task before your agent uses them.
 
-Interf Compiler is built around a few simple principles:
+A recent run in this repo on the CBRE chart sanity dataset produced:
 
-- `Explicit`: the compiled dataset is a real folder you can inspect, review, and version.
-- `Yours`: the dataset, workflow, compiled dataset, and test runs stay on your machine and in your control.
-- `File over app`: the compiled dataset is normal files and folders, not hidden app state.
-- `Source-backed`: your raw files stay the source of truth; the compiled dataset is a layer on top, not a replacement database.
-- `Bring your own agent`: the same compiled dataset 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 compiled dataset, and rerun the same checks.
+<!-- PUBLIC_BENCHMARK_TABLE:START -->
+| Agent | Files as-is | Compiled dataset |
+| --- | --- | --- |
+| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
+| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
+<!-- PUBLIC_BENCHMARK_TABLE:END -->
 
-## Example: Truth Checks
+Same task. Same saved checks. Same local setup.
 
-Truth checks are just question-and-answer pairs you already know how to verify from the dataset.
+## Why It Exists
 
-A maintained public test run in this repo uses checks like this:
+Local agents do well when the working surface is already shaped for the job. Raw task data usually is not. Reports, decks, transcripts, exports, PDFs, notes, and mixed folders are all technically available, but they are not prepared in a way that makes local agent work reliable.
 
-<!-- PUBLIC_TEST_CHECKS:START -->
-```jsonc
-{
-  "datasets": [
-    {
-      "name": "cbre-chart-sanity",
-      "path": ".",
-      "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 -->
+Interf keeps the loop honest:
 
-## Example: `interf test`
+- `Measure first`: test files as-is on saved truth checks before claiming improvement.
+- `One output`: keep one compiled dataset your agent can use directly.
+- `File-native`: the compiled dataset is a real folder you can inspect, diff, review, and version.
+- `Source-backed`: raw files remain the source of truth.
+- `Bring your own agent`: use Claude Code, Codex, or another local agent on the same compiled dataset.
+- `Self-improving`: when truth checks fail, Interf can inspect the failed run, edit the workflow, and retest new workflow variations on the same checks. Retries keep the same workflow variation; loops change the workflow itself.
 
-`interf test` compares files as-is and the compiled dataset on the same saved truth checks.
-That is the point of `interf test`: measure the same checks on both sides and keep the result honest on your own dataset, instead of relying on a frozen benchmark snapshot in the docs.
+## What You Get
 
-A recent maintained internal run on the CBRE chart sanity dataset produced:
+A project using one dataset stays simple:
 
-<!-- PUBLIC_BENCHMARK_TABLE:START -->
-| Agent | Files as-is | Compiled dataset |
-| --- | --- | --- |
-| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
-| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
-<!-- PUBLIC_BENCHMARK_TABLE:END -->
+```text
+your-task-folder/
+  report.pdf
+  notes.md
+  exports/
+  interf.json
+  interf/
+    <dataset>/
+    tests/
+      <dataset>/
+```
 
-Use `interf test` on your own dataset to measure files as-is versus the compiled dataset on the same checks.
+A compiled dataset looks like:
 
-Each dataset keeps one latest comparison under `interf/<dataset>/tests/latest.json`. Target-specific runs stay under `interf/<dataset>/tests/file-as-is/runs/` and `interf/<dataset>/tests/compiled/runs/`.
+```text
+interf/<dataset>/
+  AGENTS.md
+  CLAUDE.md
+  raw/
+  <workflow-declared compiled outputs>
+  .interf/
+    interf.json
+    workflow/
+    runtime/
+    tests/
+```
+
+The compiled dataset is the folder your agent should work from.
 
 ## Quick Start
 
@@ -80,10 +80,10 @@ Install:
 npm install -g @interf/compiler
 ```
 
-Start from a project folder that contains one or more dataset folders:
+Start from a folder that already contains the files for the task:
 
 ```bash
-cd ~/my-interf-project
+cd ~/my-task-folder
 interf
 interf test
 interf compile
@@ -93,41 +93,20 @@ interf test
 The first run can:
 
 - draft `interf.json`
-- auto-create a draft set of truth checks for a dataset folder, or let you add them manually
-- test your files as-is first on those same checks
+- help you create truth checks for the task, or let you add them manually
+- run a files-as-is baseline on those checks
 - build the compiled dataset
-- test the compiled dataset on the same truth checks
-
-## What Interf Compiler Creates
-
-After setup, the project root stays simple:
+- let you test the compiled dataset on the same checks
 
-- `interf.json` at the root holds your saved dataset entries and truth checks
-- `interf/` is created only when Interf has artifacts to save
-- `interf/<dataset>/compiled/` is the compiled dataset
-- `interf/<dataset>/tests/` is the saved comparison history for that dataset
+If Interf cannot find your local executor setup, run:
 
-A compiled dataset is a folder on top of your dataset. It includes:
-
-- a local `raw/` snapshot for direct evidence and verification
-- agent-readable summaries and cross-file notes
-- `AGENTS.md`, `CLAUDE.md`, and generated local query skills
-- workflow, test, and runtime state under `.interf/`
-
-The compiled dataset is the folder your agent should work from.
-
-## How It Works
-
-1. Save a few truth checks for a dataset in `interf.json`.
-2. Optionally test the files as-is for a baseline.
-3. Build the compiled dataset for that dataset.
-4. Test the compiled dataset on the same truth checks.
-5. Optionally let Interf retry or improve the workflow until it passes or hits the configured limit.
+```bash
+interf doctor --live
+```
 
-Truth checks are simple:
+## Truth Checks
 
-- one question
-- one expected answer
+Truth checks are just question-and-answer pairs you already know how to verify from the files behind the task.
 
 Good first truth checks are small and practical:
 
@@ -135,51 +114,75 @@ 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 `interf.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:
+A maintained public test run in this repo uses checks like this:
 
-```bash
-interf doctor
+<!-- PUBLIC_TEST_CHECKS:START -->
+```jsonc
+{
+  "datasets": [
+    {
+      "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 -->
+
+## What `interf test` Proves
+
+`interf test` compares files as-is and the compiled dataset on the same saved truth checks.
 
-## What `interf test` Does
+That comparison is the product record:
 
-By default, if a compiled dataset exists, it runs both sides and saves one latest comparison under `interf/<dataset>/tests/latest.json`.
+- same task
+- same saved checks
+- same local agent setup
+- raw files on one side
+- compiled dataset on the other
 
-You can also select one or more detected local agents in the CLI and compare them in one table.
+Use `interf test` on your own files instead of trusting a frozen benchmark snapshot in the docs.
 
-For live runs:
+Interf saves the latest comparison plus detailed raw and compiled runs under `interf/tests/` in the same folder.
 
-- files-as-is tests execute from a sanitized raw-only shell built from the selected dataset folder
-- compiled-dataset tests execute from a copied compiled sandbox with embedded sanitized `raw/`
-- both sides use the same saved truth checks from `interf.json`
-- neither sandbox includes the project control plane
-- detailed dataset-visible runs are kept under `interf/<dataset>/tests/file-as-is/runs/` and `interf/<dataset>/tests/compiled/runs/`
-- local detailed target runs and preserved sandboxes stay under `.interf/tests/targets/`
-- failed test sandboxes are kept automatically
-- `interf test --keep-sandboxes` keeps every sandbox, even successful ones
+## The Core Loop
 
-From inside a compiled dataset, `interf test` uses that dataset's `.interf/interf.json` directly. From the project root, `interf.json` bootstraps dataset selection and the same saved truth checks are mirrored into the compiled dataset runtime contract.
+1. Save a few truth checks for the task in `interf.json`.
+2. Optionally run `interf test` to measure files as-is first.
+3. Run `interf compile` to build the compiled dataset.
+4. Run `interf test` again on the same saved checks.
+5. If loops are enabled, let Interf retry the same workflow variation or edit the workflow and test the new variation.
 
-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`.
+The project root owns dataset setup and saved truth checks. The compiled dataset carries the local runtime copy needed for repeat runs.
 
-## Advanced: Multiple Datasets
+## Workflows
 
-Most projects only need one dataset entry.
+A workflow tells Interf how to prepare the files for this task.
 
-Add another only when you want a different dataset folder, focus, or set of truth checks, for example:
+Interf ships with a built-in `interf` workflow for the common case. If you need a different method, create one locally:
+
+```bash
+interf create workflow
+```
 
-- general folder understanding
-- finance reporting
-- board prep
-- diligence review
+Workflow creation supports two paths:
 
-Why add another:
+- draft a workflow from the current project with a local agent
+- copy an existing workflow and edit stage guidance directly
 
-- it keeps a separate set of truth checks
-- it gives that dataset its own compiled output under `interf/<dataset>/compiled/`
-- it lets you test that dataset separately
+After assignment, compile the dataset and run `interf test` on the same truth checks.
 
-## Advanced: Compile Loops
+## Compile Loops
 
 `max_attempts` is a retry budget for the same workflow variation.
 
@@ -190,7 +193,7 @@ Retries keep the target fixed:
 - same truth checks
 - same measurement
 
-`max_loops` enables the self-improving workflow loop in the normal `interf compile` path.
+`max_loops` enables self-improving workflow edits in the normal `interf compile` path.
 
 In that loop, the thing that changes is the workflow itself.
 
@@ -198,43 +201,11 @@ Each loop can:
 
 - 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
-
-- `max_attempts` retries the same workflow variation
-- a self-improving loop creates and tests workflow variations
-
-The workflow is the right surface for that kind of improvement because it is:
-
-- the reusable artifact
-- the human-reviewable method
-- the thing a future workflow-editing agent should inspect and change
+- inspect failed traces, preserved stage shells, and test artifacts
+- edit the workflow
+- build and test the next workflow variation
 
-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 `interf.json`:
-
-```jsonc
-{
-  "datasets": [
-    {
-      "name": "cbre-chart-sanity",
-      "max_attempts": 3, // retry compile + test for the same workflow until this dataset passes or hits this limit
-      "max_loops": 2, // workflow-editing loops after retries fail
-      "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."
-        }
-      ]
-    }
-  ]
-}
-```
-
-Use the normal retry and loop controls first. Maintainers can use the internal repeated-test runner when they want controlled comparisons across workflows, compile profiles, or models.
+Interf preserves workflow-improvement shells, workflow-before / workflow-after snapshots, failed stage shells, and saved test runs from each loop so you can inspect exactly what changed.
 
 ## Use It With Your Agent
 
@@ -243,54 +214,21 @@ If you already work through a local coding agent, it can run this process for yo
 Paste something like this into your agent:
 
 ```text
-Install @interf/compiler, run `interf` in this folder, and use the local agent executor.
+Install `@interf/compiler`, run `interf` in this folder, and use the local agent executor.
 
-If `interf.json` is missing, draft one dataset entry with a few truth checks this agent should be able to answer from the selected dataset and add the expected answers for me to confirm.
+If `interf.json` is missing, draft one dataset entry for this task with a few truth checks this agent should be able to answer from the selected files and add the expected answers for me to confirm.
 
 Then run a files-as-is baseline if helpful, compile the dataset, and run `interf test`.
 
 Tell me whether the compiled dataset passes the truth checks, and only recommend it if it does.
 ```
 
-## Custom Workflows
-
-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
-interf create workflow
-interf verify workflow --path <path>
-```
-
-Then test that workflow on the same dataset and the same truth checks.
-
-Workflow docs live in [docs/workflow-spec.md](./docs/workflow-spec.md).
-
-## Core Commands
-
-- `interf` = open the project-root wizard
-- `interf init` = alias for the project-root wizard
-- `interf create dataset` = add another dataset entry when you need one
-- `interf create workflow` = create a reusable local seed workflow
-- `interf compile` = build a selected compiled dataset for the current project
-- `interf test` = compare files as-is and a compiled dataset 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 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/test-matrix.md](./docs/test-matrix.md) for the internal repeated-test matrix runner used in maintainer model/workflow comparisons
+- [docs/architecture.md](./docs/architecture.md) for the short system map
+- [docs/interf-primitives.md](./docs/interf-primitives.md) for runtime and workflow concepts
+- [docs/workflow-spec.md](./docs/workflow-spec.md) for the workflow model
+- [docs/runtime-contract.md](./docs/runtime-contract.md) for the runtime execution ABI
 
 Maintainers should use [CONTRIBUTING.md](./CONTRIBUTING.md) for test and release gates.
 

package/builtin-workflows/interf/README.md

@@ -1,19 +1,31 @@
-# Interf Compiler (Recommended)
+# Interf (Built-in Workflow)
 
-Interf Compiler's default methodology: summarize source-grounded evidence, structure the cross-file layer, then shape the final compiled dataset around its focus and saved truth checks.
+Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final compiled dataset around its task focus and saved truth checks.
 
-## Package
+## Purpose
 
-- `workflow.json` = stage graph, compiler API target, and compile contract mapping
-- `compiled.schema.json` = deterministic compiled-dataset 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
+- General agent-ready dataset preparation
+- Prepare mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on.
+
+## Zones
+
+- `raw` — input directory at `raw`
+- `summaries` — working directory at `summaries`
+- `knowledge-entities` — output directory at `knowledge/entities`
+- `knowledge-claims` — output directory at `knowledge/claims`
+- `knowledge-indexes` — output directory at `knowledge/indexes`
+- `home` — output file at `home.md` used as the primary entrypoint for this workflow
+- `runtime` — runtime zone at `.interf/runtime`
 
 ## Stages
 
 - `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: raw, runtime; writes: summaries)
 - `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final compiled dataset around the saved focus and truth checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+- `shape` — Shape the final compiled dataset around the saved task focus and truth checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+
+## Why `home.md` exists here
+
+This built-in workflow creates `home.md` as the main agent entrypoint for the compiled dataset.
+That is behavior of the `interf` workflow, not a compiler-wide rule.
 
-This package is the built-in seed for `interf`. Interf Compiler copies or materializes it into `.interf/workflow/` and runs that local package directly.
+This package is the built-in seed for `interf`.

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

@@ -1,13 +1,16 @@
 # Shape
 
-Shape the final compiled dataset around the saved focus and truth checks.
+Shape the final compiled dataset around the saved task focus and truth checks.
 
 Contract type: `compiled-query-shape`
 
 ## Requirements
 
-- Use the compiled focus plus saved truth-check question text to shape `home.md` and retrieval routes.
+- Use the compiled task 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 you add wikilinks, target real compiled notes by exact basename or explicit relative path.
+- If you introduce a new note name in `home.md` or another shaped output, the same stage must also create that note file.
+- Prefer direct file-reading and search tools over shell commands for routine file inspection.
 - 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.
@@ -19,7 +22,7 @@ Contract type: `compiled-query-shape`
 
 ## Notes
 
-- Use the dataset focus and saved truth checks to bias the final compiled dataset toward the job it should be especially good at.
+- Use the saved task focus and truth checks to bias the final compiled dataset toward the job it should be especially good at.
 - Do not copy expected answers into the final compiled dataset 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.

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

@@ -8,6 +8,8 @@ Contract type: `compiled-knowledge-structure`
 
 - Treat the knowledge layer as retrieval structure, not final truth.
 - Prefer durable entity, claim, and index notes over one giant catch-all file.
+- Keep structure-stage links stage-local: prefer linking only to summaries or knowledge notes that are already meaningful by the end of this stage. Avoid relying on `home.md` or other shape-stage routes as the main navigation surface.
+- Prefer direct file-reading and search tools over shell commands for routine file inspection.
 
 ## Notes
 
@@ -15,4 +17,5 @@ Contract type: `compiled-knowledge-structure`
 - 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 compiled 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.
+- Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.
 - 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

@@ -6,8 +6,24 @@ Contract type: `compiled-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.
+- Each summary must start with literal JSON frontmatter between `---` lines, not a fenced code block.
+- Required opening shape:
+- `---`
+- `{`
+- `  "source": "raw/example.md",`
+- `  "source_kind": "markdown",`
+- `  "evidence_tier": "primary",`
+- `  "truth_mode": "source-grounded",`
+- `  "state": "complete"`
+- `}`
+- `---`
+- Do not wrap that JSON in triple backticks or emit ```json anywhere in the summary file.
+- Prefer direct file-reading and search tools over shell commands for routine file inspection.
+- Include a clear abstract either in frontmatter or under a markdown `## Abstract` heading so a human can skim the summary quickly.
+- Valid abstract forms for deterministic validation are:
+- frontmatter key `"abstract"` with a real sentence, or
+- a markdown heading `## Abstract` followed by at least one sentence
+- A bare `Abstract` label without markdown heading syntax does not count.
 - Do not skip the abstract just because the overview section is present.
 
 ## Notes

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

@@ -2,14 +2,14 @@
 
 Workflow: interf
 
-This file is the editable authoring source for Interf Compiler's generated native workflow-improver shell.
+This file is the editable authoring source for Interf's generated native workflow-improver shell.
 The improver edits this 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 compiled dataset to create a better workflow variation for this dataset.
-4. Keep `workflow.json`, `compiled.schema.json`, and any changed stage docs aligned.
+4. Keep `workflow.json`, `workflow.schema.json`, and any changed stage docs aligned.
 
 Guardrails:
 - do not edit truth checks, test specs, or raw dataset files

package/builtin-workflows/interf/workflow.json

@@ -5,8 +5,12 @@
     "kind": "compiled",
     "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 compiled dataset around its focus and saved truth checks.",
+  "purpose": {
+    "label": "General agent-ready dataset preparation",
+    "task_hint": "Prepare mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on."
+  },
+  "label": "Interf (Built-in)",
+  "hint": "Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final compiled dataset around its task focus and saved truth checks.",
   "stages": [
     {
       "id": "summarize",
@@ -31,6 +35,15 @@
         "markdown_frontmatter_valid_zones": [
           "summaries"
         ],
+        "frontmatter_required_keys_in_zones": {
+          "summaries": [
+            "source",
+            "source_kind",
+            "evidence_tier",
+            "truth_mode",
+            "state"
+          ]
+        },
         "markdown_abstract_valid_zones": [
           "summaries"
         ]
@@ -69,7 +82,7 @@
     {
       "id": "shape",
       "label": "Shape",
-      "description": "Shape the final compiled dataset around the saved focus and truth checks.",
+      "description": "Shape the final compiled dataset around the saved task focus and truth checks.",
       "contract_type": "compiled-query-shape",
       "skill_dir": "shape",
       "reads": [
@@ -118,10 +131,11 @@
       "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 compiled 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.",
+      "Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.",
       "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 dataset focus and saved truth checks to bias the final compiled dataset toward the job it should be especially good at.",
+      "Use the saved task focus and truth checks to bias the final compiled dataset toward the job it should be especially good at.",
       "Do not copy expected answers into the final compiled dataset 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.",