@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/build-plans/package/local-build-plans.js

@@ -7,9 +7,11 @@ import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/u
 import { isMarkdownFile } from "../../contracts/utils/file-types.js";
 import { BuildPlanRuntimeApiSchema, BuildPlanPurposeSchema, BuildPlanStageArtifactReadAccessSchema, BuildPlanStageArtifactWriteAccessSchema, } from "../../runtime/build/lib/schema.js";
 import { RuntimeContractTypeSchema, InterfIdPattern, } from "../../contracts/lib/schema.js";
+import { CANONICAL_LAYER_DIRS, } from "../../contracts/lib/context-graph-layer.js";
 import { asProjectDataDir, projectBuildPlansRoot, } from "../../contracts/lib/project-paths.js";
 import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, BuildPlanInputSpecSchema, writeContextInterface, } from "./context-interface.js";
 import { BuildPlanAuthoringBriefSchema, } from "../authoring/brief.js";
+import { DEFAULT_BUILD_PLAN_ID } from "../build-plan-resolution.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 const LocalBuildPlanStageDefinitionSchema = z.object({
     id: z.string().regex(InterfIdPattern),
@@ -73,16 +75,20 @@ export function builtinBuildPlanPackagePath(buildPlanId) {
 export function buildPlanDefinitionPath(projectDataDir, id) {
     return join(buildPlanRootPath(projectDataDir), id);
 }
+// The single, readable list of which package-relative docs `collectStarterDocs`
+// and `buildPlanPackageCopyPaths` treat as portable starter docs: the package
+// README plus the three authoring-doc trees. A relative path qualifies when it
+// equals or lives under one of these entries.
+const SUPPORTED_STARTER_DOC_PATHS = [
+    "README.md",
+    "improve/",
+    "use/query/",
+    "build/stages/",
+];
 function isSupportedBuildPlanStarterDocPath(relativePath) {
-    if (relativePath === "README.md")
-        return true;
-    if (relativePath.startsWith("improve/"))
-        return true;
-    if (relativePath.startsWith("use/query/"))
-        return true;
-    if (relativePath.startsWith("build/stages/"))
-        return true;
-    return false;
+    return SUPPORTED_STARTER_DOC_PATHS.some((supported) => supported.endsWith("/")
+        ? relativePath.startsWith(supported)
+        : relativePath === supported);
 }
 function collectStarterDocs(dirPath) {
     return listFilesRecursive(dirPath, isMarkdownFile)
@@ -92,7 +98,11 @@ function collectStarterDocs(dirPath) {
         relativePath,
         content: readFileSync(join(dirPath, relativePath), "utf8"),
     }))
-        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+        // Codepoint order, not locale order: starter-doc ordering must be
+        // deterministic across machines (full vs small ICU, LANG/LC_ALL). With
+        // localeCompare, "README.md" sorts before lowercase paths in some locales
+        // and after in others, which made this collection environment-dependent.
+        .sort((a, b) => (a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0));
 }
 function buildPlanPackageCopyPaths(dirPath) {
     return [
@@ -188,7 +198,7 @@ export function resolveBuildPlanPackageSourcePath(projectDataDir, buildPlanId) {
     return null;
 }
 export function seedLocalDefaultBuildPlan(options) {
-    const buildPlanId = "interf-default";
+    const buildPlanId = DEFAULT_BUILD_PLAN_ID;
     const targetPath = buildPlanDefinitionPath(options.projectDataDir, buildPlanId);
     if (existsSync(join(targetPath, "build-plan.json"))) {
         return { buildPlanId, targetPath, alreadyExisted: true };
@@ -201,7 +211,7 @@ export function seedLocalDefaultBuildPlan(options) {
     patchBuildPlanPackageMetadata(targetPath, {
         id: buildPlanId,
         label: "Built-in Interf Build Plan",
-        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, structure cross-file connections, and shape the Context Graph around the saved Checks.",
+        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, build task-aware knowledge, and shape the Context Graph around the Project intent and coverage metrics.",
     });
     return { buildPlanId, targetPath, alreadyExisted: false };
 }
@@ -392,7 +402,10 @@ export function validateBuildPlanPackage(dirPath) {
             const longer = a.length <= b.length ? b : a;
             return shorter.every((part, index) => longer[index] === part);
         };
-        const requiredLayerPaths = new Set(["summaries", "knowledge", "artifacts"]);
+        // Canonical required layer dirs come from the central layer model. Package
+        // validation is a strict-declaration context (it mirrors authoring), so it
+        // matches the exact lowercase dir name a Build Plan must declare.
+        const requiredLayerPaths = new Set(CANONICAL_LAYER_DIRS);
         const isRequiredLayerArtifact = (artifact) => artifact.kind === "directory" && requiredLayerPaths.has(normalizedPathKey(artifact.path));
         const allowsRequiredLayerContainment = (artifact, existingArtifact) => {
             const artifactPath = normalizedPathKey(artifact.path);
@@ -405,58 +418,58 @@ export function validateBuildPlanPackage(dirPath) {
         };
         for (const artifact of schemaArtifacts) {
             if (seenArtifactIds.has(artifact.id)) {
-                errors.push(`build-plan.schema.json repeats Artifact id "${artifact.id}".`);
+                errors.push(`build-plan.schema.json repeats requested output id "${artifact.id}".`);
             }
             seenArtifactIds.add(artifact.id);
             const pathKey = normalizedPathKey(artifact.path);
             const existingPathOwner = seenArtifactsByPath.get(pathKey);
             if (existingPathOwner) {
-                errors.push(`build-plan.schema.json repeats Artifact path "${artifact.path}".`);
+                errors.push(`build-plan.schema.json repeats requested output path "${artifact.path}".`);
             }
             for (const existingArtifact of seenArtifactsByPath.values()) {
                 if (normalizedPathKey(existingArtifact.path) === pathKey)
                     continue;
                 if (hasOverlappingPath(artifact.path, existingArtifact.path) &&
                     !allowsRequiredLayerContainment(artifact, existingArtifact)) {
-                    errors.push(`build-plan.schema.json Artifacts "${artifact.id}" and "${existingArtifact.id}" overlap on path "${artifact.path}" / "${existingArtifact.path}".`);
+                    errors.push(`build-plan.schema.json requested outputs "${artifact.id}" and "${existingArtifact.id}" overlap on path "${artifact.path}" / "${existingArtifact.path}".`);
                 }
             }
             seenArtifactsByPath.set(pathKey, artifact);
             for (const owner of artifact.owned_by) {
                 if (!stageIds.has(owner)) {
-                    errors.push(`build-plan.schema.json references unknown stage "${owner}" for Artifact path "${artifact.path}".`);
+                    errors.push(`build-plan.schema.json references unknown stage "${owner}" for requested output path "${artifact.path}".`);
                     continue;
                 }
                 const ownerStage = stages.find((stage) => stage.id === owner);
                 if (ownerStage && !ownerStage.writes.includes(artifact.id)) {
-                    errors.push(`build-plan.schema.json Artifact "${artifact.id}" is owned by stage "${owner}" but that stage does not write it in build-plan.json.`);
+                    errors.push(`build-plan.schema.json requested output "${artifact.id}" is owned by stage "${owner}" but that stage does not write it in build-plan.json.`);
                 }
             }
         }
-        for (const requiredPath of ["summaries", "knowledge", "artifacts"]) {
+        for (const requiredPath of CANONICAL_LAYER_DIRS) {
             const artifact = seenArtifactsByPath.get(requiredPath);
             if (!artifact) {
-                errors.push(`File-based Build Plan packages must declare a writable Artifact at "${requiredPath}".`);
+                errors.push(`File-based Build Plan packages must declare a writable requested output at "${requiredPath}".`);
                 continue;
             }
             if (artifact.owned_by.length === 0) {
-                errors.push(`File-based Build Plan Artifact "${artifact.id}" at "${requiredPath}" must be owned by at least one stage.`);
+                errors.push(`File-based Build Plan requested output "${artifact.id}" at "${requiredPath}" must be owned by at least one stage.`);
             }
         }
         for (const stage of stages) {
             for (const artifactId of stage.reads) {
                 if (!artifactById.has(artifactId)) {
-                    errors.push(`Stage "${stage.id}" reads unknown Artifact "${artifactId}".`);
+                    errors.push(`Stage "${stage.id}" reads unknown requested output "${artifactId}".`);
                 }
             }
             for (const artifactId of stage.writes) {
                 const artifact = artifactById.get(artifactId);
                 if (!artifact) {
-                    errors.push(`Stage "${stage.id}" writes unknown Artifact "${artifactId}".`);
+                    errors.push(`Stage "${stage.id}" writes unknown requested output "${artifactId}".`);
                     continue;
                 }
                 if (!artifact.owned_by.includes(stage.id)) {
-                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but that Artifact is not owned by the stage in build-plan.schema.json.`);
+                    errors.push(`Stage "${stage.id}" writes requested output "${artifactId}" but that output is not owned by the stage in build-plan.schema.json.`);
                 }
             }
         }
@@ -477,21 +490,33 @@ export function validateBuildPlanPackage(dirPath) {
         counts,
     };
 }
-function describeContextInterfaceValidationIssues(dirPath) {
+/**
+ * Explain WHY a `build-plan.schema.json` failed to read. Exported so the
+ * regression test can assert the corrected branch directly: a valid schema must
+ * return `[]` (no issues), an invalid one must return the concrete Zod issues.
+ * The previous inverted `if (parsed.success)` reported a VALID schema as
+ * "missing or invalid."
+ */
+export function describeContextInterfaceValidationIssues(dirPath) {
     const buildPlanSchemaPath = contextInterfaceFilePath(dirPath);
     if (!existsSync(buildPlanSchemaPath)) {
         return ["build-plan.schema.json is missing."];
     }
-    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan requested Artifact contract");
+    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan requested output contract");
     if (raw === null) {
         return ["build-plan.schema.json is invalid JSON."];
     }
     const parsed = ContextInterfaceSchema.safeParse(raw);
-    if (parsed.success) {
-        return ["build-plan.schema.json is missing or invalid."];
+    if (!parsed.success) {
+        // Invalid schema: surface the concrete Zod issues. Matches the sibling
+        // `readContextInterface` (context-interface.ts:174), which treats
+        // `!parsed.success` as the failure case. The previous `if (parsed.success)`
+        // was inverted and reported a VALID schema as "missing or invalid."
+        return parsed.error.issues.map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+            return `build-plan.schema.json ${path}: ${issue.message}`;
+        });
     }
-    return parsed.error.issues.map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
-        return `build-plan.schema.json ${path}: ${issue.message}`;
-    });
+    // A valid schema has no issues to describe.
+    return [];
 }

package/dist/packages/contracts/index.d.ts

@@ -1,5 +1,6 @@
 export * as schema from "./lib/schema.js";
 export * as projectSchema from "./lib/project-schema.js";
-export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, BuildCheckRow, BuildEvidenceIssueState, BuildEvidenceMetric, BuildEvidenceRef, BuildEvidenceResource, ContextCheck, ContextCheckDeclaration, ContextCheckProjection, ContextCheckStatus, GateStatus, Locator, LocatorKind, BuildPlanId, ProjectId, CheckResult, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceState, StageEvidence, StageEvidenceCount, StageEvidenceEdge, StageEvidenceItem, StageEvidenceOutputRef, StageEvidenceSourceRef, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
-export type { ContextGraph, ContextGraphLocator, DriftKind, ProjectName, ProjectSourceState, Trace, Traces, } from "./lib/project-schema.js";
-export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, BuildCheckRow, BuildEvidenceIssueState, BuildEvidenceMetric, BuildEvidenceRef, BuildEvidenceResource, ContextCheck, ContextCheckDeclaration, ContextCheckProjection, ContextCheckStatus, GateStatus, Locator, LocatorKind, BuildPlanId, ProjectId, ProjectIntent, CheckResult, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceBinding, SourceFile, SourceFiles, SourceKind, SourceState, StageEvidence, StageEvidenceCount, StageEvidenceEdge, StageEvidenceItem, StageEvidenceOutputRef, StageEvidenceSourceRef, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
+export type { ContextGraph, ContextGraphArtifactHandoff, ContextGraphHandoff, ContextGraphLocator, ContextGraphPortableHandoff, DriftKind, ProjectName, ProjectSourceState, Trace, Traces, } from "./lib/project-schema.js";
+export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, ProjectIntentSchema, SourceBindingSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export { ContextGraphArtifactHandoffSchema, ContextGraphHandoffSchema, ContextGraphPortableHandoffSchema, } from "./lib/project-schema.js";

package/dist/packages/contracts/index.js

@@ -1,3 +1,4 @@
 export * as schema from "./lib/schema.js";
 export * as projectSchema from "./lib/project-schema.js";
-export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export { CANONICAL_ROLES, CHECK_PARAM_CONTRACTS, CHECK_KINDS, ContextCheckDeclarationSchema, ContextCheckProjectionSchema, ContextCheckSchema, ContextCheckStatusSchema, ProjectIntentSchema, SourceBindingSchema, BuildCheckRowSchema, BuildEvidenceIssueStateSchema, BuildEvidenceMetricSchema, BuildEvidenceRefSchema, BuildEvidenceResourceSchema, EvidenceCountKeySchema, StageEvidenceCountSchema, StageEvidenceEdgeSchema, StageEvidenceItemSchema, StageEvidenceOutputRefSchema, StageEvidenceSchema, StageEvidenceSourceRefSchema, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";
+export { ContextGraphArtifactHandoffSchema, ContextGraphHandoffSchema, ContextGraphPortableHandoffSchema, } from "./lib/project-schema.js";

package/dist/packages/contracts/lib/context-graph-layer.d.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+/**
+ * The Context Graph layer model — defined ONCE here and imported by every
+ * consumer (Build Plan authoring validation, package validation, StageManifest
+ * role inference, the graph-relative link scanner, and the deterministic check
+ * defaults). This is the single source of truth for "what are the canonical
+ * top-level layers of a Context Graph, and how does a path classify into one."
+ *
+ * The architecture is FIXED top-level layers / FLEXIBLE interior:
+ *   - `summaries/` — the grounding/coverage layer (one folder per Source file).
+ *   - `knowledge/` — the knowledge graph layer; its interior is free
+ *     (`knowledge/claims/`, `knowledge/entities/`, `knowledge/timelines/`, …).
+ *   - `artifacts/`  — task handoffs / supplemental entrypoints.
+ *   - `home.md`    — the primary entrypoint spine file (exact, no children).
+ *
+ * Two faces, one definition:
+ *   - The canonical lowercase set (`CANONICAL_LAYER_DIRS`, `CanonicalLayerSchema`,
+ *     `isCanonicalLayerDeclaration`) is what a Build Plan may DECLARE. Authoring
+ *     is strict: a layer must be declared in exact lowercase (`knowledge/`, not
+ *     `Knowledge/`).
+ *   - The tolerant classifier (`layerForPath`, `roleForLayerPath`) is DEFENSIVE
+ *     POLICING of already-built (possibly hand-edited or bad) outputs. It is
+ *     case-insensitive so a graph that shipped `Knowledge/` notes is still
+ *     routed into the knowledge layer and still policed by the orphan / web
+ *     gates — casing can never be used to dodge a gate. Classification only ever
+ *     widens membership; it never narrows it.
+ */
+/**
+ * The three canonical top-level DIRECTORY layers, in lockstep lowercase. These
+ * are the only top-level folders a Build Plan may declare for core derived
+ * content. `home.md` is the spine FILE and is handled separately (it is not a
+ * directory layer).
+ */
+export declare const CANONICAL_LAYER_DIRS: readonly ["summaries", "knowledge", "artifacts"];
+export type CanonicalLayerDir = (typeof CANONICAL_LAYER_DIRS)[number];
+/**
+ * Set form of the canonical directory layers, for membership tests at call
+ * sites (authoring guard, package validation) that previously hand-rolled their
+ * own `new Set(["summaries", "knowledge", "artifacts"])`.
+ */
+export declare const CANONICAL_LAYER_DIR_SET: ReadonlySet<CanonicalLayerDir>;
+/**
+ * The canonical layer "label" a path resolves to. Mirrors the directory layers
+ * plus `home` (the spine) and `other` (anything outside the canonical
+ * skeleton). This is the layer identity used for role inference and per-layer
+ * rollups.
+ */
+export declare const CanonicalLayerSchema: z.ZodEnum<{
+    other: "other";
+    knowledge: "knowledge";
+    summaries: "summaries";
+    artifacts: "artifacts";
+    home: "home";
+}>;
+export type CanonicalLayer = z.infer<typeof CanonicalLayerSchema>;
+/**
+ * The exact spine file name. Canonical only as the top-level file `home.md`
+ * with no children.
+ */
+export declare const HOME_SPINE_FILE = "home.md";
+/**
+ * Normalize a path to forward slashes with no leading `./` and no trailing
+ * slashes. Shared so every consumer normalizes identically before classifying
+ * — a layer must not depend on `\` vs `/` or a stray trailing separator.
+ */
+export declare function normalizeLayerPath(value: string): string;
+/**
+ * The FIRST path segment of a normalized path (the top-level folder, or the
+ * file name when the path is a bare top-level file). Empty string for an empty
+ * path. Layer membership keys off this segment only, so the entire interior of
+ * `knowledge/` is unconstrained.
+ */
+export declare function topLevelSegment(value: string): string;
+/**
+ * Is `segment` an EXACT canonical layer declaration a Build Plan may use? Used
+ * by authoring validation. Strict: `knowledge` passes, `Knowledge` does NOT.
+ * The mixed-case form is rejected at authoring so a declaration can never pass
+ * authoring and then break the lowercase-path-based package validators and
+ * runtime scanners downstream.
+ */
+export declare function isCanonicalLayerDeclaration(segment: string): boolean;
+/**
+ * Is this normalized top-level path a legal canonical DECLARATION? Accepts the
+ * exact lowercase layer dirs (and their interiors, since only the first segment
+ * is checked) and the exact spine file `home.md`. Strict on case. A non-path
+ * artifact (no folder) is the caller's concern; this only judges path shape.
+ */
+export declare function isCanonicalDeclarationPath(rawPath: string): boolean;
+/**
+ * Classify any path into its canonical layer. Case-INSENSITIVE on the top-level
+ * segment: a custom plan (or a hand-edited output) writing notes into
+ * `Knowledge/` (or `Summaries/`/`Artifacts/`) still classifies into the right
+ * layer, so the orphan + web + connectivity gates can't be dodged by path
+ * casing. Canonical layers are lowercase; this only WIDENS membership, never
+ * narrows it, and is the single classifier every consumer (note role, stage
+ * role, disconnected/web checks, metrics) routes through.
+ *
+ * Returns `home` for the spine file, a directory layer for `summaries/`,
+ * `knowledge/`, `artifacts/`, and `other` for anything else.
+ */
+export declare function layerForPath(rawPath: string): CanonicalLayer;
+/**
+ * The directory layer (or `null`) a check should scan for a given artifact
+ * target path. `home` and `other` have no scannable directory layer, so they
+ * return `null`; the three directory layers return their lowercase dir name.
+ * Used by the deterministic checks to derive their scan root from the artifact
+ * they are attached to instead of hardcoding a layer dir.
+ */
+export declare function layerDirForPath(rawPath: string): CanonicalLayerDir | null;
+/**
+ * The fine-grained kind of a note INSIDE the knowledge layer, by the structural
+ * convention every consumer agreed on: a `knowledge/claims/` folder (or a
+ * `claim-` leaf) is a claim, `knowledge/entities/` (or `entity-`) an entity,
+ * `knowledge/indexes/` (or `index-`) an index. `null` means "knowledge note
+ * with no recognized sub-kind". This is the single definition both the
+ * StageManifest note-kind labels and the semantic-graph node kinds delegate to,
+ * so the `knowledge/claims/` / `claim-` rules can never drift between them.
+ *
+ * Only the STRUCTURAL rules live here (folder prefix + leaf-token prefix). The
+ * looser "leaf merely contains `index`" heuristic is intentionally NOT here; it
+ * is a semantic-graph display nicety, and folding it in would silently
+ * reclassify manifest note kinds. Case-insensitive, like the rest of this
+ * module, so casing can never dodge the classification.
+ */
+export type KnowledgeNoteKind = "claim" | "entity" | "index" | null;
+export declare function knowledgeNoteKind(rawPath: string): KnowledgeNoteKind;
+/**
+ * The ResourceRef role a canonical layer maps to. `summaries → summary`,
+ * `knowledge → knowledge`, `artifacts`/`home → entrypoint`, `other → other`.
+ * Kept here (next to the layer model) so manifest role inference and the layer
+ * classifier never drift apart. The string union is the same as
+ * `ResourceRoleSchema`'s layer-bearing members; it is intentionally a plain
+ * union so this module has no import cycle back into the big schema.
+ */
+export type ContextGraphLayerRole = "summary" | "knowledge" | "entrypoint" | "other";
+export declare function roleForLayer(layer: CanonicalLayer): ContextGraphLayerRole;
+/**
+ * Role for a produced-note path (or any graph-relative path), via the tolerant
+ * classifier. This is the single mapping `roleForPath` callers route through.
+ */
+export declare function roleForLayerPath(rawPath: string): ContextGraphLayerRole;
+/**
+ * Role for a Build Plan artifact's WRITE path. A directory artifact declared as
+ * a bare layer token (`knowledge`, `summaries`, `artifacts`) carries no
+ * trailing segment; it is still classified as that layer because classification
+ * keys off the (case-insensitive) first segment. The `home`/`home.md` spine is
+ * the entrypoint. This makes a custom plan that writes artifact id "claims" to
+ * path `knowledge/` (or the bare token `knowledge`) still classify as the
+ * knowledge layer, with no reliance on stringly ids.
+ */
+export declare function roleForWritePath(rawPath: string): ContextGraphLayerRole;
+/**
+ * Matches a graph-relative reference to a canonical layer note inside free text
+ * (note bodies): `summaries/…`, `knowledge/…`, `artifacts/…` (optionally ending
+ * `.md`), or the exact `home.md`, when bounded by whitespace/brackets/quotes.
+ * Derived from `CANONICAL_LAYER_DIRS` so the scanner and the layer model can
+ * never list different folders. A fresh RegExp is returned each call because the
+ * pattern is stateful (`/g`) and reusing one instance across `matchAll` loops
+ * would carry `lastIndex` between callers.
+ */
+export declare function graphRelativePathPattern(): RegExp;

package/dist/packages/contracts/lib/context-graph-layer.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+/**
+ * The Context Graph layer model — defined ONCE here and imported by every
+ * consumer (Build Plan authoring validation, package validation, StageManifest
+ * role inference, the graph-relative link scanner, and the deterministic check
+ * defaults). This is the single source of truth for "what are the canonical
+ * top-level layers of a Context Graph, and how does a path classify into one."
+ *
+ * The architecture is FIXED top-level layers / FLEXIBLE interior:
+ *   - `summaries/` — the grounding/coverage layer (one folder per Source file).
+ *   - `knowledge/` — the knowledge graph layer; its interior is free
+ *     (`knowledge/claims/`, `knowledge/entities/`, `knowledge/timelines/`, …).
+ *   - `artifacts/`  — task handoffs / supplemental entrypoints.
+ *   - `home.md`    — the primary entrypoint spine file (exact, no children).
+ *
+ * Two faces, one definition:
+ *   - The canonical lowercase set (`CANONICAL_LAYER_DIRS`, `CanonicalLayerSchema`,
+ *     `isCanonicalLayerDeclaration`) is what a Build Plan may DECLARE. Authoring
+ *     is strict: a layer must be declared in exact lowercase (`knowledge/`, not
+ *     `Knowledge/`).
+ *   - The tolerant classifier (`layerForPath`, `roleForLayerPath`) is DEFENSIVE
+ *     POLICING of already-built (possibly hand-edited or bad) outputs. It is
+ *     case-insensitive so a graph that shipped `Knowledge/` notes is still
+ *     routed into the knowledge layer and still policed by the orphan / web
+ *     gates — casing can never be used to dodge a gate. Classification only ever
+ *     widens membership; it never narrows it.
+ */
+// ───────────────────────────────────────────────────────────────────────────
+// Canonical directory layers
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The three canonical top-level DIRECTORY layers, in lockstep lowercase. These
+ * are the only top-level folders a Build Plan may declare for core derived
+ * content. `home.md` is the spine FILE and is handled separately (it is not a
+ * directory layer).
+ */
+export const CANONICAL_LAYER_DIRS = ["summaries", "knowledge", "artifacts"];
+/**
+ * Set form of the canonical directory layers, for membership tests at call
+ * sites (authoring guard, package validation) that previously hand-rolled their
+ * own `new Set(["summaries", "knowledge", "artifacts"])`.
+ */
+export const CANONICAL_LAYER_DIR_SET = new Set(CANONICAL_LAYER_DIRS);
+/**
+ * The canonical layer "label" a path resolves to. Mirrors the directory layers
+ * plus `home` (the spine) and `other` (anything outside the canonical
+ * skeleton). This is the layer identity used for role inference and per-layer
+ * rollups.
+ */
+export const CanonicalLayerSchema = z.enum([
+    "summaries",
+    "knowledge",
+    "artifacts",
+    "home",
+    "other",
+]);
+/**
+ * The exact spine file name. Canonical only as the top-level file `home.md`
+ * with no children.
+ */
+export const HOME_SPINE_FILE = "home.md";
+// ───────────────────────────────────────────────────────────────────────────
+// Path normalization
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Normalize a path to forward slashes with no leading `./` and no trailing
+ * slashes. Shared so every consumer normalizes identically before classifying
+ * — a layer must not depend on `\` vs `/` or a stray trailing separator.
+ */
+export function normalizeLayerPath(value) {
+    return value
+        .replaceAll("\\", "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/+$/g, "");
+}
+/**
+ * The FIRST path segment of a normalized path (the top-level folder, or the
+ * file name when the path is a bare top-level file). Empty string for an empty
+ * path. Layer membership keys off this segment only, so the entire interior of
+ * `knowledge/` is unconstrained.
+ */
+export function topLevelSegment(value) {
+    const normalized = normalizeLayerPath(value);
+    if (normalized.length === 0)
+        return "";
+    return normalized.split("/")[0] ?? "";
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Authoring face — strict, exact-lowercase declarations
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Is `segment` an EXACT canonical layer declaration a Build Plan may use? Used
+ * by authoring validation. Strict: `knowledge` passes, `Knowledge` does NOT.
+ * The mixed-case form is rejected at authoring so a declaration can never pass
+ * authoring and then break the lowercase-path-based package validators and
+ * runtime scanners downstream.
+ */
+export function isCanonicalLayerDeclaration(segment) {
+    return CANONICAL_LAYER_DIRS.includes(segment);
+}
+/**
+ * Is this normalized top-level path a legal canonical DECLARATION? Accepts the
+ * exact lowercase layer dirs (and their interiors, since only the first segment
+ * is checked) and the exact spine file `home.md`. Strict on case. A non-path
+ * artifact (no folder) is the caller's concern; this only judges path shape.
+ */
+export function isCanonicalDeclarationPath(rawPath) {
+    const normalized = normalizeLayerPath(rawPath);
+    if (normalized.length === 0)
+        return false;
+    const segment = topLevelSegment(normalized);
+    // `home.md` is canonical only as the exact top-level spine file (no children).
+    if (segment === HOME_SPINE_FILE && normalized === segment)
+        return true;
+    return isCanonicalLayerDeclaration(segment);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Policing face — tolerant, case-insensitive classification
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Classify any path into its canonical layer. Case-INSENSITIVE on the top-level
+ * segment: a custom plan (or a hand-edited output) writing notes into
+ * `Knowledge/` (or `Summaries/`/`Artifacts/`) still classifies into the right
+ * layer, so the orphan + web + connectivity gates can't be dodged by path
+ * casing. Canonical layers are lowercase; this only WIDENS membership, never
+ * narrows it, and is the single classifier every consumer (note role, stage
+ * role, disconnected/web checks, metrics) routes through.
+ *
+ * Returns `home` for the spine file, a directory layer for `summaries/`,
+ * `knowledge/`, `artifacts/`, and `other` for anything else.
+ */
+export function layerForPath(rawPath) {
+    const lower = normalizeLayerPath(rawPath).toLowerCase();
+    if (lower.length === 0)
+        return "other";
+    if (lower === HOME_SPINE_FILE)
+        return "home";
+    const segment = lower.split("/")[0] ?? "";
+    if (CANONICAL_LAYER_DIRS.includes(segment)) {
+        return segment;
+    }
+    return "other";
+}
+/**
+ * The directory layer (or `null`) a check should scan for a given artifact
+ * target path. `home` and `other` have no scannable directory layer, so they
+ * return `null`; the three directory layers return their lowercase dir name.
+ * Used by the deterministic checks to derive their scan root from the artifact
+ * they are attached to instead of hardcoding a layer dir.
+ */
+export function layerDirForPath(rawPath) {
+    const layer = layerForPath(rawPath);
+    return layer === "home" || layer === "other" ? null : layer;
+}
+export function knowledgeNoteKind(rawPath) {
+    const normalized = normalizeLayerPath(rawPath).toLowerCase();
+    const leaf = normalized.split("/").pop() ?? "";
+    if (normalized.startsWith("knowledge/claims/") || leaf.startsWith("claim-"))
+        return "claim";
+    if (normalized.startsWith("knowledge/entities/") || leaf.startsWith("entity-"))
+        return "entity";
+    if (normalized.startsWith("knowledge/indexes/") || leaf.startsWith("index-"))
+        return "index";
+    return null;
+}
+export function roleForLayer(layer) {
+    switch (layer) {
+        case "summaries":
+            return "summary";
+        case "knowledge":
+            return "knowledge";
+        case "artifacts":
+        case "home":
+            return "entrypoint";
+        case "other":
+            return "other";
+    }
+}
+/**
+ * Role for a produced-note path (or any graph-relative path), via the tolerant
+ * classifier. This is the single mapping `roleForPath` callers route through.
+ */
+export function roleForLayerPath(rawPath) {
+    return roleForLayer(layerForPath(rawPath));
+}
+/**
+ * Role for a Build Plan artifact's WRITE path. A directory artifact declared as
+ * a bare layer token (`knowledge`, `summaries`, `artifacts`) carries no
+ * trailing segment; it is still classified as that layer because classification
+ * keys off the (case-insensitive) first segment. The `home`/`home.md` spine is
+ * the entrypoint. This makes a custom plan that writes artifact id "claims" to
+ * path `knowledge/` (or the bare token `knowledge`) still classify as the
+ * knowledge layer, with no reliance on stringly ids.
+ */
+export function roleForWritePath(rawPath) {
+    const path = normalizeLayerPath(rawPath);
+    if (path === "home" || path === HOME_SPINE_FILE)
+        return "entrypoint";
+    return roleForLayerPath(path);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Graph-relative link scanner
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Matches a graph-relative reference to a canonical layer note inside free text
+ * (note bodies): `summaries/…`, `knowledge/…`, `artifacts/…` (optionally ending
+ * `.md`), or the exact `home.md`, when bounded by whitespace/brackets/quotes.
+ * Derived from `CANONICAL_LAYER_DIRS` so the scanner and the layer model can
+ * never list different folders. A fresh RegExp is returned each call because the
+ * pattern is stateful (`/g`) and reusing one instance across `matchAll` loops
+ * would carry `lastIndex` between callers.
+ */
+export function graphRelativePathPattern() {
+    const dirs = CANONICAL_LAYER_DIRS.join("|");
+    return new RegExp(`(?:^|[\\s"'([{<])((?:${dirs})\\/[A-Za-z0-9._~!$&*+,;=:@%/-]+(?:\\.md)?|${HOME_SPINE_FILE.replace(".", "\\.")})(?=$|[\\s"'\`)\\]}>.,;:])`, "g");
+}

package/dist/packages/contracts/lib/project-paths.d.ts

@@ -103,6 +103,13 @@ export declare function projectRunContextGraphPath(projectDataDir: ProjectDataDi
 export declare function projectServiceRoot(projectDataDir: ProjectDataDir): string;
 /** `<project-data>/.service/jobs/`. */
 export declare function projectServiceJobsRoot(projectDataDir: ProjectDataDir): string;
+/**
+ * `<project-data>/.service/jobs/shells/` — preserved, inspectable execution
+ * shells for graph-less agent jobs (Build Plan draft/improve, benchmark-question
+ * draft). Each `LocalJobRun.result.shell_path` points at one frozen shell here,
+ * the graph-less analogue of a Context Graph's stage execution shells.
+ */
+export declare function projectServiceJobShellsRoot(projectDataDir: ProjectDataDir): string;
 /** `<project-data>/.service/action-proposals/`. */
 export declare function projectServiceActionProposalsRoot(projectDataDir: ProjectDataDir): string;
 /** `<project-data>/.service/action-plans/`. */

package/dist/packages/contracts/lib/project-paths.js

@@ -140,6 +140,15 @@ export function projectServiceRoot(projectDataDir) {
 export function projectServiceJobsRoot(projectDataDir) {
     return join(projectServiceRoot(projectDataDir), SERVICE_JOBS_DIR);
 }
+/**
+ * `<project-data>/.service/jobs/shells/` — preserved, inspectable execution
+ * shells for graph-less agent jobs (Build Plan draft/improve, benchmark-question
+ * draft). Each `LocalJobRun.result.shell_path` points at one frozen shell here,
+ * the graph-less analogue of a Context Graph's stage execution shells.
+ */
+export function projectServiceJobShellsRoot(projectDataDir) {
+    return join(projectServiceJobsRoot(projectDataDir), "shells");
+}
 /** `<project-data>/.service/action-proposals/`. */
 export function projectServiceActionProposalsRoot(projectDataDir) {
     return join(projectServiceRoot(projectDataDir), SERVICE_ACTION_PROPOSALS_DIR);