@deftai/directive-core 0.68.1 → 0.70.0

package/dist/init-deposit/scaffold.js

@@ -212,6 +212,63 @@ export function writeInstallManifest(projectDir, deftDir, fields) {
     writeFileSync(path, body, "utf8");
     return path;
 }
+/** Canonical committed pin dependency name (mirrors resolution/pin.ts). */
+export const PIN_DEPENDENCY_NAME = "@deftai/directive";
+/**
+ * Write the committed `package.json` version pin on `@deftai/directive`
+ * (exact devDependency; `"private": true` preserved) so the resolution spine
+ * has a canonical, npm-native pin to read before directive runs. This unblocks
+ * #2269 (which is gated on the pin existing).
+ *
+ * Behavior:
+ *  - existing `package.json`  -> the exact devDependency pin is set/updated;
+ *    an existing `"private"` value is preserved verbatim (never clobbered).
+ *  - absent `package.json`    -> a minimal `{ "private": true, ... }` is created.
+ *  - idempotent               -> re-running with the same pin makes no change.
+ *
+ * This is a deposit primitive; wiring it into the `init` verb flow is owned by
+ * #2265 (the init-consumes-plan child), per the #2264 scope guard.
+ */
+export function ensurePackageJsonPin(projectDir, version, io) {
+    const pinVersion = version.trim().replace(/^v/i, "");
+    const path = join(projectDir, "package.json");
+    const existed = existsSync(path);
+    let pkg = {};
+    if (existed) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                pkg = parsed;
+            }
+            else {
+                throw new Error("package.json root must be a JSON object");
+            }
+        }
+        catch (cause) {
+            throw new Error(`could not parse package.json (leaving it unchanged): ${String(cause)}`);
+        }
+    }
+    else {
+        // Fresh scaffold: a consumer deposit is a non-published workspace.
+        pkg.private = true;
+    }
+    const devDeps = typeof pkg.devDependencies === "object" &&
+        pkg.devDependencies !== null &&
+        !Array.isArray(pkg.devDependencies)
+        ? { ...pkg.devDependencies }
+        : {};
+    if (devDeps[PIN_DEPENDENCY_NAME] === pinVersion) {
+        io.printf(`package.json already pins ${PIN_DEPENDENCY_NAME}@${pinVersion} — skipping.\n`);
+        return { changed: false, pinVersion, created: false };
+    }
+    devDeps[PIN_DEPENDENCY_NAME] = pinVersion;
+    pkg.devDependencies = devDeps;
+    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    io.printf(existed
+        ? `package.json updated: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact).\n`
+        : `package.json created: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact, private).\n`);
+    return { changed: true, pinVersion, created: !existed };
+}
 export function writeAgentsMd(projectDir, deftDir, io) {
     const plan = agentsRefreshPlan(projectDir, { frameworkRoot: deftDir });
     const state = plan.state;

package/dist/init-deposit/untrack-core.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `migrate --untrack-core`: the one-time vendored→hybrid `.deft/core` un-commit
+ * (#2269). Owns the single destructive `git rm --cached -r .deft/core` index
+ * mutation in the framework — `init`/`update` only ever write the
+ * non-destructive `.gitignore` entry (boundary asserted by the colocated test).
+ *
+ * Safety contract:
+ *   - NEVER touches working-tree content. `git rm --cached` removes files from
+ *     the index only; the on-disk deposit is left intact.
+ *   - Gated on a committed `package.json` pin existing (#2264 / Decision 2):
+ *     once `.deft/core` is un-committed, content can be reconstituted from the
+ *     pinned engine, so nothing is lost. With no pin, un-committing could leave
+ *     the deposit unrecoverable, so we refuse.
+ *   - Idempotent: once the deposit is un-tracked and ignored, re-running is a
+ *     no-op that mutates nothing.
+ *
+ * The doctor detection that SURFACES this verb (the "payload tracked but should
+ * be ignored" signpost emitting `Next command: directive migrate --untrack-core`)
+ * is owned by child D (#2267); this module provides only the verb it points at.
+ *
+ * Refs #2269, #2264, #2123, #2124, #2203.
+ */
+import { type PinReadResult } from "../resolution/pin.js";
+import type { InitDepositIo } from "./constants.js";
+import { type GitLsFiles } from "./gitignore.js";
+/** The deposit path un-committed from the git index (never from the working tree). */
+export declare const UNTRACK_CORE_PATH = ".deft/core";
+export type UntrackCoreOutcome = "untracked" | "already-clean" | "refused-missing-pin" | "git-error";
+export interface UntrackCoreResult {
+    readonly outcome: UntrackCoreOutcome;
+    /** 0: untracked / already-clean · 1: refused (missing pin) · 2: git error. */
+    readonly exitCode: 0 | 1 | 2;
+    /** Whether `.deft/core` was tracked in git when the verb ran. */
+    readonly deftCoreTracked: boolean;
+    /** The committed exact pin version, or null when absent / non-exact. */
+    readonly pinVersion: string | null;
+    /** Whether the `.gitignore` reconciliation changed the file. */
+    readonly gitignoreChanged: boolean;
+    readonly message: string;
+}
+/** Outcome of the injected `git rm --cached -r <paths>` runner. */
+export interface GitRmCachedResult {
+    readonly ok: boolean;
+    /** stdout on success, or the error detail on failure. */
+    readonly detail: string;
+}
+/** Injected git runner for the destructive index mutation (default shells out). */
+export type GitRmCached = (projectDir: string, paths: readonly string[]) => GitRmCachedResult;
+export interface UntrackCoreSeams {
+    /** Probe whether `.deft/core` is git-tracked (default: `git ls-files`). */
+    gitLsFiles?: GitLsFiles;
+    /** Run `git rm --cached -r <paths>` (default: shells out to git). */
+    gitRmCached?: GitRmCached;
+    /** Read the committed `package.json` pin (default: resolution/pin.ts readPin). */
+    readPin?: (projectRoot: string) => PinReadResult;
+    /** Reconcile `.gitignore` (default: ensureUntrackCoreGitignoreLines). */
+    ensureGitignore?: (projectDir: string, io: InitDepositIo) => {
+        changed: boolean;
+        deftCoreIgnored: boolean;
+    };
+    /** Output sink for reconciliation messages (default: no-op; the CLI prints the summary). */
+    io?: InitDepositIo;
+}
+/**
+ * Orchestrate the vendored→hybrid `.deft/core` un-commit for `projectRoot`.
+ * Pure of process exit; the CLI wrapper maps {@link UntrackCoreResult.exitCode}
+ * to a process code. Three primary outcomes (untracked / already-clean /
+ * refused-missing-pin) plus a git-error fallthrough.
+ */
+export declare function untrackCore(projectRoot: string, seams?: UntrackCoreSeams): UntrackCoreResult;
+export interface RunUntrackCoreCliOptions {
+    readonly projectDir: string;
+    readonly jsonOut: boolean;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: UntrackCoreSeams;
+}
+/**
+ * CLI-facing wrapper: runs the un-commit, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Refusals and git errors print to stderr;
+ * success prints to stdout.
+ */
+export declare function runUntrackCoreCli(options: RunUntrackCoreCliOptions): number;
+//# sourceMappingURL=untrack-core.d.ts.map

package/dist/init-deposit/untrack-core.js

@@ -0,0 +1,150 @@
+/**
+ * `migrate --untrack-core`: the one-time vendored→hybrid `.deft/core` un-commit
+ * (#2269). Owns the single destructive `git rm --cached -r .deft/core` index
+ * mutation in the framework — `init`/`update` only ever write the
+ * non-destructive `.gitignore` entry (boundary asserted by the colocated test).
+ *
+ * Safety contract:
+ *   - NEVER touches working-tree content. `git rm --cached` removes files from
+ *     the index only; the on-disk deposit is left intact.
+ *   - Gated on a committed `package.json` pin existing (#2264 / Decision 2):
+ *     once `.deft/core` is un-committed, content can be reconstituted from the
+ *     pinned engine, so nothing is lost. With no pin, un-committing could leave
+ *     the deposit unrecoverable, so we refuse.
+ *   - Idempotent: once the deposit is un-tracked and ignored, re-running is a
+ *     no-op that mutates nothing.
+ *
+ * The doctor detection that SURFACES this verb (the "payload tracked but should
+ * be ignored" signpost emitting `Next command: directive migrate --untrack-core`)
+ * is owned by child D (#2267); this module provides only the verb it points at.
+ *
+ * Refs #2269, #2264, #2123, #2124, #2203.
+ */
+import { execFileSync } from "node:child_process";
+import { PIN_DEPENDENCY_NAME, readPin } from "../resolution/pin.js";
+import { ensureUntrackCoreGitignoreLines, isDepositTrackedInGit, } from "./gitignore.js";
+/** The deposit path un-committed from the git index (never from the working tree). */
+export const UNTRACK_CORE_PATH = ".deft/core";
+/** Default `git rm --cached -r <paths>`: index-only removal, working tree preserved. */
+function defaultGitRmCached(projectDir, paths) {
+    try {
+        const out = execFileSync("git", ["rm", "--cached", "-r", "--", ...paths], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, detail: out };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail };
+    }
+}
+function refusedMissingPinMessage(pin) {
+    const reason = pin.nonExact
+        ? `package.json pins ${PIN_DEPENDENCY_NAME} with a non-exact range spec (${pin.rawSpec ?? "?"})`
+        : `no committed exact package.json pin on ${PIN_DEPENDENCY_NAME} was found`;
+    return ("directive migrate --untrack-core: refusing to run git rm --cached on .deft/core because " +
+        `${reason}. Un-committing without a committed exact pin could leave the deposit content ` +
+        "unrecoverable (nothing to reconstitute from). Write and commit an exact pin " +
+        "(e.g. via `directive init` / `directive update`), then re-run.");
+}
+/**
+ * Orchestrate the vendored→hybrid `.deft/core` un-commit for `projectRoot`.
+ * Pure of process exit; the CLI wrapper maps {@link UntrackCoreResult.exitCode}
+ * to a process code. Three primary outcomes (untracked / already-clean /
+ * refused-missing-pin) plus a git-error fallthrough.
+ */
+export function untrackCore(projectRoot, seams = {}) {
+    const gitRmCached = seams.gitRmCached ?? defaultGitRmCached;
+    const readPinFn = seams.readPin ?? readPin;
+    const ensureGitignore = seams.ensureGitignore ?? ensureUntrackCoreGitignoreLines;
+    const io = seams.io ?? { printf: () => { } };
+    const tracked = isDepositTrackedInGit(projectRoot, seams.gitLsFiles);
+    // Not tracked (or no git repo / git unavailable): nothing destructive to do.
+    // Reconcile the ignore entry so the layout is unambiguous, then report clean.
+    if (tracked !== true) {
+        const gi = ensureGitignore(projectRoot, io);
+        return {
+            outcome: "already-clean",
+            exitCode: 0,
+            deftCoreTracked: false,
+            pinVersion: readPinFn(projectRoot).pinVersion,
+            gitignoreChanged: gi.changed,
+            message: `directive migrate --untrack-core: .deft/core is not tracked in git — nothing to ` +
+                `un-commit. .gitignore ${gi.changed ? "reconciled (now ignores .deft/core/)" : "already ignores it"}.`,
+        };
+    }
+    // Tracked: gate on the committed pin so content stays reconstitutable.
+    // Refuse on either an absent pin OR a non-exact range spec — a range cannot
+    // deterministically reconstitute the exact deposit, so it is not a safe gate.
+    // The `|| pin.nonExact` makes the invariant self-documenting and robust to any
+    // future `readPin` that resolves a version alongside `nonExact: true` (#2269).
+    const pin = readPinFn(projectRoot);
+    if (pin.pinVersion === null || pin.nonExact) {
+        return {
+            outcome: "refused-missing-pin",
+            exitCode: 1,
+            deftCoreTracked: true,
+            pinVersion: null,
+            gitignoreChanged: false,
+            message: refusedMissingPinMessage(pin),
+        };
+    }
+    const rm = gitRmCached(projectRoot, [UNTRACK_CORE_PATH]);
+    if (!rm.ok) {
+        return {
+            outcome: "git-error",
+            exitCode: 2,
+            deftCoreTracked: true,
+            pinVersion: pin.pinVersion,
+            gitignoreChanged: false,
+            message: `directive migrate --untrack-core: git rm --cached failed: ${rm.detail.trim()}`,
+        };
+    }
+    const gi = ensureGitignore(projectRoot, io);
+    return {
+        outcome: "untracked",
+        exitCode: 0,
+        deftCoreTracked: true,
+        pinVersion: pin.pinVersion,
+        gitignoreChanged: gi.changed,
+        message: `directive migrate --untrack-core: removed ${UNTRACK_CORE_PATH} from the git index ` +
+            `(working tree untouched); pin ${pin.pinVersion} lets \`directive update\` reconstitute ` +
+            `content. .gitignore ${gi.changed ? "reconciled (now ignores .deft/core/)" : "already ignores it"}. ` +
+            "Commit the removal to complete the un-commit.",
+    };
+}
+function buildUntrackCoreSummaryJson(result, projectDir) {
+    return {
+        success: result.exitCode === 0,
+        action: "migrate-untrack-core",
+        outcome: result.outcome,
+        exit_code: result.exitCode,
+        project_dir: projectDir,
+        deft_core_tracked: result.deftCoreTracked,
+        pin_version: result.pinVersion,
+        gitignore_changed: result.gitignoreChanged,
+        message: result.message,
+    };
+}
+/**
+ * CLI-facing wrapper: runs the un-commit, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Refusals and git errors print to stderr;
+ * success prints to stdout.
+ */
+export function runUntrackCoreCli(options) {
+    const result = untrackCore(options.projectDir, { ...options.seams, io: { printf: () => { } } });
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify(buildUntrackCoreSummaryJson(result, options.projectDir), null, 2)}\n`);
+        return result.exitCode;
+    }
+    if (result.exitCode === 0) {
+        options.writeOut(`${result.message}\n`);
+    }
+    else {
+        options.writeErr(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=untrack-core.js.map

package/dist/intake/issue-ingest.d.ts

@@ -1,7 +1,18 @@
+import { type ScanFlag } from "../cache/scanner.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
+/**
+ * Thrown when the quarantine scanner hard-fails (credential-shaped content) on
+ * an ingested issue body/comment thread (#2306). Ingest MUST fail closed: emit
+ * nothing and propagate a non-zero exit rather than persisting the xBRIEF.
+ */
+export declare class ScannerHardFailError extends Error {
+    readonly issueNumber: number;
+    readonly flags: readonly ScanFlag[];
+    constructor(issueNumber: number, flags: readonly ScanFlag[]);
+}
 /** GitHub issue comment thread entry (REST `repos/.../issues/N/comments`). */
 export interface IssueComment {
     readonly id?: number;

package/dist/intake/issue-ingest.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
+import { scan } from "../cache/scanner.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -11,6 +12,27 @@ import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MI
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
+/**
+ * Thrown when the quarantine scanner hard-fails (credential-shaped content) on
+ * an ingested issue body/comment thread (#2306). Ingest MUST fail closed: emit
+ * nothing and propagate a non-zero exit rather than persisting the xBRIEF.
+ */
+export class ScannerHardFailError extends Error {
+    issueNumber;
+    flags;
+    constructor(issueNumber, flags) {
+        const details = flags
+            .filter((f) => f.severity === "hard-fail")
+            .map((f) => f.detail)
+            .join("; ");
+        super(`issue:ingest refused #${issueNumber}: quarantine scanner hard-fail` +
+            (details.length > 0 ? ` (${details})` : "") +
+            " -- nothing written.");
+        this.name = "ScannerHardFailError";
+        this.issueNumber = issueNumber;
+        this.flags = flags;
+    }
+}
 /** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
 export const ISSUE_COMMENT_THREAD_KEY = "issueCommentThread";
 const STATUS_MAP = {
@@ -311,7 +333,14 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     };
     if (overviewSource.length > 0) {
         warnBodyControlCharacters(number, overviewSource);
-        narratives.Overview = overviewSource;
+        // #2306: quarantine-scan untrusted body + comment-thread content before it
+        // is persisted as agent-facing scope authority. Fail closed on a credential
+        // hard-fail; otherwise persist the fenced/quarantined transform.
+        const scanResult = scan(overviewSource);
+        if (!scanResult.passed) {
+            throw new ScannerHardFailError(number, scanResult.flags);
+        }
+        narratives.Overview = scanResult.transformed_content;
     }
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
@@ -369,6 +398,19 @@ export function fetchFromCache(repo, number, options = {}) {
         if (typeof issue.html_url === "string" && issue.html_url.length > 0) {
             issue.url = issue.html_url;
         }
+        // #2306: consume the cache entry's SCANNED content.md (fenced/quarantined at
+        // cache-put) rather than the raw body, so the cache read path cannot bypass
+        // the quarantine transform. When content.md is absent (e.g. a credential
+        // hard-fail deleted it), the raw body falls through and is re-scanned in
+        // buildIssueVbrief.
+        if (result.contentPath !== null) {
+            try {
+                issue.body = readFileSync(result.contentPath, "utf8");
+            }
+            catch {
+                // fall back to the raw body (re-scanned downstream)
+            }
+        }
         return issue;
     }
     catch {
@@ -514,9 +556,25 @@ export function ingestBulk(issues, options) {
         created: [],
         duplicate: [],
         dryrun: [],
+        failed: [],
     };
     for (const issue of filtered) {
-        const [result, path, _msg] = ingestOne(issue, { ...options, existingRefs: refs });
+        let ingested;
+        try {
+            ingested = ingestOne(issue, { ...options, existingRefs: refs });
+        }
+        catch (exc) {
+            // #2306: a per-issue quarantine hard-fail must not sink the whole batch;
+            // record it, emit nothing for that issue, and surface a non-zero exit
+            // upstream via the `failed` bucket.
+            if (exc instanceof ScannerHardFailError) {
+                summary.failed.push(`#${exc.issueNumber}`);
+                process.stderr.write(`${exc.message}\n`);
+                continue;
+            }
+            throw exc;
+        }
+        const [result, path, _msg] = ingested;
         const rel = path !== null ? path.replace(`${options.vbriefDir}/`, "").replace(/\\/g, "/") : "";
         summary[result].push(rel);
         if (result === "created" && path !== null) {
@@ -581,7 +639,8 @@ export function issueIngestMain(args) {
         const created = summary.created;
         const duplicate = summary.duplicate;
         const dryrun = summary.dryrun;
-        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run (total considered: ${summary.total})\n`);
+        const failed = summary.failed ?? [];
+        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run, ${failed.length} refused (total considered: ${summary.total})\n`);
         for (const entry of created) {
             process.stdout.write(`  CREATED ${entry}\n`);
         }
@@ -591,19 +650,35 @@ export function issueIngestMain(args) {
         for (const entry of duplicate) {
             process.stdout.write(`  SKIP    ${entry} (already has scope vBRIEF)\n`);
         }
-        return 0;
+        for (const entry of failed) {
+            process.stdout.write(`  REFUSED ${entry} (quarantine scanner hard-fail; nothing written)\n`);
+        }
+        // #2306: fail closed on any quarantine hard-fail in the batch.
+        return failed.length > 0 ? 2 : 0;
     }
     const issue = fetchIssue(repo, args.number, { cwd: projectRoot });
     if (issue === null) {
         return 2;
     }
-    const [result, _path, msg] = ingestOne(issue, {
-        vbriefDir,
-        status,
-        repoUrl,
-        dryRun: args.dryRun,
-        cwd: projectRoot,
-    });
+    let result;
+    let msg;
+    try {
+        [result, , msg] = ingestOne(issue, {
+            vbriefDir,
+            status,
+            repoUrl,
+            dryRun: args.dryRun,
+            cwd: projectRoot,
+        });
+    }
+    catch (exc) {
+        // #2306: fail closed -- emit nothing, non-zero exit on a quarantine hard-fail.
+        if (exc instanceof ScannerHardFailError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     process.stdout.write(`${msg}\n`);
     return result === "duplicate" ? 1 : 0;
 }

package/dist/policy/plan-extensions.d.ts

@@ -32,4 +32,35 @@ export declare function readPlanCompletedNote(plan: unknown): unknown;
  * bare block alongside the namespaced one.
  */
 export declare function migrateLegacyPolicyKey(plan: Record<string, unknown>): void;
+/** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
+export declare const SHADOWABLE_PLAN_EXTENSIONS: ReadonlyArray<{
+    readonly namespacedKey: string;
+    readonly legacyKey: string;
+}>;
+/** A plan-extension key whose bare form is silently shadowed by the namespaced form. */
+export interface ShadowedPlanExtension {
+    /** The namespaced key that wins the read (e.g. `x-directive/policy`). */
+    readonly namespacedKey: string;
+    /** The bare legacy key that is silently ignored (e.g. `policy`). */
+    readonly legacyKey: string;
+    /**
+     * Best-effort list of sub-keys present in the shadowed bare object (e.g.
+     * `["triageScope", "wipCap"]`). Empty when the bare value is not an object.
+     */
+    readonly shadowedSubKeys: readonly string[];
+}
+/**
+ * Detect every plan-extension key where a bare (legacy) block coexists with the
+ * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the
+ * bare block is never read once the namespaced key exists -- edits to it take no
+ * effect. Detecting the coexistence lets callers emit a loud diagnostic instead
+ * of the silent no-op that the #2295 onboarding trap exhibited.
+ */
+export declare function detectShadowedPlanExtensions(plan: unknown): ShadowedPlanExtension[];
+/**
+ * Render a human-readable, loud diagnostic for a single shadowed plan-extension
+ * key. The message is surface-agnostic (no leading tag) so each caller can
+ * prefix it (`[policy:show]`, a doctor finding, ...).
+ */
+export declare function describeShadowedPlanExtension(shadow: ShadowedPlanExtension): string;
 //# sourceMappingURL=plan-extensions.d.ts.map

package/dist/policy/plan-extensions.js

@@ -54,4 +54,49 @@ export function migrateLegacyPolicyKey(plan) {
         delete plan[LEGACY_PLAN_POLICY_KEY];
     }
 }
+/** The namespaced/legacy key pairs a bare block can silently shadow (#2301). */
+export const SHADOWABLE_PLAN_EXTENSIONS = [
+    { namespacedKey: PLAN_POLICY_KEY, legacyKey: LEGACY_PLAN_POLICY_KEY },
+    { namespacedKey: PLAN_COMPLETED_NOTE_KEY, legacyKey: LEGACY_PLAN_COMPLETED_NOTE_KEY },
+];
+/**
+ * Detect every plan-extension key where a bare (legacy) block coexists with the
+ * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the
+ * bare block is never read once the namespaced key exists -- edits to it take no
+ * effect. Detecting the coexistence lets callers emit a loud diagnostic instead
+ * of the silent no-op that the #2295 onboarding trap exhibited.
+ */
+export function detectShadowedPlanExtensions(plan) {
+    const planObj = asPlanObject(plan);
+    if (planObj === null) {
+        return [];
+    }
+    const shadows = [];
+    for (const { namespacedKey, legacyKey } of SHADOWABLE_PLAN_EXTENSIONS) {
+        if (planObj[namespacedKey] === undefined || planObj[legacyKey] === undefined) {
+            continue;
+        }
+        const legacyValue = planObj[legacyKey];
+        const shadowedSubKeys = typeof legacyValue === "object" && legacyValue !== null && !Array.isArray(legacyValue)
+            ? Object.keys(legacyValue)
+            : [];
+        shadows.push({ namespacedKey, legacyKey, shadowedSubKeys });
+    }
+    return shadows;
+}
+/**
+ * Render a human-readable, loud diagnostic for a single shadowed plan-extension
+ * key. The message is surface-agnostic (no leading tag) so each caller can
+ * prefix it (`[policy:show]`, a doctor finding, ...).
+ */
+export function describeShadowedPlanExtension(shadow) {
+    const subKeys = shadow.shadowedSubKeys.length > 0
+        ? ` Shadowed field(s): ${shadow.shadowedSubKeys
+            .map((k) => `plan.${shadow.legacyKey}.${k}`)
+            .join(", ")}.`
+        : "";
+    return (`bare \`plan.${shadow.legacyKey}\` coexists with namespaced \`plan.${shadow.namespacedKey}\`; ` +
+        `the bare block is IGNORED (namespaced-first read) so edits to it silently take no effect.${subKeys} ` +
+        `Fold its values into \`plan.${shadow.namespacedKey}\` and delete \`plan.${shadow.legacyKey}\`.`);
+}
 //# sourceMappingURL=plan-extensions.js.map

package/dist/policy/wip.d.ts

@@ -1,5 +1,5 @@
-/** Framework default WIP cap (#1124 / umbrella #1119). */
-export declare const DEFAULT_WIP_CAP = 10;
+/** Framework default WIP cap (#2319; raised from 10 per #1124 / umbrella #1119). */
+export declare const DEFAULT_WIP_CAP = 20;
 /** vBRIEF lifecycle folders that count toward the WIP set. */
 export declare const WIP_LIFECYCLE_DIRS: readonly ["pending", "active"];
 export type WipCapSource = "typed" | "default" | "default-on-error";

package/dist/policy/wip.js

@@ -3,8 +3,8 @@ import { join } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
-/** Framework default WIP cap (#1124 / umbrella #1119). */
-export const DEFAULT_WIP_CAP = 10;
+/** Framework default WIP cap (#2319; raised from 10 per #1124 / umbrella #1119). */
+export const DEFAULT_WIP_CAP = 20;
 /** vBRIEF lifecycle folders that count toward the WIP set. */
 export const WIP_LIFECYCLE_DIRS = ["pending", "active"];
 function pythonTypeName(value) {

package/dist/resolution/classify.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Orthogonal fact-set classifier for the resolution spine (#2264 / epic #2203).
+ *
+ * `classify()` returns a flat, independent fact-set — never a single collapsed
+ * enum. `plan()` owns the collapse into one recommended action, so there is
+ * exactly one precedence table in the system.
+ *
+ * It REUSES the existing detectors rather than re-implementing them:
+ *  - pre-cutover artifacts    -> `../vbrief-validate/precutover.ts`
+ *  - managed-section sha      -> `../platform/agents-md.ts::parseManagedSectionAttrs`
+ *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
+ *  - committed pin            -> `./pin.ts`
+ */
+import type { ResolutionFacts } from "@deftai/directive-types";
+/** Result of probing whether an engine is reachable in the execution environment. */
+export interface EngineProbeResult {
+    readonly reachable: boolean;
+    readonly version: string | null;
+}
+export interface ClassifySeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly isDir?: (p: string) => boolean;
+    readonly readText?: (p: string) => string | null;
+    /**
+     * Probe for a reachable engine IN THE ENVIRONMENT THE CALLER IS RUNNING IN.
+     * Injected so classification is deterministic + offline in tests; the default
+     * shells out to the `directive` / `deft` CLI (the #2124 execution-env probe).
+     */
+    readonly engineProbe?: () => EngineProbeResult;
+    /** Pre-cutover probe; defaults to the shared `detectPreCutover` detector. */
+    readonly preCutoverProbe?: (cwd: string) => boolean;
+}
+/** Default engine probe: try `directive --version`, then `deft --version`. */
+export declare function defaultEngineProbe(): EngineProbeResult;
+/**
+ * Classify a project directory into the orthogonal resolution fact-set. All I/O
+ * is behind injectable seams so callers (tests, sandboxed runtimes) can supply a
+ * deterministic view of the filesystem and the engine-reachability probe.
+ */
+export declare function classify(cwd: string, seams?: ClassifySeams): ResolutionFacts;
+//# sourceMappingURL=classify.d.ts.map