@deftai/directive-core 0.104.0 → 0.106.0

package/dist/init-deposit/gitignore.js

@@ -29,7 +29,16 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/.cli/",
     ".deft/ritual-state.json",
     ".deft/last-session.json",
+    ".deft/occupancy.json",
     ".deft/routing.local.json",
+    // Agent-host working state (#3502). Selective, NEVER blanket `.claude/`:
+    // `.claude/settings.json`, `.claude/skills/` and `.claude/commands/` are
+    // MANAGED DEPOSITS (agent-hooks.ts / skill-discovery-hosts.ts) and must stay
+    // trackable -- same #1144 hybrid rule that forbids blanket `.eval/`.
+    // Un-ignored agent worktrees leave a permanently dirty tree, which refuses
+    // release Step 1 for every consumer that dispatches subagents.
+    ".claude/worktrees/",
+    ".claude/settings.local.json",
     // #3282: opt-in default run-summary JSONL at repo root (collectible; must not dirty trees).
     ".deft-run-summary.json",
     // Temporary test/local kill-switch — must stay untracked (#3039).

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

@@ -8,8 +8,10 @@
  * 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, #3193.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117, #3193, #3393.
  */
+import { type MutationSummary } from "../fs/mutation-ledger.js";
+import { type BranchSyncDetection } from "../policy/branch-sync.js";
 import { type InitDepositIo } from "./constants.js";
 export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 export declare const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
@@ -121,6 +123,13 @@ export interface PinContentFilePair {
  * (deposited guard + unit tests for #3193).
  */
 export declare function classifyMixedCoreAndApp(changedPaths: readonly string[], matchers?: readonly InstallerManagedMatcher[]): MixedCoreAndAppClassification;
+/**
+ * Path classifier plus the shared #3388 sync predicate. Feature mixes still
+ * fail; a matching sync PR passes with a loud exemption message.
+ */
+export declare function classifyMixedCoreAndAppForPr(changedPaths: readonly string[], sync: BranchSyncDetection, matchers?: readonly InstallerManagedMatcher[]): MixedCoreAndAppClassification & {
+    loudMessage: string | null;
+};
 /**
  * Content-aware upgrade co-travel classifier (#3193).
  *
@@ -135,21 +144,37 @@ export declare function classifyMixedCoreAndApp(changedPaths: readonly string[],
 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
-     * `true` for init and real payload swaps. No-op updates set this to `false`
-     * so CRLF-only core noise cannot be staged while safe projections are repaired.
+     * Include the vendored `.deft/core` payload in the exist-walk stage set.
+     * Defaults to `true`. Ignored when a mutation ledger is bound (#3394) —
+     * core paths stage only if they appear on this-run ledger.
      */
     readonly includeCore?: boolean;
     /**
-     * Include the project-root ``Taskfile.yml`` in the stage set. Defaults to
-     * ``false``: unlike the other allowlisted paths, ``Taskfile.yml`` is a
-     * consumer-owned file that merely *contains* an installer-managed include
-     * block, so it must only be staged when the installer actually wired that
-     * block this run -- otherwise an unrelated user edit would be silently
-     * ``git add``ed (#1576 review).
+     * Unused (#3394). Ledger intersection stages Taskfile.yml only when this run
+     * mutated it. Kept so existing callers compile. Exist-walk (no ledger) stages
+     * Taskfile.yml when the file exists — do not reintroduce the include skip.
      */
     readonly includeTaskfile?: boolean;
 }
+/** True for the vendored payload tree (not the installer-managed allowlist). */
+export declare function isCoreStagePath(path: string): boolean;
+export interface LedgerStageSplit {
+    readonly stagePaths: string[];
+    readonly unstagedRemainder: string[];
+    readonly skippedUntrackedDeletes: string[];
+}
+/**
+ * True when `git ls-files` named the path or a descendant (directory prune).
+ * Exact-only membership misses a ledgered directory whose tracked children
+ * are the ls-files hits (#3394 Greptile).
+ */
+export declare function isTrackedDeletePath(path: string, trackedDeletes: ReadonlySet<string>): boolean;
+/**
+ * Split this-run ledger paths into stageable (allowlist or core) vs remainder.
+ * Deleted paths not present in `trackedDeletes` (or under a tracked prefix)
+ * are skipped so one untracked delete cannot fail a batch `git add` (#3394).
+ */
+export declare function splitLedgerForStaging(summary: MutationSummary, trackedDeletes?: ReadonlySet<string>): LedgerStageSplit;
 export declare function frameworkStagePaths(projectDir: string, deftDir: string, options?: FrameworkStagePathsOptions): string[];
 export interface StageFrameworkPathsSeams {
     gitPorcelain?: (projectRoot: string) => string | null;
@@ -198,6 +223,9 @@ export interface PrunePackageAbsentDepositPathsResult {
  * Individual removal failures are reported but do not throw — callers that must
  * refuse a VERSION stamp until the deposit matches the content package should
  * use {@link reconcileDepositToContentPackage} (#2913).
+ *
+ * Dest-only file removers go through {@link containedRemove} so a bound
+ * mutation ledger records them (#3392).
  */
 export declare function prunePackageAbsentDepositPaths(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PrunePackageAbsentDepositPathsResult>;
 /**
@@ -223,13 +251,21 @@ export interface PruneStrayDepositPathsResult {
  */
 export declare function pruneStrayDepositPaths(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PruneStrayDepositPathsResult>;
 export declare const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
-export declare function printCommitGuidance(io: InitDepositIo, paths: readonly string[], staged: boolean): void;
+export declare function printUnstagedLedgerRemainder(io: InitDepositIo, remainder: readonly string[]): void;
+export declare function printCommitGuidance(io: InitDepositIo, paths: readonly string[], staged: boolean, unstagedRemainder?: readonly string[]): void;
 export interface DepositStagePathsOptions extends StageFrameworkPathsSeams, FrameworkStagePathsOptions {
     readCachedNames?: (projectDir: string) => string[];
+    /** `git ls-files` seam for filtering untracked ledger deletions (#3394). */
+    readTrackedNames?: (projectDir: string, paths: readonly string[]) => string[];
+    /** Explicit this-run ledger. Defaults to the bound snapshot. */
+    mutations?: MutationSummary;
+    printf?: (text: string) => void;
 }
 export declare function depositStagePaths(projectDir: string, options?: DepositStagePathsOptions): {
     stagePaths: string[];
     staged: boolean;
     stagedPaths: string[];
+    unstagedRemainder: string[];
+    skippedUntrackedDeletes: string[];
 };
 //# sourceMappingURL=hygiene.d.ts.map

package/dist/init-deposit/hygiene.js

@@ -8,12 +8,15 @@
  * 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, #3193.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117, #3193, #3393.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { readdir, rm, stat } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
+import { containedDestExec, containedRemove } from "../fs/contained-write.js";
+import { activeMutationLedger, isPortRecordMode, snapshotMutationSummary, } from "../fs/mutation-ledger.js";
+import { applyCoreGuardWithBranchSync } from "../policy/branch-sync.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { CONSUMER_SKILL_DISCOVERY_INVENTORY } from "./skill-discovery-deposit.js";
@@ -68,6 +71,12 @@ export function installerManagedMatchers() {
         { exact: ".claude/settings.json" },
         { exact: ".grok/hooks/deft.json" },
         { exact: ".cursor/hooks.json" },
+        // Official Cursor adapter only (#3393). Exact paths — not a `.cursor/hooks/`
+        // prefix — so consumer-authored hooks stay app. Consumers using
+        // `pull_request_target` or pinned workflow refs evaluate the deposited
+        // guard from the previous allowlist for one PR; document, do not work around.
+        { exact: ".cursor/hooks/deft-cursor-hook-adapter.mjs" },
+        { exact: ".cursor/hooks/deft-cursor-hook-adapter.test.mjs" },
         { exact: ".codex/hooks.json" },
         // Multi-host slash product files only (#3054 / L8 prefer commit).
         // Exact paths — not directory prefixes — so consumer custom commands under
@@ -753,6 +762,15 @@ export function classifyMixedCoreAndApp(changedPaths, matchers = installerManage
         wouldFail: core.length > 0 && app.length > 0,
     };
 }
+/**
+ * Path classifier plus the shared #3388 sync predicate. Feature mixes still
+ * fail; a matching sync PR passes with a loud exemption message.
+ */
+export function classifyMixedCoreAndAppForPr(changedPaths, sync, matchers = installerManagedMatchers()) {
+    const base = classifyMixedCoreAndApp(changedPaths, matchers);
+    const applied = applyCoreGuardWithBranchSync(base, sync);
+    return { ...base, wouldFail: applied.wouldFail, loudMessage: applied.loudMessage };
+}
 /**
  * Content-aware upgrade co-travel classifier (#3193).
  *
@@ -794,6 +812,65 @@ export function classifyMixedCoreAndAppContentAware(changedPaths, fileContents,
         pinContentRejected,
     };
 }
+/** True for the vendored payload tree (not the installer-managed allowlist). */
+export function isCoreStagePath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    return normalized === ".deft/core" || normalized.startsWith(".deft/core/");
+}
+/**
+ * True when `git ls-files` named the path or a descendant (directory prune).
+ * Exact-only membership misses a ledgered directory whose tracked children
+ * are the ls-files hits (#3394 Greptile).
+ */
+export function isTrackedDeletePath(path, trackedDeletes) {
+    const normalized = path.replace(/\\/g, "/");
+    if (trackedDeletes.has(normalized))
+        return true;
+    const prefix = normalized.endsWith("/") ? normalized : `${normalized}/`;
+    for (const tracked of trackedDeletes) {
+        if (tracked === normalized || tracked.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Split this-run ledger paths into stageable (allowlist or core) vs remainder.
+ * Deleted paths not present in `trackedDeletes` (or under a tracked prefix)
+ * are skipped so one untracked delete cannot fail a batch `git add` (#3394).
+ */
+export function splitLedgerForStaging(summary, trackedDeletes = new Set()) {
+    const seen = new Set();
+    const stagePaths = [];
+    const unstagedRemainder = [];
+    const skippedUntrackedDeletes = [];
+    const deleted = new Set(summary.deleted.map((path) => path.replace(/\\/g, "/")));
+    const visit = (raw) => {
+        const path = raw.replace(/\\/g, "/");
+        if (!path || seen.has(path))
+            return;
+        seen.add(path);
+        if (!isInstallerManagedPath(path) && !isCoreStagePath(path)) {
+            unstagedRemainder.push(path);
+            return;
+        }
+        if (deleted.has(path) && !isTrackedDeletePath(path, trackedDeletes)) {
+            skippedUntrackedDeletes.push(path);
+            return;
+        }
+        stagePaths.push(path);
+    };
+    for (const path of summary.wrote)
+        visit(path);
+    for (const path of summary.stripped)
+        visit(path);
+    for (const path of summary.deleted)
+        visit(path);
+    for (const path of summary.chmod)
+        visit(path);
+    for (const path of summary.exec)
+        visit(path);
+    return { stagePaths, unstagedRemainder, skippedUntrackedDeletes };
+}
 export function frameworkStagePaths(projectDir, deftDir, options = {}) {
     const paths = [];
     const seen = new Set();
@@ -814,8 +891,6 @@ export function frameworkStagePaths(projectDir, deftDir, options = {}) {
         add(relDeft);
     }
     for (const matcher of installerManagedMatchers()) {
-        if (matcher.exact === "Taskfile.yml" && !options.includeTaskfile)
-            continue;
         if (matcher.exact) {
             add(matcher.exact);
         }
@@ -834,11 +909,15 @@ export function stageFrameworkPaths(projectDir, paths, seams = {}) {
         return { staged: false, error: null };
     const runGitAdd = seams.runGitAdd ??
         ((root, stagePaths) => {
-            execFileSync("git", ["add", ...stagePaths], {
-                cwd: root,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
+            const result = containedDestExec({
+                root,
+                destTarget: join(".git", "index"),
+                file: "git",
+                args: ["add", "--", ...stagePaths],
             });
+            if (!result.ok) {
+                throw new Error("git add failed");
+            }
         });
     try {
         runGitAdd(projectDir, paths);
@@ -961,7 +1040,7 @@ async function pruneEmptyParentsForFile(deftDir, contentDirs, relFile) {
         try {
             if (!existsSync(abs) || readdirSync(abs).length !== 0)
                 break;
-            rmSync(abs, { recursive: false, force: true });
+            containedRemove({ root: deftDir, target: abs, mutation: false });
             prunedDirs.push(normalized);
         }
         catch {
@@ -979,6 +1058,9 @@ async function pruneEmptyParentsForFile(deftDir, contentDirs, relFile) {
  * Individual removal failures are reported but do not throw — callers that must
  * refuse a VERSION stamp until the deposit matches the content package should
  * use {@link reconcileDepositToContentPackage} (#2913).
+ *
+ * Dest-only file removers go through {@link containedRemove} so a bound
+ * mutation ledger records them (#3392).
  */
 export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     const absent = await findPackageAbsentDepositPaths(deftDir, contentRoot);
@@ -987,7 +1069,7 @@ export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     const prunedDirs = [];
     for (const rel of absent) {
         try {
-            rmSync(join(deftDir, rel), { force: true });
+            containedRemove({ root: deftDir, target: join(deftDir, rel) });
             pruned.push(rel);
             prunedDirs.push(...(await pruneEmptyParentsForFile(deftDir, contentDirs, rel)));
         }
@@ -1015,6 +1097,10 @@ export async function reconcileDepositToContentPackage(deftDir, contentRoot, io)
     const result = await prunePackageAbsentDepositPaths(deftDir, contentRoot, io);
     const remaining = await findPackageAbsentDepositPaths(deftDir, contentRoot);
     if (remaining.length > 0) {
+        if (isPortRecordMode()) {
+            // Dest IO was skipped; dest-only paths stay on disk and are already ledgered.
+            return result;
+        }
         const sample = remaining.slice(0, 5).join(", ");
         const more = remaining.length > 5 ? ` (+${remaining.length - 5} more)` : "";
         throw new Error(`deposit reconcile failed: ${remaining.length} package-absent path(s) remain under .deft/core ` +
@@ -1063,31 +1149,42 @@ export async function pruneStrayDepositPaths(deftDir, contentRoot, io) {
     return { pruned };
 }
 export const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
-export function printCommitGuidance(io, paths, staged) {
-    if (paths.length === 0)
+export function printUnstagedLedgerRemainder(io, remainder) {
+    if (remainder.length === 0)
         return;
-    const addCmd = `git add ${paths.join(" ")}`;
-    io.printf("\nCommit hygiene (#1453, #1671, #3127, #3193): keep the framework upgrade in its OWN branch/PR.\n");
-    io.printf("Do NOT use `git add -A` -- mixing the payload with product/app files trips the\n");
-    io.printf("deft-core-guard CI check.\n");
-    io.printf("One upgrade PR MAY co-travel: .deft/core/** + installer-managed deposits + package.json\n");
-    io.printf("pin/lock (Directive pin-only + lock follow-through, #3193) + .deft/GENERATION.json.\n");
-    io.printf("True app/product paths still require a separate PR.\n");
-    if (staged) {
-        io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
-        io.printf(`  ${addCmd}\n`);
+    io.printf("Left unstaged (not installer-managed this run; do not git add -A):\n");
+    for (const path of remainder) {
+        io.printf(`  ${path}\n`);
     }
-    else {
-        io.printf("Stage ONLY these framework + installer-managed paths:\n");
-        io.printf(`  ${addCmd}\n`);
+}
+export function printCommitGuidance(io, paths, staged, unstagedRemainder = []) {
+    if (paths.length === 0 && unstagedRemainder.length === 0)
+        return;
+    if (paths.length > 0) {
+        const addCmd = `git add -- ${paths.join(" ")}`;
+        io.printf("\nCommit hygiene (#1453, #1671, #3127, #3193, #3394): keep the framework upgrade in its OWN branch/PR.\n");
+        io.printf("Do NOT use `git add -A` -- mixing the payload with product/app files trips the\n");
+        io.printf("deft-core-guard CI check.\n");
+        io.printf("One upgrade PR MAY co-travel: .deft/core/** + installer-managed deposits + package.json\n");
+        io.printf("pin/lock (Directive pin-only + lock follow-through, #3193) + .deft/GENERATION.json.\n");
+        io.printf("True app/product paths still require a separate PR.\n");
+        if (staged) {
+            io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
+            io.printf(`  ${addCmd}\n`);
+        }
+        else {
+            io.printf("Stage ONLY these framework + installer-managed paths:\n");
+            io.printf(`  ${addCmd}\n`);
+        }
+        io.printf("Then take the framework deposit through the full PR lifecycle so deft-core-guard\n");
+        io.printf("evaluates a clean, standalone upgrade PR:\n");
+        io.printf(`  1. Branch: git switch -c ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+        io.printf('  2. Commit: git commit -m "chore(deft): update framework payload"\n');
+        io.printf(`  3. Push:   git push -u origin ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+        io.printf('  4. PR:     gh pr create --fill --title "chore(deft): update framework payload"\n');
+        io.printf("  5. Merge:  gh pr merge --squash --delete-branch   # after deft-core-guard passes\n");
     }
-    io.printf("Then take the framework deposit through the full PR lifecycle so deft-core-guard\n");
-    io.printf("evaluates a clean, standalone upgrade PR:\n");
-    io.printf(`  1. Branch: git switch -c ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
-    io.printf('  2. Commit: git commit -m "chore(deft): update framework payload"\n');
-    io.printf(`  3. Push:   git push -u origin ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
-    io.printf('  4. PR:     gh pr create --fill --title "chore(deft): update framework payload"\n');
-    io.printf("  5. Merge:  gh pr merge --squash --delete-branch   # after deft-core-guard passes\n");
+    printUnstagedLedgerRemainder(io, unstagedRemainder);
 }
 function defaultCachedNames(projectDir) {
     try {
@@ -1115,12 +1212,48 @@ function defaultCachedNames(projectDir) {
 function actuallyStagedPaths(stagePaths, cachedNames) {
     return stagePaths.filter((candidate) => cachedNames.some((name) => name === candidate || name.startsWith(`${candidate}/`)));
 }
+function defaultTrackedNames(projectDir, paths) {
+    if (paths.length === 0)
+        return [];
+    try {
+        const out = execFileSync("git", ["ls-files", "-z", "--", ...paths], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return out
+            .split("\0")
+            .map((entry) => entry.trim().replace(/\\/g, "/"))
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
 export function depositStagePaths(projectDir, options = {}) {
-    const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
-    const stagePaths = frameworkStagePaths(projectDir, deftDir, {
-        includeCore: options.includeCore,
-        includeTaskfile: options.includeTaskfile ?? false,
-    });
+    const summary = options.mutations ?? snapshotMutationSummary();
+    const ledgerBound = options.mutations !== undefined || activeMutationLedger() !== undefined;
+    let stagePaths;
+    let unstagedRemainder = [];
+    let skippedUntrackedDeletes = [];
+    if (ledgerBound) {
+        const readTracked = options.readTrackedNames ?? defaultTrackedNames;
+        const tracked = new Set(readTracked(projectDir, summary.deleted));
+        const split = splitLedgerForStaging(summary, tracked);
+        stagePaths = split.stagePaths;
+        unstagedRemainder = split.unstagedRemainder;
+        skippedUntrackedDeletes = split.skippedUntrackedDeletes;
+    }
+    else {
+        const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
+        stagePaths = frameworkStagePaths(projectDir, deftDir, {
+            includeCore: options.includeCore,
+        });
+    }
+    const leftover = [...unstagedRemainder, ...skippedUntrackedDeletes];
+    if (leftover.length > 0 && options.printf) {
+        printUnstagedLedgerRemainder({ printf: options.printf }, leftover);
+    }
     const { staged } = stageFrameworkPaths(projectDir, stagePaths, options);
     const readCachedNames = options.readCachedNames ?? defaultCachedNames;
     const cachedNames = staged ? readCachedNames(projectDir) : [];
@@ -1128,6 +1261,8 @@ export function depositStagePaths(projectDir, options = {}) {
         stagePaths,
         staged,
         stagedPaths: staged ? actuallyStagedPaths(stagePaths, cachedNames) : [],
+        unstagedRemainder,
+        skippedUntrackedDeletes,
     };
 }
 //# sourceMappingURL=hygiene.js.map

package/dist/init-deposit/legacy-detect.js

@@ -24,11 +24,12 @@
  * Refs #1912, #1669.
  */
 import { execFileSync } from "node:child_process";
-import { rmSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
 import { join } from "node:path";
 import { GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL } from "../doctor/constants.js";
 import { extractManagedSection, parseInstallRootFromAgentsMd } from "../doctor/manifest.js";
 import { readTextSafe } from "../doctor/paths.js";
+import { containedRemove } from "../fs/contained-write.js";
 import { gitPorcelain } from "../story-ready/git.js";
 /** Non-zero exit code for a use-time legacy-layout refusal (needs-action). */
 export const LEGACY_LAYOUT_REFUSED_EXIT_CODE = 2;
@@ -314,7 +315,10 @@ export function tryCleanupLegacyDeftTree(projectDir, seams = {}) {
         };
     }
     const deftDir = join(projectDir, LEGACY_DEFT_DIR);
-    const removeDir = seams.removeDir ?? ((p) => rmSync(p, { recursive: true, force: true }));
+    const removeDir = seams.removeDir ??
+        ((p) => {
+            containedRemove({ root: projectDir, target: p, recursive: true });
+        });
     const runGitRm = seams.runGitRm ??
         ((root, relPath) => {
             execFileSync("git", ["rm", "-r", "--ignore-unmatch", relPath], {

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

@@ -8,6 +8,7 @@
  * Refs #1942, #1430, #1671.
  */
 import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
+import { type MutationSummary } from "../fs/mutation-ledger.js";
 import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, type LadderFacts, type ReprojectRunner } from "../resolution/index.js";
 import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type GitLsFiles } from "./gitignore.js";
@@ -30,10 +31,13 @@ export interface RefreshDepositResult {
     readonly legacyLayout: boolean;
     readonly taskfileWired: boolean;
     readonly stagedPaths: string[];
+    /** This-run write/remove ledger (#3392). Same source as printf + JSON. */
+    readonly mutations: MutationSummary;
 }
 export type RefreshDepositStrategy = "file-swap" | "no-op";
 export interface RefreshDepositSeams {
     resolveContentRoot?: () => Promise<string>;
+    /** Folded into the dest port (ADR-004). Default {@link replaceTree} records dest writes/removes. */
     copyContent?: (src: string, dst: string) => Promise<void>;
     readPackageVersion?: () => string;
     readEngineVersion?: () => string;
@@ -48,7 +52,7 @@ export interface RefreshDepositSeams {
     gitLsFiles?: GitLsFiles;
     /** #2530: injected git config seams for {@link writeConsumerGitHooks}. */
     gitHooks?: GitHooksSeams;
-    /** #2822: optional seam for trusted-org policy force-on migration. */
+    /** #2822: optional seam. Default {@link runOrgForceOnMigration} already writes via containedWrite. */
     runOrgForceOn?: (projectRoot: string) => void;
     /** Post-deposit functional readiness gate (#3100). */
     evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
@@ -126,12 +130,22 @@ export interface RefreshSideEffects {
 export declare function frameworkRefreshSideEffects(projectDir: string, options?: FrameworkRefreshSideEffectsOptions): RefreshSideEffects;
 export declare function printRefreshSideEffects(io: InitDepositIo, effects: RefreshSideEffects): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
+/** True when recorded deposit version and content package version disagree (#3437). */
+export declare function depositRefreshPending(previousDepositVersion: string | null, contentVersion: string): boolean;
+/** First-line dry-run headline when deposit manifest and content disagree (#3437). */
+export declare function buildDepositVersionSkewHeadline(previousDepositVersion: string | null, contentVersion: string): string | null;
 export declare function buildUpdateSummaryJson(input: {
     result: RefreshDepositResult;
     options: RefreshDepositArgs;
     updateState: UpdateState | undefined;
     readiness: AgentHookReadinessResult | undefined;
 }): Record<string, unknown>;
+/** Consumer-owned prefixes whose rewrite can fail a repo Prettier/fmt gate (#3395). */
+export declare const PRETTIER_SENSITIVE_CONSUMER_PREFIXES: readonly ["xbrief/schemas/"];
+export declare const PRETTIER_SENSITIVE_FMT_HINT = "run `task fmt` or your repo formatter before the upgrade PR";
+/** Ledger `wrote` paths under prettier-sensitive consumer-owned prefixes. */
+export declare function prettierSensitiveRewrites(summary: MutationSummary): string[];
+export declare function formatPrettierSensitiveAnnounce(paths: readonly string[]): string;
 export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;
 export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
 export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {
@@ -149,6 +163,12 @@ export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {
     /** #2266: injected content re-projection after a self-heal install. */
     readonly reproject?: ReprojectRunner;
 }
+/**
+ * Dest effects the port cannot yet capture (ADR-004 condition 3).
+ * Shrink as sites fold; never drop the printed label.
+ */
+export declare const UPDATE_DRY_RUN_EXCLUSIONS: readonly ["openclaw-home-skills"];
+export declare const UPDATE_DRY_RUN_EXCLUSIONS_LABEL = "Excluded from dest plan (not yet captured by the port): OpenClaw $HOME skills.";
 /** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */
 export declare function runRefreshDepositCli(options: RunRefreshDepositCliOptions): Promise<number>;
 export declare function parseUpdateArgv(canonicalArgv: readonly string[], userArgv?: readonly string[]): RefreshDepositArgs;