@deftai/directive-core 0.99.0 → 0.100.0

package/dist/authz/types.js

@@ -5,7 +5,9 @@
  * agent authors must not independently satisfy implementation-approval gates.
  * Local-file forgery by a credential-compromised agent remains #983-class OOS.
  */
-/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs). */
+/** Structural apply op for scope:decompose (#3239 / epic #3237 Q2). Always gated. */
+export const SCOPE_DECOMPOSE_APPLY_STRUCTURAL = "scope.decompose.apply.structural";
+/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs + #3239). */
 export const AUTHZ_OPERATIONS = [
     "edit",
     "push",
@@ -18,6 +20,8 @@ export const AUTHZ_OPERATIONS = [
     "release-cut",
     "release-publish",
     "release-rollback",
+    /** Human-origin exact-draft-digest gate for scope:decompose apply (#3239). */
+    SCOPE_DECOMPOSE_APPLY_STRUCTURAL,
 ];
 /**
  * Human-origin kinds accepted as approval provenance.

package/dist/doctor/checks.d.ts

@@ -1,9 +1,42 @@
+import type { XbriefSchemaDistance } from "../staleness-tickler/types.js";
 import type { CheckResult } from "./types.js";
+/** Remediation verb for project envelope behind-major (#2971 / #3243 / #3236). */
+export declare const XBRIEF_ENVELOPE_MIGRATE_COMMAND: "deft migrate:xbrief";
+/** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
+export declare const XBRIEF_ENVELOPE_MAJOR_CHECK: "xbrief-envelope-version";
 export interface CheckSeams {
     readonly readText?: (path: string) => string | null;
     readonly isFile?: (path: string) => boolean;
     readonly isDir?: (path: string) => boolean;
+    /** List directory entries; throws on enum failure (fail-closed for live lifecycle dirs). */
+    readonly readdir?: (path: string) => string[];
 }
+/** One scanned project envelope and its schema distance vs the framework target. */
+export interface XbriefEnvelopeScanEntry {
+    readonly relativePath: string;
+    readonly declaredVersion: string | null;
+    readonly distance: XbriefSchemaDistance;
+}
+/**
+ * Scan live project xbrief envelopes (PROJECT-DEFINITION + pending/active) for
+ * schema distance vs the installed framework envelope major (#3243). Complements
+ * #2971 PROJECT-DEFINITION-only probe; remediation aligns with migrate hybrid
+ * rewrite (#3236).
+ */
+export declare function scanXbriefEnvelopeVersions(projectRoot: string, seams?: CheckSeams, targetVersion?: string): {
+    readonly targetVersion: string;
+    readonly entries: readonly XbriefEnvelopeScanEntry[];
+    readonly worstDistance: XbriefSchemaDistance | null;
+    readonly behindMajor: readonly XbriefEnvelopeScanEntry[];
+};
+/**
+ * Fail closed when any scanned project xBRIEF envelope declares a major behind
+ * the framework target (#3243 / epic #3237 Q5 Option 2). Behind-minor does not
+ * fail this check. Remediation: `deft migrate:xbrief` (rewrites hybrid 0.6 on
+ * already-xbrief trees — #3236). Distinct from `stale-xbrief-schema-deposit`
+ * which routes schema-only drift to `directive update`.
+ */
+export declare function checkXbriefEnvelopeMajorVersion(projectRoot: string, seams?: CheckSeams): CheckResult;
 export declare function checkQuickStartResolves(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function checkSkillPathsResolve(projectRoot: string, agentsMdText: string, seams?: CheckSeams): CheckResult;
 export declare function checkManifestAgreement(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
@@ -60,6 +93,17 @@ export declare function checkGitignoreCoverage(projectRoot: string, seams?: Chec
  * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
  * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
  */
+/**
+ * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
+ * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
+ * until historical corpora are backfilled; scope:complete enforces items hard).
+ */
+export declare function checkCompletedLifecycleConsistency(projectRoot: string): CheckResult;
+/**
+ * Surface non-terminal plan.items under completed/ (#3242). Exit-exempt so
+ * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
+ */
+export declare function checkCompletedOpenItems(projectRoot: string): CheckResult;
 export declare function checkCoverageCheckResumePolicy(projectRoot: string): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {

package/dist/doctor/checks.js

@@ -1,21 +1,363 @@
-import { join } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { CANONICAL_GITIGNORE_BASELINE } from "../init-deposit/gitignore.js";
 import { detectDualLayout, detectLegacyLayout, dualLayoutSignpostLine, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
 import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
+import { scanCompletedLifecycleConsistency } from "../lifecycle/completed-consistency.js";
 import { resolveCheckResume } from "../policy/check-resume.js";
 import { resolveCoverageDebt } from "../policy/coverage-debt.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
+import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
-import { LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, } from "../xbrief-migrate/constants.js";
 import { detectXbriefConvergence } from "../xbrief-migrate/detect.js";
+import { readDeclaredArtifactVersion } from "../xbrief-migrate/transforms.js";
 import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
 import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestReportableVersion, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
 import { readTextSafe } from "./paths.js";
+/** Remediation verb for project envelope behind-major (#2971 / #3243 / #3236). */
+export const XBRIEF_ENVELOPE_MIGRATE_COMMAND = "deft migrate:xbrief";
+/** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
+export const XBRIEF_ENVELOPE_MAJOR_CHECK = "xbrief-envelope-version";
+/** True when an fs error means the path is cleanly absent (not unreadable). */
+function isEnoentError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === "ENOENT");
+}
 function readText(path, seams) {
     return (seams.readText ?? readTextSafe)(path);
 }
+function isDirectoryPath(path, seams) {
+    if (seams.isDir) {
+        return seams.isDir(path);
+    }
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Probe whether `path` is a file, absent, or unstatable (include for fail-closed). */
+function probeFilePresence(path, seams) {
+    if (seams.isFile) {
+        try {
+            return seams.isFile(path) ? "present" : "absent";
+        }
+        catch (err) {
+            return isEnoentError(err) ? "absent" : "unreadable";
+        }
+    }
+    try {
+        return statSync(path).isFile() ? "present" : "absent";
+    }
+    catch (err) {
+        // ENOENT → cleanly missing; EACCES/EPERM/other → treat as live but unreadable
+        // so Doctor cannot skip/pass past a definition it cannot inspect (#3243).
+        return isEnoentError(err) ? "absent" : "unreadable";
+    }
+}
+/**
+ * Probe whether `path` is a directory, absent, or unstatable.
+ * Unreadable pending/active must fail closed via enumFailures, not silent skip.
+ */
+function probeDirectoryPresence(path, seams) {
+    if (seams.isDir) {
+        try {
+            return seams.isDir(path) ? "present" : "absent";
+        }
+        catch (err) {
+            return isEnoentError(err) ? "absent" : "unreadable";
+        }
+    }
+    try {
+        return statSync(path).isDirectory() ? "present" : "absent";
+    }
+    catch (err) {
+        return isEnoentError(err) ? "absent" : "unreadable";
+    }
+}
+/**
+ * Live project envelopes for fail-closed major mismatch (#3243 first ship).
+ * PROJECT-DEFINITION + pending/active in-flight work. Proposed backlog and
+ * completed/cancelled archives are not fail-closed here (historical debt; full
+ * tree rewrite remains on `deft migrate:xbrief` / #3236).
+ */
+const ENVELOPE_MAJOR_SCAN_FOLDERS = ["pending", "active"];
+/**
+ * Collect live-path `*.xbrief.json` envelopes under xbrief/ for major check.
+ * Existing lifecycle dirs that cannot be listed are returned as
+ * `enumFailures` (directory relative paths) so the scan fails closed rather
+ * than treating the tree as empty (#3243 review).
+ */
+function collectLiveXbriefEnvelopePaths(projectRoot, seams) {
+    const migratedRoot = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    const paths = [];
+    const enumFailures = [];
+    const definitionPath = join(migratedRoot, `PROJECT-DEFINITION${MIGRATED_ARTIFACT_SUFFIX}`);
+    // Existence must not require a successful read/stat — unreadable definitions
+    // still enter the scan so the fail-closed unreadable branch can fire
+    // (#3243 review: ENOENT = absent; EACCES/EPERM/other = include).
+    const readdir = seams.readdir ?? readdirSync;
+    const definitionPresence = probeFilePresence(definitionPath, seams);
+    if (definitionPresence === "present" || definitionPresence === "unreadable") {
+        paths.push(definitionPath);
+    }
+    for (const folder of ENVELOPE_MAJOR_SCAN_FOLDERS) {
+        const dir = join(migratedRoot, folder);
+        const dirPresence = probeDirectoryPresence(dir, seams);
+        if (dirPresence === "absent") {
+            // Clean absence (ENOENT / seam false) — greenfield-ok for that folder.
+            continue;
+        }
+        if (dirPresence === "unreadable") {
+            // Stat failed with non-ENOENT before readdir — fail closed (do not pretend empty).
+            enumFailures.push(relative(projectRoot, dir).replace(/\\/g, "/"));
+            continue;
+        }
+        let names;
+        try {
+            names = readdir(dir);
+        }
+        catch {
+            // Dir exists but cannot be listed — fail closed via synthetic scan entry
+            // (directory path; no invented filenames).
+            enumFailures.push(relative(projectRoot, dir).replace(/\\/g, "/"));
+            continue;
+        }
+        for (const name of names) {
+            if (name.endsWith(MIGRATED_ARTIFACT_SUFFIX)) {
+                paths.push(join(dir, name));
+            }
+        }
+    }
+    return { paths, enumFailures };
+}
+/**
+ * Scan live project xbrief envelopes (PROJECT-DEFINITION + pending/active) for
+ * schema distance vs the installed framework envelope major (#3243). Complements
+ * #2971 PROJECT-DEFINITION-only probe; remediation aligns with migrate hybrid
+ * rewrite (#3236).
+ */
+export function scanXbriefEnvelopeVersions(projectRoot, seams = {}, targetVersion = VBRIEF_VERSION) {
+    const { paths, enumFailures } = collectLiveXbriefEnvelopePaths(projectRoot, seams);
+    const entries = [];
+    // Existing pending/active dirs that cannot be enumerated fail closed as
+    // behind-major (null declared) — same class as unreadable files (#3243 review).
+    for (const relativePath of enumFailures) {
+        entries.push({
+            relativePath,
+            declaredVersion: null,
+            distance: "behind-major",
+        });
+    }
+    for (const filePath of paths) {
+        const relativePath = relative(projectRoot, filePath).replace(/\\/g, "/");
+        const text = readText(filePath, seams);
+        // Unreadable / malformed live envelopes fail closed as behind-major (null
+        // declared) so Doctor cannot skip to no-envelopes/pass (#3243 review).
+        if (text === null) {
+            entries.push({
+                relativePath,
+                declaredVersion: null,
+                distance: "behind-major",
+            });
+            continue;
+        }
+        let declared = null;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                declared = readDeclaredArtifactVersion(parsed);
+            }
+            else {
+                declared = null;
+            }
+        }
+        catch {
+            declared = null;
+        }
+        const distance = classifyXbriefSchemaDistance(declared, targetVersion);
+        entries.push({
+            relativePath,
+            declaredVersion: declared,
+            distance,
+        });
+    }
+    const behindMajor = entries.filter((e) => e.distance === "behind-major");
+    let worstDistance = null;
+    if (behindMajor.length > 0) {
+        worstDistance = "behind-major";
+    }
+    else if (entries.some((e) => e.distance === "behind-minor")) {
+        worstDistance = "behind-minor";
+    }
+    else if (entries.length > 0) {
+        worstDistance = "current";
+    }
+    return { targetVersion, entries, worstDistance, behindMajor };
+}
+/**
+ * Fail closed when any scanned project xBRIEF envelope declares a major behind
+ * the framework target (#3243 / epic #3237 Q5 Option 2). Behind-minor does not
+ * fail this check. Remediation: `deft migrate:xbrief` (rewrites hybrid 0.6 on
+ * already-xbrief trees — #3236). Distinct from `stale-xbrief-schema-deposit`
+ * which routes schema-only drift to `directive update`.
+ */
+export function checkXbriefEnvelopeMajorVersion(projectRoot, seams = {}) {
+    const checkName = XBRIEF_ENVELOPE_MAJOR_CHECK;
+    const targetVersion = VBRIEF_VERSION;
+    const migratedRoot = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    const legacyRoot = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    const hasMigrated = isDirectoryPath(migratedRoot, seams);
+    const hasLegacy = isDirectoryPath(legacyRoot, seams);
+    // Pure legacy vbrief/ trees need layout migrate first; skip rather than
+    // false-positive on missing xbrief envelopes.
+    if (hasLegacy && !hasMigrated) {
+        return {
+            name: checkName,
+            status: "skip",
+            detail: "Legacy-only layout (use layout migrate first); envelope major check skipped.",
+            data: { reason: "legacy-only-layout", target_version: targetVersion },
+        };
+    }
+    const scan = scanXbriefEnvelopeVersions(projectRoot, seams, targetVersion);
+    if (scan.entries.length === 0) {
+        return {
+            name: checkName,
+            status: "skip",
+            detail: "No project xBRIEF envelopes scanned (greenfield or empty lifecycle).",
+            data: {
+                reason: "no-envelopes",
+                target_version: targetVersion,
+                scanned: 0,
+            },
+        };
+    }
+    // Fail closed for behind-major live envelopes (#3243 / #3236):
+    // - exact 0.6 → migratable via `deft migrate:xbrief`
+    // - null / 0.5 / unreadable / … → structural rewrite (migrate does not clear)
+    // When both classes are present, report BOTH remediations in one fail so
+    // migrate-only guidance cannot hide the non-migratable repair (#3243 review).
+    const migratableBehindMajor = scan.behindMajor.filter((e) => e.declaredVersion === LEGACY_VBRIEF_VERSION);
+    const nonMigratableBehindMajor = scan.behindMajor.filter((e) => e.declaredVersion !== LEGACY_VBRIEF_VERSION);
+    if (migratableBehindMajor.length > 0 && nonMigratableBehindMajor.length > 0) {
+        const migSample = migratableBehindMajor.slice(0, 3);
+        const nonSample = nonMigratableBehindMajor.slice(0, 3);
+        const nonDeclared = [
+            ...new Set(nonSample.map((e) => e.declaredVersion ?? "missing/unreadable")),
+        ].join(", ");
+        return {
+            name: checkName,
+            status: "fail",
+            detail: `behind-major (mixed) -- framework ${targetVersion}: ` +
+                `${migratableBehindMajor.length} migratable (${LEGACY_VBRIEF_VERSION}: ` +
+                `${migSample.map((e) => e.relativePath).join(", ")}) and ` +
+                `${nonMigratableBehindMajor.length} non-migratable (declared ${nonDeclared}: ` +
+                `${nonSample.map((e) => e.relativePath).join(", ")}). ` +
+                `Next: (1) run \`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` for exact ${LEGACY_VBRIEF_VERSION}; ` +
+                `(2) rewrite non-migratable live envelopes to full xBRIEFInfo@${targetVersion} structure ` +
+                `(not version-only; migrate does not clear them).`,
+            data: {
+                status: "behind-major-mixed",
+                target_version: targetVersion,
+                migratable_count: migratableBehindMajor.length,
+                non_migratable_count: nonMigratableBehindMajor.length,
+                behind_major_count: scan.behindMajor.length,
+                sample_paths: [
+                    ...migSample.map((e) => e.relativePath),
+                    ...nonSample.map((e) => e.relativePath),
+                ],
+                next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+                suggestion: `${XBRIEF_ENVELOPE_MIGRATE_COMMAND} for 0.6; rewrite non-migratable to full ` +
+                    `xBRIEFInfo@${targetVersion} structure (not version-only)`,
+            },
+        };
+    }
+    if (migratableBehindMajor.length > 0) {
+        const sample = migratableBehindMajor.slice(0, 5);
+        const samplePaths = sample.map((e) => e.relativePath).join(", ");
+        const more = migratableBehindMajor.length > sample.length
+            ? ` (+${migratableBehindMajor.length - sample.length} more)`
+            : "";
+        return {
+            name: checkName,
+            status: "fail",
+            detail: `behind-major -- declared ${LEGACY_VBRIEF_VERSION}, framework ${targetVersion} ` +
+                `(${migratableBehindMajor.length} artifact(s): ${samplePaths}${more}). ` +
+                `Next action: run \`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` to bump project JSON envelopes ` +
+                `to xBRIEFInfo@${targetVersion} (layout rename alone is not enough; #3236 rewrites hybrid 0.6 in place).`,
+            data: {
+                status: "behind-major",
+                declared_versions: sample.map((e) => e.declaredVersion),
+                target_version: targetVersion,
+                behind_major_count: migratableBehindMajor.length,
+                sample_paths: sample.map((e) => e.relativePath),
+                next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+                suggestion: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+            },
+        };
+    }
+    if (nonMigratableBehindMajor.length > 0) {
+        // Fail closed without claiming migrate:xbrief alone clears these — that verb
+        // rewrites exact 0.6 only (#3236). Give executable next actions per class
+        // (permissions / re-emit / delete-replace) so Doctor is not permanently blocked
+        // after a non-applicable remediation (#3243 review).
+        const sample = nonMigratableBehindMajor.slice(0, 5);
+        const declaredVersions = [
+            ...new Set(sample.map((e) => e.declaredVersion ?? "missing/unreadable")),
+        ].join(", ");
+        const samplePaths = sample.map((e) => e.relativePath).join(", ");
+        const more = nonMigratableBehindMajor.length > sample.length
+            ? ` (+${nonMigratableBehindMajor.length - sample.length} more)`
+            : "";
+        return {
+            name: checkName,
+            status: "fail",
+            detail: `behind-major (non-migratable) -- declared ${declaredVersions}, framework ${targetVersion} ` +
+                `(${nonMigratableBehindMajor.length} artifact(s): ${samplePaths}${more}). ` +
+                `Next actions: (1) if a path is unreadable, fix FS permissions then re-run doctor; ` +
+                `(2) re-emit full xBRIEFInfo@${targetVersion} via scope tools ` +
+                `(\`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` only when declared is exact ${LEGACY_VBRIEF_VERSION}); ` +
+                `(3) delete or replace invalid lifecycle artifacts after human confirm — ` +
+                `do not only bump the version field.`,
+            data: {
+                status: "behind-major-non-migratable",
+                declared_versions: sample.map((e) => e.declaredVersion),
+                target_version: targetVersion,
+                behind_major_count: nonMigratableBehindMajor.length,
+                sample_paths: sample.map((e) => e.relativePath),
+                next_command: null,
+                suggestion: `fix FS permissions if unreadable; re-emit full xBRIEFInfo@${targetVersion} via scope tools ` +
+                    `(migrate:xbrief only for exact ${LEGACY_VBRIEF_VERSION}); or delete/replace invalid artifacts after human confirm (not version-only)`,
+            },
+        };
+    }
+    // current or behind-minor: this check is major-only (#3243).
+    const declaredSummary = scan.entries
+        .map((e) => e.declaredVersion)
+        .filter((v) => typeof v === "string")
+        .slice(0, 3)
+        .join(", ") || targetVersion;
+    return {
+        name: checkName,
+        status: "pass",
+        detail: `current -- scanned ${scan.entries.length} envelope(s) at framework major ` +
+            `(declared sample ${declaredSummary}; framework ${targetVersion})` +
+            (scan.worstDistance === "behind-minor" ? "; behind-minor is non-failing for this check" : ""),
+        data: {
+            status: scan.worstDistance ?? "current",
+            target_version: targetVersion,
+            scanned: scan.entries.length,
+            worst_distance: scan.worstDistance,
+        },
+    };
+}
 export function checkQuickStartResolves(projectRoot, installRoot, seams = {}) {
     if (installRoot === null) {
         return {
@@ -734,6 +1076,82 @@ export function checkGitignoreCoverage(projectRoot, seams = {}) {
  * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
  * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
  */
+/**
+ * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
+ * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
+ * until historical corpora are backfilled; scope:complete enforces items hard).
+ */
+export function checkCompletedLifecycleConsistency(projectRoot) {
+    const checkName = "completed-lifecycle-consistency";
+    const result = scanCompletedLifecycleConsistency(projectRoot);
+    // Hard fail: folder/status drift and unreadable completed artifacts (not open items).
+    const hardFindings = result.findings.filter((f) => f.kind === "status_mismatch" || f.kind === "unreadable");
+    if (hardFindings.length === 0) {
+        return {
+            name: checkName,
+            status: "pass",
+            detail: "Completed folder/status consistency OK (#3242): no plan.status drift under completed/",
+            data: {
+                finding_count: 0,
+                open_items_deferred_to: "completed-open-items",
+            },
+        };
+    }
+    const message = `Completed lifecycle folder/status consistency failed (#3242). ` +
+        `${hardFindings.length} finding(s):\n` +
+        hardFindings.map((f) => `  - ${f.detail}`).join("\n") +
+        `\nRule: completed/ requires plan.status in [completed|failed]; artifacts must be readable.`;
+    return {
+        name: checkName,
+        status: "fail",
+        detail: message,
+        data: {
+            finding_count: hardFindings.length,
+            findings: hardFindings.map((f) => ({
+                rel_path: f.relPath,
+                plan_status: f.planStatus,
+                kind: f.kind,
+                detail: f.detail,
+            })),
+        },
+    };
+}
+/**
+ * Surface non-terminal plan.items under completed/ (#3242). Exit-exempt so
+ * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
+ */
+export function checkCompletedOpenItems(projectRoot) {
+    const checkName = "completed-open-items";
+    const result = scanCompletedLifecycleConsistency(projectRoot);
+    const openFindings = result.findings.filter((f) => f.kind === "open_items");
+    if (openFindings.length === 0) {
+        return {
+            name: checkName,
+            status: "pass",
+            detail: "Completed open-items consistency OK (#3242): no non-terminal plan.items under completed/",
+            data: { finding_count: 0 },
+        };
+    }
+    const message = `Completed lifecycle open plan.items (#3242, advisory). ` +
+        `${openFindings.length} artifact(s) under completed/ still list non-terminal items:\n` +
+        openFindings.map((f) => `  - ${f.detail}`).join("\n") +
+        `\nscope:complete fails closed on this class; historical corpus is advisory until backfill.`;
+    return {
+        name: checkName,
+        status: "fail",
+        detail: message,
+        data: {
+            finding_count: openFindings.length,
+            advisory: true,
+            findings: openFindings.map((f) => ({
+                rel_path: f.relPath,
+                plan_status: f.planStatus,
+                kind: f.kind,
+                detail: f.detail,
+            })),
+        },
+    };
+}
 export function checkCoverageCheckResumePolicy(projectRoot) {
     const debt = resolveCoverageDebt(projectRoot);
     const resume = resolveCheckResume(projectRoot);
@@ -813,6 +1231,8 @@ export function deriveExitCode(checks, errors) {
         "stale-xbrief-schema-deposit",
         "typescript-7-side-by-side",
         "coverage-check-resume-policy",
+        // Historical pre-#2862 completed/ corpora; hard fail is scope:complete (#3242).
+        "completed-open-items",
     ]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
@@ -853,9 +1273,12 @@ export function runChecksImpl(projectRoot, seams = {}) {
         checks.push(checkLegacyLayout(projectRoot, seams));
         checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
         checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
+        checks.push(checkXbriefEnvelopeMajorVersion(projectRoot, seams));
         checks.push(checkGitignoreCoverage(projectRoot, seams));
         checks.push(checkTypescript7SideBySide(projectRoot, seams));
         checks.push(checkCoverageCheckResumePolicy(projectRoot));
+        checks.push(checkCompletedLifecycleConsistency(projectRoot));
+        checks.push(checkCompletedOpenItems(projectRoot));
         return {
             projectRoot,
             installRoot: null,
@@ -872,9 +1295,12 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkLegacyLayout(projectRoot, seams));
     checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
     checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
+    checks.push(checkXbriefEnvelopeMajorVersion(projectRoot, seams));
     checks.push(checkGitignoreCoverage(projectRoot, seams));
     checks.push(checkTypescript7SideBySide(projectRoot, seams));
     checks.push(checkCoverageCheckResumePolicy(projectRoot));
+    checks.push(checkCompletedLifecycleConsistency(projectRoot));
+    checks.push(checkCompletedOpenItems(projectRoot));
     return {
         projectRoot,
         installRoot,

package/dist/doctor/main.d.ts

@@ -5,13 +5,12 @@ export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams):
 export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): boolean;
 export declare function runAgentHooksLiveProbeCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
 /**
- * Fail closed when PROJECT-DEFINITION under an xbrief/ layout still declares
- * envelope 0.6 while the framework schema is 0.8 (#2971). Greenfield (no
- * project definition yet) and current 0.8 envelopes pass. Unreadable paths
- * (test seams / permission) skip rather than false-positive fail. Behind-major
- * records `deft migrate:xbrief` as the next action — layout rename alone is not
- * enough. Distinct from deposited-schema (`stale-xbrief-schema-deposit`) which
- * must NOT route to migrate:xbrief when only framework schema files are stale.
+ * Fail closed when any scanned project xbrief lifecycle `*.xbrief.json` envelope
+ * declares a schema major behind the framework target (#2971 / #3243). Greenfield
+ * (no envelopes) skips. Behind-major records `deft migrate:xbrief` as the next
+ * action (hybrid in-place rewrite on already-xbrief trees — #3236). Distinct from
+ * deposited-schema (`stale-xbrief-schema-deposit`) which must NOT route to
+ * migrate:xbrief when only framework schema files are stale.
  */
 export declare function runXbriefEnvelopeVersionCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (f: Finding) => void, seams: DoctorSeams): void;
 /**