@interf/compiler 0.22.2 → 0.50.0

package/public-repo/build-plans/interf-default/build/stages/knowledge/SKILL.md

@@ -0,0 +1,95 @@
+# Knowledge
+
+Build the task-aware Context Graph knowledge layer from the summaries.
+
+Contract type: `build-knowledge`
+
+## Requirements
+
+- Treat the Context Graph knowledge layer as retrieval support, not final truth.
+- Read `runtime/project.json` and `runtime/stage-contract.json.project.intent`
+  before choosing the knowledge notes. The knowledge layer must be task-aware:
+  extract claims, entities, timelines, comparisons, risks, or indexes that help
+  the saved Project intent, not just a generic source outline.
+- Read `runtime/expected-inputs.json` before writing notes and write
+  `runtime/reviewed-inputs.json` with one decision for every required expected
+  summary before DONE.
+- `runtime/reviewed-inputs.json` must use this shape:
+- `{`
+- `  "kind": "interf-stage-reviewed-inputs",`
+- `  "version": 1,`
+- `  "generated_at": "2026-01-01T00:00:00.000Z",`
+- `  "stage_id": "knowledge",`
+- `  "reviewed": [`
+- `    { "resource_id": "summary-example", "decision": "used", "source_refs": ["summaries/example/summary.md"] }`
+- `  ]`
+- `}`
+- Prefer durable entity, claim, and index notes over one giant catch-all file.
+- Write those notes as flat markdown files under `knowledge/` unless this
+  Build Plan explicitly declares typed child folders.
+- The Context Graph has three FIXED top-level layers plus `home.md`, each with a
+  purpose serving humans AND agents:
+  - `summaries/` — grounding/coverage: one folder per Source file, each linking
+    back to its Source. Human-first: navigate and understand "what's in my data".
+  - `knowledge/` — the knowledge web: claims, entities, timelines, tables, etc.
+    Agent-first: traverse and query. Every note links DOWN to its summary, carries
+    raw `source_refs`, and links to OTHER knowledge notes.
+  - `artifacts/` — higher-level task outputs/handoffs that reference summaries and
+    knowledge (plus raw source refs for exact claims). Human deliverable and agent
+    entrypoint.
+  - `home.md` — start here; routes into all three.
+- The interior of `knowledge/` is free: a typed interior such as
+  `knowledge/entities/`, `knowledge/claims/`, `knowledge/timelines/`,
+  `knowledge/tables/`, or `knowledge/atlas/` is encouraged when the task needs
+  richer structure. But core derived content must stay UNDER these canonical
+  layers — never invent a new top-level folder (for example `graph/` or
+  `insights/`) for core content. If you need richer structure, nest it under
+  `knowledge/<interior>/`; the layer recognition routes `knowledge/<anything>/`
+  to the knowledge layer.
+- Keep claims connected to the summaries and original source references that
+  support them, so users can follow links back to sources.
+- Every knowledge note MUST wikilink the summary of every source it cites.
+  For each source a note records in its `source_refs`, add a
+  `[[summaries/<source-name>/summary]]` wikilink (or
+  `[[summaries/<source-name>/manifest]]` for paginated/visual sources) in that
+  note's body. Source refs alone are not enough: a note that cites a source
+  without linking its summary leaves that summary an orphaned island and fails
+  the stage. This is not optional — there is no plain-source-ref opt-out for the
+  summary layer.
+- Build the knowledge layer as a connected WEB, not isolated islands. In
+  addition to the mandatory `[[summaries/...]]` down-link, every knowledge note
+  should link at least one OTHER knowledge note (entity to claim, claim to
+  related claim, note to index) using its filename stem under `knowledge/`. A
+  note that links no other knowledge note is a disconnected island and fails the
+  `knowledge_web_connectivity` check. This enforces CONNECTEDNESS, not a count: a
+  single genuine link is enough, and a genuinely lone note on a sparse Source is
+  fine. Never invent links to pass — fabricated links are worse than honest
+  sparsity.
+- Every claim or entity note MUST also record raw `source_refs` in JSON
+  frontmatter — the original Source paths it asserts from — so a reader can drop
+  to ground truth and verify instead of trusting a paraphrased summary. Keep
+  both pointers: the `[[summary]]` wikilink is for navigation, the `source_refs`
+  are for verification, and every source in `source_refs` must also have its
+  summary wikilinked (above).
+- A pure index or navigation note that asserts nothing of its own (for example a
+  `knowledge/index.md` route map, or the no-intent `knowledge/task-focus.md`
+  fallback) may set `"note_role": "index"` in its JSON frontmatter to opt out of
+  the `source_refs` requirement. Do not use this to dodge provenance on a note
+  that makes a claim — fabricated source refs are worse than none.
+- Use knowledge notes as navigation and assurance. They are not the authority
+  for exact wording, table values, chart reads, or provenance-sensitive claims.
+- Keep knowledge-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 entrypoint-stage routes as the main navigation surface.
+- Prefer direct file-reading and search tools over shell commands for routine file inspection.
+
+## Notes
+
+- Bias knowledge notes toward canonical entities, claims, timelines, and stable indexes.
+- Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.
+- For small Sources, prefer a minimal stable substrate over exhaustive flow sprawl.
+- When you add wikilinks, target real Context Graph 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 knowledge outputs to files that the entrypoint stage creates later. If a route belongs in `home.md` or a later entrypoint note, leave plain text now and let the later stage add the link.
+- Build task-aware claims, entities, topics, timelines, comparisons, and indexes from the summaries and their source refs. Use clear filenames such as `knowledge/rent-growth-claims.md`, `knowledge/market-entities.md`, or `knowledge/index.md`.
+- If the Project intent is missing, write a small `knowledge/task-focus.md`
+  note that says the graph has no saved Project intent yet and bias the rest of
+  the knowledge layer toward coverage and source routing.
+- For summary references, you MUST link the summary itself: `[[summaries/<source-name>/summary]]` or, for paginated/visual sources, `[[summaries/<source-name>/manifest]]` (page note links are an optional addition). Do not cite a summary's source with plain source refs only — link the summary note. For links to other knowledge notes, use the final filename stem under `knowledge/` — and use these to satisfy the web requirement above: every knowledge note should reach at least one other knowledge note so the layer is a connected web, not a star of islands flagged by `knowledge_web_connectivity`.

package/public-repo/build-plans/interf-default/build/stages/summarize/SKILL.md

@@ -1,6 +1,6 @@
 # Summarize
 
-Turn source files into per-file summaries.
+Turn source files into source-named coverage folders with source metadata.
 
 Contract type: `build-file-evidence`
 
@@ -10,7 +10,10 @@ Contract type: `build-file-evidence`
 - Required opening shape:
 - `---`
 - `{`
+- `  "source_file_id": "file-example",`
 - `  "source": "example.md",`
+- `  "source_path": "example.md",`
+- `  "source_locator": "agent-readable/source/ref",`
 - `  "source_kind": "markdown",`
 - `  "evidence_tier": "primary",`
 - `  "truth_mode": "source-grounded",`
@@ -25,11 +28,53 @@ Contract type: `build-file-evidence`
 - 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.
+- Build `summaries/` as a coverage layer:
+  - one folder per source file, named exactly from `runtime/expected-inputs.json` metadata `source_path`
+  - keep the original file extension in the folder name; do not strip `.md`, `.txt`, `.pdf`, or similar suffixes
+  - non-paginated sources: `summaries/<source_path>/summary.md`, for example `summaries/01-source-note.md/summary.md`
+  - PDFs, decks, images, or paginated/visual reports: `summaries/<source_path>/manifest.md` plus `pages/001/summary.md`, `pages/002/summary.md`, etc. for every page/slide that can be inspected
+  - if a page/slide cannot be extracted, record `not_extracted_reason` in the manifest instead of silently skipping it
+  - optional `screenshot.png` or visual trace paths only when useful and available
+- Preserve links back to sources through the `source_file_id`, `source`, `source_path`, `source_locator`, page,
+  section, table, chart, figure, or region references the source provides.
+- Connect every summary INTO the graph web — a summary that no note links and that
+  links no note is a free-floating island and fails the whole-graph
+  `graph_notes_connected` gate. Source refs point DOWN to the original file; they
+  are NOT graph-note links and do not connect a summary to the web. So in each
+  summary's body add at least one `[[wikilink]]` to a sibling note in the graph:
+  a `summaries/<index>` / section index you maintain for the group, a related
+  summary, or `[[home]]`. If this stage writes a per-group or per-folder index
+  note under `summaries/`, link each summary to its index and link the index back
+  from `home.md` (the entrypoint stage may also route `home.md` into the coverage
+  layer). The point is reachability: every summary must be reachable through the
+  link web, not only through a source_ref.
+- Do not copy source files into the Context Graph. Store source references.
+- Treat this stage as common grounding. Capture what each Source contains and
+  how to get back to it; leave task-specific synthesis to `knowledge` and
+  `entrypoint` unless a source detail is needed to preserve coverage.
+- Read `runtime/expected-inputs.json` and write `runtime/reviewed-inputs.json`
+  with one decision for every required expected input before DONE.
+- Mark an expected source unit `used` or `reviewed` when you summarized it.
+  Mark it `missing`, `blocked`, or `not-relevant` only with a concrete reason.
+- `runtime/reviewed-inputs.json` must use this shape:
+- `{`
+- `  "kind": "interf-stage-reviewed-inputs",`
+- `  "version": 1,`
+- `  "generated_at": "2026-01-01T00:00:00.000Z",`
+- `  "stage_id": "summarize",`
+- `  "reviewed": [`
+- `    { "resource_id": "source-unit-example", "decision": "used", "source_refs": ["example.md"] }`
+- `  ]`
+- `}`
 
 ## Notes
 
 - Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.
-- Read `runtime/stage-inputs.json` for the exact source references assigned to this stage.
-- 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.
+- Read `runtime/source-manifest.json` for the authoritative Source inventory, `runtime/stage-inputs.json` for the exact source references assigned to this stage, and `runtime/expected-inputs.json` for coverage decisions.
+- Read `runtime/project.json` and `runtime/stage-contract.json` so you know the Project intent, but keep summaries broadly reusable source coverage rather than final task answers.
+- For large reports or decks, capture page coverage, scope, headline evidence, and chart/table routing in one light pass. Prefer explicit page records over one loose file summary.
+- One summary folder per Source file; this is the file-level COVERAGE proof — it
+  proves every file was read, not that every fact was captured. Summaries do not
+  need to answer the final task, and missing coverage is detectable at the file
+  level only, never claimed at the fact level.
 - Keep scratch extraction commands single-purpose and non-destructive.

package/public-repo/build-plans/interf-default/build-plan.json

@@ -1,13 +1,13 @@
 {
   "id": "interf-default",
   "type": "build-plan",
-  "engine_api": {
+  "runtime_api": {
     "kind": "build",
     "version": 1
   },
   "purpose": {
-    "label": "Built-in Build Plan for verifiable context",
-    "task_hint": "Build mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this agent work depends on."
+    "label": "Build Context Graph",
+    "task_hint": "Reads your files and builds a task-specific Context Graph — summaries, key facts, and entities, each linked back to the original Source file so your agent works from prepared context it can open and check."
   },
   "inputs": [
     {
@@ -18,13 +18,14 @@
     }
   ],
   "label": "Built-in Interf Build Plan",
-  "hint": "Built-in file-processing Build Plan: build traceable artifacts with proof by summarizing source-grounded evidence, structuring cross-file connections, and shaping verifiable context around the saved readiness checks.",
+  "hint": "Reads your files and builds a Context Graph of summaries, key facts, and entities — each linked back to the original file your agent can open.",
   "stages": [
     {
       "id": "summarize",
       "label": "Summarize",
-      "description": "Turn source files into per-file summaries.",
+      "description": "Turn source files into exact source-path coverage folders under summaries/, with summary.md or manifest.md plus page/slide notes for every inspectable paginated or visual source page.",
       "contract_type": "build-file-evidence",
+      "role": "summarizer",
       "skill_dir": "summarize",
       "reads": [],
       "writes": [
@@ -32,59 +33,68 @@
       ]
     },
     {
-      "id": "structure",
-      "label": "Structure",
-      "description": "Build the cross-file knowledge structure from the summaries.",
-      "contract_type": "build-knowledge-structure",
-      "skill_dir": "structure",
+      "id": "knowledge",
+      "label": "Knowledge",
+      "description": "Build the task-aware knowledge graph from summaries as flat knowledge/*.md notes, including claims, entities, topics, indexes, and links back to source refs.",
+      "contract_type": "build-knowledge",
+      "role": "structurer",
+      "skill_dir": "knowledge",
       "reads": [
         "summaries"
       ],
       "writes": [
-        "knowledge-entities",
-        "knowledge-claims",
-        "knowledge-indexes"
+        "knowledge"
       ]
     },
     {
-      "id": "shape",
-      "label": "Shape",
-      "description": "Shape the final verifiable context around the saved task focus and readiness checks.",
-      "contract_type": "build-query-shape",
-      "skill_dir": "shape",
+      "id": "entrypoint",
+      "label": "Entrypoint",
+      "description": "Assemble home.md as the primary agent entrypoint plus task-specific entrypoint notes around the saved Project intent and coverage.",
+      "contract_type": "build-entrypoint",
+      "role": "structurer",
+      "skill_dir": "entrypoint",
       "reads": [
         "summaries",
-        "knowledge-entities",
-        "knowledge-claims",
-        "knowledge-indexes"
+        "knowledge"
       ],
       "writes": [
-        "knowledge-indexes",
-        "atlas"
+        "knowledge",
+        "artifacts",
+        "home"
       ]
     }
   ],
   "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.",
+      "Favor conservative, source-grounded summaries that prove coverage and preserve evidence tiers; leave broader synthesis for later stages.",
+      "Create one folder under `summaries/` per source file, named exactly from `runtime/expected-inputs.json` metadata `source_path`, including the original file extension.",
+      "For non-paginated sources, write `summaries/<source_path>/summary.md`, for example `summaries/01-source-note.md/summary.md`.",
+      "For PDFs, decks, images, or paginated/visual reports, write `summaries/<source_path>/manifest.md` and page or slide folders such as `pages/001/summary.md` for every page/slide that can be inspected. If a page/slide cannot be extracted, record `not_extracted_reason` in the manifest instead of silently skipping it. Include optional screenshots or visual trace paths only when useful and available.",
+      "Every summary or page note must link back to the original Source path and the relevant page, section, figure, table, or region. Do not copy source files into the Context Graph.",
       "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 Source Folders, prefer a minimal stable substrate over exhaustive graph sprawl.",
-      "When you add wikilinks, target real verifiable-context 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/`."
+    "knowledge": [
+      "Read Project intent and the expected summaries before choosing the knowledge notes.",
+      "Build task-aware claims, entities, topics, and indexes from the summaries and their source refs as flat markdown notes under `knowledge/`.",
+      "Use taxonomy and ontology only when it improves retrieval, navigation, and evidence tracking.",
+      "Treat knowledge notes as navigation and assurance, not as the authority for exact wording, table values, chart reads, or provenance-sensitive claims.",
+      "For small Sources, prefer a minimal stable graph over exhaustive note sprawl.",
+      "When you add wikilinks, target real Context Graph 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 knowledge outputs to files that the entrypoint stage creates later. If a route belongs in `home.md` or a later entrypoint note, leave plain text now and let the later stage add the link.",
+      "Every knowledge note MUST wikilink the summary of every source it cites: for each source in a note's `source_refs`, add `[[summaries/<source-name>/summary]]` (or `[[summaries/<source-name>/manifest]]` for paginated/visual sources). Source refs alone are not enough and leave the summary an orphaned island; there is no plain-source-ref opt-out. For links to other knowledge notes, use final filenames under `knowledge/`.",
+      "The knowledge layer must be an interlinked web, not isolated islands: in addition to the mandatory summary down-link, every knowledge note should link at least one OTHER knowledge note. A note that links no other knowledge note is a disconnected island and fails the `knowledge_web_connectivity` check. This enforces connectedness, not a count — a single genuine link is enough — and never fabricate links to pass.",
+      "Every claim or entity note MUST also record raw `source_refs` in JSON frontmatter — the original Source paths it asserts from — so a reader can verify against ground truth instead of trusting a paraphrased summary. Keep both: the summary wikilink is for navigation, the `source_refs` are for verification. A pure index or navigation note that asserts nothing of its own may set `\"note_role\": \"index\"` in frontmatter to opt out of `source_refs`."
     ],
-    "shape": [
-      "Use the saved task focus and readiness checks to bias the final verifiable context toward the job it should be especially good at.",
-      "Do not copy expected answers into the final verifiable context just because the checks imply them.",
-      "If a saved readiness check depends on source-derived values that may be approximate, preserve the stated range, limits, and provenance.",
-      "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
-      "Any wikilinks you add to `home.md` or indexes must resolve to real verifiable-context note basenames or explicit relative paths."
+    "entrypoint": [
+      "Use the saved Project intent and coverage metrics to bias the final Context Graph toward the agent task it should be especially good at.",
+      "Do not copy benchmark expected answers into the final Context Graph.",
+      "Rewrite `home.md` as the primary downstream agent entrypoint. It should tell the agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter.",
+      "Write one or more notes under `artifacts/` when a task-specific handoff helps the agent continue from prepared context.",
+      "Entrypoints should route the agent to original Source refs for exact claims. Do not present generated summaries or knowledge notes as the dataset or source of truth.",
+      "If a prepared value depends on source-derived values that may be approximate, preserve the stated range, limits, evidence tier, and source inspection requirement.",
+      "For unlabeled charts or visual marks, either create a measurement note with visual reference, calibration, method, and uncertainty, or tell the downstream agent to inspect the original Source before answering.",
+      "Prefer better routing, prioritization, and focused navigation over speculative synthesis or answer-only notes.",
+      "Any wikilinks you add to `home.md` or indexes must resolve to real Context Graph note basenames or explicit relative paths."
     ]
   }
 }

package/public-repo/build-plans/interf-default/build-plan.schema.json

@@ -1,75 +1,101 @@
 {
   "kind": "build-plan-schema",
   "version": 1,
-  "target_type": "verifiable-context",
+  "target_type": "context-graph",
   "label": "Interf built-in Build Plan schema",
   "artifacts": [
     {
-      "id": "atlas",
-      "description": "Primary entrypoint note that agents read first. Routes to summaries, knowledge entities, claims, and indexes.",
+      "id": "home",
+      "description": "Primary Context Graph agent entrypoint. Routes to the summaries coverage layer, knowledge graph layer, and task-specific entrypoint notes; downstream agents should start from home.md for task work.",
       "shape": { "kind": "path", "path": "home.md", "artifact_kind": "file" },
       "checks": [
-        { "id": "exists", "kind": "file_exists", "required": true },
+        { "id": "exists", "kind": "file_exists", "description": "The graph index note exists.", "required": true },
         {
           "id": "no-placeholder",
           "kind": "must_not_contain",
+          "description": "The graph index note does not contain placeholder text.",
           "required": true,
           "params": { "phrases": ["Not yet built."] }
         },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every graph index wikilink resolves.", "required": true },
+        { "id": "graph-connected", "kind": "graph_notes_connected", "description": "Every Context Graph note — across summaries/, knowledge/, artifacts/, and home.md — is link-connected to at least one other note. No summary or note is left a free-floating island unreachable through the link web. Connectedness, not a quota.", "required": true }
       ],
-      "built_by_stages": ["shape"]
+      "built_by_stages": ["entrypoint"]
     },
     {
       "id": "summaries",
-      "description": "Per-file evidence notes that preserve the source-grounded synthesis agents quote against.",
+      "description": "Coverage layer with one exact source-path folder per source file. Non-paginated sources have summary.md. PDFs, decks, and visual/paginated sources include manifest.md plus page/slide folders for every inspected page/slide; uninspected pages/slides must be called out with not_extracted_reason. Every note links back to the original Source path and page/section/figure/table refs instead of copying source files.",
       "shape": { "kind": "path", "path": "summaries", "artifact_kind": "directory" },
       "checks": [
         {
-          "id": "all-files-summarized",
-          "kind": "min_file_count_matches_source",
+          "id": "source-summary-folders",
+          "kind": "source_summary_folders",
+          "description": "Every source file has an exact source-path folder with summary.md or manifest.md.",
           "required": true,
           "params": { "match": "source_total" }
         },
-        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "required": true },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "description": "Every summary note has valid frontmatter.", "required": true },
         {
           "id": "evidence-keys",
           "kind": "frontmatter_required_keys",
+          "description": "Every summary note records source and evidence metadata.",
           "required": true,
-          "params": { "keys": ["source", "source_kind", "evidence_tier", "truth_mode", "state"] }
+          "params": { "keys": ["source", "source_file_id", "source_path", "source_locator", "source_kind", "evidence_tier", "state"] }
         }
       ],
       "built_by_stages": ["summarize"]
     },
     {
-      "id": "knowledge-entities",
-      "description": "Canonical entity notes that anchor the cross-file knowledge structure.",
-      "shape": { "kind": "path", "path": "knowledge/entities", "artifact_kind": "directory" },
+      "id": "knowledge",
+      "description": "Task-aware Context Graph layer built from summaries and source refs. Current default is flat knowledge/*.md notes. Notes may contain claims, entities, topics, and indexes, but remain navigation and assurance rather than the authority for exact source claims.",
+      "shape": { "kind": "path", "path": "knowledge", "artifact_kind": "directory" },
       "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "exists", "kind": "min_file_count", "description": "Knowledge layer contains notes for task-aware navigation.", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every knowledge wikilink resolves.", "required": true },
+        { "id": "summary-backlinks", "kind": "summary_backlinks_present", "description": "Every summary a knowledge note cites via source_refs is also wikilinked from the knowledge layer — no orphaned summaries.", "required": true },
+        { "id": "knowledge-web", "kind": "knowledge_web_connectivity", "description": "Every knowledge note links at least one OTHER knowledge note — the knowledge layer forms a connected web, not isolated islands. Connectedness, not a quota; a single genuine link is enough.", "required": true },
+        { "id": "claim-source-refs", "kind": "source_refs_required", "description": "Every claim/entity note cites the raw Source it asserts from (verification), so a reader can drop to ground truth instead of trusting a paraphrased summary. Pure index/navigation notes that assert nothing may opt out with note_role: index.", "required": true, "params": { "keys": ["source_refs"], "exempt_when": { "note_role": ["index", "navigation"] } } }
       ],
-      "built_by_stages": ["structure"]
+      "built_by_stages": ["knowledge", "entrypoint"]
     },
     {
-      "id": "knowledge-claims",
-      "description": "Claim notes extracted from summaries with evidence references.",
-      "shape": { "kind": "path", "path": "knowledge/claims", "artifact_kind": "directory" },
+      "id": "artifacts",
+      "description": "Task-specific entrypoint notes for downstream agents. These notes supplement home.md and point to original Source files, pages, figures, tables, sections, units, periods, and caveats; they may link to summaries or knowledge notes for drilldown, but source files remain the authority for exact claims.",
+      "shape": { "kind": "path", "path": "artifacts", "artifact_kind": "directory" },
       "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
-      ],
-      "built_by_stages": ["structure"]
-    },
-    {
-      "id": "knowledge-indexes",
-      "description": "Retrieval indexes and navigation notes for the knowledge structure.",
-      "shape": { "kind": "path", "path": "knowledge/indexes", "artifact_kind": "directory" },
-      "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "exists", "kind": "min_file_count", "description": "At least one task-specific entrypoint note exists.", "required": true, "params": { "min": 1 } },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "description": "Every task entrypoint note has valid frontmatter.", "required": true },
+        {
+          "id": "handoff-frontmatter",
+          "kind": "frontmatter_required_keys",
+          "description": "Every task entrypoint note records task, source refs, handoff type, and caveats.",
+          "required": true,
+          "params": { "keys": ["task", "source_refs", "handoff_type", "caveats"] }
+        },
+        {
+          "id": "handoff-source-refs",
+          "kind": "source_refs_required",
+          "description": "Every task entrypoint note has non-empty source refs.",
+          "required": true,
+          "params": { "keys": ["source_refs"] }
+        },
+        {
+          "id": "handoff-nonempty-fields",
+          "kind": "frontmatter_nonempty_keys",
+          "description": "Every task entrypoint note has non-empty task, source refs, and caveats.",
+          "required": true,
+          "params": { "keys": ["task", "source_refs", "caveats"] }
+        },
+        {
+          "id": "source-authority-caveat",
+          "kind": "must_contain",
+          "description": "Task entrypoint notes tell agents to follow original Source refs for exact claims.",
+          "required": true,
+          "params": { "phrases": ["original Source", "source refs"] }
+        },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every task entrypoint note wikilink resolves.", "required": true }
       ],
-      "built_by_stages": ["structure", "shape"]
+      "built_by_stages": ["entrypoint"]
     }
   ]
 }

package/public-repo/build-plans/interf-default/improve/SKILL.md

@@ -7,12 +7,12 @@ The improver edits this local Build Plan 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 Build Plan for this verifiable context to create a better implementation for this agent work.
+2. Review preserved stage shells, runtime logs, and saved benchmark runs from failed attempts.
+3. Edit only the local Build Plan for this Context Graph to create a better implementation for this agent task.
 4. Keep `build-plan.json`, `build-plan.schema.json`, and any changed stage docs aligned.
 
 Guardrails:
-- do not edit checks, test specs, or source files
+- do not edit checks, benchmark specs, or source files
 - do not hardcode expected answers into Build Plan docs
 - keep this package standalone; do not rely on runtime inheritance
 - prefer small, defensible Build Plan changes over random churn

package/public-repo/build-plans/interf-default/use/query/SKILL.md

@@ -3,21 +3,28 @@
 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 source re-checks.
-3. Use `summaries/` for source-grounded evidence.
-4. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, and exact source lookups.
+1. Read `.interf/build-plan/README.md` and this file first.
+2. Read `home.md` first. It is the primary agent entrypoint.
+3. Use `.interf/runtime/graph-manifest.json` when you need coverage metrics, stage summaries, entrypoints, or readiness.
+4. Follow at least one linked `knowledge/` or `summaries/` note when the answer depends on a claim, entity, timeline, comparison, or source-backed fact.
+5. Use `.interf/runtime/source-manifest.json` and note source refs to follow graph-provided source references for direct quotes, exact values, visual/table verification, and provenance-sensitive claims.
 
 Answering rule:
 - do not modify source files while answering
+- use the Context Graph as the knowledge map, not as a raw-source replacement
+- do not bypass the graph with ad hoc source browsing; drill into source only through graph-provided source references, traces, entrypoint notes, or the recorded Source Manifest
+- start from `home.md`; treat entrypoints and task entrypoint notes as routing and source-evidence maps, not as a replacement dataset
+- use `summaries/` for coverage proof and `knowledge/` for navigation/drilldown; do not treat generated knowledge notes as the authority for exact claims
+- record the entrypoint note and linked `knowledge/` or `summaries/` notes you used when a trace log is requested
+- when exact wording, table values, chart positions, visual ranges, or provenance matter, follow the cited source reference before making a strong claim
 - when a number is approximate or source-derived from a visual, say that explicitly
-- if the verifiable context already contains a bounded value for the exact metric and period the user asked about, answer from that value first
-- use source references to confirm the source page, metric family, or provenance, not to replace a good bounded read with a mismatched range
-- when the verifiable context preserves a bounded range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
+- if the Context Graph already contains a bounded value for the exact metric and period the user asked about, verify the cited source reference when precision matters, then answer from that bounded value
+- use source references to confirm the source page, metric family, visual series, axis/range, period, unit, and provenance
+- when the Context Graph preserves a bounded range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
 - match the source granularity and do not invent finer precision than the source supports
-- when reading visuals, verify you are on the correct metric family and period before answering
-- keep annual, quarterly, sector, and snapshot metrics separate unless the source explicitly connects them
+- when reading visuals, verify you are on the correct metric family and period before making a claim
+- keep annual, quarterly, sector, and point-in-time metrics separate unless the source explicitly connects them
 - if multiple notes mention the same value, keep the answer consistent with the most focused note rather than synthesizing a new midpoint or shifted range
-- when the verifiable context is insufficient, verify against source references and then answer
+- when the Context Graph is insufficient but points to the right source evidence, improve or rebuild if the missing semantics are part of the Build Plan output contract; do not present a weak graph as ready
 
-You can edit this file to bias manual question-answering behavior for this verifiable context.
+You can edit this file to bias manual question-answering behavior for this Context Graph.