@deftai/directive-core 0.97.0 → 0.98.0

package/dist/doctor/checks.js

@@ -3,6 +3,9 @@ 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 { resolveCheckResume } from "../policy/check-resume.js";
+import { resolveCoverageDebt } from "../policy/coverage-debt.js";
+import { policyColonInvocation } from "../policy/policy-invocation.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";
@@ -725,6 +728,83 @@ export function checkGitignoreCoverage(projectRoot, seams = {}) {
         },
     };
 }
+/**
+ * Surface undecided / invalid coverageDebt + checkResume policy (#3189).
+ * Advisory skip when undecided; never hard-fails doctor / check:consumer.
+ * 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.
+ */
+export function checkCoverageCheckResumePolicy(projectRoot) {
+    const debt = resolveCoverageDebt(projectRoot);
+    const resume = resolveCheckResume(projectRoot);
+    if (debt.source === "default-on-error" || resume.source === "default-on-error") {
+        return {
+            name: "coverage-check-resume-policy",
+            status: "skip",
+            detail: "advisory: coverageDebt and/or checkResume block is invalid; " +
+                "resolution is fail-closed (mode off, localStamp off, CI never trusts stamps). " +
+                `coverageDebt.error=${JSON.stringify(debt.error)}; ` +
+                `checkResume.error=${JSON.stringify(resume.error)}. ` +
+                "Fix the typed block or re-apply Strict / Hatch-aware / dismiss-with-reason.",
+            data: {
+                coverageDebt: { status: debt.status, source: debt.source, error: debt.error },
+                checkResume: { status: resume.status, source: resume.source, error: resume.error },
+                advisory: true,
+                invalid: true,
+            },
+        };
+    }
+    const undecided = debt.status === "unset" || resume.status === "unset";
+    if (!undecided) {
+        const dismissParts = [];
+        if (debt.dismissReason) {
+            dismissParts.push(`coverageDebt.dismissReason=${JSON.stringify(debt.dismissReason)}`);
+        }
+        if (resume.dismissReason) {
+            dismissParts.push(`checkResume.dismissReason=${JSON.stringify(resume.dismissReason)}`);
+        }
+        const dismissNote = dismissParts.length > 0 ? ` Dismissed: ${dismissParts.join("; ")}.` : "";
+        return {
+            name: "coverage-check-resume-policy",
+            status: "pass",
+            detail: `coverageDebt status=${debt.status} mode=${debt.mode}; ` +
+                `checkResume status=${resume.status} localStamp=${resume.localStamp}; ` +
+                `ciTrustsLocalStamp=false (fixed v1).${dismissNote}`,
+            data: {
+                coverageDebt: {
+                    status: debt.status,
+                    mode: debt.mode,
+                    autoFile: debt.autoFile,
+                    dismissReason: debt.dismissReason,
+                },
+                checkResume: {
+                    status: resume.status,
+                    localStamp: resume.localStamp,
+                    ciTrustsLocalStamp: false,
+                    dismissReason: resume.dismissReason,
+                },
+            },
+        };
+    }
+    // Advisory only (status=skip): never hard-fails doctor / check:consumer (#3189).
+    // Behavior remains fail-closed while unset; session-start nudge carries the ask.
+    return {
+        name: "coverage-check-resume-policy",
+        status: "skip",
+        detail: "advisory: coverageDebt and/or checkResume policy is undecided (status=unset). " +
+            "Behavior stays fail-closed (no hatch soft-pass, no local suite stamp, CI never trusts stamps). " +
+            "Choose Strict / Hatch-aware on the next interactive session-start nudge, or record " +
+            "dismiss-with-reason. Inspect: " +
+            `\`${policyColonInvocation("show", " --field=coverageDebt")}\` / ` +
+            `\`${policyColonInvocation("show", " --field=checkResume")}\`.`,
+        data: {
+            coverageDebt: { status: debt.status, mode: debt.mode },
+            checkResume: { status: resume.status, localStamp: resume.localStamp },
+            suggested_fix: policyColonInvocation("show", " --field=coverageDebt"),
+            advisory: true,
+        },
+    };
+}
 export function deriveExitCode(checks, errors) {
     const exitExempt = new Set([
         "canonical-vendored-npm-signpost",
@@ -732,6 +812,7 @@ export function deriveExitCode(checks, errors) {
         "gitignore-coverage",
         "stale-xbrief-schema-deposit",
         "typescript-7-side-by-side",
+        "coverage-check-resume-policy",
     ]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
@@ -774,6 +855,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
         checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
         checks.push(checkGitignoreCoverage(projectRoot, seams));
         checks.push(checkTypescript7SideBySide(projectRoot, seams));
+        checks.push(checkCoverageCheckResumePolicy(projectRoot));
         return {
             projectRoot,
             installRoot: null,
@@ -792,6 +874,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
     checks.push(checkGitignoreCoverage(projectRoot, seams));
     checks.push(checkTypescript7SideBySide(projectRoot, seams));
+    checks.push(checkCoverageCheckResumePolicy(projectRoot));
     return {
         projectRoot,
         installRoot,

package/dist/hooks/dispatcher.d.ts

@@ -119,6 +119,11 @@ export declare const ASSIST_SCRATCH_ROOT_PREFIXES: readonly [".deft-scratch/", "
  * True when the write target is under an allowlisted disposable scratch root (#1802).
  * Fail closed on null/empty/unparseable targets and on path escape (`..`).
  * Does not authorize tracked product paths even under assist posture.
+ *
+ * #3186: after lexical allowlist match, realpath the scratch root and require
+ * {@link assertProjectionContained}; refuse symlink scratch roots and any
+ * realpath outside the project (host Write would follow the link).
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
  */
 export declare function isAllowlistedAssistScratchPath(projectRoot: string, targetPath: string | null): boolean;
 /**

package/dist/hooks/dispatcher.js

@@ -1,6 +1,7 @@
-import { realpathSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { appendAuthzAudit, classifyHookAuthzOps, evaluateAuthzMutation, evidenceSatisfiesImplementationApproval, listActiveHumanGrants, loadAuthzStateResult, markGrantUsed, shouldConsumeSingleUseGrant, utcIso, } from "../authz/index.js";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { evaluateIntentCeilingFromEnv } from "../policy/intent-ceiling.js";
@@ -110,6 +111,11 @@ export const ASSIST_SCRATCH_ROOT_PREFIXES = [".deft-scratch/", "temp/"];
  * True when the write target is under an allowlisted disposable scratch root (#1802).
  * Fail closed on null/empty/unparseable targets and on path escape (`..`).
  * Does not authorize tracked product paths even under assist posture.
+ *
+ * #3186: after lexical allowlist match, realpath the scratch root and require
+ * {@link assertProjectionContained}; refuse symlink scratch roots and any
+ * realpath outside the project (host Write would follow the link).
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
  */
 export function isAllowlistedAssistScratchPath(projectRoot, targetPath) {
     if (targetPath === null || targetPath.trim().length === 0)
@@ -120,11 +126,55 @@ export function isAllowlistedAssistScratchPath(projectRoot, targetPath) {
         return false;
     if (isLexicalOutsideProjectRoot(posix))
         return false;
+    let matchedPrefix = null;
     for (const prefix of ASSIST_SCRATCH_ROOT_PREFIXES) {
-        if (posix === prefix.slice(0, -1) || posix.startsWith(prefix))
-            return true;
+        if (posix === prefix.slice(0, -1) || posix.startsWith(prefix)) {
+            matchedPrefix = prefix;
+            break;
+        }
     }
-    return false;
+    if (matchedPrefix === null)
+        return false;
+    // #3186 containment: realpath scratch root + projection fence (symlink escape).
+    const projectAbs = resolve(projectRoot);
+    try {
+        realpathSync(projectAbs);
+    }
+    catch {
+        // Unit fixtures / missing project dir — lexical allowlist only.
+        return true;
+    }
+    const scratchRootName = matchedPrefix.slice(0, -1); // ".deft-scratch" | "temp"
+    const scratchRootAbs = resolve(projectAbs, scratchRootName);
+    try {
+        // Refuse when the scratch root (or any parent on the path) escapes via symlink.
+        assertProjectionContained(projectAbs, scratchRootAbs);
+    }
+    catch (err) {
+        if (err instanceof ProjectionContainmentError)
+            return false;
+        return false;
+    }
+    // Refuse symlink scratch roots entirely (#3186) — even in-tree links can divert Write.
+    try {
+        const st = lstatSync(scratchRootAbs);
+        if (st.isSymbolicLink())
+            return false;
+    }
+    catch {
+        // Scratch root does not exist yet — mkdir will create a real directory; allow.
+    }
+    // Also fence the concrete write target when it already exists on disk.
+    const targetAbs = resolve(projectAbs, targetPath.replace(/\\/g, "/"));
+    try {
+        assertProjectionContained(projectAbs, targetAbs);
+    }
+    catch (err) {
+        if (err instanceof ProjectionContainmentError)
+            return false;
+        return false;
+    }
+    return true;
 }
 /**
  * Assist/ephemeral classification for scratch-write carve-out (#1802).

package/dist/init-deposit/hygiene.d.ts

@@ -8,7 +8,7 @@
  * and scope briefs are never installer-managed; if they reappear in
  * `installerManagedMatchers()`, unit tests and deposit-time assert fail closed.
  *
- * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117, #3193.
  */
 import { type InitDepositIo } from "./constants.js";
 export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
@@ -51,13 +51,82 @@ export interface MixedCoreAndAppClassification {
     readonly app: string[];
     /** True when both core and app are non-empty — the deposited guard fails. */
     readonly wouldFail: boolean;
+    /**
+     * Pin/lock paths that were path-allowlisted but failed content-aware checks
+     * when co-travelling with core (#3193). Empty when path-only classification.
+     */
+    readonly pinContentRejected?: string[];
+}
+/** Paths that path-allowlist for upgrade co-travel but need content checks with core (#3193). */
+export declare const UPGRADE_PIN_CONTENT_PATHS: readonly ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
+export type UpgradePinContentPath = (typeof UPGRADE_PIN_CONTENT_PATHS)[number];
+/** package.json dependency map fields that may hold @deftai/directive* pins. */
+export declare const PACKAGE_JSON_DEP_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+/**
+ * True when `name` is an `@deftai/directive*` dependency **key** (#3193).
+ * Substring hits in scripts/settings values do not qualify.
+ */
+export declare function isDirectiveDependencyKey(name: string): boolean;
+/**
+ * package.json co-travel is allowed only when the sole differences are
+ * `@deftai/directive*` dependency-key pins under the standard dep maps (#3193).
+ * Scripts/settings/metadata that merely contain the substring still fail.
+ */
+export declare function isPackageJsonDirectivePinOnlyDiff(baseRaw: string, headRaw: string): boolean;
+/**
+ * package-lock.json follow-through: non-@deftai/directive* root direct dependency
+ * identities (and their `node_modules/<name>` package entries when present) must
+ * be unchanged. Directive pin identity + transitive/resolution churn may change.
+ */
+export declare function isPackageLockDirectivePinFollowThrough(baseRaw: string, headRaw: string): boolean;
+/**
+ * Minimal pnpm-lock.yaml (v6/v9) root importer (`.`) direct-dep extractor.
+ * Avoids a YAML dependency; sufficient for pin follow-through identity checks.
+ */
+export declare function pnpmLockRootDirectDeps(raw: string): Record<string, string>;
+/**
+ * Extract pnpm `packages:` section records keyed by the package name (not
+ * name@version). Used to freeze product package resolution blocks.
+ */
+export declare function pnpmPackagesByName(raw: string): Map<string, string>;
+export declare function isPnpmLockDirectivePinFollowThrough(baseRaw: string, headRaw: string): boolean;
+/**
+ * yarn.lock (v1) package identity blocks: every non-@deftai/directive* package
+ * must keep identical block text (or fail if added/removed). Directive package
+ * blocks may change freely as pin follow-through (#3193).
+ */
+export declare function isYarnLockDirectivePinFollowThrough(baseRaw: string, headRaw: string): boolean;
+/**
+ * Content-aware check for a single upgrade pin path (#3193).
+ * Returns true when the path may co-travel with `.deft/core/**`.
+ */
+export declare function isUpgradePinPathContentAllowed(path: string, baseRaw: string, headRaw: string): boolean;
+export interface PinContentFilePair {
+    readonly base: string;
+    readonly head: string;
 }
 /**
  * TS twin of Go `classifyChangedPaths` / deposited shell guard (#1430).
  * Core = `.deft/core/**`; installer-managed = allowlist; app = everything else.
  * Guard fails iff both core and app are non-empty.
+ *
+ * Path-only: does not inspect package/lock contents. Prefer
+ * {@link classifyMixedCoreAndAppContentAware} when base/head blobs are available
+ * (deposited guard + unit tests for #3193).
  */
 export declare function classifyMixedCoreAndApp(changedPaths: readonly string[], matchers?: readonly InstallerManagedMatcher[]): MixedCoreAndAppClassification;
+/**
+ * Content-aware upgrade co-travel classifier (#3193).
+ *
+ * Starts from path classification (#3127 allowlist), then when `.deft/core/**`
+ * is present reclassifies package.json / lockfile paths as **app** unless their
+ * base→head content is the Directive pin unit (or lock follow-through).
+ * `.deft/GENERATION.json` remains path-allowlisted with no content constraint.
+ *
+ * Missing content for a pin path co-travelling with core fails closed (treated
+ * as app) so partial fixtures cannot silently re-open the path-only hole.
+ */
+export declare function classifyMixedCoreAndAppContentAware(changedPaths: readonly string[], fileContents: Readonly<Partial<Record<string, PinContentFilePair>>>, matchers?: readonly InstallerManagedMatcher[]): MixedCoreAndAppClassification;
 export interface FrameworkStagePathsOptions {
     /**
      * Include the vendored `.deft/core` payload in the stage set. Defaults to