@deftai/directive-core 0.90.0 → 0.91.0

package/dist/doctor/openclaw-skills.d.ts

@@ -1,10 +1,16 @@
 /**
- * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001 / #3008).
  *
  * When OpenClaw signals are present, doctor checks the main workspace skills
  * root for the four always-pin skills (#2508). Missing pins emit a warning with
- * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
- * or copied from the installed content package into the target skills dir.
+ * remediation `deft doctor --fix`. Under fixMode, pins are **copied** into the
+ * workspace skills root (not symlinked into the npm content package).
+ *
+ * OpenClaw 2026.7.x rejects workspace skills that resolve outside the configured
+ * skills root (`reason=symlink-escape`). A pin that is only a symlink into
+ * `@deftai/directive-content` therefore looks "present" on disk while the host
+ * never loads it (#3008). Prefer real directory copies; treat escaping
+ * symlinks as divergent so `--fix` can replace them.
  *
  * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
  */
@@ -29,6 +35,7 @@ export interface OpenClawSkillPinsSeams {
     readonly symlinkDir?: (target: string, path: string) => void;
     readonly copyDir?: (src: string, dst: string) => void;
     readonly removePath?: (path: string) => void;
+    readonly renamePath?: (from: string, to: string) => void;
     readonly contentRootFor?: (frameworkRoot: string) => string;
     readonly isTty?: () => boolean;
     readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
@@ -77,21 +84,48 @@ export declare function listInScopeSkillsDirs(stateDir: string, allAgents: boole
  * Resolve content package skills/<id> for a pin.
  */
 export declare function resolvePinSourceDir(contentBase: string, skillId: string): string;
+/**
+ * True when `path` is a symlink whose resolved real path is outside `skillsDir`
+ * (OpenClaw `symlink-escape` / #3008).
+ */
+export declare function isEscapingSkillSymlink(skillsDir: string, path: string, seams?: Pick<OpenClawSkillPinsSeams, "lstatKind">): boolean;
 /**
  * Assess which always-pins are present / missing / divergent in a skills root.
  *
- * - present: directory (or symlink) with SKILL.md
+ * - present: real directory (or non-escaping symlink) with SKILL.md matching
+ *   the content package when `contentBase` is supplied
  * - missing: path does not exist
- * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ * - divergent: path exists but is not a usable OpenClaw pin (file, empty dir,
+ *   broken link, **escaping symlink**, or **stale SKILL.md** vs package — #3008)
  */
-export declare function assessOpenClawPins(skillsDir: string, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "isFile" | "pathExists" | "lstatKind">): OpenClawPinAssessment;
+export declare function assessOpenClawPins(skillsDir: string, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "isFile" | "pathExists" | "lstatKind">, options?: {
+    contentBase?: string;
+}): OpenClawPinAssessment;
 /**
- * Install one pin into a skills root. Prefer symlink; copy on failure.
- * Never deletes user skills. Divergent targets require force or TTY confirm.
+ * Install one pin into a skills root.
+ *
+ * Default: **copy** into the workspace skills root (#3008). OpenClaw rejects
+ * skills that resolve outside the workspace skills root via symlink-escape, so
+ * symlinking into the npm content package leaves pins unloaded while doctor
+ * reports "present". Opt into legacy symlink-first with `preferSymlink: true`
+ * (still falls back to copy). Never deletes unrelated user skills. Divergent
+ * targets (including escaping symlinks) require force or TTY confirm.
+ *
+ * Stale copies (SKILL.md differs from package) are not "already-present" —
+ * doctor --fix refreshes them so upgrades land without manual delete (#3008 P1).
+ * Forced replace stages into a sibling temp dir first so a failed copy does not
+ * leave the pin permanently deleted (#3008 P1).
  */
 export declare function installOpenClawPin(skillId: OpenClawAlwaysPinSkill, sourceDir: string, skillsDir: string, options?: {
     force?: boolean;
     allowOverwrite?: boolean;
+    /** When true, try symlink first (legacy #3001). Default false — copy (#3008). */
+    preferSymlink?: boolean;
+    /**
+     * When true, refresh copied pins whose SKILL.md no longer matches the
+     * package (package upgrade path). Doctor --fix sets this.
+     */
+    refreshStale?: boolean;
 }, seams?: OpenClawSkillPinsSeams): PinInstallResult;
 export interface RunOpenClawSkillPinsOptions {
     readonly frameworkRoot: string;

package/dist/doctor/openclaw-skills.js

@@ -1,16 +1,22 @@
 /**
- * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001 / #3008).
  *
  * When OpenClaw signals are present, doctor checks the main workspace skills
  * root for the four always-pin skills (#2508). Missing pins emit a warning with
- * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
- * or copied from the installed content package into the target skills dir.
+ * remediation `deft doctor --fix`. Under fixMode, pins are **copied** into the
+ * workspace skills root (not symlinked into the npm content package).
+ *
+ * OpenClaw 2026.7.x rejects workspace skills that resolve outside the configured
+ * skills root (`reason=symlink-escape`). A pin that is only a symlink into
+ * `@deftai/directive-content` therefore looks "present" on disk while the host
+ * never loads it (#3008). Prefer real directory copies; treat escaping
+ * symlinks as divergent so `--fix` can replace them.
  *
  * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { contentRoot } from "../content-root.js";
 /** Stable doctor check id for JSON findings. */
 export const OPENCLAW_SKILL_PINS_CHECK = "openclaw-skill-pins";
@@ -159,18 +165,57 @@ function skillHasBody(skillDir, isFile, isDir) {
     // Accept dir or symlink-to-dir that contains SKILL.md
     return isFile(join(skillDir, "SKILL.md"));
 }
+/**
+ * True when both dirs have SKILL.md with identical bytes (pin still current
+ * after package upgrade). False / unreadable → treat as stale (#3008 P1).
+ */
+function skillBodyMatchesPackage(sourceDir, targetDir, isFile) {
+    const src = join(sourceDir, "SKILL.md");
+    const dst = join(targetDir, "SKILL.md");
+    if (!isFile(src) || !isFile(dst))
+        return false;
+    try {
+        return readFileSync(src, "utf8") === readFileSync(dst, "utf8");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when `path` is a symlink whose resolved real path is outside `skillsDir`
+ * (OpenClaw `symlink-escape` / #3008).
+ */
+export function isEscapingSkillSymlink(skillsDir, path, seams = {}) {
+    const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    if (lstatKind(path) !== "symlink")
+        return false;
+    try {
+        const skillsReal = realpathSync(skillsDir);
+        const pathReal = realpathSync(path);
+        const rel = relative(skillsReal, pathReal);
+        // Outside root, or walks up with ".."
+        return rel === "" || rel.startsWith(`..${sep}`) || rel.startsWith("..") || rel === "..";
+    }
+    catch {
+        // Broken symlink / unreadable realpath — treat as escape / unusable.
+        return true;
+    }
+}
 /**
  * Assess which always-pins are present / missing / divergent in a skills root.
  *
- * - present: directory (or symlink) with SKILL.md
+ * - present: real directory (or non-escaping symlink) with SKILL.md matching
+ *   the content package when `contentBase` is supplied
  * - missing: path does not exist
- * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ * - divergent: path exists but is not a usable OpenClaw pin (file, empty dir,
+ *   broken link, **escaping symlink**, or **stale SKILL.md** vs package — #3008)
  */
-export function assessOpenClawPins(skillsDir, seams = {}) {
+export function assessOpenClawPins(skillsDir, seams = {}, options = {}) {
     const isDir = seams.isDir ?? defaultIsDir;
     const isFile = seams.isFile ?? defaultIsFile;
     const pathExists = seams.pathExists ?? defaultPathExists;
     const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    const contentBase = options.contentBase;
     const present = [];
     const missing = [];
     const divergent = [];
@@ -181,7 +226,21 @@ export function assessOpenClawPins(skillsDir, seams = {}) {
             missing.push(skillId);
             continue;
         }
+        // Escaping symlink: SKILL.md may resolve, but OpenClaw skips load (#3008).
+        if (kind === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind })) {
+            divergent.push(skillId);
+            continue;
+        }
         if (skillHasBody(target, isFile, isDir)) {
+            if (contentBase) {
+                const sourceDir = resolvePinSourceDir(contentBase, skillId);
+                if (!skillBodyMatchesPackage(sourceDir, target, isFile)) {
+                    // Stale copy after package upgrade — surface as divergent so doctor
+                    // does not report "present" and skip repair (#3008 Greptile P1).
+                    divergent.push(skillId);
+                    continue;
+                }
+            }
             present.push(skillId);
             continue;
         }
@@ -218,8 +277,19 @@ function defaultCopyDir(src, dst) {
     cpSync(src, dst, { recursive: true });
 }
 /**
- * Install one pin into a skills root. Prefer symlink; copy on failure.
- * Never deletes user skills. Divergent targets require force or TTY confirm.
+ * Install one pin into a skills root.
+ *
+ * Default: **copy** into the workspace skills root (#3008). OpenClaw rejects
+ * skills that resolve outside the workspace skills root via symlink-escape, so
+ * symlinking into the npm content package leaves pins unloaded while doctor
+ * reports "present". Opt into legacy symlink-first with `preferSymlink: true`
+ * (still falls back to copy). Never deletes unrelated user skills. Divergent
+ * targets (including escaping symlinks) require force or TTY confirm.
+ *
+ * Stale copies (SKILL.md differs from package) are not "already-present" —
+ * doctor --fix refreshes them so upgrades land without manual delete (#3008 P1).
+ * Forced replace stages into a sibling temp dir first so a failed copy does not
+ * leave the pin permanently deleted (#3008 P1).
  */
 export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {}, seams = {}) {
     const isFile = seams.isFile ?? defaultIsFile;
@@ -234,8 +304,11 @@ export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {},
         });
     const copyDir = seams.copyDir ?? defaultCopyDir;
     const removePath = seams.removePath ?? ((p) => rmSync(p, { recursive: true, force: true }));
+    const renamePath = seams.renamePath ?? ((from, to) => renameSync(from, to));
     const target = join(skillsDir, skillId);
     const force = options.force === true || options.allowOverwrite === true;
+    const preferSymlink = options.preferSymlink === true;
+    const refreshStale = options.refreshStale === true;
     if (!isDir(sourceDir) || !isFile(join(sourceDir, "SKILL.md"))) {
         return {
             skillId,
@@ -248,43 +321,199 @@ export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {},
     mkdirp(skillsDir);
     const kind = lstatKind(target);
     if (kind !== "missing") {
-        if (skillHasBody(target, isFile, isDir)) {
-            return {
-                skillId,
-                method: "already-present",
-                target,
-                source: sourceDir,
-            };
+        const escaping = kind === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind });
+        if (!escaping && skillHasBody(target, isFile, isDir)) {
+            const matches = skillBodyMatchesPackage(sourceDir, target, isFile);
+            if (matches) {
+                return {
+                    skillId,
+                    method: "already-present",
+                    target,
+                    source: sourceDir,
+                };
+            }
+            // Stale copy after package upgrade — refresh under --fix / force.
+            if (!force && !refreshStale) {
+                return {
+                    skillId,
+                    method: "skipped",
+                    target,
+                    source: sourceDir,
+                    detail: "stale pin (SKILL.md differs from content package); re-run with --force or doctor --fix to refresh",
+                };
+            }
+            // fall through to safe replace
         }
-        if (!force) {
+        else if (!force) {
             return {
                 skillId,
                 method: "skipped",
                 target,
                 source: sourceDir,
-                detail: "divergent target exists; re-run with --force or confirm on TTY to replace",
+                detail: escaping
+                    ? "escaping symlink (OpenClaw symlink-escape); re-run with --force to replace with a real copy (#3008)"
+                    : "divergent target exists; re-run with --force or confirm on TTY to replace",
             };
         }
-        removePath(target);
     }
+    if (preferSymlink && kind === "missing") {
+        try {
+            symlinkDir(sourceDir, target);
+            return { skillId, method: "symlink", target, source: sourceDir };
+        }
+        catch {
+            // fall through to copy
+        }
+    }
+    // Exclusive lock dir serializes concurrent doctor --fix on the same pin
+    // (non-recursive mkdir fails with EEXIST — atomic on win32 + posix). No
+    // writeFileSync (contained-writes #2951). Crash recovery: reclaim locks older
+    // than 10 minutes (pin install is seconds; long steal window is intentional).
+    const lockDir = `${target}.deft-lock`;
+    const STALE_LOCK_MS = 10 * 60 * 1000;
+    const tryAcquireLock = () => {
+        try {
+            mkdirSync(lockDir);
+            return true;
+        }
+        catch {
+            try {
+                const ageMs = Date.now() - statSync(lockDir).mtimeMs;
+                if (ageMs >= STALE_LOCK_MS) {
+                    rmSync(lockDir, { recursive: true, force: true });
+                    mkdirSync(lockDir);
+                    return true;
+                }
+            }
+            catch {
+                try {
+                    mkdirSync(lockDir);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        }
+    };
+    if (!tryAcquireLock()) {
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: "another doctor process is installing this pin; re-run after it finishes",
+        };
+    }
+    const releaseLock = () => {
+        try {
+            removePath(lockDir);
+        }
+        catch {
+            // ignore
+        }
+    };
+    // Stage copy first so a failed install never deletes the prior target without
+    // a replacement ready (#3008 Greptile P1: failed copies lose replaced targets).
+    // Unique suffix avoids leftover collision if a prior crash left staging files.
+    const swapId = `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const staging = `${target}.deft-installing-${swapId}`;
     try {
-        symlinkDir(sourceDir, target);
-        return { skillId, method: "symlink", target, source: sourceDir };
+        removePath(staging);
     }
     catch {
+        // ignore missing staging
+    }
+    try {
+        copyDir(sourceDir, staging);
+    }
+    catch (err) {
         try {
-            copyDir(sourceDir, target);
-            return { skillId, method: "copy", target, source: sourceDir };
+            removePath(staging);
         }
-        catch (err) {
-            return {
-                skillId,
-                method: "skipped",
-                target,
-                source: sourceDir,
-                detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
+        catch {
+            // ignore cleanup
         }
+        releaseLock();
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Re-check under the lock: another process may have already refreshed to a
+    // matching real copy. Escaping symlinks still match SKILL.md bytes through
+    // the link — never short-circuit those; they must become real copies.
+    const kindUnderLock = lstatKind(target);
+    const escapingUnderLock = kindUnderLock === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind });
+    if (kindUnderLock !== "missing" &&
+        !escapingUnderLock &&
+        skillHasBody(target, isFile, isDir) &&
+        skillBodyMatchesPackage(sourceDir, target, isFile)) {
+        try {
+            removePath(staging);
+        }
+        catch {
+            // ignore
+        }
+        releaseLock();
+        return {
+            skillId,
+            method: "already-present",
+            target,
+            source: sourceDir,
+        };
+    }
+    const backup = kindUnderLock !== "missing" ? `${target}.deft-backup-${swapId}` : null;
+    try {
+        if (backup !== null) {
+            try {
+                removePath(backup);
+            }
+            catch {
+                // ignore
+            }
+            renamePath(target, backup);
+        }
+        renamePath(staging, target);
+        if (backup !== null) {
+            try {
+                removePath(backup);
+            }
+            catch {
+                // leftover backup is harmless
+            }
+        }
+        releaseLock();
+        return { skillId, method: "copy", target, source: sourceDir };
+    }
+    catch (err) {
+        // Restore backup if we moved it away and the swap failed.
+        try {
+            removePath(staging);
+        }
+        catch {
+            // ignore
+        }
+        if (backup !== null && lstatKind(target) === "missing" && lstatKind(backup) !== "missing") {
+            try {
+                renamePath(backup, target);
+            }
+            catch {
+                // best-effort restore
+            }
+        }
+        releaseLock();
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }
 /**
@@ -318,7 +547,7 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
     const divergentByDir = [];
     let allPresent = true;
     for (const skillsDir of skillsDirs) {
-        const assessment = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+        const assessment = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind }, { contentBase });
         if (assessment.missing.length > 0) {
             allPresent = false;
             missingByDir.push({ skillsDir, missing: [...assessment.missing] });
@@ -363,21 +592,35 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
                     isDir,
                     isFile,
                     lstatKind: seams.lstatKind,
-                });
+                }, { contentBase });
                 const toInstall = new Set([
                     ...assessment.missing,
                     ...(options.force ? assessment.divergent : []),
                 ]);
-                if (!options.force && assessment.divergent.length > 0 && isTty() && !options.jsonMode) {
+                // Stale pins (SKILL.md ≠ package) are classified divergent; under --fix
+                // refresh them without TTY confirm (safe overwrite of our own pins).
+                if (!options.force) {
                     for (const skillId of assessment.divergent) {
-                        if (readYn(`Replace divergent OpenClaw skill dir ${join(skillsDir, skillId)} with pin from content package?`, false)) {
+                        const sourceDir = resolvePinSourceDir(contentBase, skillId);
+                        const target = join(skillsDir, skillId);
+                        if (skillHasBody(target, isFile, isDir) &&
+                            !skillBodyMatchesPackage(sourceDir, target, isFile)) {
                             toInstall.add(skillId);
+                            continue;
+                        }
+                        if (isTty() && !options.jsonMode) {
+                            if (readYn(`Replace divergent OpenClaw skill dir ${join(skillsDir, skillId)} with pin from content package?`, false)) {
+                                toInstall.add(skillId);
+                            }
                         }
                     }
                 }
                 for (const skillId of toInstall) {
                     const sourceDir = resolvePinSourceDir(contentBase, skillId);
-                    const result = installOpenClawPin(skillId, sourceDir, skillsDir, { force: options.force || assessment.divergent.includes(skillId) }, seams);
+                    const result = installOpenClawPin(skillId, sourceDir, skillsDir, {
+                        force: options.force || assessment.divergent.includes(skillId),
+                        refreshStale: true,
+                    }, seams);
                     installResults.push(result);
                     if (result.method === "symlink" || result.method === "copy") {
                         sink.success(`OpenClaw pin ${skillId}: ${result.method} → ${result.target}${result.method === "symlink" ? ` (from ${result.source})` : ""}`);
@@ -395,7 +638,7 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
         let stillMissing = false;
         const postMissing = [];
         for (const skillsDir of skillsDirs) {
-            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind }, { contentBase });
             if (post.missing.length > 0 || post.divergent.length > 0) {
                 stillMissing = true;
                 postMissing.push(...post.missing.map((id) => `${skillsDir}/${id}`), ...post.divergent.map((id) => `${skillsDir}/${id} (divergent)`));

package/dist/eval/health.d.ts

@@ -40,7 +40,16 @@ export interface EvaluateHealthResult {
 }
 /** Absolute path to the versioned health history ledger (#2545). */
 export declare function healthHistoryPath(projectRoot: string): string | null;
-/** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
+/**
+ * Residual regression detector for the #1694 wipCap unsatisfiable-nudge.
+ *
+ * Pre-fix: classify treated absent `plan.policy.wipCap` as incomplete while
+ * omit-by-design (#1186 D1) made materializing the default a self-check trap.
+ * The fix records decision-provenance out-of-band (`x-directive/onboarding`),
+ * so greenfield "missing wipCap decision" is satisfiable without materializing
+ * the value field. This detector now only fires if a decision marker is set
+ * but classify still lists wipCap as missing (classifier regression).
+ */
 export declare function detectWipCapUnsatisfiableNudge(projectRoot: string): ContradictionEvidence | null;
 /** Run all registered contradictory-gate detectors. */
 export declare function detectContradictoryGates(projectRoot: string): ContradictionEvidence[];

package/dist/eval/health.js

@@ -6,7 +6,6 @@ import { readCorePackageVersion } from "../engine-version.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { healthMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
-import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { classifyOnboarding, detectPriorState } from "../triage/welcome/prior-state.js";
 import { validateLinks } from "../validate-content/index.js";
 import { evaluateConformance } from "../vbrief-validate/conformance.js";
@@ -106,26 +105,27 @@ function probeContentManifest(projectRoot) {
 export function healthHistoryPath(projectRoot) {
     return healthMetricsHistoryPath(projectRoot);
 }
-/** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
+/**
+ * Residual regression detector for the #1694 wipCap unsatisfiable-nudge.
+ *
+ * Pre-fix: classify treated absent `plan.policy.wipCap` as incomplete while
+ * omit-by-design (#1186 D1) made materializing the default a self-check trap.
+ * The fix records decision-provenance out-of-band (`x-directive/onboarding`),
+ * so greenfield "missing wipCap decision" is satisfiable without materializing
+ * the value field. This detector now only fires if a decision marker is set
+ * but classify still lists wipCap as missing (classifier regression).
+ */
 export function detectWipCapUnsatisfiableNudge(projectRoot) {
     const loaded = loadPlan(projectRoot);
     if (loaded === null) {
         return null;
     }
-    const { plan, filepath } = loaded;
-    const policy = readPlanPolicy(plan);
-    const wipCapPresent = typeof policy === "object" &&
-        policy !== null &&
-        !Array.isArray(policy) &&
-        "wipCap" in policy;
-    if (wipCapPresent) {
-        return null;
-    }
     const state = detectPriorState(projectRoot);
     const [, missing] = classifyOnboarding(state);
-    if (!missing.includes("wipCap")) {
+    if (!(state.wipCapDecided && missing.includes("wipCap"))) {
         return null;
     }
+    const { plan, filepath } = loaded;
     const validatorErrors = validateWipCapOnPlan(plan, filepath);
     if (validatorErrors.length > 0) {
         return null;
@@ -133,11 +133,11 @@ export function detectWipCapUnsatisfiableNudge(projectRoot) {
     return {
         id: "wipCap-unsatisfiable-nudge",
         kind: "unsatisfiable-nudge",
-        summary: "Onboarding completeness treats absent plan.policy.wipCap as incomplete, but omit-by-design accepts absence as valid (#1694 / #1186 D1).",
+        summary: "wipCap decision marker is set but classifyOnboarding still lists wipCap as missing (#1694 regression).",
         signals: [
-            "classifyOnboarding: wipCap listed in missing onboarding signals",
-            "validateWipCapOnPlan: omitted wipCap is valid",
-            "triage:welcome --onboard nudge cannot clear without violating omit-by-design contract",
+            "x-directive/onboarding.wipCapDecided: true",
+            "classifyOnboarding: wipCap still in missing onboarding signals",
+            "decision-provenance and completeness classifier are out of sync",
         ],
     };
 }

package/dist/init-deposit/hygiene.js

@@ -45,6 +45,9 @@ export function installerManagedMatchers() {
         // `deft update` framework-deposit PR trips no-mixed-core-and-app (#2277).
         { exact: "xbrief/.deft-version" },
         { exact: "xbrief/xbrief.md" },
+        // Minimal render-ready seed from init (#3013); operator may later edit identity.
+        { exact: "xbrief/PROJECT-DEFINITION.xbrief.json" },
+        { exact: "vbrief/PROJECT-DEFINITION.vbrief.json" },
         { prefix: "xbrief/schemas/" },
         { prefix: "xbrief/migration/" },
         ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `xbrief/${sub}/.gitkeep` })),

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

@@ -34,6 +34,11 @@ export declare function userConfigDir(): string;
 export declare function createUserConfigDir(io: InitDepositIo): string;
 export declare function buildInstallSummaryJson(result: InitDepositResult, options: InitDepositArgs): Record<string, unknown>;
 export declare function printNextSteps(result: InitDepositResult, io: InitDepositIo): void;
+/**
+ * Ensure a minimal render-ready PROJECT-DEFINITION exists after lifecycle dirs
+ * are deposited (#3013 / epic #3009). Idempotent: never overwrites existing identity.
+ */
+export declare function seedMinimalProjectDefinition(projectDir: string, io: InitDepositIo): boolean;
 export declare function runInitDeposit(args: InitDepositArgs, io: InitDepositIo, seams?: InitDepositSeams): Promise<InitDepositResult>;
 export interface RunInitDepositCliOptions extends InitDepositArgs {
     readonly writeOut: (text: string) => void;