@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/build/lib/schema.js

@@ -1,13 +1,30 @@
 import { z } from "zod";
 import { BUILD_PLAN_ARTIFACT_KINDS, } from "../build-plan-primitives.js";
-import { ArtifactIdSchema, ArtifactSchema, CheckSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, InterfIdPattern, BuildPlanIdSchema, isInterfRelativePath, } from "../../../contracts/lib/schema.js";
+import { ArtifactIdSchema, ArtifactSchema, CheckSchema, ProjectIntentSchema, ProjectIdSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, InterfIdPattern, BuildPlanIdSchema, isInterfRelativePath, } from "../../../contracts/lib/schema.js";
 // `ArtifactSchema` is used internally below in `BuildPlanContextRawSchema`'s
 // `artifacts[]` field. The other Artifact* schemas/types are NOT
 // re-exported through this module — callers import them directly from
 // `contracts/lib/schema.js`. Re-exports with zero consumers were pruned
 // to keep this barrel narrow.
-export { GateStatusSchema, ReadinessGateSchema, ReadinessSchema, ReadinessStatusSchema, VerifyTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceManifestAuditSchema, SourceManifestEvidenceSchema, SourceManifestFileKindSchema, SourceManifestFileSchema, SourceManifestScannerSchema, SourceManifestSchema, SourceInspectableUnitSchema, SourceSchema, SourceStateSchema, StageInputSchema, StageInputsSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, BuildPlanIdSchema, } from "../../../contracts/lib/schema.js";
+export { GateStatusSchema, ProjectIntentSchema, ReadinessGateSchema, ReadinessSchema, ReadinessStatusSchema, VerifyTargetResultSchema, RuntimeContractTypeSchema, RuntimeExecutorInfoSchema, RuntimeStageSchema, RuntimeTargetTypeSchema, SourceFilesSchema, SourceFileSchema, SourceKindSchema, SourceManifestAuditSchema, SourceManifestEvidenceSchema, SourceManifestFileKindSchema, SourceManifestFileSchema, SourceManifestScannerSchema, SourceManifestSchema, SourceInspectableUnitSchema, SourceSchema, SourceStateSchema, StageInputSchema, StageInputsSchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, GraphManifestSchema, GraphManifestStageSummarySchema, GraphOutputCountsSchema, GraphReadinessRollupSchema, MetricCountSchema, MissingInputSchema, ResourceRefSchema, ResourceRoleSchema, ReviewedInputDecisionSchema, ReviewedInputSchema, StageManifestSchema, SourceBuildMaxAttemptsSchema, SourceBuildMaxLoopsSchema, TestCaseExpectSchema, TestTargetTypeSchema, InterfIdPattern, BuildPlanIdSchema, } from "../../../contracts/lib/schema.js";
+import { BuildPlanContextCheckDraftSchema, } from "../../../build-plans/authoring/brief.js";
 const JsonRecordSchema = z.record(z.string(), z.unknown());
+// Lifecycle status of a built Context Graph as reported by `health.json`.
+// Defined once here and reused inside `ContextGraphHealthSchema.status` so the
+// `RuntimeStatus` type can never drift from the schema that validates the file.
+export const RuntimeStatusSchema = z.enum(["idle", "running", "built", "stale", "failed"]);
+// Which stage `health.json` reports: a terminal pseudo-stage
+// (`idle`/`built`/`failed`) or a concrete Build Plan stage id. This is the
+// SAME union used at `ContextGraphHealthSchema.stage`; the type is inferred
+// from it so the inline alias no longer widens to a bare `string`.
+export const BuildStageSchema = z.union([
+    z.enum(["idle", "built", "failed"]),
+    RuntimeStageSchema,
+]);
+// Status of one agent-run execution (a stage session and the run-scoped
+// ledger that records it). Single source for both `StageExecutionSessionSchema`
+// and `ExecutionStageLedgerSchema` so the two records can never disagree.
+export const ExecutionStatusSchema = z.enum(["running", "succeeded", "failed"]);
 export const BuildPlanArtifactIdSchema = z.string().regex(InterfIdPattern);
 export const BuildPlanArtifactKindSchema = z.enum(BUILD_PLAN_ARTIFACT_KINDS);
 export const BuildPlanArtifactRoleSchema = z.literal("output");
@@ -34,13 +51,34 @@ export const ContextGraphStateSchema = z.object({
     warning_count: z.number().optional(),
     error_count: z.number().optional(),
 }).strict();
-export const ViewSectionSchema = z.object({
+// A view-spec section, discriminated on `type` so each variant declares its
+// own path contract instead of one object where both `path?` and `paths?` are
+// always optional. The producer is `buildDefaultContextGraphViewSpec`
+// (state-view.ts): `status`/`cards` carry a single source `path`; `documents`
+// carries a `paths` list. `flow`/`table` have no producer yet, so their path
+// contract is genuinely unknown — both fields stay optional for those two
+// rather than guessing a shape no caller has committed to.
+const ViewSectionBaseFields = {
     id: z.string(),
-    type: z.enum(["status", "cards", "flow", "documents", "table"]),
     title: z.string(),
-    path: z.string().optional(),
-    paths: z.array(z.string()).optional(),
-});
+};
+export const ViewSectionSchema = z.discriminatedUnion("type", [
+    z.object({ ...ViewSectionBaseFields, type: z.literal("status"), path: z.string() }),
+    z.object({ ...ViewSectionBaseFields, type: z.literal("cards"), path: z.string() }),
+    z.object({ ...ViewSectionBaseFields, type: z.literal("documents"), paths: z.array(z.string()) }),
+    z.object({
+        ...ViewSectionBaseFields,
+        type: z.literal("flow"),
+        path: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+    }),
+    z.object({
+        ...ViewSectionBaseFields,
+        type: z.literal("table"),
+        path: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+    }),
+]);
 export const ViewCardSchema = z.object({
     id: z.string(),
     label: z.string(),
@@ -53,11 +91,8 @@ export const ContextGraphHealthSchema = z.object({
     version: z.number().int().min(1),
     generated_at: z.string(),
     target_name: z.string(),
-    status: z.enum(["idle", "running", "built", "stale", "failed"]),
-    stage: z.union([
-        z.enum(["idle", "built", "failed"]),
-        RuntimeStageSchema,
-    ]),
+    status: RuntimeStatusSchema,
+    stage: BuildStageSchema,
     summary: z.string(),
     metrics: z.record(z.string(), z.number()),
     checks: z.record(z.string(), z.boolean()),
@@ -129,6 +164,117 @@ export const ExecutionShellPathsSchema = z.object({
     reads: z.array(ExecutionShellArtifactMountSchema),
     writes: z.array(ExecutionShellArtifactMountSchema),
 });
+export const StageExecutionSessionValidationAttemptSchema = z.object({
+    attempt: z.number().int().min(1),
+    recorded_at: z.string().min(1),
+    status: z.enum(["succeeded", "failed"]),
+    summary: z.string().min(1),
+}).strict();
+/**
+ * Which kind of agent job a `StageExecutionSession` preserves. Every
+ * `executor.execute()` job that writes a graph-scoped session leaves the SAME
+ * inspectable session shape; `job_type` is the discriminator a reader keys off
+ * instead of inferring the job from coincidental fields. The default is `stage`
+ * so every existing writer/caller (a Build-Plan stage attempt inside a Context
+ * Graph) is unchanged. The stage-only fields (`stage_id`, `stage_label`,
+ * `contract_type`) stay populated for `stage`/`source-inventory` jobs.
+ *
+ * Only `stage` and `source-inventory` are ever produced by a session writer:
+ * `writeStageExecutionSessionStarted` defaults to `stage`, and source-inventory
+ * passes `jobType: "source-inventory"`. Graph-less jobs (Build Plan draft/
+ * improvement, benchmark-question drafting) record `LocalJobRun` instead — see
+ * `LocalJobTypeSchema` in `schemas/jobs.ts` — so their kinds never appear here.
+ *
+ * job_type -> preserved shell_type map (`PreservedShellTypeSchema` below):
+ *   stage             -> "stage-execution"
+ *   source-inventory  -> "stage-execution"
+ * The other `PreservedShellTypeSchema` members are driven by their own job
+ * substrate, NOT by an `AgentJobType`:
+ *   build-plan-authoring        <- LocalJobRun "build-plan-draft"
+ *   build-plan-improvement      <- LocalJobRun "build-plan-improvement"
+ *   benchmark-question-draft    <- LocalJobRun "benchmark-question-draft"
+ *   test-judge                  <- the verify/judge path (verify-execution.ts),
+ *                                  which is not an AgentJobType at all.
+ */
+export const AgentJobTypeSchema = z.enum([
+    "stage",
+    "source-inventory",
+]);
+export const StageExecutionSessionSchema = z.object({
+    kind: z.literal("interf-stage-execution-session"),
+    version: z.literal(1),
+    // `.default("stage")` lets every session written before this discriminator
+    // existed parse as a stage job, and keeps all current stage/source-inventory
+    // writers byte-identical without passing job_type explicitly.
+    job_type: AgentJobTypeSchema.default("stage"),
+    generated_at: z.string().min(1),
+    updated_at: z.string().min(1),
+    project: ProjectIdSchema,
+    project_intent: ProjectIntentSchema.nullable(),
+    context_graph_path: z.string().min(1),
+    build_plan: BuildPlanIdSchema,
+    build_run_id: z.string().min(1).nullable(),
+    // Stage identity: present for `stage`/`source-inventory` jobs (both produced
+    // here today). Kept nullable so a future non-stage `AgentJobType` could carry
+    // null without a schema migration.
+    stage_id: RuntimeStageSchema.nullable(),
+    stage_label: z.string().min(1).nullable(),
+    contract_type: RuntimeContractTypeSchema.nullable(),
+    stage_run_id: z.string().min(1),
+    attempt: z.number().int().min(1),
+    status: ExecutionStatusSchema,
+    executor: RuntimeExecutorInfoSchema,
+    shell: z.object({
+        root_path: z.string().min(1),
+        workspace_manifest_path: z.string().min(1).nullable(),
+        preserved_shell_manifest_path: z.string().min(1).nullable(),
+        replay_ready: z.boolean(),
+        // Why a non-replayable session is still truthful. Null while the shell is
+        // live; set when the shell was intentionally pruned (e.g. a successful
+        // attempt under `on-failure` retention) so "session exists" never implies a
+        // replay shell that is gone. When set, `replay_ready` is false and
+        // `preserved_shell_manifest_path` is null. `.default(null)` lets sessions
+        // written before this field existed parse without it.
+        retention_reason: z.string().min(1).nullable().default(null),
+    }).strict(),
+    logs: z.object({
+        prompt_path: z.string().min(1).nullable(),
+        event_stream_path: z.string().min(1).nullable(),
+        status_path: z.string().min(1).nullable(),
+    }).strict(),
+    runtime_files: z.object({
+        project_path: z.string().min(1).nullable(),
+        contract_path: z.string().min(1).nullable(),
+        paths_path: z.string().min(1).nullable(),
+        source_locator_path: z.string().min(1).nullable(),
+        source_manifest_path: z.string().min(1).nullable(),
+        source_state_path: z.string().min(1).nullable(),
+        stage_inputs_path: z.string().min(1).nullable(),
+        expected_inputs_path: z.string().min(1).nullable(),
+        reviewed_inputs_path: z.string().min(1).nullable(),
+        previous_attempts_path: z.string().min(1).nullable(),
+        retry_feedback_path: z.string().min(1).nullable(),
+        last_validation_failure_path: z.string().min(1).nullable(),
+        verifier_path: z.string().min(1).nullable(),
+        stage_evidence_path: z.string().min(1).nullable(),
+        // Best-effort transcript of the agent's reasoning/thinking spans, teed from
+        // the live event stream during the run (one JSON object per line). Null when
+        // the executor emitted no reasoning. This is the inspectable "full
+        // transcript" reference for a preserved attempt.
+        reasoning_path: z.string().min(1).nullable().default(null),
+    }).strict(),
+    artifacts: z.object({
+        reads: z.array(ExecutionShellArtifactMountSchema).default([]),
+        writes: z.array(ExecutionShellArtifactMountSchema).default([]),
+    }).strict(),
+    validation_attempts: z.array(StageExecutionSessionValidationAttemptSchema).default([]),
+    summary: z.string().min(1).nullable(),
+    error: z.string().min(1).nullable(),
+}).strict();
+export const RuntimeProjectContextSchema = z.object({
+    id: ProjectIdSchema,
+    intent: z.string().min(1).nullable(),
+}).strict();
 export const RuntimeStageInstructionsSchema = z.object({
     stage_skill_dir: z.string().regex(InterfIdPattern),
     effective_mode: z.enum(["builtin", "extend", "override"]),
@@ -143,6 +289,7 @@ export const RuntimeStageContractSchema = z.object({
     run_id: z.string(),
     target_type: RuntimeTargetTypeSchema,
     target_name: z.string(),
+    project: RuntimeProjectContextSchema,
     build_plan: z.object({
         id: BuildPlanIdSchema,
         stage_index: z.number().nullable(),
@@ -164,6 +311,7 @@ export const RuntimeStageContractSchema = z.object({
             checks: z.array(CheckSchema),
         }).strict()).default([]),
     }),
+    context_checks: z.array(BuildPlanContextCheckDraftSchema).default([]),
     policies: z.object({
         execution_mode: z.literal("deterministic"),
         status_prefixes: z.array(z.string()),
@@ -188,7 +336,7 @@ export const ExecutionStageLedgerSchema = z.object({
     stage: RuntimeStageSchema,
     stage_label: z.string(),
     contract_type: RuntimeContractTypeSchema,
-    status: z.enum(["running", "succeeded", "failed"]),
+    status: ExecutionStatusSchema,
     executor: RuntimeExecutorInfoSchema,
     started_at: z.string(),
     updated_at: z.string(),
@@ -235,8 +383,12 @@ export const ExecutionInventoryEntrySchema = z.object({
     metadata: JsonRecordSchema.optional(),
 }).strict();
 export const ExecutionInventorySchema = z.object({
-    kind: z.literal("context-graph-runtime-ledger").optional(),
-    version: z.number().int().min(1).optional(),
+    // Both discriminators are always written by the only producers
+    // (`emptyExecutionInventory`/`buildInventoryFromEntries` in
+    // runtime-inventory.ts), so they are required, not optional. A persisted
+    // inventory missing `kind`/`version` is malformed and must fail to parse.
+    kind: z.literal("context-graph-runtime-ledger"),
+    version: z.literal(1),
     stage: RuntimeStageSchema.optional(),
     entries: z.array(ExecutionInventoryEntrySchema),
     total: z.number().int().nonnegative(),
@@ -284,6 +436,8 @@ export const PreservedShellTypeSchema = z.enum([
     "stage-execution",
     "build-plan-authoring",
     "build-plan-improvement",
+    "benchmark-question-draft",
+    "test-judge",
 ]);
 export const PreservedShellStateSchema = z.object({
     kind: z.literal("interf-preserved-shell"),
@@ -319,6 +473,10 @@ export const BuildPlanImprovementLoopRecordSchema = z.object({
     prompt_log_path: z.string(),
     event_log_path: z.string(),
     status_log_path: z.string(),
+    // The agent's reasoning transcript inside the preserved improvement shell
+    // (runtime/agent-reasoning.jsonl), so the record indexes the reasoning the
+    // same way a stage session exposes reasoning_path. Nullable for older records.
+    reasoning_path: z.string().nullable().default(null),
     preserved_shell_manifest_path: z.string().nullable(),
     validation: BuildPlanPackageValidationSchema.nullable(),
 });

package/dist/packages/runtime/build/native-entrypoint.d.ts

@@ -0,0 +1,2 @@
+import type { AgentExecutor } from "../agents/lib/executors.js";
+export declare function createNativeEntrypointExecutor(): AgentExecutor;

package/dist/packages/runtime/build/native-entrypoint.js

@@ -0,0 +1,286 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+import { appendAgentEventLog, } from "../agents/lib/logs.js";
+import { ExpectedInputsFileSchema, ResourceRefSchema, SourceManifestSchema, } from "../../contracts/lib/schema.js";
+import { normalizeLayerPath } from "../../contracts/lib/context-graph-layer.js";
+import { listFilesRecursive, } from "../../contracts/utils/filesystem.js";
+import { parseJsonFrontmatter, renderJsonFrontmatter, } from "../../contracts/utils/parse.js";
+function markdownTitle(path, content) {
+    const parsed = parseJsonFrontmatter(content);
+    const title = parsed && typeof parsed.frontmatter.title === "string"
+        ? parsed.frontmatter.title.trim()
+        : "";
+    if (title)
+        return title;
+    const body = parsed?.body ?? content;
+    const heading = body.split(/\r?\n/).find((line) => /^#{1,3}\s+\S/.test(line));
+    if (heading)
+        return heading.replace(/^#{1,3}\s+/, "").trim();
+    return basename(path, extname(path));
+}
+function markdownSummary(content) {
+    const parsed = parseJsonFrontmatter(content);
+    if (parsed && typeof parsed.frontmatter.summary === "string" && parsed.frontmatter.summary.trim()) {
+        return parsed.frontmatter.summary.trim();
+    }
+    const body = parsed?.body ?? content;
+    const paragraph = body
+        .split(/\n\s*\n/)
+        .map((block) => block.replace(/\s+/g, " ").trim())
+        .find((block) => block.length > 0 && !block.startsWith("#"));
+    if (!paragraph)
+        return null;
+    return paragraph.length > 180 ? `${paragraph.slice(0, 177)}...` : paragraph;
+}
+function safeReadJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function readExpectedInputs(shellRoot) {
+    const parsed = ExpectedInputsFileSchema.safeParse(safeReadJson(join(shellRoot, "runtime", "expected-inputs.json")));
+    return parsed.success ? parsed.data.expected : [];
+}
+function readSourceManifest(shellRoot) {
+    const raw = safeReadJson(join(shellRoot, "runtime", "source-manifest.json"));
+    const parsed = SourceManifestSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+function readProjectIntent(shellRoot) {
+    const contract = safeReadJson(join(shellRoot, "runtime", "stage-contract.json"));
+    const intent = typeof contract?.project?.intent === "string" ? contract.project.intent.trim() : "";
+    return intent || "Build a task-specific Context Graph from the Project Source.";
+}
+function collectMarkdownResources(shellRoot, directory) {
+    const root = join(shellRoot, directory);
+    if (!existsSync(root))
+        return [];
+    return listFilesRecursive(root, (filePath) => filePath.endsWith(".md"))
+        .sort((left, right) => left.localeCompare(right))
+        .map((filePath) => {
+        const path = normalizeLayerPath(relative(shellRoot, filePath));
+        const content = readFileSync(filePath, "utf8");
+        const parsed = parseJsonFrontmatter(content);
+        const sourceRefs = sourceRefsFromFrontmatter(parsed?.frontmatter ?? {});
+        return ResourceRefSchema.parse({
+            id: `${directory}:${path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")}`,
+            role: directory === "knowledge" ? "knowledge" : "summary",
+            kind: directory === "knowledge" ? "knowledge.note" : "summary.note",
+            label: markdownTitle(path, content),
+            path,
+            source_refs: sourceRefs,
+            links: [],
+            metadata: {
+                ...(markdownSummary(content) ? { summary: markdownSummary(content) } : {}),
+            },
+        });
+    });
+}
+function sourceRefsFromFrontmatter(frontmatter) {
+    const values = [
+        frontmatter.source_refs,
+        frontmatter.source_ref,
+        frontmatter.source_path,
+        frontmatter.source,
+    ];
+    const refs = values.flatMap((value) => {
+        if (typeof value === "string" && value.trim())
+            return [value.trim()];
+        if (Array.isArray(value)) {
+            return value
+                .filter((item) => typeof item === "string" && item.trim().length > 0)
+                .map((item) => item.trim());
+        }
+        return [];
+    });
+    return [...new Set(refs)];
+}
+function collectSourceRefs(expected, manifest, notes) {
+    const refs = new Set();
+    for (const resource of [...expected, ...notes]) {
+        for (const ref of resource.source_refs)
+            refs.add(ref);
+    }
+    for (const file of manifest?.files ?? [])
+        refs.add(file.path);
+    return [...refs].sort((left, right) => left.localeCompare(right));
+}
+function markdownLink(resource) {
+    const path = resource.path ?? "";
+    return path ? `[${resource.label}](${path})` : resource.label;
+}
+function renderResourceList(resources, limit) {
+    return resources.slice(0, limit).map((resource) => {
+        const summary = typeof resource.metadata?.summary === "string" ? resource.metadata.summary : null;
+        return `- ${markdownLink(resource)}${summary ? ` - ${summary}` : ""}`;
+    });
+}
+function renderSourceRefList(sourceRefs, limit) {
+    return sourceRefs.slice(0, limit).map((ref) => `- \`${ref}\``);
+}
+function writeReviewedInputs(shellRoot, expected) {
+    const now = new Date().toISOString();
+    const reviewed = expected.map((resource) => ({
+        resource_id: resource.id,
+        decision: "used",
+        source_refs: resource.source_refs.length > 0 ? resource.source_refs : [resource.path ?? resource.id],
+        metadata: {
+            reviewer: "interf-native-entrypoint",
+        },
+    }));
+    writeFileSync(join(shellRoot, "runtime", "reviewed-inputs.json"), `${JSON.stringify({
+        kind: "interf-stage-reviewed-inputs",
+        version: 1,
+        generated_at: now,
+        stage_id: "entrypoint",
+        reviewed,
+    }, null, 2)}\n`);
+}
+function writeEntrypointOutputs(shellRoot) {
+    const intent = readProjectIntent(shellRoot);
+    const expected = readExpectedInputs(shellRoot);
+    const manifest = readSourceManifest(shellRoot);
+    const knowledge = collectMarkdownResources(shellRoot, "knowledge");
+    const summaries = collectMarkdownResources(shellRoot, "summaries");
+    const expectedByPath = new Map(expected.map((resource) => [resource.path, resource]));
+    const knowledgeForRouting = knowledge.length > 0
+        ? knowledge
+        : expected.filter((resource) => resource.role === "knowledge");
+    const notesForRefs = [...knowledgeForRouting, ...summaries, ...expectedByPath.values()];
+    const sourceRefs = collectSourceRefs(expected, manifest, notesForRefs);
+    const generatedAt = new Date().toISOString();
+    const topKnowledge = knowledgeForRouting.slice(0, 12);
+    const topSummaries = summaries.slice(0, 12);
+    const links = [
+        "artifacts/agent-handoff.md",
+        ...topKnowledge.map((resource) => resource.path).filter((path) => Boolean(path)),
+        ...topSummaries.slice(0, 6).map((resource) => resource.path).filter((path) => Boolean(path)),
+    ];
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    writeFileSync(join(shellRoot, "home.md"), [
+        renderJsonFrontmatter({
+            title: "Context Graph Home",
+            summary: "Primary agent entrypoint for the prepared Context Graph.",
+            task: intent,
+            source_refs: sourceRefs,
+            links,
+            generated_by: "interf-native-entrypoint",
+        }),
+        "",
+        "# Context Graph Home",
+        "",
+        `Project intent: ${intent}`,
+        "",
+        "Start with the task handoff, then follow the linked knowledge notes and summaries. Generated notes are routing and synthesis; original Source and source refs remain the authority for exact claims.",
+        "",
+        "## Start Here",
+        "",
+        "- [Agent handoff](artifacts/agent-handoff.md)",
+        ...renderResourceList(topKnowledge, 10),
+        "",
+        "## Coverage Routes",
+        "",
+        ...(topSummaries.length > 0
+            ? renderResourceList(topSummaries, 10)
+            : ["- No summary notes were available to route."]),
+        "",
+        "## Source Refs",
+        "",
+        ...(sourceRefs.length > 0
+            ? renderSourceRefList(sourceRefs, 20)
+            : ["- No source refs were recorded."]),
+        "",
+    ].join("\n"));
+    writeFileSync(join(shellRoot, "artifacts", "agent-handoff.md"), [
+        renderJsonFrontmatter({
+            title: "Agent Handoff",
+            summary: "Task-specific route through the prepared Context Graph.",
+            task: intent,
+            source_refs: sourceRefs,
+            handoff_type: "agent-context-handoff",
+            truth_mode: "source-backed routing",
+            verification_state: "Ready to use; follow original Source and source refs for exact claims.",
+            caveats: [
+                "Generated summaries and knowledge notes are prepared context, not replacement source material.",
+                "Use original Source and source refs when exact wording, table values, chart reads, dates, or provenance-sensitive claims matter.",
+            ],
+            links,
+            generated_at: generatedAt,
+            generated_by: "interf-native-entrypoint",
+        }),
+        "",
+        "# Agent Handoff",
+        "",
+        `Task: ${intent}`,
+        "",
+        "Use this Context Graph as prepared context. For exact claims, follow the original Source and source refs from the notes below back to the source files.",
+        "",
+        "## Useful Knowledge",
+        "",
+        ...(topKnowledge.length > 0
+            ? renderResourceList(topKnowledge, 12)
+            : ["- No knowledge notes were available."]),
+        "",
+        "## Coverage And Source Routes",
+        "",
+        ...(topSummaries.length > 0
+            ? renderResourceList(topSummaries, 12)
+            : ["- No summary notes were available."]),
+        "",
+        "## Source Refs To Recheck",
+        "",
+        ...(sourceRefs.length > 0
+            ? renderSourceRefList(sourceRefs, 30)
+            : ["- No source refs were recorded."]),
+        "",
+    ].join("\n"));
+    writeReviewedInputs(shellRoot, expected);
+}
+function appendStatus(options, line) {
+    appendAgentEventLog(options?.eventLogPath, {
+        type: "native-stage.status",
+        message: line,
+    });
+    options?.onStatus?.(line);
+    if (options?.statusLogPath) {
+        appendFileSync(options.statusLogPath, `${line}\n`);
+    }
+}
+function appendNativeEvent(options, event) {
+    appendAgentEventLog(options?.eventLogPath, {
+        type: "native-stage.event",
+        ...event,
+    });
+}
+export function createNativeEntrypointExecutor() {
+    return {
+        kind: "managed",
+        name: "interf-native-entrypoint",
+        displayName: "Interf native entrypoint",
+        command: null,
+        execute(rootPath, _prompt, options) {
+            try {
+                appendNativeEvent(options, { phase: "started", root_path: rootPath });
+                appendStatus(options, "STATUS: loaded entrypoint stage.");
+                appendStatus(options, "STATUS: reading declared inputs.");
+                writeEntrypointOutputs(rootPath);
+                appendStatus(options, "STATUS: writing declared outputs.");
+                appendStatus(options, "DONE: entrypoint complete.");
+                appendNativeEvent(options, { phase: "succeeded", root_path: rootPath });
+                return Promise.resolve(0);
+            }
+            catch (error) {
+                appendStatus(options, `ERROR: native entrypoint failed: ${error instanceof Error ? error.message : String(error)}`);
+                appendNativeEvent(options, {
+                    phase: "failed",
+                    root_path: rootPath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return Promise.resolve(1);
+            }
+        },
+    };
+}

package/dist/packages/runtime/build/runtime-contracts.js

@@ -4,6 +4,7 @@ export function buildRuntimeStageContract(options) {
     const buildPlanNotes = options.buildPlanNotes ?? [];
     return {
         instructions: options.instructions,
+        project: options.project,
         counts: {
             ...(options.counts ?? {}),
             local_skill_docs: localSkillDocs.length,
@@ -19,16 +20,21 @@ export function buildRuntimeStageContract(options) {
             writes: options.stageWriteArtifacts,
             write_contracts: options.stageWriteContracts ?? [],
         },
+        context_checks: options.contextChecks ?? [],
         policies: {
             execution_mode: "deterministic",
             status_prefixes: ["STATUS:", "DONE:", "BLOCKED:", "ERROR:"],
             notes: [
                 `This is the "${options.stageLabel}" stage for the context graph "${options.contextGraphName}".`,
+                options.project.intent
+                    ? `Project intent: ${options.project.intent}`
+                    : "Project intent is not set. Keep outputs source-grounded and explicitly note missing task focus where it limits usefulness.",
                 "The Build Plan is the authoritative plan layer for this run.",
-                `Use \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` as the deterministic requested Artifact contract for this context graph.`,
-                "Honor the declared read and write artifacts instead of inventing a parallel process.",
+                `Use \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` as the deterministic requested output contract for this context graph.`,
+                "Use `context_checks[]` only as legacy coverage-goal context; StageManifest and GraphManifest metrics are the readiness proof.",
+                "Honor the declared read and write outputs instead of inventing a parallel process.",
                 "Only create or update files that fall under the declared write targets for this stage.",
-                "Before emitting DONE, satisfy every check listed under `artifacts.write_contracts[]` for the write Artifacts this stage owns.",
+                "Before emitting DONE, satisfy every check listed under `artifacts.write_contracts[]` for the write outputs this stage owns.",
                 "Interf writes `.interf/runtime/` ledgers such as run, state, health, and view-spec files. Read them if needed, but do not create, edit, or replace them in this stage unless the contract explicitly marks a runtime artifact as stage-owned.",
                 "Keep scratch extraction commands single-purpose and non-destructive. Avoid wildcard cleanup and multi-command chains.",
                 ...buildPlanNotes,

package/dist/packages/runtime/build/runtime-log-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function promptLogPath(dirPath: string, runId: string): string;
+export declare function eventLogPath(dirPath: string, runId: string): string;
+export declare function statusLogPath(dirPath: string, runId: string): string;

package/dist/packages/runtime/build/runtime-log-paths.js

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+import { contextGraphRuntimeLogsRoot } from "./context-graph-paths.js";
+// Canonical per-run log-file builders for stage execution without a shell.
+// They share the runtime logs root with the archived stage contract
+// (contextGraphRuntimeArchivedStageContractPath) and use the same
+// `<runId>.<suffix>` naming. Shell-backed runs use the parallel
+// shell-workspace builders instead.
+export function promptLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.prompt.txt`);
+}
+export function eventLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.events.ndjson`);
+}
+export function statusLogPath(dirPath, runId) {
+    return join(contextGraphRuntimeLogsRoot(dirPath), `${runId}.status.log`);
+}

package/dist/packages/runtime/build/runtime-prompt.js

@@ -21,12 +21,14 @@ export function buildStagePrompt(instructions, contractPath, statusLines) {
         "The user has already invoked this stage through the Interf CLI. Execute it now.",
         "Do not ask what the user wants, offer help, list tools, or wait for another instruction.",
         `Read \`${contractPath}\` first. It is the authoritative contract for this stage.`,
-        "If `runtime/paths.json` exists in this shell, read it next. It maps Build Plan Artifact ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
-        "For file Artifact mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
+        "Use `project.intent` in that contract as the task focus for task-aware summaries, knowledge, entrypoints, and task note work.",
+        "Use `runtime/expected-inputs.json` as the coverage contract and write `runtime/reviewed-inputs.json` before DONE.",
+        "If `runtime/paths.json` exists in this shell, read it next. It maps Build Plan output ids onto the shell-local `inputs/` and `outputs/` mounts for this stage.",
+        "For file output mounts, `runtime/paths.json` also gives the exact file path inside the `inputs/` or `outputs/` mount root.",
         "Before DONE, run `node runtime/check-stage.mjs` from the shell root and fix outputs until it prints `VALID:`.",
         "Honor the contract's counts, artifact paths, and policies instead of inventing another Build Plan.",
-        "The contract's `artifacts.write_contracts[]` lists the checks Interf will run against the Artifacts this stage writes. Treat those checks as required output constraints.",
-        "Read only the files named by the contract's `artifacts.reads` list, `runtime/source-manifest.json`, `runtime/stage-inputs.json`, and any paths those files explicitly assign to this stage. `runtime/source-state.json` is compatibility-only and is not stage authority.",
+        "The contract's `artifacts.write_contracts[]` lists the checks Interf will run against the outputs this stage writes. Treat those checks as required output constraints.",
+        "Read only the files named by the contract's `artifacts.reads` list, `runtime/source-manifest.json`, `runtime/stage-inputs.json`, `runtime/expected-inputs.json`, and any paths those files explicitly assign to this stage. `runtime/source-state.json` is compatibility-only and is not stage authority.",
         "Prefer direct file-reading and search tools over shell commands when you inspect inputs, docs, or generated outputs.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` for routine file inspection if a native read/search tool can do the same job.",
         "If the contract lists `instructions.local_docs`, open every one of those files before you write artifacts or declare the stage complete.",