@deftai/directive-core 0.69.0 → 0.71.0

package/dist/branch/evaluate.js

@@ -1,3 +1,4 @@
+import { recordBypassSignal, recordGateCatch } from "../events/attribution-ledger.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
 import { currentBranch, GitNotFoundError } from "./git.js";
@@ -42,6 +43,7 @@ export function evaluate(projectRoot, options = {}) {
     const defaultBranches = options.defaultBranches ?? DEFAULT_BRANCHES;
     const allowMissingProjectDefinition = options.allowMissingProjectDefinition ?? false;
     if (setupExemptionActive()) {
+        recordBypassSignal(projectRoot, "verify:branch", `${ENV_SETUP_EXEMPTION}=1 setup-interview exemption`);
         return {
             exitCode: 0,
             message: "✓ deft branch-protection: setup-interview exemption active " +
@@ -97,6 +99,9 @@ export function evaluate(projectRoot, options = {}) {
     }
     const result = resolvePolicy(projectRoot);
     if (result.allowDirectCommits) {
+        if (result.source === "env-bypass") {
+            recordBypassSignal(projectRoot, "verify:branch", `${ENV_BYPASS}=1 on default branch '${branch}'`);
+        }
         return {
             exitCode: 0,
             message: `⚠ deft branch-protection: on default branch '${branch}', but ` +
@@ -105,6 +110,7 @@ export function evaluate(projectRoot, options = {}) {
     }
     if (result.source === "default-fail-closed" && result.error !== null) {
         if (allowMissingProjectDefinition && result.error.includes("not found")) {
+            recordBypassSignal(projectRoot, "verify:branch", "--allow-missing-project-definition bootstrap on default branch");
             return {
                 exitCode: 0,
                 message: "✓ deft branch-protection: PROJECT-DEFINITION missing AND " +
@@ -128,6 +134,7 @@ export function evaluate(projectRoot, options = {}) {
                 recovery,
         };
     }
+    recordGateCatch(projectRoot, "verify:branch", `blocked commit on default branch '${branch}'`);
     return {
         exitCode: 1,
         message: buildBlockMessage(branch, result),

package/dist/deposit/contain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * contain.ts — deposit-boundary symlink-escape guard (#2305).
+ *
+ * The framework deposit derives its destination as
+ * `deftDir = join(projectDir, ".deft/core")` and copies the (trusted) content
+ * payload into it. If a malicious project repo commits `.deft` (or `.deft/core`,
+ * or a parent) as a symlink that escapes the tree — e.g. `.deft -> ../../evil` —
+ * the deposit would write/replace framework content THROUGH that symlink,
+ * outside the resolved project tree, under the victim's account.
+ *
+ * `assertDepositContained` refuses that: it anchors on `realpath(projectDir)`,
+ * walks each existing component from the project root down to `deftDir`, rejects
+ * any component that is a symlink escaping the project tree, and asserts the
+ * deepest existing ancestor of `deftDir` resolves back UNDER the project tree
+ * using path-SEGMENT containment (not string `startsWith`).
+ *
+ * Callers MUST invoke it BEFORE the first copy/mkdir/reconstitute so a refusal
+ * deposits nothing.
+ *
+ * Refs #2305.
+ */
+/** Non-zero exit code for a deposit-containment refusal (needs-action). */
+export declare const DEPOSIT_CONTAINMENT_REFUSED_EXIT_CODE = 2;
+/** Thrown by the deposit/refresh path when the destination escapes the tree. */
+export declare class DepositContainmentError extends Error {
+    readonly projectDir: string;
+    readonly deftDir: string;
+    readonly offendingPath: string;
+    constructor(message: string, details: {
+        projectDir: string;
+        deftDir: string;
+        offendingPath: string;
+    });
+}
+/**
+ * Refuse the deposit when `.deft` / `.deft/core` (or a parent) is a symlink that
+ * escapes the resolved project tree. Throws {@link DepositContainmentError};
+ * MUST be called BEFORE any deposit write so a refusal deposits nothing.
+ */
+export declare function assertDepositContained(projectDir: string, deftDir: string): void;
+//# sourceMappingURL=contain.d.ts.map

package/dist/deposit/contain.js

@@ -0,0 +1,113 @@
+/**
+ * contain.ts — deposit-boundary symlink-escape guard (#2305).
+ *
+ * The framework deposit derives its destination as
+ * `deftDir = join(projectDir, ".deft/core")` and copies the (trusted) content
+ * payload into it. If a malicious project repo commits `.deft` (or `.deft/core`,
+ * or a parent) as a symlink that escapes the tree — e.g. `.deft -> ../../evil` —
+ * the deposit would write/replace framework content THROUGH that symlink,
+ * outside the resolved project tree, under the victim's account.
+ *
+ * `assertDepositContained` refuses that: it anchors on `realpath(projectDir)`,
+ * walks each existing component from the project root down to `deftDir`, rejects
+ * any component that is a symlink escaping the project tree, and asserts the
+ * deepest existing ancestor of `deftDir` resolves back UNDER the project tree
+ * using path-SEGMENT containment (not string `startsWith`).
+ *
+ * Callers MUST invoke it BEFORE the first copy/mkdir/reconstitute so a refusal
+ * deposits nothing.
+ *
+ * Refs #2305.
+ */
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+/** Non-zero exit code for a deposit-containment refusal (needs-action). */
+export const DEPOSIT_CONTAINMENT_REFUSED_EXIT_CODE = 2;
+/** Thrown by the deposit/refresh path when the destination escapes the tree. */
+export class DepositContainmentError extends Error {
+    projectDir;
+    deftDir;
+    offendingPath;
+    constructor(message, details) {
+        super(message);
+        this.name = "DepositContainmentError";
+        this.projectDir = details.projectDir;
+        this.deftDir = details.deftDir;
+        this.offendingPath = details.offendingPath;
+    }
+}
+/**
+ * Path-SEGMENT containment: is `child` equal to `parent` or nested under it?
+ * Uses `path.relative` so `/foo` is NOT treated as containing `/foobar`
+ * (`relative("/foo", "/foobar")` is `"../foobar"`, which is rejected).
+ */
+function isContained(parent, child) {
+    if (parent === child) {
+        return true;
+    }
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Refuse the deposit when `.deft` / `.deft/core` (or a parent) is a symlink that
+ * escapes the resolved project tree. Throws {@link DepositContainmentError};
+ * MUST be called BEFORE any deposit write so a refusal deposits nothing.
+ */
+export function assertDepositContained(projectDir, deftDir) {
+    const projectAbs = resolve(projectDir);
+    let projectReal;
+    try {
+        projectReal = realpathSync(projectAbs);
+    }
+    catch {
+        // The project directory does not exist yet (e.g. `directive init <new-path>`).
+        // Nothing under it can exist, so there is no pre-existing symlink to escape
+        // through -- the downstream init flow creates fresh, clean directories. Let
+        // the deposit proceed; a missing content payload / mkdir failure surfaces its
+        // own error later.
+        return;
+    }
+    const deftAbs = resolve(deftDir);
+    const rel = relative(projectAbs, deftAbs);
+    if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new DepositContainmentError(`deposit refused: deposit target ${deftAbs} is not nested under the project tree ${projectAbs}`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: deftAbs });
+    }
+    const segments = rel.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    let current = projectAbs;
+    let deepestExistingReal = projectReal;
+    for (const segment of segments) {
+        current = join(current, segment);
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch {
+            // This component does not exist yet; nothing below it can exist either.
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            let linkReal;
+            try {
+                linkReal = realpathSync(current);
+            }
+            catch {
+                throw new DepositContainmentError(`deposit refused: ${current} is a broken/dangling symlink on the deposit path`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: current });
+            }
+            if (!isContained(projectReal, linkReal)) {
+                throw new DepositContainmentError(`deposit refused: ${current} is a symlink escaping the project tree ` +
+                    `(resolves to ${linkReal}, outside ${projectReal})`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: current });
+            }
+            deepestExistingReal = linkReal;
+        }
+        else {
+            deepestExistingReal = realpathSync(current);
+        }
+    }
+    // Defense-in-depth: the deepest EXISTING ancestor of deftDir must resolve back
+    // under the project tree (segment containment, not string startsWith).
+    if (!isContained(projectReal, deepestExistingReal)) {
+        throw new DepositContainmentError(`deposit refused: deposit path escapes the project tree ` +
+            `(${deepestExistingReal} is outside ${projectReal})`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: deepestExistingReal });
+    }
+}
+//# sourceMappingURL=contain.js.map

package/dist/deposit/copy-tree.js

@@ -8,7 +8,7 @@
  * Refs #1942 S1, #1477.
  */
 import { createReadStream, createWriteStream } from "node:fs";
-import { chmod, mkdir, readdir, stat } from "node:fs/promises";
+import { chmod, lstat, mkdir, readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 const DEFAULT_FILE_MODE = 0o644;
@@ -34,7 +34,13 @@ async function copyDirContents(src, dst) {
     for (const entry of entries) {
         const srcPath = join(src, entry.name);
         const dstPath = join(dst, entry.name);
-        const srcStat = await stat(srcPath);
+        // #2305: lstat (not stat) so a symlinked entry is NOT followed silently.
+        // The deposit copies regular files/dirs only; a symlink in the (trusted)
+        // payload is skipped rather than dereferenced.
+        const srcStat = await lstat(srcPath);
+        if (srcStat.isSymbolicLink()) {
+            continue;
+        }
         if (srcStat.isDirectory()) {
             await copyDirContents(srcPath, dstPath);
         }

package/dist/doctor/checks.d.ts

@@ -19,6 +19,17 @@ export declare function checkLegacyLayout(projectRoot: string, seams?: CheckSeam
  * been stamped npm-managed. Local-only (no network).
  */
 export declare function checkCanonicalVendoredNpmSignpost(projectRoot: string, seams?: CheckSeams): CheckResult;
+/**
+ * #2294: report whether the located install manifest can surface a version.
+ * A legacy `deft-install` deposit made without a release pin writes empty
+ * `tag`/`ref` and only a short `sha`, leaving the framework version silently
+ * unreportable. Since the Go installer is a frozen legacy bridge (#1912) and
+ * the Python/Go rails are retired (#1933/#2022/#2068), the fix is doctor-side:
+ * turn the silent blank into a visible, actionable finding. Advisory only --
+ * exit-code-exempt like `canonical-vendored-npm-signpost` -- because a sha-only
+ * deposit is still a working install, just an unpinned one.
+ */
+export declare function checkManifestVersionReportable(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {
     isDir?: (p: string) => boolean;

package/dist/doctor/checks.js

@@ -4,7 +4,7 @@ import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
-import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
+import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestReportableVersion, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
 import { readTextSafe } from "./paths.js";
 function readText(path, seams) {
     return (seams.readText ?? readTextSafe)(path);
@@ -366,11 +366,82 @@ export function checkCanonicalVendoredNpmSignpost(projectRoot, seams = {}) {
         },
     };
 }
+/**
+ * #2294: report whether the located install manifest can surface a version.
+ * A legacy `deft-install` deposit made without a release pin writes empty
+ * `tag`/`ref` and only a short `sha`, leaving the framework version silently
+ * unreportable. Since the Go installer is a frozen legacy bridge (#1912) and
+ * the Python/Go rails are retired (#1933/#2022/#2068), the fix is doctor-side:
+ * turn the silent blank into a visible, actionable finding. Advisory only --
+ * exit-code-exempt like `canonical-vendored-npm-signpost` -- because a sha-only
+ * deposit is still a working install, just an unpinned one.
+ */
+export function checkManifestVersionReportable(projectRoot, installRoot, seams = {}) {
+    const isFile = seams.isFile ?? ((p) => readText(p, seams) !== null);
+    const manifestPath = locateManifest(projectRoot, installRoot, isFile);
+    if (manifestPath === null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "skip",
+            detail: "No install manifest found; no framework version to report.",
+            data: { manifest_path: null },
+        };
+    }
+    const text = readText(manifestPath, seams);
+    if (text === null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "skip",
+            detail: `Install manifest at ${manifestPath} is unreadable.`,
+            data: { manifest_path: manifestPath },
+        };
+    }
+    const manifest = parseInstallManifest(text);
+    const reportable = manifestReportableVersion(manifest);
+    if (reportable.version !== null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "pass",
+            detail: `Framework version resolves to ${reportable.version} (from manifest ${reportable.source}) at ${manifestPath}.`,
+            data: {
+                manifest_path: manifestPath,
+                version: reportable.version,
+                source: reportable.source,
+            },
+        };
+    }
+    if (reportable.sha !== null) {
+        const shortSha = reportable.sha.slice(0, 8);
+        return {
+            name: "manifest-version-reportable",
+            status: "fail",
+            detail: `Install manifest at ${manifestPath} carries no semver tag/ref (sha ${shortSha} only), ` +
+                "so the framework version is unreportable. This happens on legacy `deft-install` deposits " +
+                `made without a release pin (#2294). Run \`${CANONICAL_UPGRADE_COMMAND}\` then \`directive update\` ` +
+                `to obtain a pinned npm-managed manifest. See ${UPGRADING_DOC_URL}.`,
+            data: {
+                manifest_path: manifestPath,
+                version: null,
+                source: reportable.source,
+                sha: reportable.sha,
+                upgrade_command: CANONICAL_UPGRADE_COMMAND,
+                upgrading_doc_url: UPGRADING_DOC_URL,
+            },
+        };
+    }
+    return {
+        name: "manifest-version-reportable",
+        status: "skip",
+        detail: `Install manifest at ${manifestPath} has neither a semver tag/ref nor a sha; no provenance to report.`,
+        data: { manifest_path: manifestPath, version: null, sha: null, source: reportable.source },
+    };
+}
 export function deriveExitCode(checks, errors) {
+    const exitExempt = new Set(["canonical-vendored-npm-signpost", "manifest-version-reportable"]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
     }
-    if (checks.some((c) => c.status === "fail" && c.name !== "canonical-vendored-npm-signpost")) {
+    if (checks.some((c) => c.status === "fail" && !exitExempt.has(c.name))) {
         return 1;
     }
     return 0;
@@ -402,6 +473,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
             data: { agents_md_path: agentsMdPath },
         });
         checks.push(checkManifestAgreement(projectRoot, null, seams));
+        checks.push(checkManifestVersionReportable(projectRoot, null, seams));
         checks.push(checkLegacyLayout(projectRoot, seams));
         checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
         return {
@@ -415,6 +487,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkQuickStartResolves(projectRoot, installRoot, seams));
     checks.push(checkSkillPathsResolve(projectRoot, agentsMdText, seams));
     checks.push(checkManifestAgreement(projectRoot, installRoot, seams));
+    checks.push(checkManifestVersionReportable(projectRoot, installRoot, seams));
     checks.push(checkInstallPathConsistency(projectRoot, installRoot, seams));
     checks.push(checkLegacyLayout(projectRoot, seams));
     checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));

package/dist/doctor/doctor-state.js

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { resolveTriageCachePath } from "../triage/cache-path.js";
 import { CLEAN_WINDOW_HOURS, DIRTY_WINDOW_HOURS, ENV_STATE_PATH } from "./constants.js";
 const STATE_FILENAME = "doctor-state.json";
 export function statePath(projectRoot) {
@@ -10,7 +10,7 @@ export function statePath(projectRoot) {
             ? join(process.env.HOME ?? projectRoot, override.slice(1))
             : override;
     }
-    return resolveEvalPath(projectRoot, STATE_FILENAME);
+    return resolveTriageCachePath(projectRoot, STATE_FILENAME);
 }
 function parseIso(ts) {
     if (typeof ts !== "string" || !ts) {

package/dist/doctor/main.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { contentRoot } from "../content-root.js";
+import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "../policy/plan-extensions.js";
+import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
@@ -257,6 +259,11 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking plan.policy namespacing (shadowed bare keys)...");
+    runPlanExtensionShadowCheck(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking optional root Taskfile.yml include...");
     runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams);
     let resolution = null;
@@ -364,7 +371,9 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                 sink.info(`${name}: skip -- ${detail}`);
                 continue;
             }
-            if ((name === "legacy-layout" || name === "canonical-vendored-npm-signpost") &&
+            if ((name === "legacy-layout" ||
+                name === "canonical-vendored-npm-signpost" ||
+                name === "manifest-version-reportable") &&
                 status === "fail") {
                 sink.warn(`${name}: ${detail}`);
                 addFinding({
@@ -618,6 +627,50 @@ function runUserMdResolutionCheck(projectRoot, sink, addFinding, seams) {
     });
     return result;
 }
+/**
+ * Loud shadow diagnostic (#2301): flag every plan-extension key whose bare form
+ * (e.g. `plan.policy`) coexists with the namespaced form (`plan.x-directive/policy`).
+ * Because the reader is namespace-first, the bare block is silently ignored --
+ * the exact "edit takes no effect, no warning" trap behind #2295. Emits a
+ * `warning` finding per shadowed key; never an `error`, so `deft doctor` stays
+ * green on a merely-legibility issue. A clean project reports a `skip` finding.
+ */
+function runPlanExtensionShadowCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "plan-extension-shadow";
+    const detect = seams.detectPlanExtensionShadows ??
+        ((root) => {
+            const [data] = loadProjectDefinition(root);
+            return data === null ? [] : detectShadowedPlanExtensions(data.plan);
+        });
+    try {
+        const shadows = detect(projectRoot);
+        if (shadows.length === 0) {
+            const cleanMessage = `${checkName}: no shadowed bare plan keys`;
+            sink.success(cleanMessage);
+            addFinding({ severity: "skip", message: cleanMessage, check: checkName, status: "clean" });
+            return;
+        }
+        for (const shadow of shadows) {
+            const message = `plan.policy shadow -- ${describeShadowedPlanExtension(shadow)}`.replace(/\r?\n/g, " ");
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: "shadowed",
+                namespaced_key: shadow.namespacedKey,
+                legacy_key: shadow.legacyKey,
+                shadowed_sub_keys: [...shadow.shadowedSubKeys],
+            });
+        }
+    }
+    catch (exc) {
+        const detail = `${exc instanceof Error ? exc.name : "Error"}: ${exc}`.replace(/\r?\n/g, " ");
+        const message = `${checkName}: probe failed -- ${detail}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
  * (#2267). The `directive` surface always works; `task deft:X` is optional and

package/dist/doctor/manifest.d.ts

@@ -2,6 +2,26 @@ import { readTextSafe } from "./paths.js";
 export declare function parseManifest(text: string): Record<string, string>;
 export declare function parseInstallManifest(text: string): Record<string, string>;
 export declare function manifestTagToVersion(manifest: Record<string, string>): string | null;
+/** Reportability classes for an install manifest's version provenance (#2294). */
+export type ManifestVersionSource = "tag" | "ref" | "sha" | "none";
+export interface ReportableVersion {
+    /** Semver derived from `tag`/`ref` (leading `v` stripped), else null. */
+    readonly version: string | null;
+    /** Recorded commit `sha`, trimmed, else null. */
+    readonly sha: string | null;
+    /** Where a reportable identity was found. */
+    readonly source: ManifestVersionSource;
+}
+/**
+ * Classify what a manifest can report as its version (#2294). A legacy
+ * `deft-install` deposit made without a release pin writes empty `tag`/`ref`
+ * and only a short `sha`; `manifestTagToVersion` then returns null and the
+ * version is silently unreportable. This helper distinguishes a pinned
+ * semver (`tag`/`ref`) from a sha-only deposit from a manifest with no
+ * provenance at all, so callers can surface an actionable signal instead of a
+ * blank.
+ */
+export declare function manifestReportableVersion(manifest: Record<string, string>): ReportableVersion;
 export declare function manifestCandidatePaths(projectRoot: string, installRoot: string | null): string[];
 export declare function locateManifest(projectRoot: string, installRoot: string | null, isFile?: (p: string) => boolean): string | null;
 export declare function parseInstallRootFromAgentsMd(text: string): string | null;

package/dist/doctor/manifest.js

@@ -43,6 +43,28 @@ export function manifestTagToVersion(manifest) {
     }
     return null;
 }
+/**
+ * Classify what a manifest can report as its version (#2294). A legacy
+ * `deft-install` deposit made without a release pin writes empty `tag`/`ref`
+ * and only a short `sha`; `manifestTagToVersion` then returns null and the
+ * version is silently unreportable. This helper distinguishes a pinned
+ * semver (`tag`/`ref`) from a sha-only deposit from a manifest with no
+ * provenance at all, so callers can surface an actionable signal instead of a
+ * blank.
+ */
+export function manifestReportableVersion(manifest) {
+    const version = manifestTagToVersion(manifest);
+    if (version !== null) {
+        const tag = typeof manifest.tag === "string" ? manifest.tag.trim() : "";
+        return { version, sha: readSha(manifest), source: tag ? "tag" : "ref" };
+    }
+    const sha = readSha(manifest);
+    return { version: null, sha, source: sha !== null ? "sha" : "none" };
+}
+function readSha(manifest) {
+    const raw = typeof manifest.sha === "string" ? manifest.sha.trim() : "";
+    return raw || null;
+}
 export function manifestCandidatePaths(projectRoot, installRoot) {
     const raw = [];
     if (installRoot) {

package/dist/doctor/types.d.ts

@@ -1,4 +1,5 @@
 import type { AdvisoryEvaluateResult } from "../agents-md-advisory/evaluate.js";
+import type { ShadowedPlanExtension } from "../policy/plan-extensions.js";
 import type { EngineProbeResult } from "../resolution/classify.js";
 import type { ResolutionMode } from "../resolution/index.js";
 import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
@@ -127,5 +128,12 @@ export interface DoctorSeams {
      * first-hit-wins resolver scoped to the project root.
      */
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
+    /**
+     * Plan-extension shadow detector seam (#2301). Injected so the doctor
+     * shadow-diagnostic surface stays deterministic + offline in tests. Defaults
+     * to loading PROJECT-DEFINITION and running `detectShadowedPlanExtensions` on
+     * its `plan` object; returns [] when no project definition is present.
+     */
+    readonly detectPlanExtensionShadows?: (projectRoot: string) => readonly ShadowedPlanExtension[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/eval/crud-telemetry.d.ts

@@ -0,0 +1,59 @@
+export declare const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+export type CrudOperation = "create" | "read" | "update" | "delete";
+export type ByteDiffMinimality = "surgical" | "whole-file-rewrite";
+export interface CrudOperationMetric {
+    readonly directiveVersion: string;
+    readonly operation: CrudOperation;
+    readonly path: string;
+    readonly schemaValid: boolean;
+    readonly schemaErrors: readonly string[];
+    readonly fieldInventionCount: number;
+    readonly inventedKeys: readonly string[];
+    readonly byteDiffMinimality: ByteDiffMinimality | null;
+    readonly byteDiffChangedRatio: number | null;
+    readonly recordedAt: string;
+}
+export interface CrudResult {
+    readonly ok: boolean;
+    readonly content?: string;
+    readonly error?: string;
+}
+export interface InstrumentedVbriefCrudOptions {
+    readonly directiveVersion?: string;
+    readonly now?: () => Date;
+}
+/** Whole-file rewrites change at least half of the bytes or re-serialize with high drift. */
+export declare const BYTE_DIFF_WHOLE_FILE_THRESHOLD = 0.5;
+/** Ratio of edit distance to the longer string length. */
+export declare function computeChangedByteRatio(before: string, after: string): number;
+/** Classify whether an update preserved bytes (surgical) or rewrote the file. */
+export declare function classifyByteDiffMinimality(before: string, after: string): {
+    readonly kind: ByteDiffMinimality;
+    readonly changedRatio: number;
+};
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
+export declare function crudMetricsHistoryPath(projectRoot: string): string;
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+export declare function persistCrudMetrics(projectRoot: string, metrics: readonly CrudOperationMetric[]): void;
+/**
+ * Instrumented vBRIEF/xBRIEF CRUD chokepoint (#1703 Tier 1).
+ * Every operation emits a version-tagged metric covering schema validity,
+ * field invention, and (for updates) byte-diff minimality.
+ * Delete intentionally succeeds on schema-invalid files so corrupt artifacts can be removed.
+ */
+export declare class InstrumentedVbriefCrud {
+    private readonly directiveVersion;
+    private readonly now;
+    private readonly metrics;
+    constructor(options?: InstrumentedVbriefCrudOptions);
+    getMetrics(): readonly CrudOperationMetric[];
+    clearMetrics(): void;
+    create(path: string, content: string): CrudResult;
+    read(path: string): CrudResult;
+    update(path: string, content: string, options?: {
+        trustedWrite?: boolean;
+    }): CrudResult;
+    delete(path: string): CrudResult;
+    private recordMetric;
+}
+//# sourceMappingURL=crud-telemetry.d.ts.map