@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/build-plans/authoring/build-plan-authoring.js

@@ -1,10 +1,13 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { createBuildPlanAuthoringShell, } from "../../engine/agents/lib/shells.js";
+import { CANONICAL_LAYER_DIRS, isCanonicalDeclarationPath, layerForPath, normalizeLayerPath, } from "../../contracts/lib/context-graph-layer.js";
+import { createBuildPlanAuthoringShell, freezeBuildPlanAuthoringShell, } from "../../runtime/agents/lib/shells.js";
+import { asProjectDataDir, projectServiceJobShellsRoot, } from "../../contracts/lib/project-paths.js";
+import { scanSourceContext } from "../../runtime/agents/lib/source-context-scan.js";
 import { createScratchLocalBuildPlanPackage } from "../package/interf-build-plan-package.js";
 import { CONTEXT_INTERFACE_FILE, listContextInterfaceArtifacts } from "../package/context-interface.js";
-import { loadBuildPlanDefinitionFromDir, validateBuildPlanPackage, buildPlanDefinitionPath, } from "../package/local-build-plans.js";
-import { runBuildPlanEditSession } from "./build-plan-edit-session.js";
+import { loadBuildPlanDefinitionFromDir, validateBuildPlanPackage, } from "../package/local-build-plans.js";
+import { runBuildPlanEditSession, SHARED_BUILD_PLAN_EDIT_RULES, } from "./build-plan-edit-session.js";
 /**
  * Walk build-plan.json after a successful authoring run and fill in
  * `role: "general"` for any stage missing a role field. Custom role
@@ -61,32 +64,60 @@ function buildBuildPlanAuthoringPrompt() {
     return [
         "This is an automated Interf Build Plan authoring run, not an open-ended chat session.",
         "Execute it now.",
-        "Create one standalone Build Plan package for the source data, desired verifiable-context outputs, and proof requirements in this source folder.",
+        "Create one standalone Build Plan package for the Source data, Project intent, requested outputs, coverage metrics, and evidence requirements behind the Source locator.",
         "Read `runtime/authoring-context.json` first.",
-        "Treat `task_prompt` as the user's preparation-and-evidence brief: source data, output shape, and evidence that should show the data is ready.",
+        "Treat `intent`, `requested_artifacts` (legacy field for requested outputs and graph entrypoints), `checks` (diagnostic context only), `user_prep_instructions`, and `source_context` as the user's agent task and coverage brief.",
         `Then read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${CONTEXT_INTERFACE_FILE}\`.`,
         "The `build-plan/` directory starts as a neutral Build Plan scaffold, not as a suggested final plan.",
-        "Replace the scaffold purpose, inputs, Artifacts, stages, stage docs, checks, and query guidance with the Build Plan this agent work actually needs.",
-        "Read `runtime/source-files.json` and inspect the listed source locators before editing the package.",
+        "Replace the scaffold purpose, inputs, outputs, stages, stage docs, coverage expectations, and query guidance with the Build Plan this agent task actually needs.",
+        "Read `runtime/source-locator.json`, then use the `source_context` inventory in `runtime/authoring-context.json` as your primary picture of what is actually in this Source: its `summary`, the `items[]` (each with `name`, `path`, `kind`, optional `page_count`, and `note`), and the listed `observations` and `limitations`. Open specific Source files through your own available tools only to confirm or fill gaps the inventory leaves open before editing the package.",
+        "Derive the stage shape from that inventory. Choose stage ids and stage labels that NAME what is genuinely present in this Source — its folder structure, the dominant file kinds, the natural groupings, and any date or period ranges the inventory reveals. Do NOT emit a generic cover/build/verify/assemble (or extract/summarize/structure/verify) skeleton unless the inventory shows the Source is genuinely unstructured and offers no better organizing principle. There is no fixed stage taxonomy: reason from this Source's inventory, not from a template.",
         "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
         "Edit only files under `build-plan/`.",
         "Keep the Build Plan valid for the current local-engine API and `build-plan.schema.json`.",
-        "Choose stage ids, stage order, artifact reads, artifact writes, artifact checks, and stage docs from the source data and preparation-and-evidence brief.",
-        "Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
+        "Do not edit the root `brief`; the service restores it from Project intent, requested outputs, diagnostic checks, and Source context after every edit attempt.",
+        "Do not add ad-hoc top-level keys to `build-plan/build-plan.json`; only use keys already present in the scaffold or documented by the local Build Plan schema.",
+        "If you want to express user-facing promises, use the Build Plan's existing root `brief` field, `purpose.label`, `purpose.task_hint`, and requested output contract. Never add `purpose.brief` or any other ad-hoc nested promise field.",
+        "Choose stage ids, stage order, requested output reads/writes, StageManifest coverage expectations, and stage docs from the `source_context` inventory, the agent task, and the coverage brief. The stage shape must reflect this Source's real structure and content, not a reused skeleton.",
+        "Stage `reads` may only contain requested output ids that are declared in `build-plan.schema.json` and produced by an earlier stage. Source files are implicit input through runtime stage assignment; never put `source`, source file paths, or source-folder ids in stage `reads`.",
+        // Stable kebab-case-id rule (shared verbatim with the repair prompt).
+        SHARED_BUILD_PLAN_EDIT_RULES[0],
         "Each stage MAY declare a `role`: one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Pick the role that best matches what the stage's prompt asks the agent to do. Omit `role` (or use `general`) when the stage doesn't fit any specialized role. Custom role names are allowed; the engine treats unknown roles as `general`.",
         "Do not preserve the placeholder `prepare` stage unless the final Build Plan genuinely needs a stage with that exact role.",
-        "Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
+        "Treat `checks` as optional context, not the primary product surface.",
+        "Design coverage first: expected inputs, reviewed inputs, produced outputs, entrypoints, and missing/blocked/not-relevant coverage decisions that can roll into a GraphManifest.",
+        "For file-based Projects, every final Build Plan must preserve the Context Graph shape: `summaries/` for source coverage, `knowledge/` for task-aware claims/entities/topics/indexes, `home.md` as primary entrypoint, and `artifacts/` for supplemental task handoffs.",
+        "`summaries/` is the coverage layer. It should prove what source files were inspected. For PDFs, decks, or paginated reports, prefer page-level notes or explicit page coverage records when practical; each summary must link back to the original Source path, page, section, figure, table, or other source reference instead of copying the Source file.",
+        "`knowledge/` is the graph layer. The current default contract is flat `knowledge/*.md` notes, and may contain claims, entities, topics, and indexes. Treat knowledge notes as navigation and assurance, not as the authority for exact wording, table values, chart reads, or provenance-sensitive claims.",
+        "Knowledge notes MUST connect to the coverage layer, not orphan it. This is a hard requirement: for every summary whose evidence a knowledge/entity note draws on, that note MUST include at least one `[[summaries/<source-name>/summary]]` wikilink to that summary, IN ADDITION to its source_refs. The wikilink to the summary and the source_ref to the original are both required; one does not substitute for the other. A knowledge note that cites a source through source_refs without also linking that source's summary is INCOMPLETE and must not be treated as done. Encode this mandate in the knowledge stage's SKILL.md and in the StageManifest coverage so it is enforced, not optional — never describe it as preferred, optional, or a choice between summary links and plain source refs.",
+        "Make this mandate machine-enforced, not just prose: on the requested output for the knowledge/graph layer (the directory output that holds the `knowledge/*.md` notes), declare a required `summary_backlinks_present` deterministic check in `build-plan.schema.json`. Use the default params (summaries directory, `summary.md`, `manifest.md`) unless this Build Plan renames those, in which case pass `summaries_dir`, `summary_file`, and `manifest_file` to match. This is the only deterministic check that proves no cited summary is orphaned; every file-based Build Plan that produces a `knowledge/` layer must include it.",
+        "Enforce the WHOLE-GRAPH connectivity floor, not only the knowledge layer: `summary_backlinks_present` and `knowledge_web_connectivity` only police summaries a knowledge note CITES and the knowledge web itself — a summary no note cites or links would still ship as a free-floating island and pass readiness. To close that, declare a required `graph_notes_connected` deterministic check on the graph spine output (the `home.md` requested output, or another always-present output) in `build-plan.schema.json`. It scans the WHOLE Context Graph root by default and fails readiness if any note — including any uncited summary — is link-disconnected from every other note. Every file-based Build Plan that produces a Context Graph must include it. Its job is reachability, not a quota: an inbound OR outbound link satisfies a note. Make sure the entrypoint/coverage routing actually links every summary (directly or through a coverage index) so this floor can pass honestly.",
+        "`home.md` is the primary agent entrypoint. Supplemental graph entrypoints may live under `artifacts/` when they help the downstream agent and should tell it which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter for the task.",
+        "Requested outputs should normally route the downstream agent to the right original Source evidence. They should not present generated summaries or knowledge notes as the dataset or source of truth.",
+        "For tasks that depend on charts, tables, images, or other visual evidence, requested outputs must capture the source semantics needed to answer: target period, unit, series/legend, axis or table interpretation, exact printed values when available, bounded ranges when not, evidence tier, and source page.",
+        "For unlabeled charts, screenshots, diagrams, or visual marks, do not write a final numeric answer unless the requested output also captures a source-grounded measurement method, visual reference, axis/table calibration, and uncertainty. Otherwise the output must route the downstream agent to inspect the original Source before answering.",
+        "Do not let structural diagnostics such as file_exists, frontmatter_required_keys, or must_contain stand in for coverage or evidence fidelity. Use stage docs, StageManifest coverage, and requested output descriptions to require the semantic fields the agent task needs.",
+        "If a visual source has no printed data labels, the requested output should preserve a bounded read at source granularity and should mark unresolved semantics instead of inventing pseudo-exact precision.",
+        "Verification stages must not pass by comparing generated notes only to other generated notes. If a verifier did not inspect the relevant original Source reference, page-level summary with source refs, table extraction, visual trace, or measurement output required by the claim, it must report the claim as not verified.",
+        "Preserve `backed_by_artifact_ids` in the root Build Plan `brief` when present and use matching requested output ids in `build-plan.schema.json`.",
+        "When `runtime/authoring-context.json.artifact_requirements[]` is non-empty, it is binding: copy each requirement's `id`, `shape`, and `checks[]` exactly into `build-plan.schema.json`.",
+        "Do not rename, move, merge, split, or reinterpret required requested outputs. `stage_hint` can guide which stage writes the output, but it never changes the required `shape.path`, `shape.artifact_kind`, or diagnostic contract.",
+        "Keep deterministic validation on requested output `checks[]` minimal; do not use diagnostics as the primary proof surface.",
         "Use only the CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases.",
-        "Keep Artifact checks aligned with produced outputs. Use stage docs to describe the output contract, but do not turn source-specific user wording into brittle stage-doc wording requirements.",
+        // Stable check-param-contract + diagnostic-description rules (shared verbatim
+        // with the repair prompt).
+        SHARED_BUILD_PLAN_EDIT_RULES[1],
+        SHARED_BUILD_PLAN_EDIT_RULES[2],
+        "Keep diagnostics aligned with produced requested outputs. Use stage docs and StageManifest coverage to describe the output contract, but do not turn source-specific user wording into brittle stage-doc wording requirements.",
         "For every stage in `build-plan.json`, create `build-plan/build/stages/<skill_dir>/SKILL.md` and make the folder name exactly match that stage's kebab-case `skill_dir`.",
-        "Every Artifact path in `build-plan.schema.json` must be unique and non-overlapping.",
-        "Make the package materially specific to this Preparation task, output shape, and proof requirement. A no-op scaffold is not acceptable.",
-        "Treat the Build Plan as four aligned layers: purpose, inputs, context interface, and stages.",
-        "If the Build Plan writes an agent entrypoint, declare it as an Artifact and make the final shaping stage own it.",
-        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and context-interface edits over vague rewrites.",
+        "Every requested output path in `build-plan.schema.json` must be unique. Child outputs may live under the required layer directories `summaries/`, `knowledge/`, and `artifacts/`; unrelated output paths must not overlap.",
+        "Make the package materially specific to this Project's agent task, output shape, coverage, and evidence requirement. A no-op scaffold is not acceptable.",
+        "Treat the Build Plan as four aligned layers: purpose, inputs, requested output contract, and stages.",
+        "If the Build Plan writes `home.md`, declare it as a requested output and make the entrypoint stage own it.",
+        "Prefer explicit stage-doc, stage-policy, purpose, input-contract, and requested-output-contract edits over vague rewrites.",
         "Do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path.",
-        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read Artifacts.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read outputs.",
         "Do not make one stage point at files or notes that are only created later by another stage.",
         "Prefer conservative retrieval routing over speculative note sprawl.",
         "Do not narrate plans or ask follow-up questions.",
@@ -107,12 +138,45 @@ function stableJson(value) {
         .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
         .join(",")}}`;
 }
+/**
+ * Persist the authoring brief (intent, requested outputs, `source_context`,
+ * `artifact_requirements`) into the package's `build-plan.json` so the saved
+ * plan and every validation pass carry the SAME brief the shell was built
+ * from.
+ *
+ * Returns `true` when the brief was written, `false` when it could not be
+ * (missing or unparseable `build-plan.json`). The caller MUST observe the
+ * `false` case: previously this no-op was silent, so a brief carrying the
+ * Source inventory and the binding artifact requirements could be dropped
+ * with no signal — validation would then run against a plan that has no
+ * brief, and an untailored draft could persist. The drop is now reportable,
+ * never silent.
+ */
+function writeBuildPlanAuthoringBrief(buildPlanPath, brief) {
+    const buildPlanJsonPath = join(buildPlanPath, "build-plan.json");
+    if (!existsSync(buildPlanJsonPath))
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(buildPlanJsonPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    writeFileSync(buildPlanJsonPath, `${JSON.stringify({ ...parsed, brief }, null, 2)}\n`);
+    return true;
+}
 function checkMatchesRequirement(actual, required) {
     return actual.id === required.id &&
         actual.kind === required.kind &&
         (actual.required ?? true) === (required.required ?? true) &&
         stableJson(actual.params) === stableJson(required.params);
 }
+function compactJson(value) {
+    return JSON.stringify(value);
+}
 function producingStagesForArtifact(definition, artifactId) {
     return (definition.stages ?? []).filter((stage) => Array.isArray(stage.writes) && stage.writes.includes(artifactId));
 }
@@ -122,34 +186,372 @@ function validateArtifactRequirements(definition, requirements) {
     for (const requirement of requirements) {
         const artifact = artifacts.find((candidate) => candidate.id === requirement.id);
         if (!artifact) {
-            errors.push(`Missing required Artifact \`${requirement.id}\`.`);
+            errors.push(`Missing required requested output \`${requirement.id}\`.`);
             continue;
         }
         if (artifact.shape.kind !== requirement.shape.kind ||
             artifact.shape.path !== requirement.shape.path ||
             artifact.shape.artifact_kind !== requirement.shape.artifact_kind) {
-            errors.push(`Artifact \`${requirement.id}\` does not match required shape.`);
+            errors.push(`Requested output \`${requirement.id}\` must declare required shape ${compactJson(requirement.shape)}; found ${compactJson(artifact.shape)}.`);
         }
         for (const check of requirement.checks) {
             if (!artifact.checks.some((candidate) => checkMatchesRequirement(candidate, check))) {
-                errors.push(`Artifact \`${requirement.id}\` is missing required check \`${check.id}\`.`);
+                errors.push(`Requested output \`${requirement.id}\` must include required diagnostic ${compactJson(check)}.`);
             }
         }
         const producingStages = producingStagesForArtifact(definition, requirement.id);
         if (producingStages.length === 0) {
-            errors.push(`Artifact \`${requirement.id}\` is not written by any stage.`);
+            errors.push(`Requested output \`${requirement.id}\` is not written by any stage.`);
         }
     }
     return errors;
 }
-function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements = []) {
+/**
+ * A requested output materializes the `knowledge/` graph layer when it is a
+ * directory output whose path is `knowledge` or lives under `knowledge/`.
+ * Path-only and layer-agnostic — no Build-Plan-specific naming.
+ */
+function isKnowledgeLayerArtifact(artifact) {
+    if (artifact.shape.kind !== "path" || artifact.shape.artifact_kind !== "directory") {
+        return false;
+    }
+    // Central tolerant classifier: a directory output at `knowledge` or anything
+    // under `knowledge/` (any casing) is the knowledge graph layer.
+    return layerForPath(artifact.shape.path) === "knowledge";
+}
+/**
+ * Backlink guard. The product mandate is that no cited summary is left
+ * orphaned: every file-based Build Plan that produces a `knowledge/` graph
+ * layer must declare a required `summary_backlinks_present` deterministic
+ * check on the directory output holding the `knowledge/*.md` notes. That
+ * check is the only deterministic proof the graph layer connects back to the
+ * coverage layer.
+ *
+ * The authoring prompt already asks for this in prose, but prose is advisory.
+ * This guard makes it machine-enforced: if any `knowledge/` directory output
+ * exists, at least one such knowledge-layer output must carry a REQUIRED
+ * `summary_backlinks_present` check, or the package fails validation. Generic
+ * — it keys only off the layer path and the central CheckKind, never off
+ * intent or per-Build-Plan naming.
+ */
+function validateSummaryBacklinkGuard(definition) {
+    const artifacts = definition.build_plan_schema.artifacts ?? [];
+    const knowledgeArtifacts = artifacts.filter(isKnowledgeLayerArtifact);
+    if (knowledgeArtifacts.length === 0)
+        return [];
+    const hasRequiredBacklinkCheck = knowledgeArtifacts.some((artifact) => artifact.checks.some((check) => check.kind === "summary_backlinks_present" && (check.required ?? true)));
+    if (hasRequiredBacklinkCheck)
+        return [];
+    const layerPaths = knowledgeArtifacts
+        .map((artifact) => artifact.shape.kind === "path" ? artifact.shape.path : artifact.id)
+        .join(", ");
+    return [
+        `Build Plan produces a \`knowledge/\` graph layer (${layerPaths}) but no knowledge-layer ` +
+            "requested output declares a required `summary_backlinks_present` check. Add that check so no " +
+            "summary cited by a knowledge note is left orphaned (the graph layer must connect to the coverage layer).",
+    ];
+}
+/**
+ * Whole-graph connectivity floor guard. The product promise is a "deeply
+ * connected web": EVERY note across the Context Graph — including every summary,
+ * not only the ones a knowledge note happened to cite — must be reachable
+ * through the link web. The `summary_backlinks_present` guard above only covers
+ * CITED summaries, and `knowledge_web_connectivity` only the `knowledge/` layer;
+ * an uncited summary would still ship as a free-floating island and pass
+ * readiness silently. The `graph_notes_connected` check closes that floor by
+ * scanning the whole graph root.
+ *
+ * This makes the floor machine-enforced rather than advisory: a Build Plan that
+ * produces a `knowledge/` graph layer (the same trigger condition the backlink
+ * guard uses — a file-based Context Graph) must declare at least one REQUIRED
+ * `graph_notes_connected` check somewhere in its requested outputs, or the
+ * package fails validation. Generic — keys only off the layer path and the
+ * central CheckKind, never off intent or per-Build-Plan naming.
+ */
+function validateGraphConnectivityFloorGuard(definition) {
+    const artifacts = definition.build_plan_schema.artifacts ?? [];
+    // Same trigger as the backlink guard: a file-based Context Graph that
+    // materializes a `knowledge/` layer. A plan with no knowledge graph layer is
+    // not the connected-web product and is exempt.
+    const knowledgeArtifacts = artifacts.filter(isKnowledgeLayerArtifact);
+    if (knowledgeArtifacts.length === 0)
+        return [];
+    const hasRequiredFloorCheck = artifacts.some((artifact) => artifact.checks.some((check) => check.kind === "graph_notes_connected" && (check.required ?? true)));
+    if (hasRequiredFloorCheck)
+        return [];
+    return [
+        "Build Plan produces a Context Graph but no requested output declares a required " +
+            "`graph_notes_connected` check. Add that check (typically on the `home.md` spine output) so the " +
+            "WHOLE graph — every summary included, not only cited ones — is link-connected and no note ships " +
+            "as a free-floating island that passes readiness silently.",
+    ];
+}
+/**
+ * Canonical top-level-layer guard (FIXED SKELETON / FLEXIBLE INTERIOR). A Build
+ * Plan's core derived content must live under the three canonical top-level layers
+ * — `summaries/`, `knowledge/`, `artifacts/` — or the `home.md` spine. A plan may
+ * NOT invent a new top-level folder (e.g. `graph/`, `insights/`) for core content;
+ * graph-shaped content goes under `knowledge/<your-interior>/`, whose interior is
+ * free (`entities/`, `claims/`, `timelines/`, `tables/`, `atlas/`, anything).
+ *
+ * Authoring is STRICT on case: a layer must be DECLARED in exact lowercase. A
+ * mixed-case declaration like `Knowledge/` is REJECTED here, because package
+ * validation and the runtime scanners are lowercase-path based — a mixed-case
+ * declaration would pass a tolerant authoring check and then silently break
+ * downstream (`collectMarkdownFiles(graph, "knowledge")` finds nothing under
+ * `Knowledge/`). The tolerant, case-insensitive classifier (`layerForPath`)
+ * exists only to POLICE already-built outputs, never to bless a bad
+ * declaration. Both faces come from the one central layer model:
+ * `isCanonicalDeclarationPath` is the strict authoring face;
+ * `layerForPath`/`roleForPath` is the tolerant policing face.
+ *
+ * Keys ONLY off each path artifact's FIRST path segment and the central
+ * canonical set — no task taxonomy, no per-plan naming, no hardcoded interior.
+ * Only the first segment is checked, so the entire interior of `knowledge/` is
+ * allowed. Non-path artifacts declare no folder and are skipped.
+ */
+function validateCanonicalTopLevelLayers(definition) {
+    const errors = [];
+    for (const artifact of definition.build_plan_schema.artifacts ?? []) {
+        if (artifact.shape.kind !== "path")
+            continue;
+        const normalized = normalizeLayerPath(artifact.shape.path);
+        if (normalized.length === 0)
+            continue;
+        // Strict: exact-lowercase canonical declaration (`knowledge/…` or the exact
+        // `home.md` spine). `Knowledge/` deliberately does NOT pass.
+        if (isCanonicalDeclarationPath(normalized))
+            continue;
+        const segment = normalized.split("/")[0] ?? "";
+        // A path that the tolerant classifier WOULD route into a canonical layer but
+        // that is not an exact lowercase declaration is a case-drift declaration
+        // (e.g. `Knowledge/`). Name the canonical lowercase form it must use.
+        const classified = layerForPath(normalized);
+        const detail = classified !== "other"
+            ? `Declare it in exact lowercase as \`${classified === "home" ? "home.md" : `${classified}/`}\`; ` +
+                "canonical layers must be declared lowercase so package validation and the runtime scanners find it."
+            : "Core Context Graph content must live under the canonical layers `summaries/`, `knowledge/`, " +
+                `\`artifacts/\`, or \`home.md\` (interior free, e.g. \`knowledge/<your-interior>/\`). Canonical layers: ${CANONICAL_LAYER_DIRS.join(", ")}.`;
+        errors.push(`Build Plan declares a core requested output at top-level folder \`${segment}/\` (${artifact.id}). ${detail}`);
+    }
+    return errors;
+}
+/**
+ * Lowercase alphanumeric tokens of length >= 3 drawn from free text. Used to
+ * compare the plan's own wording against the actual Source inventory.
+ */
+function tailoringTokens(text) {
+    const tokens = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length >= 3)
+            tokens.add(raw);
+    }
+    return tokens;
+}
+/**
+ * Generic structural words the contents-free scan emits for EVERY Source
+ * (boilerplate about files/folders/groups and the scan's own caveats). They
+ * carry no Source-specific signal, so they are excluded from the tailoring
+ * vocabulary — otherwise a generic skeleton could "pass" by echoing scan
+ * boilerplate. These are not intent or task words; they are the scan's own
+ * structural vocabulary.
+ */
+const TAILORING_STOP_TOKENS = new Set([
+    "file", "files", "folder", "folders", "root", "group", "groups", "extension",
+    "kind", "kinds", "the", "and", "across", "top", "level", "free", "source",
+    "scan", "inventory", "interf", "did", "not", "open", "read", "any", "before",
+    "locking", "stages", "treat", "counts", "lower", "bound", "some", "deep",
+    "were", "enumerated", "capped", "cost", "names", "contents", "parsed",
+    "period", "span", "reference", "filenames", "structure",
+]);
+/**
+ * Distinctive vocabulary the contents-free Source scan surfaced about THIS
+ * Source: folder/group names, the file-kind labels actually present, and any
+ * date/period tokens parsed from filenames. Derived entirely from the
+ * inventory — no intent keywords, no task taxonomy. Generic structural words
+ * are stripped so the vocabulary is Source-specific, not scan-specific.
+ */
+function sourceInventoryVocabulary(sourceContext) {
+    const vocabulary = new Set();
+    const add = (text) => {
+        if (!text)
+            return;
+        for (const token of tailoringTokens(text)) {
+            if (!TAILORING_STOP_TOKENS.has(token))
+                vocabulary.add(token);
+        }
+    };
+    // The items and observations carry the Source-specific signal (folder
+    // names, present file kinds, period tokens). The summary and limitations
+    // are mostly scan boilerplate, so they are intentionally not mined here.
+    // Callers may hand in a partial SourceContext (the type defaults `items`
+    // and `observations` to [], but raw caller objects are not re-parsed), so
+    // coalesce missing arrays defensively.
+    for (const item of sourceContext.items ?? []) {
+        add(item.name);
+        add(item.path);
+        add(item.kind);
+        add(item.note);
+    }
+    for (const observation of sourceContext.observations ?? [])
+        add(observation);
+    return vocabulary;
+}
+/**
+ * Tailoring guard. The original failure was a drafted Build Plan that was
+ * generic boilerplate — a cover/build/verify-style skeleton that ignored what
+ * was actually in the Source. The authoring prompt asks the agent to NAME
+ * what is present in the Source, but prose is advisory.
+ *
+ * This makes "provably tailored" machine-checked WITHOUT a task taxonomy: it
+ * derives a vocabulary from the contents-free Source inventory (folder/group
+ * names, present file kinds, period tokens) and requires the authored plan's
+ * own wording — stage ids/labels/descriptions and the purpose — to reference
+ * at least one of those Source-specific tokens. A plan that names nothing from
+ * the actual Source is, by construction, not tailored to it.
+ *
+ * It only runs when a real inventory is available; with no inventory there is
+ * nothing to tailor against, so the guard is a no-op (it never blocks on
+ * fabricated signal when the caller supplied no Source context).
+ */
+function validateTailoringGuard(definition, sourceContext) {
+    if (!sourceContext)
+        return [];
+    const vocabulary = sourceInventoryVocabulary(sourceContext);
+    // No distinctive Source vocabulary to tailor against (e.g. an inventory of
+    // only generic structural words). Tailoring cannot be proven either way, so
+    // do not block.
+    if (vocabulary.size === 0)
+        return [];
+    const planText = [
+        definition.purpose?.label ?? "",
+        definition.purpose?.task_hint ?? "",
+        ...(definition.stages ?? []).flatMap((stage) => [
+            stage.id,
+            stage.label,
+            stage.description ?? "",
+        ]),
+    ].join(" ");
+    for (const token of tailoringTokens(planText)) {
+        if (vocabulary.has(token))
+            return [];
+    }
+    return [
+        "Authored Build Plan is not tailored to this Source: its stage ids, stage labels, descriptions, " +
+            "and purpose reference nothing from the Source inventory (folder names, present file kinds, or " +
+            "period tokens). Reshape the stages to name what is actually in this Source instead of a generic skeleton.",
+    ];
+}
+/**
+ * Does the Build Plan package at `buildPlanPath` name at least one
+ * Source-specific token from `sourceContext`? True when it is tailored to the
+ * Source (or when there is nothing to tailor against — see below), false only
+ * when a real Source vocabulary exists and the plan references none of it.
+ *
+ * Re-uses the exact draft-time tailoring guard so the two faces of "tailored"
+ * cannot drift: a plan is tailored iff `validateTailoringGuard` raises no
+ * error. A null inventory, an empty Source vocabulary, or an unloadable
+ * package all return `true` (nothing to tailor against / nothing to compare),
+ * which keeps the non-regression guard below a no-op in exactly those cases.
+ */
+function buildPlanIsTailoredToSource(buildPlanPath, sourceContext) {
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanPath);
+    if (!definition)
+        return true;
+    return validateTailoringGuard(definition, sourceContext).length === 0;
+}
+/**
+ * IMPROVE-loop tailoring NON-REGRESSION guard (the improve-path analogue of the
+ * draft-time tailoring guard).
+ *
+ * The draft guard (`validateTailoringGuard`) is an absolute "this plan must
+ * name something from the Source" check, correct for a from-scratch draft. It
+ * is the WRONG shape for the improvement loop: a user may select and improve a
+ * plan that is generic by design (the shipped `interf-default` carries no
+ * draft-time tailoring at all), and the absolute guard would reject every
+ * legitimate improvement to it the moment the Source vocabulary happened not to
+ * collide with the plan's generic wording. Running the absolute guard on
+ * improve would therefore false-reject faithful improvements, not just
+ * de-tailoring ones.
+ *
+ * The real C1 threat is narrower and is what this guards: an improvement edit
+ * must not take a plan that WAS tailored to the Source and strip that tailoring
+ * back to a generic skeleton. So this is a before/after DELTA check against the
+ * SAME scanned Source inventory: if the pre-edit plan was tailored and the
+ * post-edit plan is not, the edit de-tailored the plan and is rejected. A plan
+ * that was already generic before the edit (e.g. `interf-default`) has no
+ * tailoring to lose, so the guard is a no-op for it — improve is free to refine
+ * it without being forced to invent Source-specific vocabulary. With no
+ * Source inventory available (no Source binding, unreadable Source), there is
+ * nothing to compare and the guard is likewise a no-op.
+ */
+export function validateImproveTailoringNonRegression(beforeBuildPlanPath, afterBuildPlanPath, sourceContext) {
+    if (!sourceContext)
+        return [];
+    // Only a plan that was tailored BEFORE the edit can be de-tailored by it.
+    if (!buildPlanIsTailoredToSource(beforeBuildPlanPath, sourceContext))
+        return [];
+    if (buildPlanIsTailoredToSource(afterBuildPlanPath, sourceContext))
+        return [];
+    return [
+        "Improvement edit de-tailored the Build Plan: the pre-edit plan referenced this Source " +
+            "(folder names, present file kinds, or period tokens) in its stage ids, labels, descriptions, " +
+            "or purpose, but the edited plan references none of it. An improvement may refine the plan but " +
+            "must not strip its Source-specific tailoring back to a generic skeleton.",
+    ];
+}
+/**
+ * Re-shape a base-validation result plus extra guard errors into one result.
+ * Shared so authoring and the improvement loop fold their guard errors in the
+ * exact same way (no per-call-site re-implementation of the ok/summary logic).
+ */
+function withExtraGuardErrors(validation, extraErrors) {
+    if (extraErrors.length === 0)
+        return validation;
+    const errors = [...validation.errors, ...extraErrors];
+    return {
+        ok: validation.ok && errors.length === 0,
+        summary: errors.length === 0
+            ? validation.summary
+            : `Build Plan package has ${errors.length} issue(s).`,
+        errors,
+        counts: validation.counts,
+    };
+}
+/**
+ * Lifecycle guards that apply to EVERY lifecycle stage that mutates a Build
+ * Plan package (authoring draft AND self-improvement loop): the base package
+ * validation plus the product-critical structural invariants a self-improvement
+ * run must not be allowed to silently strip —
+ * `summary_backlinks_present` (no orphaned CITED summary),
+ * `graph_notes_connected` (the WHOLE-graph connectivity floor: no uncited-summary
+ * or any-note island), and the canonical-top-level-layer rule (core content stays
+ * under `summaries/`, `knowledge/`, `artifacts/`, or `home.md`).
+ *
+ * The authoring-only guards (scaffold-removal, artifact-requirements, tailoring)
+ * live in `validateAuthoredBuildPlanPackage` because they are draft-time
+ * concerns, not improvement concerns.
+ */
+export function validateLifecycleBuildPlanPackage(buildPlanPath) {
     const validation = validateBuildPlanPackage(buildPlanPath);
-    if (!validation.ok)
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanPath);
+    if (!definition)
         return validation;
+    return withExtraGuardErrors(validation, [
+        ...validateSummaryBacklinkGuard(definition),
+        ...validateGraphConnectivityFloorGuard(definition),
+        ...validateCanonicalTopLevelLayers(definition),
+    ]);
+}
+function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements = [], sourceContext = null) {
+    // Start from the shared lifecycle guards (base + backlink + canonical layers),
+    // then layer the authoring-only guards on top. The lifecycle guards are
+    // defined once and shared with the improvement loop.
+    const validation = validateLifecycleBuildPlanPackage(buildPlanPath);
     const definition = loadBuildPlanDefinitionFromDir(buildPlanPath);
     if (!definition)
         return validation;
-    const errors = [...validation.errors];
+    const authoringErrors = [];
     const placeholderStage = definition.stages?.find((stage) => stage.id === "prepare" &&
         stage.contract_type === "build-plan-draft-stage" &&
         stage.writes.includes("draft-context"));
@@ -157,64 +559,112 @@ function validateAuthoredBuildPlanPackage(buildPlanPath, artifactRequirements =
     const placeholderPurpose = definition.purpose?.label === "From-scratch Build Plan draft" ||
         definition.purpose?.task_hint?.includes("Replace this neutral scaffold");
     if (placeholderStage) {
-        errors.push("Authored Build Plan still contains the neutral scaffold stage `prepare`.");
+        authoringErrors.push("Authored Build Plan still contains the neutral scaffold stage `prepare`.");
     }
     if (placeholderArtifact) {
-        errors.push("Authored Build Plan still contains the neutral scaffold artifact `draft-context`.");
+        authoringErrors.push("Authored Build Plan still contains the neutral scaffold artifact `draft-context`.");
     }
     if (placeholderPurpose) {
-        errors.push("Authored Build Plan still contains the neutral scaffold purpose.");
+        authoringErrors.push("Authored Build Plan still contains the neutral scaffold purpose.");
     }
-    errors.push(...validateArtifactRequirements(definition, artifactRequirements));
-    return {
-        ok: validation.ok && errors.length === 0,
-        summary: errors.length === 0
-            ? validation.summary
-            : `Build Plan package has ${errors.length} issue(s).`,
-        errors,
-        counts: validation.counts,
-    };
+    authoringErrors.push(...validateArtifactRequirements(definition, artifactRequirements));
+    authoringErrors.push(...validateTailoringGuard(definition, sourceContext));
+    return withExtraGuardErrors(validation, authoringErrors);
 }
 export async function runBuildPlanAuthoringDraft(options) {
     const buildPlanPath = createScratchLocalBuildPlanPackage({
-        prepDataDir: options.prepDataDir,
+        projectDataDir: options.projectDataDir,
         buildPlanId: options.buildPlanId,
         label: options.label,
-        hint: options.hint,
+        hint: options.hint ?? options.intent,
     });
+    // Resolve the Source context ONCE here so the shell's authoring-context.json
+    // and the persisted authoring brief carry the SAME value. Caller-supplied
+    // context wins (e.g. an MCP brief); otherwise run the cheap, contents-free
+    // Source scan so the auto path never feeds the draft a null inventory while
+    // the shell quietly held the real scan. This is the single source of truth
+    // for source_context across both surfaces.
+    const sourceContext = options.sourceContext ?? scanSourceContext(options.sourceFolderPath) ?? null;
+    // Create the authoring shell under the Project's durable service job storage
+    // (not /tmp) so it is preserved and inspectable like a stage shell: the
+    // rendered SKILL the agent received, its reasoning transcript, the build-plan
+    // before/after, and the validation verdict all survive for debugging.
+    const shellRoot = join(projectServiceJobShellsRoot(asProjectDataDir(options.projectDataDir)), `build-plan-author-${options.buildPlanId}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
     const shell = createBuildPlanAuthoringShell({
         buildPlanPath,
         buildPlanId: options.buildPlanId,
         label: options.label,
         referenceBuildPlanId: options.baseBuildPlanId ?? null,
         sourceFolderPath: options.sourceFolderPath,
-        taskPrompt: options.taskPrompt,
+        intent: options.intent,
         checks: options.checks ?? [],
+        userPrepInstructions: options.userPrepInstructions,
         requestedArtifacts: options.requestedArtifacts ?? [],
-        sourceProfile: options.sourceProfile ?? null,
+        sourceContext,
         artifactRequirements: options.artifactRequirements ?? [],
+        shellRoot,
     });
+    const authoringBrief = {
+        intent: options.intent,
+        requested_artifacts: options.requestedArtifacts ?? [],
+        checks: options.checks ?? [],
+        ...(options.userPrepInstructions ? { user_prep_instructions: options.userPrepInstructions } : {}),
+        source_context: sourceContext,
+        artifact_requirements: options.artifactRequirements ?? [],
+    };
     const session = await runBuildPlanEditSession({
         executor: options.executor,
         buildPlanPath,
         shell,
         prompt: buildBuildPlanAuthoringPrompt(),
-        validate: (buildPlanPath) => validateAuthoredBuildPlanPackage(buildPlanPath, options.artifactRequirements ?? []),
-        maxValidationRepairAttempts: 1,
+        validate: (buildPlanPath) => {
+            // Restore the brief BEFORE validating so coverage runs against the same
+            // source_context + artifact_requirements the shell was built from. If
+            // the restore can't land (missing/unparseable build-plan.json), do NOT
+            // silently validate a brief-less plan — fail loudly so the drop is
+            // visible instead of producing a plan that lost its tailoring inputs.
+            const briefWritten = writeBuildPlanAuthoringBrief(buildPlanPath, authoringBrief);
+            const result = validateAuthoredBuildPlanPackage(buildPlanPath, options.artifactRequirements ?? [], sourceContext);
+            if (briefWritten)
+                return result;
+            const errors = [
+                "Could not restore the authoring brief into build-plan.json (file missing or unparseable); " +
+                    "refusing to accept a draft that dropped its source_context and artifact_requirements.",
+                ...result.errors,
+            ];
+            return {
+                ok: false,
+                summary: `Build Plan package has ${errors.length} issue(s).`,
+                errors,
+                counts: result.counts,
+            };
+        },
+        maxValidationRepairAttempts: 2,
         onStatus: options.onStatus,
     });
     if (session.status !== "updated") {
         rmSync(buildPlanPath, { recursive: true, force: true });
     }
     else {
-        // 0.15 — auto-fill `role: "general"` for any stage the agent
+        // auto-fill `role: "general"` for any stage the agent
         // didn't explicitly tag. Idempotent and silent when every stage
         // already declares a role.
         const touched = ensureStageRoles(buildPlanPath);
         if (touched.length > 0 && options.onStatus) {
             options.onStatus(`STATUS: filled role=general on ${touched.length} stage(s) the author didn't tag (${touched.join(", ")}).`);
         }
+        // Final brief restore on the persisted package. `ensureStageRoles` may
+        // have rewritten build-plan.json, so re-stamp the brief and surface the
+        // rare case where it can't land rather than shipping a brief-less plan.
+        if (!writeBuildPlanAuthoringBrief(buildPlanPath, authoringBrief) && options.onStatus) {
+            options.onStatus("ERROR: could not restore the authoring brief into the saved Build Plan (source_context/artifact_requirements dropped).");
+        }
     }
+    // Freeze the shell so the draft execution is preserved and inspectable: the
+    // path is unchanged (so result.shellPath stays valid), symlinks are
+    // materialized into real files, and a preserved-shell manifest is written.
+    // Best-effort — a preservation hiccup must never fail the draft itself.
+    freezeBuildPlanAuthoringShell(shell.rootPath);
     return {
         status: session.status,
         changed: session.changed,
@@ -224,6 +674,3 @@ export async function runBuildPlanAuthoringDraft(options) {
         shellPath: shell.rootPath,
     };
 }
-export function resolveBuildPlanDraftPath(sourcePath, buildPlanId) {
-    return buildPlanDefinitionPath(sourcePath, buildPlanId);
-}