@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/runtime.js

@@ -1,11 +1,11 @@
 import { resolve } from "node:path";
-import { RunListingCache, ReadinessCache, MtimeListingCache, BuildPlanListingCache, } from "./runtime-caches.js";
+import { RunListingCache, ReadinessCache, MtimeListingCache, BuildPlanListingCache, ContextGraphResourceCache, } from "./runtime-caches.js";
 import { LocalServiceHealthSchema, } from "./schemas/index.js";
 import { buildLocalServiceUrl, } from "./service/routes.js";
 import { resolveConfiguredSourceFolderPath } from "../projects/source-config.js";
 import { getExecutorStatus, getAgentsRegistry, patchAgentsRoleMap, registerCustomAgent, selectExecutor, setAgentPrefs, unregisterCustomAgent, } from "./runtime-executor.js";
 import { applyBuildPlanChange, getBuildPlanResource, listBuildPlans, } from "./runtime-build-plans.js";
-import { computeProjectReadiness, getProject, getProjectReadiness, getReadiness, getContextGraph, listProjectReadiness, listProjects, listReadiness, listSourceFiles, listContextGraphs, getLatestContextGraph, } from "./runtime-project-reads.js";
+import { computeProjectReadiness, getProject, getProjectReadiness, getReadiness, getContextGraph, getContextGraphHandoff, listProjectReadiness, listProjects, listReadiness, listSourceFiles, listContextGraphs, getLatestContextGraph, listLatestContextGraphStageSessions, } from "./runtime-project-reads.js";
 import { applyReset, defaultProjectId, ensureContextGraphForRun, resolveProjectConfig, } from "./runtime-project-mutations.js";
 import { createBuildPlanAuthoringRun, createBenchmarkQuestionDraftRun, finalizeInterruptedJobRuns, getJob, getJobEvents, listJobs, } from "./runtime-jobs.js";
 import { cancelBuildRun, createBuildRun, expireIdempotencyKeyForTesting, finalizeInterruptedBuildRuns, findIdempotentBuildRun, getBuildRun, getBuildRunArtifacts, getBuildRunEvents, getBuildRunEvidence, listBuildRuns, listBuildRunsForProject, recordIdempotentBuildRun, } from "./runtime-build-runs.js";
@@ -88,6 +88,14 @@ export class LocalServiceRuntime {
     readinessCache = new ReadinessCache();
     sourceFilesCache = new MtimeListingCache();
     buildPlanListingCache = new BuildPlanListingCache();
+    /**
+     * Per-Build-run Context Graph resource cache. A succeeded Build's graph is
+     * immutable, so the full `ContextGraphResource` (readiness join, semantic
+     * graph, evidence, validation) is memoized keyed by run id + graph-manifest
+     * mtime. Busted on Build completion and Build Plan change via
+     * `invalidateProject` on the matching write paths.
+     */
+    contextGraphResourceCache = new ContextGraphResourceCache();
     constructor(options) {
         this.host = options.host;
         this.port = options.port;
@@ -280,6 +288,12 @@ export class LocalServiceRuntime {
     getLatestContextGraph(projectDataDir, projectName) {
         return getLatestContextGraph(this, projectDataDir, projectName);
     }
+    listLatestContextGraphStageSessions(projectDataDir, projectName) {
+        return listLatestContextGraphStageSessions(this, projectDataDir, projectName);
+    }
+    getContextGraphHandoff(projectDataDir, projectName) {
+        return getContextGraphHandoff(this, projectDataDir, projectName);
+    }
     // ─── Build Plans ───────────────────────────────────────────────────
     listBuildPlans(projectDataDir) {
         return listBuildPlans(this, projectDataDir);

package/dist/packages/runtime/schemas/actions.d.ts

@@ -369,6 +369,9 @@ export declare const ActionProposalResourceSchema: z.ZodDiscriminatedUnion<[z.Zo
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";
@@ -436,6 +439,9 @@ export declare const ActionProposalResourceSchema: z.ZodDiscriminatedUnion<[z.Zo
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -535,6 +541,9 @@ export declare const ActionProposalResourceSchema: z.ZodDiscriminatedUnion<[z.Zo
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";
@@ -602,6 +611,9 @@ export declare const ActionProposalResourceSchema: z.ZodDiscriminatedUnion<[z.Zo
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -916,6 +928,9 @@ export declare const ActionProposalListResponseSchema: z.ZodObject<{
                             frontmatter_required_keys: "frontmatter_required_keys";
                             frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                             source_refs_required: "source_refs_required";
+                            summary_backlinks_present: "summary_backlinks_present";
+                            knowledge_web_connectivity: "knowledge_web_connectivity";
+                            graph_notes_connected: "graph_notes_connected";
                             wikilinks_valid: "wikilinks_valid";
                             must_not_contain: "must_not_contain";
                             must_contain: "must_contain";
@@ -983,6 +998,9 @@ export declare const ActionProposalListResponseSchema: z.ZodObject<{
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";
@@ -1082,6 +1100,9 @@ export declare const ActionProposalListResponseSchema: z.ZodObject<{
                             frontmatter_required_keys: "frontmatter_required_keys";
                             frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                             source_refs_required: "source_refs_required";
+                            summary_backlinks_present: "summary_backlinks_present";
+                            knowledge_web_connectivity: "knowledge_web_connectivity";
+                            graph_notes_connected: "graph_notes_connected";
                             wikilinks_valid: "wikilinks_valid";
                             must_not_contain: "must_not_contain";
                             must_contain: "must_contain";
@@ -1149,6 +1170,9 @@ export declare const ActionProposalListResponseSchema: z.ZodObject<{
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";

package/dist/packages/runtime/schemas/agents.d.ts

@@ -29,6 +29,34 @@ export declare const LocalExecutorStatusSchema: z.ZodObject<{
 export declare const LocalExecutorSelectRequestSchema: z.ZodObject<{
     agent: z.ZodString;
 }, z.core.$strict>;
+/** `POST /v1/agents` — register a custom execution agent. */
+export declare const CustomAgentRegisterRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    display_name: z.ZodString;
+    command: z.ZodString;
+}, z.core.$strict>;
+/**
+ * `PATCH /v1/agents/role-map` — map canonical roles to agent names. Keys are
+ * role ids; values are agent names, or `""` to clear a mapping. The non-empty
+ * mappings are applied; clears remove the role. Validated here so a non-string
+ * value is rejected at the boundary with a parse error.
+ */
+export declare const AgentRoleMapPatchSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * `PATCH /v1/agents/<name>` — update an agent's stored prefs. Mirrors the wire
+ * tolerance of the prior handler: `env_vars` is an object of string→string (or
+ * null to clear); `model`/`effort` accept a string, `null`, or `""`. Reuses the
+ * canonical `AgentPrefsSchema` env_vars value rule. The route normalizes `""`
+ * and an empty `env_vars` map exactly as before after this parse.
+ */
+export declare const AgentPrefsPatchSchema: z.ZodObject<{
+    env_vars: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    effort: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type CustomAgentRegisterRequest = z.infer<typeof CustomAgentRegisterRequestSchema>;
+export type AgentRoleMapPatch = z.infer<typeof AgentRoleMapPatchSchema>;
+export type AgentPrefsPatch = z.infer<typeof AgentPrefsPatchSchema>;
 export declare const InterfMcpServerSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         "mcp-stdio": "mcp-stdio";

package/dist/packages/runtime/schemas/agents.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { AgentPrefsSchema } from "../../contracts/lib/schema.js";
 import { LocalJobAgentSchema } from "./jobs.js";
 export const LocalExecutorOptionSchema = LocalJobAgentSchema.extend({
     current: z.boolean(),
@@ -15,6 +16,38 @@ export const LocalExecutorStatusSchema = z.object({
 export const LocalExecutorSelectRequestSchema = z.object({
     agent: z.string().min(1),
 }).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// Agent registry request bodies — parsed at the route boundary so the agent
+// POST/PATCH handlers validate against one declared shape instead of
+// hand-rolled `typeof` checks (matching the projects/build-plans routes).
+// ───────────────────────────────────────────────────────────────────────────
+/** `POST /v1/agents` — register a custom execution agent. */
+export const CustomAgentRegisterRequestSchema = z.object({
+    name: z.string().min(1),
+    display_name: z.string().min(1),
+    command: z.string().min(1),
+}).strict();
+/**
+ * `PATCH /v1/agents/role-map` — map canonical roles to agent names. Keys are
+ * role ids; values are agent names, or `""` to clear a mapping. The non-empty
+ * mappings are applied; clears remove the role. Validated here so a non-string
+ * value is rejected at the boundary with a parse error.
+ */
+export const AgentRoleMapPatchSchema = z.record(z.string(), z.string());
+/**
+ * `PATCH /v1/agents/<name>` — update an agent's stored prefs. Mirrors the wire
+ * tolerance of the prior handler: `env_vars` is an object of string→string (or
+ * null to clear); `model`/`effort` accept a string, `null`, or `""`. Reuses the
+ * canonical `AgentPrefsSchema` env_vars value rule. The route normalizes `""`
+ * and an empty `env_vars` map exactly as before after this parse.
+ */
+export const AgentPrefsPatchSchema = z.object({
+    // Same env_vars value rule as the canonical AgentPrefsSchema, made nullable so
+    // an explicit `null` clears prefs (the route's existing tolerance).
+    env_vars: AgentPrefsSchema.shape.env_vars.unwrap().nullable().optional(),
+    model: z.string().nullable().optional(),
+    effort: z.string().nullable().optional(),
+}).strict();
 export const InterfMcpServerSchema = z.object({
     kind: z.enum(["mcp-stdio", "skill", "http"]),
     label: z.string().min(1),

package/dist/packages/runtime/schemas/build-plans.d.ts

@@ -50,6 +50,9 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";
@@ -117,6 +120,9 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -140,7 +146,7 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
             output?: {
                 checks: {
                     id: string;
-                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                     required: boolean;
                     description?: string | undefined;
                     params?: Record<string, unknown> | undefined;
@@ -172,7 +178,7 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
             };
             checks: {
                 id: string;
-                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                 required: boolean;
                 description?: string | undefined;
                 params?: Record<string, unknown> | undefined;
@@ -207,7 +213,7 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
             output?: {
                 checks: {
                     id: string;
-                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                     required: boolean;
                     description?: string | undefined;
                     params?: Record<string, unknown> | undefined;
@@ -261,7 +267,7 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
             };
             checks: {
                 id: string;
-                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                 required: boolean;
                 description?: string | undefined;
                 params?: Record<string, unknown> | undefined;
@@ -282,6 +288,13 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
         local: "local";
     }>>;
     built_in: z.ZodDefault<z.ZodBoolean>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        builtin: "builtin";
+        user: "user";
+        local: "local";
+    }>>;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     active_for_projects: z.ZodDefault<z.ZodArray<z.ZodString>>;
     context_checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -315,6 +328,9 @@ export declare const BuildPlanResourceSchema: z.ZodObject<{
                 frontmatter_required_keys: "frontmatter_required_keys";
                 frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                 source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";
@@ -349,6 +365,10 @@ export declare const BuildPlanChangeCreateRequestSchema: z.ZodDiscriminatedUnion
     operation: z.ZodLiteral<"remove">;
     build_plan: z.ZodString;
     confirmation: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action_type: z.ZodOptional<z.ZodLiteral<"build-plan-change">>;
+    operation: z.ZodLiteral<"save">;
+    build_plan: z.ZodString;
 }, z.core.$strict>], "operation">;
 export declare const BuildPlanChangeResultSchema: z.ZodObject<{
     kind: z.ZodLiteral<"interf-build-plan-change-result">;
@@ -356,6 +376,7 @@ export declare const BuildPlanChangeResultSchema: z.ZodObject<{
     operation: z.ZodEnum<{
         remove: "remove";
         duplicate: "duplicate";
+        save: "save";
     }>;
     build_plan: z.ZodString;
     new_build_plan_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -397,6 +418,9 @@ export declare const BuildPlanAuthoringCreateRequestSchema: z.ZodObject<{
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -464,6 +488,9 @@ export declare const BuildPlanAuthoringCreateRequestSchema: z.ZodObject<{
                 frontmatter_required_keys: "frontmatter_required_keys";
                 frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                 source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";
@@ -516,6 +543,9 @@ export declare const BuildPlanAuthoringRuntimeRequestSchema: z.ZodObject<{
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -583,6 +613,9 @@ export declare const BuildPlanAuthoringRuntimeRequestSchema: z.ZodObject<{
                 frontmatter_required_keys: "frontmatter_required_keys";
                 frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                 source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";
@@ -602,6 +635,129 @@ export declare const BuildPlanAuthoringRuntimeRequestSchema: z.ZodObject<{
     hint: z.ZodOptional<z.ZodString>;
     source_folder_path: z.ZodString;
 }, z.core.$strict>;
+export declare const ProjectBuildPlanAuthoringCreateRequestSchema: z.ZodObject<{
+    checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodString>;
+        evidence_expectation: z.ZodOptional<z.ZodString>;
+        backed_by_artifact_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    label: z.ZodString;
+    context_checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodString>;
+        evidence_expectation: z.ZodOptional<z.ZodString>;
+        backed_by_artifact_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    requested_artifacts: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        purpose: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            label: z.ZodString;
+        }, z.core.$strict>]>>>;
+        output: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            shape: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"path">;
+                path: z.ZodString;
+                artifact_kind: z.ZodEnum<{
+                    file: "file";
+                    directory: "directory";
+                }>;
+            }, z.core.$strict>>;
+            checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    file_exists: "file_exists";
+                    source_manifest_valid: "source_manifest_valid";
+                    min_file_count: "min_file_count";
+                    min_file_count_matches_source: "min_file_count_matches_source";
+                    source_summary_folders: "source_summary_folders";
+                    source_page_coverage: "source_page_coverage";
+                    frontmatter_valid: "frontmatter_valid";
+                    frontmatter_required_keys: "frontmatter_required_keys";
+                    frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
+                    source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
+                    wikilinks_valid: "wikilinks_valid";
+                    must_not_contain: "must_not_contain";
+                    must_contain: "must_contain";
+                    qa_match: "qa_match";
+                }>;
+                description: z.ZodOptional<z.ZodString>;
+                params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                required: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            stage_hint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>>;
+    user_prep_instructions: z.ZodOptional<z.ZodString>;
+    source_context: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        summary: z.ZodOptional<z.ZodString>;
+        items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            kind: z.ZodOptional<z.ZodString>;
+            page_count: z.ZodOptional<z.ZodNumber>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        observations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        limitations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    artifact_requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        shape: z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+            artifact_kind: z.ZodEnum<{
+                file: "file";
+                directory: "directory";
+            }>;
+        }, z.core.$strict>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                file_exists: "file_exists";
+                source_manifest_valid: "source_manifest_valid";
+                min_file_count: "min_file_count";
+                min_file_count_matches_source: "min_file_count_matches_source";
+                source_summary_folders: "source_summary_folders";
+                source_page_coverage: "source_page_coverage";
+                frontmatter_valid: "frontmatter_valid";
+                frontmatter_required_keys: "frontmatter_required_keys";
+                frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
+                source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
+                wikilinks_valid: "wikilinks_valid";
+                must_not_contain: "must_not_contain";
+                must_contain: "must_contain";
+                qa_match: "qa_match";
+            }>;
+            description: z.ZodOptional<z.ZodString>;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            required: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        stage_hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    build_plan_id: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+    base_build_plan_id: z.ZodOptional<z.ZodString>;
+    reference_build_plan_id: z.ZodOptional<z.ZodString>;
+    intent: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const BuildPlanAuthoringResultSchema: z.ZodObject<{
     status: z.ZodEnum<{
         updated: "updated";
@@ -659,6 +815,9 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                             frontmatter_required_keys: "frontmatter_required_keys";
                             frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                             source_refs_required: "source_refs_required";
+                            summary_backlinks_present: "summary_backlinks_present";
+                            knowledge_web_connectivity: "knowledge_web_connectivity";
+                            graph_notes_connected: "graph_notes_connected";
                             wikilinks_valid: "wikilinks_valid";
                             must_not_contain: "must_not_contain";
                             must_contain: "must_contain";
@@ -726,6 +885,9 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                         frontmatter_required_keys: "frontmatter_required_keys";
                         frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                         source_refs_required: "source_refs_required";
+                        summary_backlinks_present: "summary_backlinks_present";
+                        knowledge_web_connectivity: "knowledge_web_connectivity";
+                        graph_notes_connected: "graph_notes_connected";
                         wikilinks_valid: "wikilinks_valid";
                         must_not_contain: "must_not_contain";
                         must_contain: "must_contain";
@@ -749,7 +911,7 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                 output?: {
                     checks: {
                         id: string;
-                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                         required: boolean;
                         description?: string | undefined;
                         params?: Record<string, unknown> | undefined;
@@ -781,7 +943,7 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                 };
                 checks: {
                     id: string;
-                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                     required: boolean;
                     description?: string | undefined;
                     params?: Record<string, unknown> | undefined;
@@ -816,7 +978,7 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                 output?: {
                     checks: {
                         id: string;
-                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                        kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                         required: boolean;
                         description?: string | undefined;
                         params?: Record<string, unknown> | undefined;
@@ -870,7 +1032,7 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                 };
                 checks: {
                     id: string;
-                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
+                    kind: "file_exists" | "source_manifest_valid" | "min_file_count" | "min_file_count_matches_source" | "source_summary_folders" | "source_page_coverage" | "frontmatter_valid" | "frontmatter_required_keys" | "frontmatter_nonempty_keys" | "source_refs_required" | "summary_backlinks_present" | "knowledge_web_connectivity" | "graph_notes_connected" | "wikilinks_valid" | "must_not_contain" | "must_contain" | "qa_match";
                     required: boolean;
                     description?: string | undefined;
                     params?: Record<string, unknown> | undefined;
@@ -891,6 +1053,13 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
             local: "local";
         }>>;
         built_in: z.ZodDefault<z.ZodBoolean>;
+        scope: z.ZodDefault<z.ZodEnum<{
+            builtin: "builtin";
+            user: "user";
+            local: "local";
+        }>>;
+        created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        updated_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         active_for_projects: z.ZodDefault<z.ZodArray<z.ZodString>>;
         context_checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -924,6 +1093,9 @@ export declare const BuildPlanListResponseSchema: z.ZodObject<{
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";
@@ -954,6 +1126,7 @@ export type BuildPlanChangeResult = z.infer<typeof BuildPlanChangeResultSchema>;
 export type BuildPlanAuthoringArtifactRequirement = z.infer<typeof BuildPlanAuthoringArtifactRequirementSchema>;
 export type BuildPlanContextCheckDraft = z.infer<typeof BuildPlanContextCheckDraftSchema>;
 export type BuildPlanAuthoringCreateRequest = z.infer<typeof BuildPlanAuthoringCreateRequestSchema>;
+export type ProjectBuildPlanAuthoringCreateRequest = z.infer<typeof ProjectBuildPlanAuthoringCreateRequestSchema>;
 export type BuildPlanAuthoringRuntimeRequest = z.infer<typeof BuildPlanAuthoringRuntimeRequestSchema>;
 export type BuildPlanAuthoringResult = z.infer<typeof BuildPlanAuthoringResultSchema>;
 export type BuildPlanListResponse = z.infer<typeof BuildPlanListResponseSchema>;

package/dist/packages/runtime/schemas/build-plans.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { BuildPlanAuthoringBriefInputSchema, BuildPlanAuthoringBriefSchema, } from "../../build-plans/authoring/brief.js";
-import { ArtifactSchema, ContextCheckDeclarationSchema, ArtifactIdSchema, ProjectIdSchema, BuildPlanIdSchema, } from "../../contracts/lib/schema.js";
+import { ArtifactSchema, ContextCheckDeclarationSchema, ArtifactIdSchema, ProjectIdSchema, ProjectIntentSchema, BuildPlanIdSchema, } from "../../contracts/lib/schema.js";
 export { BuildPlanAuthoringArtifactRequirementSchema, BuildPlanAuthoringBriefInputSchema, BuildPlanAuthoringBriefSchema, BuildPlanContextCheckDraftSchema, RequestedArtifactSchema, SourceContextSchema, } from "../../build-plans/authoring/brief.js";
 /** Body of `POST /v1/build-plans` — save a Build Plan definition by path. */
 export const BuildPlanSaveRequestSchema = z.object({
@@ -28,6 +28,23 @@ export const BuildPlanResourceSchema = z.object({
     }).strict()).default([]),
     source_kind: z.enum(["builtin", "local"]).default("local"),
     built_in: z.boolean().default(false),
+    /**
+     * Where the Build Plan lives:
+     * - `builtin` — shipped reusable Plan (interf-default, …)
+     * - `user`    — saved to the reusable library by the user
+     * - `local`   — project-scoped (a draft for one Project, not reusable)
+     * The Build Plans library lists `builtin` + `user`; `local` plans stay with
+     * their Project until the user Saves them (promotes `local` → `user`).
+     */
+    scope: z.enum(["builtin", "user", "local"]).default("local"),
+    /**
+     * Package file timestamps (ISO 8601), so clients can sort Build Plans
+     * newest-first the way Projects sort by config mtime. `updated_at` is the
+     * package mtime; `created_at` is its birthtime (falls back to mtime). Null
+     * when the package file can't be stat'd.
+     */
+    created_at: z.string().min(1).nullable().optional(),
+    updated_at: z.string().min(1).nullable().optional(),
     active_for_projects: z.array(ProjectIdSchema).default([]),
     context_checks: z.array(ContextCheckDeclarationSchema).default([]),
     artifacts: z.array(ArtifactSchema).default([]),
@@ -62,11 +79,17 @@ export const BuildPlanChangeCreateRequestSchema = z.discriminatedUnion("operatio
         build_plan: BuildPlanIdSchema,
         confirmation: BuildPlanIdSchema,
     }).strict(),
+    z.object({
+        action_type: z.literal("build-plan-change").optional(),
+        // Promote a project-scoped (local) Build Plan to the reusable user library.
+        operation: z.literal("save"),
+        build_plan: BuildPlanIdSchema,
+    }).strict(),
 ]);
 export const BuildPlanChangeResultSchema = z.object({
     kind: z.literal("interf-build-plan-change-result"),
     version: z.literal(1),
-    operation: z.enum(["duplicate", "remove"]),
+    operation: z.enum(["duplicate", "remove", "save"]),
     build_plan: BuildPlanIdSchema,
     new_build_plan_id: BuildPlanIdSchema.nullable().optional(),
     updated_projects: z.array(ProjectIdSchema).default([]),
@@ -94,6 +117,17 @@ export const BuildPlanAuthoringCreateRequestSchema = BuildPlanAuthoringBriefInpu
 export const BuildPlanAuthoringRuntimeRequestSchema = BuildPlanAuthoringCreateRequestSchema.extend({
     source_folder_path: z.string().min(1),
 }).strict();
+export const ProjectBuildPlanAuthoringCreateRequestSchema = BuildPlanAuthoringCreateRequestSchema
+    .omit({ project: true, source_folder_path: true })
+    .extend({
+    /**
+     * Project-scoped routes default this from the saved Project intent when
+     * omitted. Clients may still override it when the draft is explicitly
+     * narrower than the Project's standing agent task.
+     */
+    intent: ProjectIntentSchema.optional(),
+})
+    .strict();
 export const BuildPlanAuthoringResultSchema = z.object({
     status: z.enum(["updated", "no-change", "invalid", "executor-failed"]),
     changed: z.boolean(),