@interf/compiler 0.33.0 → 0.50.0

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

@@ -0,0 +1,74 @@
+# Entrypoint
+
+Assemble the primary Context Graph entrypoint and task-specific entrypoint
+notes around the saved Project intent and coverage.
+
+Contract type: `build-entrypoint`
+
+This stage is service-owned in the default local runtime. The local service
+uses the same stage shell, expected inputs, reviewed inputs, output validation,
+and StageManifest path, but writes deterministic routing notes from already
+prepared summaries and knowledge instead of asking an agent to reinterpret the
+Source.
+
+## Requirements
+
+- Read `runtime/project.json`, `runtime/stage-contract.json.project.intent`,
+  `runtime/expected-inputs.json`, summaries, and knowledge notes before writing
+  outputs.
+- Write `runtime/reviewed-inputs.json` with one decision for every required
+  expected knowledge note 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": "entrypoint",`
+- `  "reviewed": [`
+- `    { "resource_id": "knowledge-example", "decision": "used", "source_refs": ["knowledge/example.md"] }`
+- `  ]`
+- `}`
+- Use Project intent plus coverage from summaries and knowledge to shape
+  `home.md`, `artifacts/`, and supporting graph routes.
+- Write `home.md` as the downstream agent's primary entrypoint. It must tell
+  the next agent where to start, what source refs matter, and what caveats or
+  source re-checks remain.
+- Route into all three fixed layers: `summaries/` (coverage — every Source file
+  read), `knowledge/` (the connected knowledge web — traverse/query),
+  `artifacts/` (task handoffs). Do not introduce a new top-level folder; richer
+  structure nests under `knowledge/`.
+- Close the whole-graph connectivity floor (`graph_notes_connected`): EVERY note
+  in the graph — including every summary, not only the ones a knowledge note
+  happened to cite — must be reachable through the link web. A summary that no
+  note links is a free-floating island and fails readiness. Make `home.md` (or a
+  coverage-index note it links, e.g. `summaries/index.md`) route into the
+  coverage layer so every summary has at least one inbound link. For a large
+  coverage layer, prefer a `summaries/` index note that links each summary and
+  link that index from `home.md`, rather than listing hundreds of summaries
+  directly in `home.md`. The floor is connectedness, not a quota — one genuine
+  inbound or outbound link per note is enough; never fabricate links to pass.
+- Write at least one task-specific entrypoint note under `artifacts/` when it
+  helps the agent continue from prepared context.
+- Each task entrypoint note must start with JSON frontmatter containing non-empty `task`, `source_refs`, `handoff_type`, and `caveats`. Optional routing fields (for example a source-evidence posture or a coverage state) may be added when they help the next agent, but the gating keys are those four.
+- `source_refs` must point to original Source locations, not just generated summaries or knowledge notes.
+- Task entrypoint notes should tell the downstream agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter for the task.
+- Task entrypoint notes should route the downstream agent to original Source refs for exact claims. Do not present generated summaries or knowledge notes as the dataset or source of truth.
+- Do not leave the scaffold `Not yet built.` placeholder in place.
+- When you add wikilinks, target real Context Graph 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 source value is approximate, preserve it as a bounded range and say why it is approximate.
+- Do not invent finer precision than the source supports.
+- For unlabeled charts, screenshots, diagrams, or visual marks, either create a measurement note with source-grounded visual reference, calibration, method, and uncertainty, or tell the downstream agent to inspect the original Source before answering.
+- Keep approximate values consistent across `home.md`, focused indexes, and claim/entity notes.
+- Do not copy expected answers into the Context Graph.
+
+## Notes
+
+- Use the saved Project intent and coverage metrics to bias the final Context Graph toward the job it should be especially good at.
+- Do not copy benchmark expected answers into the final Context Graph.
+- Prefer the saved summary evidence and structured notes when they already preserve routing, source refs, and caveats.
+- Reopen source references during shaping when exact wording, table values, chart reads, or provenance-sensitive claims matter.
+- If a prepared value depends on source-derived values, route the entrypoint or handoff to source refs and preserve source granularity instead of fabricating precision.
+- Prefer better routing, prioritization, and focused navigation over speculative synthesis.
+- 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/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

@@ -29,19 +29,52 @@ Contract type: `build-file-evidence`
 - 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 so a human can match it to the original source file
-  - non-paginated sources: `summaries/<source-name>/summary.md`
-  - PDFs, decks, images, or paginated/visual reports: `summaries/<source-name>/manifest.md` plus `pages/001/summary.md`, `pages/002/summary.md`, etc. for every page/slide that can be inspected
+  - 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/source-manifest.json` for the authoritative Source inventory and `runtime/stage-inputs.json` for the exact source references assigned to this stage.
+- 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.
-- Summaries prove coverage; they do not need to answer the final task.
+- 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

@@ -7,7 +7,7 @@
   },
   "purpose": {
     "label": "Build Context Graph",
-    "task_hint": "Build mixed source files into a three-layer Context Graph: summaries for coverage, knowledge for task-aware structure, and artifacts for downstream agent handoff with links back to original sources."
+    "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,12 +18,12 @@
     }
   ],
   "label": "Built-in Interf Build Plan",
-  "hint": "Built-in Build Plan that builds a Context Graph with source coverage summaries, task-aware knowledge, requested Artifact handoffs, links back to sources, Build evidence, and traces.",
+  "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 source-named coverage folders under summaries/, with summary.md or manifest.md plus page/slide notes for every inspectable paginated or visual source page.",
+      "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",
@@ -33,12 +33,12 @@
       ]
     },
     {
-      "id": "structure",
-      "label": "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-structure",
+      "contract_type": "build-knowledge",
       "role": "structurer",
-      "skill_dir": "structure",
+      "skill_dir": "knowledge",
       "reads": [
         "summaries"
       ],
@@ -47,12 +47,12 @@
       ]
     },
     {
-      "id": "shape",
-      "label": "Shape",
-      "description": "Shape task-specific Artifact handoffs and the Context Graph index around the saved task focus and Context Checks.",
-      "contract_type": "build-query-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": "shape",
+      "skill_dir": "entrypoint",
       "reads": [
         "summaries",
         "knowledge"
@@ -67,27 +67,31 @@
   "stage_policy_notes": {
     "summarize": [
       "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 so a human can match it to the original source file.",
-      "For non-paginated sources, write `summaries/<source-name>/summary.md`.",
-      "For PDFs, decks, images, or paginated/visual reports, write `summaries/<source-name>/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.",
+      "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": [
+    "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 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/<source-name>/summary]]`, `[[summaries/<source-name>/manifest]]`, or plain source refs. For knowledge notes, prefer final filenames under `knowledge/`."
+      "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 Context Checks to bias the final Context Graph toward the agent task it should be especially good at.",
+    "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.",
-      "Write one or more notes under `artifacts/` as the downstream agent handoff. These notes should tell the agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter.",
-      "Artifacts 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 saved Context Check depends on source-derived values that may be approximate, preserve the stated range, limits, evidence tier, and source inspection requirement.",
+      "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

@@ -6,7 +6,7 @@
   "artifacts": [
     {
       "id": "home",
-      "description": "Context Graph index note. Routes to the summaries coverage layer, knowledge graph layer, and task-specific Artifact handoffs; downstream agents should start from artifacts/ for task work.",
+      "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", "description": "The graph index note exists.", "required": true },
@@ -17,19 +17,20 @@
           "required": true,
           "params": { "phrases": ["Not yet built."] }
         },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every graph index wikilink resolves.", "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": "Coverage layer with one source-named 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.",
+      "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": "source-summary-folders",
           "kind": "source_summary_folders",
-          "description": "Every source file has a source-named folder with summary.md or manifest.md.",
+          "description": "Every source file has an exact source-path folder with summary.md or manifest.md.",
           "required": true,
           "params": { "match": "source_total" }
         },
@@ -39,7 +40,7 @@
           "kind": "frontmatter_required_keys",
           "description": "Every summary note records source and evidence metadata.",
           "required": true,
-          "params": { "keys": ["source", "source_file_id", "source_path", "source_locator", "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"]
@@ -49,49 +50,52 @@
       "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", "description": "Knowledge layer contains notes for task-aware navigation.", "required": true, "params": { "min": 3 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every knowledge wikilink resolves.", "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", "shape"]
+      "built_by_stages": ["knowledge", "entrypoint"]
     },
     {
       "id": "artifacts",
-      "description": "Task-specific requested Artifact handoffs for downstream agents. These notes 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.",
+      "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", "description": "At least one task-specific Artifact handoff note exists.", "required": true, "params": { "min": 1 } },
-        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "description": "Every Artifact handoff note has valid frontmatter.", "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 Artifact handoff records task, source reference, and verification posture.",
+          "description": "Every task entrypoint note records task, source refs, handoff type, and caveats.",
           "required": true,
-          "params": { "keys": ["task", "source_refs", "handoff_type", "truth_mode", "verification_state", "caveats"] }
+          "params": { "keys": ["task", "source_refs", "handoff_type", "caveats"] }
         },
         {
           "id": "handoff-source-refs",
           "kind": "source_refs_required",
-          "description": "Every Artifact handoff has non-empty source refs.",
+          "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 Artifact handoff has non-empty task, source refs, verification state, and caveats.",
+          "description": "Every task entrypoint note has non-empty task, source refs, and caveats.",
           "required": true,
-          "params": { "keys": ["task", "source_refs", "verification_state", "caveats"] }
+          "params": { "keys": ["task", "source_refs", "caveats"] }
         },
         {
           "id": "source-authority-caveat",
           "kind": "must_contain",
-          "description": "Artifact handoffs tell agents to follow original Source refs for exact claims.",
+          "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 Artifact handoff wikilink resolves.", "required": true }
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every task entrypoint note wikilink resolves.", "required": true }
       ],
-      "built_by_stages": ["shape"]
+      "built_by_stages": ["entrypoint"]
     }
   ]
 }

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

@@ -4,17 +4,18 @@ This file is the editable authoring source for the generated native local `inter
 
 Default loop:
 1. Read `.interf/build-plan/README.md` and this file first.
-2. Read the relevant notes under `artifacts/` first. Artifact handoffs are the default task handoff surface for the agent.
-3. Use `home.md` only when you need a graph index to find the right Artifact handoff.
-4. Browse `knowledge/` and `summaries/` only when the Artifact handoff needs drilldown, broader context, or debugging.
-5. Use `.interf/runtime/source-manifest.json` and Artifact source refs to follow graph-provided source references for direct quotes, exact values, visual/table verification, and provenance-sensitive claims.
+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, requested Artifacts, or the recorded Source Manifest
-- start from `artifacts/`; treat Artifact handoffs as routing and source-evidence maps, not as a replacement dataset
+- 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 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
@@ -24,6 +25,6 @@ Answering rule:
 - 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 Context Graph is insufficient but points to the right source evidence, improve or rebuild if the missing semantics are part of the requested Artifact contract; do not present a blurry artifact as ready
+- 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 Context Graph.