@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/agents/lib/executors.d.ts

@@ -10,6 +10,7 @@ export interface AgentExecutionProfile {
 export interface AgentExecuteOptions {
     eventLogPath?: string | null;
     statusLogPath?: string | null;
+    reasoningLogPath?: string | null;
     completionCheck?: (() => boolean) | null;
     onStatus?: (line: string) => void;
 }

package/dist/packages/runtime/agents/lib/executors.js

@@ -1,4 +1,5 @@
 import { resolveAgent } from "./detection.js";
+import { resolveEffectiveAgentExecutionProfile } from "./execution-profile.js";
 import { spawnAgent } from "./execution.js";
 import { ensureAgentAutomatedRunReady } from "./preflight.js";
 export function buildRuntimeExecutorInfo(executor) {
@@ -14,17 +15,25 @@ export function buildRuntimeExecutorInfo(executor) {
     };
 }
 export function createLocalAgentExecutor(agent, executionProfile = {}) {
+    // Resolve the EFFECTIVE profile (per-run override ∨ saved agent prefs) ONCE,
+    // here, at construction. The executor then carries this single resolved value
+    // as `executionProfile`, so the model `buildRuntimeExecutorInfo` records and
+    // the model `buildAgentArgs` runs are sourced from the same object and can
+    // never disagree (F1). `spawnAgent` no longer re-merges prefs — it consumes
+    // this resolved profile as-is.
+    const effectiveProfile = resolveEffectiveAgentExecutionProfile(agent, executionProfile);
     return {
         kind: "local-agent",
         name: agent.name,
         displayName: agent.displayName,
         command: agent.command,
-        executionProfile,
+        executionProfile: effectiveProfile,
         execute(rootPath, prompt, options) {
             return spawnAgent(agent, rootPath, prompt, {
                 eventLogPath: options?.eventLogPath,
                 statusLogPath: options?.statusLogPath,
-                executionProfile,
+                reasoningLogPath: options?.reasoningLogPath,
+                executionProfile: effectiveProfile,
                 completionCheck: options?.completionCheck,
                 onStatus: options?.onStatus,
             });

package/dist/packages/runtime/agents/lib/logs.d.ts

@@ -1,2 +1,12 @@
 export declare function appendAgentEventLog(eventLogPath: string | null | undefined, event: Record<string, unknown>): void;
 export declare function appendAgentStatusLog(statusLogPath: string | null | undefined, text: string): void;
+/**
+ * Append one reasoning/thinking span to the best-effort reasoning transcript
+ * (one JSON object per line). Reasoning capture must never block or fail a run,
+ * so any write error is swallowed — a missing reasoning line is acceptable, a
+ * crashed Build is not.
+ */
+export declare function appendAgentReasoningLog(reasoningLogPath: string | null | undefined, span: {
+    kind: string;
+    text: string;
+}): void;

package/dist/packages/runtime/agents/lib/logs.js

@@ -1,17 +1,41 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-export function appendAgentEventLog(eventLogPath, event) {
-    if (!eventLogPath)
+/**
+ * Append one line to a run log file, creating its directory on demand.
+ *
+ * Run log writes are observability, never run control: a mid-run disk hiccup
+ * (mkdir/append failure) must record a recoverable session, not throw an
+ * unhandled rejection that crashes the Build and dangles the session's
+ * `logs.event_stream_path`/`logs.status_path`. The single explicit policy for
+ * every agent run log is therefore best-effort — a missing log line is
+ * acceptable, a crashed run is not. A null/empty path is a no-op.
+ */
+function ensureLogFile(path, content) {
+    if (!path)
         return;
-    mkdirSync(dirname(eventLogPath), { recursive: true });
-    appendFileSync(eventLogPath, `${JSON.stringify({
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, content);
+    }
+    catch {
+        // Best-effort only: log writes must never block or fail a run.
+    }
+}
+export function appendAgentEventLog(eventLogPath, event) {
+    ensureLogFile(eventLogPath, `${JSON.stringify({
         timestamp: new Date().toISOString(),
         ...event,
     })}\n`);
 }
 export function appendAgentStatusLog(statusLogPath, text) {
-    if (!statusLogPath)
-        return;
-    mkdirSync(dirname(statusLogPath), { recursive: true });
-    appendFileSync(statusLogPath, `${new Date().toISOString()} ${text}\n`);
+    ensureLogFile(statusLogPath, `${new Date().toISOString()} ${text}\n`);
+}
+/**
+ * Append one reasoning/thinking span to the best-effort reasoning transcript
+ * (one JSON object per line). Reasoning capture must never block or fail a run,
+ * so any write error is swallowed — a missing reasoning line is acceptable, a
+ * crashed Build is not.
+ */
+export function appendAgentReasoningLog(reasoningLogPath, span) {
+    ensureLogFile(reasoningLogPath, `${JSON.stringify({ timestamp: new Date().toISOString(), ...span })}\n`);
 }

package/dist/packages/runtime/agents/lib/preflight.js

@@ -77,7 +77,10 @@ export function ensureAgentAutomatedRunReady(agent, options = {}) {
     const details = result ? [result.error, result.stderr].filter(Boolean).join(" ") : "";
     return {
         ok: false,
-        error: `${agent.displayName} failed Interf executor preflight. Run \`interf doctor --live\` for details.${details ? ` ${details}` : ""}`,
+        error: `${agent.displayName} failed Interf executor preflight. ` +
+            `Run \`interf doctor --live\` for details, or switch active agent with \`interf agents use <name>\` ` +
+            `(e.g. \`interf agents use claude-code\`).` +
+            (details ? ` ${details}` : ""),
     };
 }
 function sanitizeAgentStderr(agent, stderr) {

package/dist/packages/runtime/agents/lib/render.d.ts

@@ -5,4 +5,22 @@ export interface VisibleTextState {
 }
 export declare function emitVisibleAgentText(text: string, statusLogPath: string | null | undefined, lastVisibleText?: VisibleTextState, onStatus?: (line: string) => void): boolean;
 export declare function displayAgentEvent(event: Record<string, unknown>, statusLogPath: string | null | undefined, lastVisibleText: VisibleTextState, onStatus?: (line: string) => void): boolean;
+/**
+ * One reasoning/thinking span lifted from an agent event, for the best-effort
+ * reasoning transcript. `kind` records where it came from so the transcript
+ * stays inspectable across executors.
+ */
+export interface AgentReasoningSpan {
+    kind: "thinking" | "reasoning";
+    text: string;
+}
+/**
+ * Extract any reasoning/thinking spans from a single parsed agent event. The
+ * event stream is already parsed for display; this lifts the reasoning the
+ * display path discards (it never renders thinking) so it can be teed to a
+ * runtime file. Covers Claude Code `assistant` messages carrying `thinking`
+ * content blocks and Codex `item.*` reasoning items. Returns `[]` for events
+ * with no reasoning — callers must treat reasoning capture as best-effort.
+ */
+export declare function extractAgentReasoning(event: Record<string, unknown>): AgentReasoningSpan[];
 export declare function summarizeAgentToolActivity(event: Record<string, unknown>): string | null;

package/dist/packages/runtime/agents/lib/render.js

@@ -2,6 +2,7 @@ import { basename } from "node:path";
 import chalk from "chalk";
 import { SHOW_AGENT_TOOL_EVENTS, VISIBLE_STATUS_PREFIXES, } from "./constants.js";
 import { appendAgentStatusLog } from "./logs.js";
+import { extractInputPath, pickString } from "./string-utils.js";
 export function emitVisibleAgentText(text, statusLogPath, lastVisibleText, onStatus) {
     if (lastVisibleText?.terminated) {
         return false;
@@ -37,7 +38,7 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
         const input = event.input;
         let detail = "";
         if (input) {
-            const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+            const path = extractInputPath(input);
             if (path)
                 detail = chalk.dim(` ${path.slice(0, 80)}`);
         }
@@ -58,7 +59,7 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
                     const input = block.input;
                     let detail = "";
                     if (input) {
-                        const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+                        const path = extractInputPath(input);
                         if (path)
                             detail = chalk.dim(` ${path.slice(0, 80)}`);
                     }
@@ -95,6 +96,45 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
     }
     return displayed;
 }
+/**
+ * Extract any reasoning/thinking spans from a single parsed agent event. The
+ * event stream is already parsed for display; this lifts the reasoning the
+ * display path discards (it never renders thinking) so it can be teed to a
+ * runtime file. Covers Claude Code `assistant` messages carrying `thinking`
+ * content blocks and Codex `item.*` reasoning items. Returns `[]` for events
+ * with no reasoning — callers must treat reasoning capture as best-effort.
+ */
+export function extractAgentReasoning(event) {
+    const type = event.type;
+    const spans = [];
+    if (type === "assistant") {
+        const message = event.message;
+        const content = message?.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block.type === "thinking" || block.type === "redacted_thinking") {
+                    const text = pickString(block.thinking) ?? pickString(block.text);
+                    if (text)
+                        spans.push({ kind: "thinking", text });
+                }
+            }
+        }
+    }
+    if (type === "item.started" || type === "item.completed") {
+        const item = event.item;
+        if (item?.type === "reasoning") {
+            const text = pickString(item.text) ?? pickString(item.summary) ?? pickString(item.content);
+            if (text)
+                spans.push({ kind: "reasoning", text });
+        }
+    }
+    if (type === "reasoning") {
+        const text = pickString(event.text) ?? pickString(event.summary) ?? pickString(event.content);
+        if (text)
+            spans.push({ kind: "reasoning", text });
+    }
+    return spans;
+}
 export function summarizeAgentToolActivity(event) {
     const type = event.type;
     if (type === "assistant") {
@@ -116,20 +156,6 @@ export function summarizeAgentToolActivity(event) {
     }
     return null;
 }
-function pickString(value) {
-    if (typeof value === "string")
-        return value;
-    if (!Array.isArray(value))
-        return null;
-    for (const entry of value) {
-        if (typeof entry === "string")
-            return entry;
-        if (entry && typeof entry === "object" && "text" in entry && typeof entry.text === "string") {
-            return entry.text;
-        }
-    }
-    return null;
-}
 function displayItemEvent(type, item, statusLogPath, lastVisibleText, onStatus) {
     const itemType = item.type;
     if (itemType === "agent_message") {
@@ -159,7 +185,7 @@ function displayItemEvent(type, item, statusLogPath, lastVisibleText, onStatus)
     return false;
 }
 function describeInput(input) {
-    const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+    const path = extractInputPath(input);
     return path ? chalk.dim(` ${path.slice(0, 80)}`) : "";
 }
 function summarizeToolUse(name, input) {
@@ -185,7 +211,7 @@ function summarizeToolUse(name, input) {
 function summarizeToolTarget(input) {
     if (!input)
         return null;
-    const raw = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? input.notebook_path);
+    const raw = extractInputPath(input);
     if (!raw || raw.length === 0)
         return null;
     if (raw.includes("\n")) {

package/dist/packages/runtime/agents/lib/shell-templates.js

@@ -26,19 +26,21 @@ export function renderContextGraphAgents(contextGraphPath, name, buildPlanId, op
         `# ${name}`,
         "",
         "This is a Context Graph built by Interf.",
-        "This folder gives agents a prepared knowledge map over the Source: summaries, claims, requested Artifacts, traces, routes, and links back to sources.",
+        "This folder gives agents a prepared knowledge map over the Source: source-backed summaries, knowledge notes, entrypoints, traces, routes, and links back to sources.",
         "It normally contains source references rather than raw source copies. The original Source remains the source of truth.",
         "Use this graph before any source drilldown so you know what exists, what matters, and where evidence lives.",
         "",
         "## How to use this Context Graph",
         "",
-        "1. Use the local native `interf-query` skill that Interf generated for this Context Graph.",
-        "2. Let the Build Plan docs and declared Artifacts guide retrieval instead of assuming a fixed note layout.",
-        "3. Use `.interf/runtime/source-manifest.json` to follow graph-provided source references for exact quotes, table values, chart reads, and provenance-sensitive claims.",
+        "1. Start with `home.md`. It is the primary agent entrypoint for this Context Graph.",
+        "2. Use the local native `interf-query` skill that Interf generated for this Context Graph.",
+        "3. Follow links from `home.md` into `knowledge/`, `summaries/`, `artifacts/`, traces, or Build Plan details.",
+        "4. Use `.interf/runtime/graph-manifest.json` for coverage metrics, stage summaries, entrypoints, and readiness.",
+        "5. Use `.interf/runtime/source-manifest.json` to follow graph-provided source references for exact quotes, table values, chart reads, and provenance-sensitive claims.",
         "",
         "## How this Context Graph works",
         "",
-        "- The Build Plan defines the requested Artifact contract this Context Graph implements on disk.",
+        "- The Build Plan defines the requested output contract this Context Graph implements on disk.",
         "- `.interf/interf.json` records the selected Source binding and Project metadata.",
         `- Build Plan seed: \`${buildPlanOriginSelected}\`.`,
         ...(buildPlanLocalDraft
@@ -46,14 +48,15 @@ export function renderContextGraphAgents(contextGraphPath, name, buildPlanId, op
             : []),
         `- Selected Build Plan id: \`${buildPlanId}\`.`,
         "- `.interf/build-plan/` is the local editable Build Plan package for this Context Graph.",
-        `- \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` is the deterministic requested Artifact contract for this Context Graph.`,
+        `- \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` is the deterministic requested output contract for this Context Graph.`,
         "- `.interf/build-plan/improve/` is the editable source for Build Plan improvement loops.",
         "- `.interf/build-plan/use/query/` is the editable source for the generated native query shell.",
         "- `.interf/build-plan/build/stages/` defines stage-specific docs that Interf projects into native execution shells for automated runs.",
         "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
         "- `.interf/runtime/source-manifest.json` is the authoritative Source inventory recorded for this Context Graph.",
-        "- `.interf/runtime/source-state.json` is a compatibility projection of the Source Manifest.",
-        `- Requested Artifact contracts are declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\`.`,
+        "- `.interf/runtime/graph-manifest.json` is the authoritative Context Graph manifest recorded for this build.",
+        "- `.interf/runtime/source-state.json` is a derived projection of the Source Manifest.",
+        `- Requested output contracts are declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\`.`,
         ...artifactLines,
         "- `.interf/runtime/` holds runtime artifacts written by Interf.",
         "- `.interf/tests/` mirrors the latest saved benchmark/evaluation run and keeps detailed target runs plus preserved sandboxes.",
@@ -61,10 +64,10 @@ export function renderContextGraphAgents(contextGraphPath, name, buildPlanId, op
         "",
         "## Manual query rules",
         "",
-        "- Prefer the Build Plan-declared Context Graph outputs before source drilldown.",
+        "- Start from `home.md` before other Context Graph outputs or source drilldown.",
         "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/build-plan/use/query/SKILL.md`.",
         "- Treat `.interf/` as Build Plan/runtime metadata, not answer evidence, unless explicitly asked to inspect Build Plan or benchmark history.",
-        "- Do not bypass the graph with ad hoc source browsing. Drill into Source only through graph-provided source references, traces, requested Artifacts, or recorded Source state.",
+        "- Do not bypass the graph with ad hoc source browsing. Drill into Source only through graph-provided source references, traces, graph entrypoints, or recorded Source state.",
         "- Use `.interf/runtime/source-manifest.json` to find source references for quotes, verification, ambiguity, or evidence the Context Graph does not expose well.",
         "- If exact chart, table, or image-derived evidence matters, inspect the cited source reference and say whether the answer was text-derived, table-derived, or chart-derived.",
         "- If the graph points to the right evidence but misses required range, axis, period, unit, series, or provenance semantics, treat the graph as not ready and improve the Build Plan instead of presenting a blurry artifact as ready.",
@@ -93,20 +96,23 @@ export function renderContextGraphQuerySkill() {
         "",
         "Default loop:",
         "1. Read `.interf/build-plan/README.md` and this file first.",
-        `2. Use the requested Artifact contract declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` plus \`home.md\` to understand the prepared map.`,
-        "3. Use Context Graph notes and requested Artifacts to locate the relevant evidence before any source drilldown.",
-        "4. Use `.interf/runtime/source-manifest.json` 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 the requested output contract declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` and \`.interf/runtime/graph-manifest.json\` when you need to understand coverage, readiness, or prepared outputs.`,
+        "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",
-        "- treat the Build Plan as the Context Graph contract and use its Artifacts as the working retrieval surface",
+        "- treat the Build Plan as the Context Graph contract and use its graph resources as the working retrieval surface",
+        "- start from `home.md`; treat entrypoints and generated graph files as routing and source-evidence maps, not as a replacement dataset",
         "- use the Context Graph as a knowledge map over the Source, not as a raw-source replacement",
-        "- do not bypass the graph with ad hoc source browsing; source drilldown must follow graph-provided source references, traces, requested Artifacts, or the recorded Source Manifest",
+        "- do not bypass the graph with ad hoc source browsing; source drilldown must follow graph-provided source references, traces, graph entrypoints, or the recorded Source Manifest",
+        "- record the entrypoint and linked `knowledge/` or `summaries/` notes you used when a trace log is requested",
         "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
         "- when exact wording, table values, chart positions, visual ranges, or provenance matter, follow the cited source reference before making a strong claim",
         "- use source references to confirm source page, metric family, visual series, axis/range, period, unit, provenance, or exact wording",
         "- do not invent navigation or note structure beyond what this Build Plan declares",
-        "- 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 requested output contract; do not present a weak graph output as ready",
         "",
         "You can edit this file to bias manual question-answering behavior for this Context Graph.",
         "",
@@ -129,7 +135,7 @@ export function renderSourceFilesTestAgents() {
         "## Rules",
         "",
         "- Answer only from source files listed in `runtime/source-manifest.json`.",
-        "- There is no Context Graph here, so do not assume any Context Graph Artifacts exist.",
+        "- There is no Context Graph here, so do not assume any generated graph outputs exist.",
         "- Do not treat hidden runtime files or benchmark artifacts as evidence.",
         ...chartNotes,
         "- Write the requested answer and trace files, then stop.",
@@ -169,27 +175,34 @@ export function renderStageExecutionAgents(contextGraphName, buildPlanId, stage)
     return [
         `# ${contextGraphName} — ${stage.label} Execution Shell`,
         "",
-        "This is an ephemeral stage-execution shell generated by Interf.",
-        "It is for automated pipeline execution only, not for manual querying.",
+        "This is a replayable stage-execution shell generated by Interf.",
+        "It contains the stage prompt, logs, local agent instructions, skill, contract, inputs, output mounts, and validator for this stage.",
         "",
         "## Start Here",
         "",
         "1. Read `runtime/stage-contract.json` now.",
-        "2. Read `runtime/source-manifest.json`, `runtime/source-state.json`, and `runtime/stage-inputs.json` now.",
-        "3. Read `runtime/paths.json` now.",
-        "4. Use the local native `interf-stage` skill now.",
-        `5. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "2. Read `runtime/project.json` now.",
+        "3. Read `runtime/source-manifest.json`, `runtime/stage-inputs.json`, and `runtime/expected-inputs.json` now.",
+        "4. Read `runtime/paths.json` now.",
+        "5. Use the local native `interf-stage` skill now.",
+        `6. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
+        "7. Write `runtime/reviewed-inputs.json` before DONE.",
         "",
         "## Shell ABI",
         "",
         "- `inputs/<artifact-id>/` = read mounts for the current stage.",
         "- `outputs/<artifact-id>/` = write mounts for the current stage.",
-        "- For file Artifacts, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- For file outputs, `runtime/paths.json` points to the exact file path inside those mount roots.",
+        "- `runtime/project.json` = Project id and task intent for this stage.",
         "- `runtime/source-manifest.json` = authoritative Source inventory for this run.",
-        "- `runtime/source-state.json` = compatibility projection of manifest source references.",
+        "- `runtime/source-state.json` = derived projection of manifest source references.",
         "- `runtime/stage-inputs.json` = exact manifest source references assigned to this stage.",
+        "- `runtime/expected-inputs.json` = required inputs this stage must review, use, or mark missing/blocked/not relevant.",
+        "- `runtime/reviewed-inputs.json` = coverage decisions this stage writes before DONE.",
         "- `runtime/check-stage.mjs` = shell-local deterministic verifier for the current stage outputs.",
-        "- declared Artifact paths are also projected at the shell root so Build Plan-relative contract paths stay valid.",
+        "- `runtime/workspace.json` = shell map for retrospective inspection and replay.",
+        "- `logs/` = prompt, event stream, and status log for this agent session.",
+        "- declared output paths are also projected at the shell root so Build Plan-relative contract paths stay valid.",
         "- `runtime/` = stage contract and machine-readable path map for this shell.",
         "- `build-plan/` = Build Plan metadata, `build-plan.schema.json`, and docs for the current stage only.",
         "",
@@ -197,12 +210,14 @@ export function renderStageExecutionAgents(contextGraphName, buildPlanId, stage)
         "",
         `- Build Plan: \`${buildPlanId}\`.`,
         `- Contract type: \`${stage.contractType}\`.`,
-        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the context-graph query shell.",
+        "- This shell has its own AGENTS/CLAUDE/native skills. It is the runnable workspace for this stage.",
         "- The context-graph root itself is not linked into this shell.",
         "- Do not switch into query mode or act like a user-facing assistant.",
+        "- Use `runtime/project.json` and `runtime/stage-contract.json.project.intent` as the task focus whenever this stage writes task-aware summaries, knowledge, entrypoints, or requested outputs.",
+        "- Use `runtime/expected-inputs.json` as the coverage contract. Every required expected input must be reviewed or marked missing, blocked, or not relevant with a reason.",
         "- Do not modify files under `inputs/` unless the same Artifact is also mounted under `outputs/`.",
         "",
-        "## Current Stage Artifacts",
+        "## Current Stage Outputs",
         "",
         `- reads: ${stage.reads.join(", ")}`,
         `- writes: ${stage.writes.join(", ")}`,
@@ -212,9 +227,32 @@ export function renderStageExecutionAgents(contextGraphName, buildPlanId, stage)
         "- complete the current stage",
         "- honor the deterministic contract",
         "- write outputs through the declared Artifact mounts",
+        "- write `runtime/reviewed-inputs.json` with one decision per required expected input",
         "- run `node runtime/check-stage.mjs` and fix failures until it prints `VALID:`",
         "- stop when the stage is complete",
         "",
+        "## Reviewed Inputs File",
+        "",
+        "Write this JSON shape at `runtime/reviewed-inputs.json`:",
+        "",
+        "```json",
+        "{",
+        "  \"kind\": \"interf-stage-reviewed-inputs\",",
+        "  \"version\": 1,",
+        "  \"generated_at\": \"2026-01-01T00:00:00.000Z\",",
+        `  \"stage_id\": \"${stage.id}\",`,
+        "  \"reviewed\": [",
+        "    {",
+        "      \"resource_id\": \"copy-one-id-from-runtime-expected-inputs\",",
+        "      \"decision\": \"used\",",
+        "      \"source_refs\": [\"source-or-note-ref\"]",
+        "    }",
+        "  ]",
+        "}",
+        "```",
+        "",
+        "Allowed decisions: `used`, `reviewed`, `missing`, `blocked`, `not-relevant`. Missing, blocked, and not-relevant decisions require a concrete `reason`.",
+        "",
     ].join("\n");
 }
 export function renderStageExecutionSkill(stage, stageBuildPlanDoc) {
@@ -230,8 +268,11 @@ export function renderStageExecutionSkill(stage, stageBuildPlanDoc) {
         "",
         "This local native skill exists for automated Interf stage execution.",
         "Read `runtime/stage-contract.json` first.",
-        "Then read `runtime/source-manifest.json`, `runtime/source-state.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
-        "Use the assigned source references and the mounted `inputs/` and `outputs/` Artifacts for this stage.",
+        "Then read `runtime/project.json`, `runtime/source-manifest.json`, `runtime/stage-inputs.json`, `runtime/expected-inputs.json`, and `runtime/paths.json`.",
+        "Use the assigned source references and the mounted `inputs/` and `outputs/` requested outputs for this stage.",
+        "Use Project intent and the expected input coverage file when this stage writes task-aware summaries, knowledge, entrypoints, or requested outputs.",
+        "Write `runtime/reviewed-inputs.json` with kind `interf-stage-reviewed-inputs`, this stage id, and one decision per required expected input before DONE.",
+        "Allowed decisions are `used`, `reviewed`, `missing`, `blocked`, and `not-relevant`; missing, blocked, and not-relevant decisions require a concrete `reason`.",
         "Before emitting DONE, run `node runtime/check-stage.mjs` from the shell root and fix outputs until it prints `VALID:`.",
         "Do not switch into manual query mode.",
         "",
@@ -286,7 +327,7 @@ export function renderBuildPlanAuthoringAgents(options) {
         `# ${options.label} — Build Plan Authoring Shell`,
         "",
         "This is an automated Build Plan authoring shell generated by Interf.",
-        "It exists to create one standalone Build Plan package from the source data, requested Artifacts, Context Checks, and evidence requirements in this task.",
+        "It exists to create one standalone Build Plan package from the Source, Project intent, requested outputs, coverage metrics, and evidence requirements in this task.",
         "",
         "## Start Here",
         "",
@@ -305,31 +346,31 @@ export function renderBuildPlanAuthoringAgents(options) {
         "- Edit only files under `build-plan/`.",
         "- Do not edit source artifacts.",
         "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
-        "- Treat `checks` from `runtime/authoring-context.json` as user-facing Context Checks: plain-English checks the requested Artifacts must satisfy.",
-        "- Create Context Checks first, then requested Artifacts that back those checks, then deterministic Artifact diagnostics (`checks[]`) under each Artifact.",
-        "- Preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for task-specific agent handoffs.",
-        "- Artifact handoffs under `artifacts/` are the default downstream agent handoff surface. They must route to original Source refs for exact claims; generated summaries and knowledge notes are not the source of truth.",
-        "- Treat `home.md` as a graph index only, not as the answer surface.",
-        "- For tasks that depend on charts, tables, images, or other visual evidence, requested Artifacts must capture target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page.",
-        "- Do not let structural diagnostics such as file existence, frontmatter keys, or phrase presence stand in for evidence fidelity. Stage docs and Artifact descriptions must require the semantic fields the agent task needs.",
+        "- Use kebab-case ids everywhere: stage ids, skill_dir values, requested output ids, reads/writes values, and package ids. Never use underscores.",
+        "- Start from the saved Project intent. Build Plans operationalize that intent into summaries, task-aware knowledge, home.md, task entrypoint notes, StageManifest coverage, and GraphManifest metrics.",
+        "- Treat `checks` from `runtime/authoring-context.json` as optional context, not the primary product surface.",
+        "- Design coverage metrics first: expected Source units, reviewed inputs, produced outputs, entrypoints, and missing/blocked/not-relevant coverage decisions.",
+        "- Preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for focused task entrypoint notes.",
+        "- `home.md` is the primary downstream agent entrypoint. Notes under `artifacts/` supplement it and route to original Source refs for exact claims.",
+        "- For tasks that depend on charts, tables, images, or other visual evidence, requested outputs must capture target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page.",
+        "- Do not let structural diagnostics such as file existence, frontmatter keys, or phrase presence stand in for evidence fidelity. Stage docs and output descriptions must require the semantic fields the agent task needs.",
         "- If visual evidence has no printed data labels, require a bounded read at source granularity and unresolved-semantics handling instead of pseudo-exact precision.",
-        "- Preserve `backed_by_artifact_ids` and make them match requested Artifact ids.",
-        "- When `artifact_requirements[]` is non-empty, copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested Artifact contract; do not rename or move required Artifacts.",
-        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "- Preserve `backed_by_artifact_ids` and make them match requested output ids.",
+        "- When `artifact_requirements[]` is non-empty, treat it as the legacy storage field for required requested outputs; copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested output contract; do not rename or move required outputs.",
+        "- Put minimal deterministic validation on requested output `checks[]`; StageManifest and GraphManifest coverage are the primary proof surface.",
         "- Use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind.",
-        "- Give every Artifact diagnostic a human-readable `description`; the UI shows that assertion first and uses evaluator details as drilldown.",
+        "- Give every deterministic check a human-readable `description`; the UI uses evaluator details only as drilldown.",
         "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "- Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
         "",
         "## Goal",
         "",
-        "- produce one standalone Build Plan package tuned to the source data, requested Artifacts, and checks in this task",
+        "- produce one standalone Build Plan package tuned to the Source, Project intent, requested outputs, and coverage metrics in this task",
         "- replace the neutral scaffold topology with the stage flow this agent task needs",
-        "- define Context Checks, requested Artifacts, and Artifact diagnostics so Interf can show which checks passed, which Artifacts back them, and what evidence or traces support them",
-        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
-        "- otherwise draft requested Artifact contracts from every `requested_artifacts[]` entry; do not ignore or truncate them",
-        "- preserve deterministic stage and requested Artifact contracts",
+        "- define requested outputs and stage docs so Interf can record StageManifests, GraphManifest primary metrics, evidence, and traces",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present; this is the legacy storage field for required requested outputs",
+        "- otherwise treat `requested_artifacts[]` as the legacy storage field for requested outputs/entrypoints and draft requested output contracts from every entry; do not ignore or truncate them",
+        "- preserve deterministic stage and requested output contracts",
         "- stop once the Build Plan edits are complete",
         "",
     ].join("\n");
@@ -350,25 +391,26 @@ export function renderBuildPlanAuthoringSkill() {
         "Rules:",
         "- edit only `build-plan/`",
         `- keep \`build-plan.json\`, \`${BUILD_PLAN_SCHEMA_FILE}\`, and any changed stage docs aligned`,
-        "- treat `checks` from `runtime/authoring-context.json` as user-facing Context Checks, not deterministic operators",
-        "- create Context Checks first, then requested Artifacts that back them, then deterministic Artifact diagnostics (`checks[]`) under those Artifacts",
-        "- preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for task-specific agent handoffs",
-        "- make `artifacts/` the downstream agent handoff layer; route to original Source refs for exact claims and do not present generated notes as the source of truth",
-        "- treat `home.md` as a graph index only, not as the answer surface",
+        "- treat `checks` from `runtime/authoring-context.json` as optional context, not the primary product surface",
+        "- design coverage metrics first: expected inputs, reviewed inputs, produced outputs, entrypoints, and missing coverage decisions",
+        "- preserve the file-based Context Graph architecture: `summaries/` for source coverage, `knowledge/` for task-aware navigation/drilldown, and `artifacts/` for focused task entrypoint notes",
+        "- make `home.md` the primary downstream agent entrypoint; route to original Source refs for exact claims and do not present generated notes as the source of truth",
         "- for charts, tables, images, and other visual evidence, require target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page",
         "- structural diagnostics are not evidence fidelity; do not treat file existence, frontmatter keys, or phrase presence as proof that a visual/table value was correctly extracted",
         "- if visual evidence has no printed data labels, preserve a bounded read at source granularity and unresolved-semantics handling instead of pseudo-exact precision",
-        "- preserve `backed_by_artifact_ids` and make them match requested Artifact ids",
-        "- when `artifact_requirements[]` is non-empty, copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested Artifact contract; do not rename or move required Artifacts",
-        "- put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks",
+        "- preserve `backed_by_artifact_ids` in the root Build Plan `brief` and make them match requested output ids",
+        "- keep `purpose` limited to its documented fields; never add `purpose.brief` or other ad-hoc nested promise fields",
+        "- when `artifact_requirements[]` is non-empty, treat it as the legacy storage field for required requested outputs; copy every requirement's `id`, `shape`, and `checks[]` exactly into the requested output contract; do not rename or move required outputs",
+        "- keep deterministic validation on requested output `checks[]` minimal; StageManifest and GraphManifest coverage are the primary proof surface",
+        "- do not edit the root `brief`; the service restores it from Project intent, requested outputs, diagnostic checks, and Source context after every edit attempt",
         "- use only CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases",
         "- use `runtime/authoring-context.json.check_param_contracts` as the exact parameter contract for each check kind",
-        "- give every Artifact diagnostic a human-readable `description`; the UI shows that assertion first and uses evaluator details as drilldown",
-        "- keep Artifact diagnostics aligned with produced outputs; use stage docs to describe the output contract without requiring exact source-specific phrases in the stage docs",
-        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
-        "- otherwise draft requested Artifact contracts from every `requested_artifacts[]` entry; do not ignore or truncate them",
+        "- give every deterministic check a human-readable `description`; the UI uses evaluator details only as drilldown",
+        "- keep deterministic checks aligned with produced outputs; use stage docs and StageManifest coverage to describe the output contract without requiring exact source-specific phrases in the stage docs",
+        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present; this is the legacy storage field for required requested outputs",
+        "- otherwise treat `requested_artifacts[]` as the legacy storage field for requested outputs/entrypoints and draft requested output contracts from every entry; do not ignore or truncate them",
         "- design the stage flow from the source data, agent task, and evidence brief",
-        "- use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids; never use underscores",
+        "- use kebab-case ids everywhere: stage ids, skill_dir values, requested output ids, reads/writes values, and package ids; never use underscores",
         "- replace the placeholder `prepare` stage unless that exact stage is truly the final Build Plan",
         "- keep the package standalone; do not introduce runtime inheritance or hidden source-package assumptions",
         "- do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path",
@@ -401,9 +443,9 @@ export function renderBuildPlanImprovementAgents(contextGraphName, buildPlanId,
         `- Improvement loop: ${loopIndex}.`,
         "- Edit only files under `build-plan/`.",
         "- Do not edit checks, benchmark specs, source files, or generated context outputs.",
-        "- Review context-graph outputs under `artifacts/context-graph-view/` and benchmark/runtime evidence under `artifacts/`.",
+        "- Review `home.md`, `knowledge/`, `summaries/`, `.interf/runtime/graph-manifest.json`, stage manifests, and benchmark/runtime evidence under `artifacts/`.",
         "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "- Keep deterministic validation on Artifact `checks[]` minimal and aligned with produced outputs; use stage docs and manifests for coverage proof.",
         "",
         "## Goal",
         "",