@deftai/directive-core 0.89.0 → 0.91.0

package/dist/doctor/constants.d.ts

@@ -7,7 +7,7 @@ export declare const DEPRECATED_REDIRECT_SENTINEL = "<!-- deft:deprecated-redire
 export declare const DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->";
 export declare const REDIRECT_STUB_HEADER_LINES = 8;
 export declare const TASKFILE_INCLUDE_SNIPPET = "version: '3'\n\nincludes:\n  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
-export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--repair", "--repair-taskfile", "--json", "--quiet", "--full", "--network", "--project-root", "-h", "--help"];
+export declare const DOCTOR_ALLOWED_FLAGS: readonly ["--session", "--fix", "--repair", "--repair-taskfile", "--json", "--quiet", "--full", "--network", "--project-root", "--force", "--openclaw-all-agents", "-h", "--help"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
 export declare const NPM_PACKAGE_NAME = "@deftai/directive";
 export declare const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";

package/dist/doctor/constants.js

@@ -23,6 +23,8 @@ export const DOCTOR_ALLOWED_FLAGS = [
     "--full",
     "--network",
     "--project-root",
+    "--force",
+    "--openclaw-all-agents",
     "-h",
     "--help",
 ];

package/dist/doctor/flags.js

@@ -8,6 +8,8 @@ export function parseDoctorFlags(args) {
     let network = false;
     let help = false;
     let projectRoot = null;
+    let force = false;
+    let openclawAllAgents = false;
     const unknown = [];
     let i = 0;
     while (i < args.length) {
@@ -30,6 +32,12 @@ export function parseDoctorFlags(args) {
         else if (token === "--network") {
             network = true;
         }
+        else if (token === "--force") {
+            force = true;
+        }
+        else if (token === "--openclaw-all-agents") {
+            openclawAllAgents = true;
+        }
         else if (token === "-h" || token === "--help") {
             help = true;
         }
@@ -56,7 +64,19 @@ export function parseDoctorFlags(args) {
         }
         i += 1;
     }
-    return { session, fix, json, quiet, full, network, help, projectRoot, unknown };
+    return {
+        session,
+        fix,
+        json,
+        quiet,
+        full,
+        network,
+        help,
+        projectRoot,
+        force,
+        openclawAllAgents,
+        unknown,
+    };
 }
 export function formatUnknownFlagsError(unknown) {
     return `Unknown flag(s): ${unknown.join(", ")}`;

package/dist/doctor/index.d.ts

@@ -7,6 +7,7 @@ export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
 export * from "./npm-registry.js";
+export * from "./openclaw-skills.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/index.js

@@ -7,6 +7,7 @@ export * from "./json.js";
 export * from "./main.js";
 export * from "./manifest.js";
 export * from "./npm-registry.js";
+export * from "./openclaw-skills.js";
 export * from "./paths.js";
 export * from "./payload-staleness.js";
 export * from "./release-availability.js";

package/dist/doctor/main.js

@@ -21,6 +21,7 @@ import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } fro
 import { pythonJsonDump } from "./json.js";
 import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
+import { runOpenClawSkillPinsCheck } from "./openclaw-skills.js";
 import { createPlainSink } from "./output.js";
 import { readTextSafe, resolveFrameworkRootForProject, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
@@ -350,6 +351,27 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking OpenClaw always-pin skills...");
+    runOpenClawSkillPinsCheck(sink, addFinding, {
+        frameworkRoot,
+        fixMode,
+        jsonMode,
+        force: flags.force,
+        allAgents: flags.openclawAllAgents,
+        seams: {
+            ...seams,
+            env: seams.openclawEnv,
+            homeDir: seams.openclawHomeDir,
+            contentRootFor: seams.openclawContentRootFor,
+            isDir: seams.isDir,
+            isFile: seams.isFile,
+            isTty: seams.isTty,
+            readYn: seams.readYn,
+        },
+    });
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking xBRIEF project envelope version...");
     runXbriefEnvelopeVersionCheck(projectRoot, sink, addFinding, seams);
     let resolution = null;

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

@@ -0,0 +1,143 @@
+/**
+ * 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 **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 type { OutputSink } from "./output.js";
+import type { DoctorSeams, Finding } from "./types.js";
+/** Stable doctor check id for JSON findings. */
+export declare const OPENCLAW_SKILL_PINS_CHECK = "openclaw-skill-pins";
+/** Always-pin skill directory names (#2508 / cold-start). */
+export declare const OPENCLAW_ALWAYS_PIN_SKILLS: readonly ["deft-directive-build", "deft-directive-pre-pr", "deft-directive-review-cycle", "deft-directive-swarm"];
+export type OpenClawAlwaysPinSkill = (typeof OPENCLAW_ALWAYS_PIN_SKILLS)[number];
+/** Env keys that count as strong OpenClaw signals (#3001). */
+export declare const OPENCLAW_ENV_SIGNAL_KEYS: readonly ["OPENCLAW", "DEFT_PROBE_OPENCLAW", "DEFT_AGENT_RUNTIME", "OPENCLAW_STATE_DIR"];
+export interface OpenClawSkillPinsSeams {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDir?: () => string;
+    readonly isDir?: (path: string) => boolean;
+    readonly isFile?: (path: string) => boolean;
+    readonly pathExists?: (path: string) => boolean;
+    readonly readDir?: (path: string) => string[];
+    readonly lstatKind?: (path: string) => "file" | "dir" | "symlink" | "other" | "missing";
+    readonly mkdirp?: (path: string) => void;
+    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;
+}
+export interface OpenClawPinAssessment {
+    readonly skillsDir: string;
+    readonly present: readonly OpenClawAlwaysPinSkill[];
+    readonly missing: readonly OpenClawAlwaysPinSkill[];
+    readonly divergent: readonly OpenClawAlwaysPinSkill[];
+}
+export interface OpenClawDetectResult {
+    readonly detected: boolean;
+    readonly reasons: readonly string[];
+    readonly stateDir: string;
+    readonly mainSkillsDir: string;
+}
+export type PinInstallMethod = "symlink" | "copy" | "skipped" | "already-present";
+export interface PinInstallResult {
+    readonly skillId: OpenClawAlwaysPinSkill;
+    readonly method: PinInstallMethod;
+    readonly target: string;
+    readonly source: string;
+    readonly detail?: string;
+}
+/**
+ * Resolve OpenClaw state directory: OPENCLAW_STATE_DIR or ~/.openclaw.
+ */
+export declare function resolveOpenClawStateDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Main agent workspace skills root under the state dir.
+ */
+export declare function resolveMainSkillsDir(stateDir: string): string;
+/**
+ * Detect OpenClaw from env signals and/or presence of the state directory.
+ */
+export declare function detectOpenClaw(env?: NodeJS.ProcessEnv, options?: {
+    homeDir?: string;
+    isDir?: (path: string) => boolean;
+}): OpenClawDetectResult;
+/**
+ * List in-scope skills directories. Default: main only.
+ * With allAgents: main + every workspace- star /skills under the state dir.
+ */
+export declare function listInScopeSkillsDirs(stateDir: string, allAgents: boolean, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "readDir">): string[];
+/**
+ * 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: 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 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">, options?: {
+    contentBase?: string;
+}): OpenClawPinAssessment;
+/**
+ * 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;
+    readonly fixMode: boolean;
+    readonly jsonMode: boolean;
+    readonly force: boolean;
+    readonly allAgents: boolean;
+    readonly seams?: DoctorSeams & OpenClawSkillPinsSeams;
+}
+/**
+ * Doctor check: detect OpenClaw + missing always-pins; optionally fix.
+ * No-ops when OpenClaw signals are absent.
+ */
+export declare function runOpenClawSkillPinsCheck(sink: OutputSink, addFinding: (finding: Finding) => void, options: RunOpenClawSkillPinsOptions): void;
+//# sourceMappingURL=openclaw-skills.d.ts.map