@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/contracts/lib/schema.js

@@ -11,9 +11,19 @@ export const ProjectIdSchema = z
     .refine((value) => !RESERVED_PROJECT_IDS.has(value), "Project name is reserved.");
 export const BuildPlanIdSchema = z.string().regex(InterfIdPattern);
 /**
- * Build Plan-declared artifact identifier. Same shape as `BuildPlanIdSchema`
- * but conceptually distinct — it identifies a produced thing inside
- * one Build Plan, while `BuildPlanIdSchema` identifies the Build Plan itself.
+ * The user's agent task for a Project.
+ *
+ * Project intent is the compact, durable instruction that explains what
+ * the Context Graph must prepare the Source for. Build Plans operationalize
+ * this field, but Project owns it.
+ */
+export const ProjectIntentSchema = z.string().trim().min(1);
+/**
+ * Legacy internal output identifier. Same shape as `BuildPlanIdSchema` but
+ * conceptually distinct: it identifies a requested output inside one Build
+ * Plan, while `BuildPlanIdSchema` identifies the Build Plan itself.
+ *
+ * The exported name remains `ArtifactIdSchema` until the ABI rename lands.
  */
 export const ArtifactIdSchema = z.string().regex(InterfIdPattern);
 export const RuntimeStageSchema = z.string().regex(InterfIdPattern);
@@ -64,6 +74,10 @@ export const LocatorSchema = z.object({
 // `internal/iterations/0.23-service-variant-parking-lot.md`.
 // ───────────────────────────────────────────────────────────────────────────
 export const SourceKindSchema = z.enum(["local-folder"]);
+export const SourceBindingSchema = z.object({
+    kind: SourceKindSchema,
+    locator: z.string().min(1),
+}).strict();
 export const SourceSchema = z.object({
     id: z.string().regex(InterfIdPattern),
     kind: SourceKindSchema,
@@ -94,7 +108,7 @@ export const SourceStateSchema = z.object({
     files: z.array(SourceFileSchema),
 }).strict();
 export const SourceInspectableUnitSchema = z.object({
-    kind: z.enum(["page", "slide", "sheet", "table", "image", "section"]),
+    kind: z.enum(["file", "page", "slide", "sheet", "table", "image", "section"]),
     index: z.number().int().min(1).optional(),
     label: z.string().min(1).optional(),
 }).strict();
@@ -212,16 +226,237 @@ export const StageInputsSchema = z.object({
 export const SourceBuildMaxAttemptsSchema = z.number().int().min(1).max(5);
 export const SourceBuildMaxLoopsSchema = z.number().int().min(1).max(3);
 // ───────────────────────────────────────────────────────────────────────────
-// Check / Evidence / Ready — the locked verification vocabulary
+// Context Graph manifests — canonical coverage/runtime proof
+// ───────────────────────────────────────────────────────────────────────────
+export const ResourceRoleSchema = z.enum([
+    "source",
+    "summary",
+    "knowledge",
+    "entrypoint",
+    "diagnostic",
+    "other",
+]);
+export const MetricKeySchema = z.string().regex(/^[a-z][a-z0-9_.:-]*$/);
+export const ResourceRefSchema = z.object({
+    id: z.string().min(1),
+    role: ResourceRoleSchema,
+    kind: z.string().min(1),
+    label: z.string().min(1),
+    path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Resource paths must stay inside their root (no `..`, no absolute paths).",
+    }).optional(),
+    locator: z.string().min(1).optional(),
+    stage_id: RuntimeStageSchema.optional(),
+    source_refs: z.array(z.string().min(1)).default([]),
+    links: z.array(z.string().min(1)).default([]),
+    required: z.boolean().default(false),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+// metadata.guarantee groups a metric under one honest guarantee: "coverage" (every Source file read), "traceability" (every claim/summary/knowledge node linked). Verification (qa_match) is a separate fallible Check scope, never a coverage/traceability metric and never gates readiness.
+export const MetricCountSchema = z.object({
+    key: MetricKeySchema,
+    label: z.string().min(1),
+    value: z.number().int().min(0),
+    total: z.number().int().min(0).optional(),
+    unit: z.string().min(1).optional(),
+    primary: z.boolean().default(false),
+    issue_state: z.enum(["pass", "missing", "review", "fail"]).optional(),
+    detail: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict().superRefine((value, ctx) => {
+    if (typeof value.total === "number" && value.value > value.total) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["value"],
+            message: "Metric value cannot exceed total.",
+        });
+    }
+});
+export const ReviewedInputDecisionSchema = z.enum([
+    "used",
+    "reviewed",
+    "missing",
+    "blocked",
+    "not-relevant",
+]);
+export const ReviewedInputSchema = z.object({
+    resource_id: z.string().min(1),
+    decision: ReviewedInputDecisionSchema,
+    reason: z.string().min(1).optional(),
+    output_resource_ids: z.array(z.string().min(1)).default([]),
+    source_refs: z.array(z.string().min(1)).default([]),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const MissingInputSchema = z.object({
+    resource_id: z.string().min(1),
+    status: z.enum(["missing", "blocked", "not-relevant"]),
+    reason: z.string().min(1),
+}).strict();
+/**
+ * Stage runtime-file contracts: the `expected-inputs.json` and
+ * `reviewed-inputs.json` files a stage shell reads and writes. Defined once
+ * here so the build engine (stage-manifest writer, native entrypoint reader)
+ * and any future client validate against one shape instead of a hand-rolled
+ * parallel `interface`.
+ */
+export const ExpectedInputsFileSchema = z.object({
+    kind: z.literal("interf-stage-expected-inputs"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    stage_id: z.string().min(1),
+    expected: z.array(ResourceRefSchema),
+}).strict();
+export const ReviewedInputsFileSchema = z.object({
+    kind: z.literal("interf-stage-reviewed-inputs"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    stage_id: z.string().min(1),
+    reviewed: z.array(ReviewedInputSchema),
+}).strict();
+export const StageManifestSchema = z.object({
+    kind: z.literal("interf-stage-manifest"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    project: ProjectIdSchema,
+    run_id: z.string().min(1).nullable(),
+    build_plan: BuildPlanIdSchema,
+    stage_id: RuntimeStageSchema,
+    stage_label: z.string().min(1),
+    role: ResourceRoleSchema,
+    summary: z.string().min(1),
+    input_manifests: z.array(ResourceRefSchema).default([]),
+    expected: z.array(ResourceRefSchema).default([]),
+    reviewed: z.array(ReviewedInputSchema).default([]),
+    referenced: z.array(ResourceRefSchema).default([]),
+    missing: z.array(MissingInputSchema).default([]),
+    produced: z.array(ResourceRefSchema).default([]),
+    metrics: z.array(MetricCountSchema).default([]),
+}).strict().superRefine((value, ctx) => {
+    for (const field of ["input_manifests", "expected", "referenced", "produced"]) {
+        const seen = new Set();
+        for (const [index, resource] of value[field].entries()) {
+            if (seen.has(resource.id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [field, index, "id"],
+                    message: `Duplicate resource id: ${resource.id}.`,
+                });
+            }
+            seen.add(resource.id);
+        }
+    }
+    const expectedIds = new Set(value.expected.map((resource) => resource.id));
+    const producedIds = new Set(value.produced.map((resource) => resource.id));
+    const reviewedIds = new Set(value.reviewed.map((review) => review.resource_id));
+    const missingIds = new Set(value.missing.map((entry) => entry.resource_id));
+    for (const [index, review] of value.reviewed.entries()) {
+        if (!expectedIds.has(review.resource_id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["reviewed", index, "resource_id"],
+                message: `Reviewed input "${review.resource_id}" is not in expected inputs.`,
+            });
+        }
+        for (const [outputIndex, outputId] of review.output_resource_ids.entries()) {
+            if (!producedIds.has(outputId)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["reviewed", index, "output_resource_ids", outputIndex],
+                    message: `Reviewed input references unknown produced output "${outputId}".`,
+                });
+            }
+        }
+    }
+    for (const [index, entry] of value.missing.entries()) {
+        if (!expectedIds.has(entry.resource_id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["missing", index, "resource_id"],
+                message: `Missing input "${entry.resource_id}" is not in expected inputs.`,
+            });
+        }
+    }
+    for (const [index, resource] of value.expected.entries()) {
+        if (resource.required !== true)
+            continue;
+        if (!reviewedIds.has(resource.id) && !missingIds.has(resource.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["expected", index, "id"],
+                message: `Required expected input "${resource.id}" must be reviewed or marked missing.`,
+            });
+        }
+    }
+});
+export const GraphManifestStageSummarySchema = z.object({
+    stage_id: RuntimeStageSchema,
+    stage_label: z.string().min(1),
+    role: ResourceRoleSchema,
+    manifest_path: z.string().min(1).refine(isInterfRelativePath, {
+        message: "Stage manifest paths must stay inside the Context Graph root.",
+    }),
+    summary: z.string().min(1),
+    produced_total: z.number().int().min(0),
+    missing_required_total: z.number().int().min(0),
+    metrics: z.array(MetricCountSchema).default([]),
+}).strict();
+export const GraphReadinessRollupSchema = z.object({
+    status: z.enum(["ready", "not-ready"]),
+    ready: z.boolean(),
+    summary: z.string().min(1),
+    context_graph_path: z.string().min(1).nullable().optional(),
+    missing_required_total: z.number().int().min(0),
+    missing: z.array(MissingInputSchema).default([]),
+}).strict();
+export const GraphOutputCountsSchema = z.object({
+    nodes: z.number().int().min(0),
+    edges: z.number().int().min(0),
+    notes: z.number().int().min(0),
+    links: z.number().int().min(0),
+    source_refs: z.number().int().min(0),
+    claims: z.number().int().min(0).optional(),
+    entities: z.number().int().min(0).optional(),
+}).strict();
+export const GraphManifestSchema = z.object({
+    kind: z.literal("interf-graph-manifest"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    project: ProjectIdSchema,
+    graph_id: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    build_plan: BuildPlanIdSchema,
+    intent: ProjectIntentSchema.nullable(),
+    graph_path: z.string().min(1),
+    primary_metrics: z.array(MetricCountSchema).default([]),
+    stages: z.array(GraphManifestStageSummarySchema).default([]),
+    entrypoints: z.array(ResourceRefSchema).default([]),
+    resources: z.array(ResourceRefSchema).default([]),
+    graph_outputs: GraphOutputCountsSchema,
+    readiness: GraphReadinessRollupSchema,
+}).strict().superRefine((value, ctx) => {
+    const resourceIds = new Set();
+    for (const [index, resource] of value.resources.entries()) {
+        if (resourceIds.has(resource.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["resources", index, "id"],
+                message: `Duplicate graph resource id: ${resource.id}.`,
+            });
+        }
+        resourceIds.add(resource.id);
+    }
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Check / Diagnostics / Ready — legacy verification primitives
 //
 // Three words doing three precise jobs:
 //   - Check: the rule that must pass (with a `kind` and optional params)
-//   - Evidence: records that a check ran (pass/fail + summary + details)
+//   - Diagnostics: records that a check ran (pass/fail + summary + details)
 //   - Ready: aggregate verdict (`ready` or `not_ready`)
 //
 // A check has a SCOPE (where it's declared), not a different name:
 //   - stage check    — Build Plan-declared per stage; runs end-of-stage
-//   - Artifact diagnostic — Build Plan-declared per artifact; runs end-of-build
+//   - Output diagnostic — Build Plan-declared per requested output; runs end-of-build
 //   - benchmark check — Project-declared Q&A / fact check; runs on `interf benchmark`
 //
 // Same `Check` primitive across all three scopes. Same `CheckKind`
@@ -244,6 +479,9 @@ export const SourceBuildMaxLoopsSchema = z.number().int().min(1).max(3);
  *   frontmatter_required_keys      — every markdown file has these frontmatter keys (params: { keys: string[] })
  *   frontmatter_nonempty_keys      — every markdown file has non-empty values for these frontmatter keys
  *   source_refs_required           — every markdown file has non-empty source_refs/source_ref/source_path frontmatter
+ *   summary_backlinks_present      — every summary cited by a note's source_refs is also wikilinked from that layer (no orphaned summaries)
+ *   knowledge_web_connectivity     — every knowledge note links at least one OTHER knowledge note (no disconnected islands in the knowledge web)
+ *   graph_notes_connected          — every markdown note across the WHOLE Context Graph (summaries, knowledge, artifacts, home) is link-connected to at least one other note (no free-floating island anywhere, including uncited summaries)
  *   wikilinks_valid                — every wikilink resolves
  *   must_not_contain               — file/directory does not contain forbidden phrases (params: { phrases: string[] } or { text: string })
  *   must_contain                   — file/directory contains required phrases (params: { phrases: string[] } or { text: string })
@@ -260,6 +498,9 @@ export const CHECK_KINDS = [
     "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",
@@ -326,6 +567,26 @@ export const CHECK_PARAM_CONTRACTS = {
         },
         examples: [{ keys: ["source_refs"] }],
     },
+    summary_backlinks_present: {
+        params: {
+            summaries_dir: "optional summaries directory name; defaults to summaries",
+            summary_file: "optional summary filename; defaults to summary.md",
+            manifest_file: "optional manifest filename; defaults to manifest.md",
+        },
+        examples: [{}, { summaries_dir: "summaries" }],
+    },
+    knowledge_web_connectivity: {
+        params: {
+            knowledge_dir: "optional knowledge directory; defaults to the artifact's own target path. May only narrow the scan to a path inside that target layer.",
+        },
+        examples: [{}, { knowledge_dir: "knowledge" }],
+    },
+    graph_notes_connected: {
+        params: {
+            graph_root: "optional graph-root-relative directory to scan; defaults to the Context Graph root (every note in every layer). Use to narrow the floor to one layer (e.g. summaries) when a Build Plan splits the connectivity floor across outputs.",
+        },
+        examples: [{}, { graph_root: "summaries" }],
+    },
     wikilinks_valid: {
         params: {},
         examples: [{}],
@@ -393,10 +654,10 @@ export const ContextCheckStatusSchema = z.enum([
     "skipped",
 ]);
 /**
- * User-facing Build Plan check: the plain-English assertion the user
- * reviews as a Context Check. Requested Artifacts back these checks.
- * Deterministic Artifact diagnostics remain nested under Artifacts
- * and use `CheckSchema`.
+ * Legacy Build Plan check declaration. Current product surfaces should prefer
+ * concrete coverage metrics, Stage Manifests, and Graph Manifest readiness.
+ * Deterministic output diagnostics remain nested under requested outputs and
+ * use `CheckSchema`.
  */
 export const ContextCheckDeclarationSchema = z.object({
     id: z.string().regex(InterfIdPattern),
@@ -457,7 +718,7 @@ export const ArtifactPathShapeSchema = z.object({
 }).strict();
 export const ArtifactShapeSchema = ArtifactPathShapeSchema;
 /**
- * Build Plan-declared Artifact — a produced thing.
+ * Legacy internal requested-output schema.
  *
  * `checks[]` is the locked vocabulary: an array of `Check` (with
  * `kind` from `CHECK_KINDS`). The runtime evaluates them via the
@@ -484,10 +745,10 @@ export const ArtifactStatusSchema = z.object({
     summary: z.string().min(1).optional(),
 }).strict();
 // ───────────────────────────────────────────────────────────────────────────
-// Build evidence — user-visible readiness rows
+// Supplemental graph diagnostics
 //
-// Check rows are the app-facing review primitive for a Build. They
-// deliberately keep the surface small:
+// Diagnostic rows are secondary review records for a Build. They deliberately
+// keep the surface small:
 //   assertion label + metric + evidence link/ref + optional issue state
 //
 // Denominators are engine-owned (Source inventory or declared Build Plan
@@ -539,7 +800,7 @@ export const BuildEvidenceResourceSchema = z.object({
     summary: z.string().min(1),
     rows: z.array(BuildCheckRowSchema).default([]),
 }).strict();
-export const EvidenceCountKeySchema = z.string().regex(/^[a-z][a-z0-9_.:-]*$/);
+export const EvidenceCountKeySchema = MetricKeySchema;
 export const StageEvidenceSourceRefSchema = z.object({
     path: z.string().min(1),
     source_file_id: z.string().min(1).optional(),
@@ -593,7 +854,7 @@ export const StageEvidenceSchema = z.object({
 // ───────────────────────────────────────────────────────────────────────────
 // Readiness — project-level aggregate verdict
 //
-// Rolls up Artifact diagnostics, benchmark results, and engine-level gates
+// Rolls up output diagnostics, benchmark results, and engine-level gates
 // (is the project configured, has a Build, etc.) into a single
 // `ready` / `not_ready` answer for the ICP.
 // ───────────────────────────────────────────────────────────────────────────
@@ -621,7 +882,7 @@ export const ReadinessGateSchema = z.enum([
  * Per-gate status — one row in the readiness summary. A gate is a
  * high-level layer (is config valid? is the Context Graph built? did
  * the latest Build succeed?). Gate failures are aggregated alongside
- * Artifact diagnostic failures into the overall `Readiness` verdict.
+ * output diagnostic failures into the overall `Readiness` verdict.
  */
 export const GateStatusSchema = z.object({
     gate: ReadinessGateSchema,

package/dist/packages/contracts/utils/filesystem.d.ts

@@ -1,3 +1,4 @@
+export declare function isFilesystemArtifact(filePath: string): boolean;
 export declare function countFilesRecursive(dirPath: string): number;
 export declare function listFilesRecursive(dirPath: string, predicate?: (filePath: string) => boolean): string[];
 /**

package/dist/packages/contracts/utils/filesystem.js

@@ -1,6 +1,34 @@
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { readdir, realpath } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+/**
+ * OS-generated filesystem junk that is provably not user content: macOS
+ * `.DS_Store`, AppleDouble resource forks (`._name`), Spotlight/Trash sidecars,
+ * Windows `Thumbs.db` / `desktop.ini`. These are filesystem bookkeeping, not
+ * Source files, so they must never count as required/expected coverage units —
+ * otherwise a macOS Source folder shows "not ready" purely because Finder left
+ * a `.DS_Store` behind.
+ *
+ * This match is by filename only (deterministic, provable), never by an agent's
+ * `not-relevant` label. A real content gap an agent skipped is NOT matched here
+ * and still counts toward readiness.
+ */
+const FILESYSTEM_ARTIFACT_NAMES = new Set([
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    "Icon\r",
+    ".localized",
+]);
+export function isFilesystemArtifact(filePath) {
+    const name = basename(filePath.replace(/\\/g, "/"));
+    if (FILESYSTEM_ARTIFACT_NAMES.has(name))
+        return true;
+    // AppleDouble resource forks copied onto non-HFS volumes: `._<realname>`.
+    if (name.startsWith("._"))
+        return true;
+    return false;
+}
 export function countFilesRecursive(dirPath) {
     if (!existsSync(dirPath))
         return 0;

package/dist/packages/projects/lib/schema.d.ts

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { BuildPlanIdSchema, ProjectIdSchema } from "../../contracts/lib/schema.js";
-import { RequestedArtifactCheckSchema, RequestedArtifactOutputSchema, RequestedArtifactSchema, SourceContextSchema } from "../../build-plans/authoring/brief.js";
 export { BuildPlanIdSchema, ProjectIdSchema, } from "../../contracts/lib/schema.js";
 export declare const BenchmarkCheckSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
@@ -19,6 +17,7 @@ export { RequestedArtifactCheckSchema, RequestedArtifactOutputSchema, RequestedA
 export declare const ProjectConfigSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
     path: z.ZodString;
     build_plan: z.ZodOptional<z.ZodString>;
     latest_context_graph_run_id: z.ZodOptional<z.ZodString>;
@@ -29,6 +28,7 @@ export declare const SourceFolderBindingSchema: z.ZodObject<{
 export declare const ContextGraphInterfConfigSchema: z.ZodObject<{
     type: z.ZodLiteral<"context-graph">;
     name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
     build_plan: z.ZodString;
     build_plan_origin: z.ZodOptional<z.ZodObject<{
         selected: z.ZodString;
@@ -43,6 +43,7 @@ export declare const ContextGraphInterfConfigSchema: z.ZodObject<{
 export declare const InterfConfigSchema: z.ZodObject<{
     type: z.ZodLiteral<"context-graph">;
     name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
     build_plan: z.ZodString;
     build_plan_origin: z.ZodOptional<z.ZodObject<{
         selected: z.ZodString;
@@ -61,19 +62,16 @@ export declare const SourceFolderConfigSchema: z.ZodObject<{
     projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         name: z.ZodString;
+        intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
         path: z.ZodString;
         build_plan: z.ZodOptional<z.ZodString>;
         latest_context_graph_run_id: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type SourceFolderBinding = z.infer<typeof SourceFolderBindingSchema>;
-export type RequestedArtifactCheck = z.infer<typeof RequestedArtifactCheckSchema>;
-export type RequestedArtifact = z.infer<typeof RequestedArtifactSchema>;
-export type RequestedArtifactOutput = z.infer<typeof RequestedArtifactOutputSchema>;
 export type BenchmarkCheck = z.infer<typeof BenchmarkCheckSchema>;
-export type SourceContext = z.infer<typeof SourceContextSchema>;
-export type ProjectId = z.infer<typeof ProjectIdSchema>;
-export type BuildPlanId = z.infer<typeof BuildPlanIdSchema>;
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+export type { RequestedArtifactCheck, RequestedArtifact, RequestedArtifactOutput, SourceContext, } from "../../build-plans/authoring/brief.js";
+export type { ProjectId, BuildPlanId, ProjectIntent, } from "../../contracts/lib/schema.js";
 export type InterfConfig = z.infer<typeof InterfConfigSchema>;
 export type SourceFolderConfig = z.infer<typeof SourceFolderConfigSchema>;

package/dist/packages/projects/lib/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { InterfIdPattern, BuildPlanIdSchema, ProjectIdSchema, TestCaseExpectSchema, } from "../../contracts/lib/schema.js";
+import { InterfIdPattern, BuildPlanIdSchema, ProjectIdSchema, ProjectIntentSchema, TestCaseExpectSchema, } from "../../contracts/lib/schema.js";
 export { BuildPlanIdSchema, ProjectIdSchema, } from "../../contracts/lib/schema.js";
 /**
  * Absolute paths that an attacker-controlled config must never reach. The
@@ -52,6 +52,7 @@ export { RequestedArtifactCheckSchema, RequestedArtifactOutputSchema, RequestedA
 export const ProjectConfigSchema = z.object({
     id: z.string().regex(InterfIdPattern).optional(),
     name: ProjectIdSchema,
+    intent: ProjectIntentSchema.or(z.literal("")).default(""),
     path: z
         .string()
         .min(1)
@@ -70,6 +71,7 @@ export const SourceFolderBindingSchema = z.object({
 export const ContextGraphInterfConfigSchema = z.object({
     type: z.literal("context-graph"),
     name: ProjectIdSchema,
+    intent: ProjectIntentSchema.or(z.literal("")).default(""),
     build_plan: BuildPlanIdSchema,
     build_plan_origin: z.object({
         selected: BuildPlanIdSchema,

package/dist/packages/projects/source-config.d.ts

@@ -1,6 +1,5 @@
 import { type InterfConfig, type SourceFolderBinding, type BenchmarkCheck, type ProjectConfig, type SourceFolderConfig } from "./lib/schema.js";
 import type { TestSpec, TestTargetType } from "../runtime/verify/lib/schema.js";
-export declare const SOURCE_FOLDER_CONFIG_PATH = "interf.json";
 interface LoadedSourceTestSpec extends TestSpec {
     id: string;
     filePath: string;
@@ -16,16 +15,13 @@ export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig } from "../build-pla
 export declare function listProjectConfigs(config: SourceFolderConfig | null): ProjectConfig[];
 export declare function resolveBuildMaxAttempts(override?: number | null): number | null;
 export declare function resolveBuildMaxLoops(override?: number | null): number | null;
-export declare function getDefaultProjectConfig(config: SourceFolderConfig | null): ProjectConfig | null;
 export declare function findProjectConfig(config: SourceFolderConfig | null, projectId: string): ProjectConfig | null;
-export declare function configuredSourceFolderPath(config: SourceFolderConfig | WritableSourceFolderConfig | null | undefined): string | null;
 export declare function resolveConfiguredSourceFolderPath(projectDataDir: string, config?: SourceFolderConfig | WritableSourceFolderConfig | null | undefined): string | null;
 export declare function saveSourceFolderConfig(projectDataDir: string, config: WritableSourceFolderConfig): void;
 export declare function upsertProjectConfig(projectDataDir: string, projectConfig: ProjectConfig, options?: {
     matchName?: string;
 }): void;
 export declare function markProjectLatestContextGraphRun(projectDataDir: string, projectName: string, runId: string): ProjectConfig;
-export declare function removeProjectConfig(projectDataDir: string, projectId: string): boolean;
 export declare function projectConfigFromInterfConfig(config: InterfConfig, projectPath?: string): ProjectConfig;
 export declare function loadContextGraphProjectConfig(contextGraphPath: string): ProjectConfig | null;
 export declare function saveContextGraphInterfConfig(contextGraphPath: string, config: InterfConfig): InterfConfig;
@@ -48,7 +44,6 @@ export declare function writeBenchmarkSpecsForProject(options: {
     source_files?: string;
     context_graph?: string;
 };
-export declare function fingerprintTestSpec(spec: Pick<TestSpec, "cases">): string;
 export declare function fingerprintSavedBenchmarkSpec(options: {
     projectDataDir: string;
     projectName: string;

package/dist/packages/projects/source-config.js

@@ -12,8 +12,7 @@ import { listTestSpecs, writeTestSpec, } from "../runtime/verify/verify-specs.js
 import { slugify } from "../contracts/utils/naming.js";
 import { assertPathWithinRoot, isPathWithinRoot } from "../contracts/utils/path-guards.js";
 import { defaultControlPathForContextGraph, resolveSourceControlPathForContextGraph, contextGraphInterfConfigPath, contextGraphInterfRoot, } from "../runtime/build/context-graph-paths.js";
-import { asProjectDataDir, projectConfigPath, PROJECT_CONFIG_FILENAME, } from "../contracts/lib/project-paths.js";
-export const SOURCE_FOLDER_CONFIG_PATH = PROJECT_CONFIG_FILENAME;
+import { asProjectDataDir, projectConfigPath, } from "../contracts/lib/project-paths.js";
 export function sourceFolderConfigPath(projectDataDir) {
     return projectConfigPath(asProjectDataDir(projectDataDir));
 }
@@ -85,18 +84,11 @@ export function resolveBuildMaxLoops(override = null) {
         return 1;
     return Math.min(3, normalized);
 }
-export function getDefaultProjectConfig(config) {
-    const projects = listProjectConfigs(config);
-    return projects[0] ?? null;
-}
 export function findProjectConfig(config, projectId) {
     return listProjectConfigs(config).find((project) => project.name === projectId) ?? null;
 }
-export function configuredSourceFolderPath(config) {
-    return config?.source_folder?.path ?? null;
-}
 export function resolveConfiguredSourceFolderPath(projectDataDir, config = loadSourceFolderConfig(projectDataDir)) {
-    const configuredPath = configuredSourceFolderPath(config);
+    const configuredPath = config?.source_folder?.path ?? null;
     return configuredPath ? resolve(projectDataDir, configuredPath) : null;
 }
 function toWritableSourceFolderConfig(config) {
@@ -115,8 +107,12 @@ function toWritableSourceFolderConfig(config) {
 }
 function toWritableProjectConfig(project) {
     const buildPlan = buildPlanIdForProjectConfig(project);
+    const intent = typeof project.intent === "string" && project.intent.trim().length > 0
+        ? project.intent.trim()
+        : "";
     return {
         name: project.name,
+        intent,
         path: project.path,
         ...(buildPlan ? { build_plan: buildPlan } : {}),
         ...(project.latest_context_graph_run_id ? { latest_context_graph_run_id: project.latest_context_graph_run_id } : {}),
@@ -158,20 +154,10 @@ export function markProjectLatestContextGraphRun(projectDataDir, projectName, ru
     upsertProjectConfig(projectDataDir, next);
     return next;
 }
-export function removeProjectConfig(projectDataDir, projectId) {
-    const existing = loadSourceFolderConfig(projectDataDir);
-    const projects = listProjectConfigs(existing);
-    const nextProjects = projects.filter((entry) => entry.name !== projectId);
-    if (nextProjects.length === projects.length)
-        return false;
-    saveSourceFolderConfig(projectDataDir, {
-        projects: nextProjects,
-    });
-    return true;
-}
 export function projectConfigFromInterfConfig(config, projectPath = `./${config.name}`) {
     return {
         name: config.name,
+        intent: config.intent ?? "",
         path: projectPath,
         build_plan: config.build_plan,
     };
@@ -228,6 +214,7 @@ export function syncContextGraphInterfConfigFromProjectConfig(contextGraphPath,
         } : {}),
         type: "context-graph",
         name: projectConfig.name,
+        intent: projectConfig.intent ?? "",
         build_plan: buildPlanId,
         build_plan_origin: buildPlanOrigin,
         source: {
@@ -288,7 +275,7 @@ export function writeBenchmarkSpecsForProject(options) {
         context_graph: writeTestSpec(options.projectDataDir, { ...baseSpec, type: "context-graph" }, { overwrite: true }),
     };
 }
-export function fingerprintTestSpec(spec) {
+function fingerprintTestSpec(spec) {
     const normalized = spec.cases.map((testCase) => ({
         question: testCase.question.trim(),
         ...(testCase.file ? { file: testCase.file.trim() } : {}),

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

@@ -45,6 +45,7 @@ export type CreateProjectActionContext = {
     buildPlans: BuildPlanActionChoice[];
     projectDataDir: string;
     suggestedName: string;
+    suggestedIntent?: string;
 };
 export type BuildRunActionContext = {
     buildPlanId: string;
@@ -54,12 +55,14 @@ export type BuildRunActionContext = {
 export type SelectBuildPlanActionContext = {
     currentBuildPlanId?: string | null;
     buildPlans: BuildPlanActionChoice[];
+    intent: string;
     name: string;
     sourceFolderPath: string;
 };
 export type CreateBuildPlanActionContext = {
     defaultProject: string;
     existingBuildPlanIds: string[];
+    projectIntent?: string | null;
     suggestedBuildPlanId: string;
 };
 export type BuildPlanChangeAction = "modify" | "duplicate" | "remove";
@@ -77,6 +80,7 @@ export type ProjectChangeActionContext = {
     action: ProjectChangeAction;
     existingNames: string[];
     buildPlanId?: string | null;
+    intent: string;
     project: string;
     sourceFolderPath: string;
 };