@deftai/directive-core 0.96.0 → 0.97.0

package/dist/session/compact-ritual.js

@@ -0,0 +1,237 @@
+/**
+ * Soft post-compact / post-amnesia AGENTS re-bind (#3171 / epic #2769 pass-3).
+ *
+ * Single in-repo source of truth for the soft checklist. File-host compact and
+ * SessionStart hooks, Codex best-effort SessionStart, and the OpenClaw durable
+ * skill adapter all derive from this module — no divergent host-only rule text.
+ *
+ * Soft complements hard Tier-1 compact re-arm (#2113). Soft never replaces,
+ * weakens, or short-circuits PreToolUse deny / mutation ritual.
+ */
+/** Epic + implement child anchors for docs and wire markers. */
+export const SOFT_AGENTS_REBIND_EPIC = 2769;
+export const SOFT_AGENTS_REBIND_ISSUE = 3171;
+export const SOFT_AGENTS_REBIND_EVIDENCE_ISSUE = 3161;
+/** Stable marker substring present in every host-facing soft deposit. */
+export const SOFT_AGENTS_REBIND_MARKER = "Directive soft post-compact AGENTS re-bind (#3171 / #2769)";
+/** Managed OpenClaw skill directory name (doctor/init deposit). */
+export const OPENCLAW_SOFT_REBIND_SKILL_ID = "deft-directive-post-compact-rebind";
+/** Sentinel inside managed OpenClaw skill bodies for rewrite detection. */
+export const OPENCLAW_SOFT_REBIND_MANAGED_MARKER = "<!-- deft:managed soft-agents-rebind #3171 -->";
+/**
+ * Pass-3 §2 checklist obligations — one ordered list, all hosts consume.
+ * Host adapters may wrap packaging; they must not invent alternate rule text.
+ */
+export const SOFT_AGENTS_REBIND_CHECKLIST = [
+    {
+        id: "reread-agents",
+        text: "Re-read managed AGENTS.md session routing (#2176). Do not treat the " +
+            "compaction summary or host runbook as SoT.",
+    },
+    {
+        id: "confirm-learned",
+        text: "Confirm-what-you-learned in the user-visible reply (brief): alignment " +
+            "posture; addressing-name when USER.md applies; product SoT is not the " +
+            "compaction/summary.",
+    },
+    {
+        id: "deposit-integrity",
+        text: "Deposit integrity: if .deft/core/main.md (or managed deposit) is missing " +
+            "or broken while deft may still be on PATH, fail closed to doctor / " +
+            "QUICK-START before product shell. (deft on PATH ≠ healthy deposit.)",
+    },
+    {
+        id: "summary-not-sot",
+        text: "Summary ≠ SoT: compaction/session runbooks (demo DBs, demo apps, ports, " +
+            '"start the frontend") are hypotheses. Re-verify against PROJECT-DEFINITION ' +
+            "/ USER.md / real local config before starting services or inventing demo " +
+            "stacks. (#3161 G)",
+    },
+    {
+        id: "operational-ask-trap",
+        text: 'Operational-ask trap: "open / start / run the app", "bring it up locally", ' +
+            '"open the browser" are still session-routed. They are not an escape hatch ' +
+            "from AGENTS.md, USER.md, or PROJECT-DEFINITION. (#3161 F)",
+    },
+    {
+        id: "mutation-vs-readonly",
+        text: "Mutation vs read-only: read-only / advisory / pure orientation → soft " +
+            "checklist only (do not force full cold session:start). Mutation intent " +
+            "(writes, implement, start-of-story) → soft checklist plus hard re-arm " +
+            "where the host supports it (session:ready / session:start --rearm or cold) " +
+            "before gated tools. Soft never authorizes skipping the mutation ritual for writes.",
+    },
+];
+/**
+ * Five-row host matrix (Cursor / Claude / Grok / Codex / OpenClaw).
+ * Docs and deposit tests must stay aligned with this table.
+ */
+export const SOFT_REBIND_HOST_MATRIX = [
+    {
+        host: "cursor",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "session.compact (preCompact) + session.start additional_context",
+    },
+    {
+        host: "claude",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "PreCompact/PostCompact + SessionStart additionalContext",
+    },
+    {
+        host: "grok",
+        family: "file-host hooks",
+        hardCompact: "deposited",
+        softRebind: "required",
+        wire: "PreCompact/PostCompact + SessionStart soft cue (#3161 dogfood host)",
+    },
+    {
+        host: "codex",
+        family: "file-host (limited)",
+        hardCompact: "unsupported",
+        softRebind: "docs-best-effort",
+        wire: "SessionStart soft cue only — no native compact hook",
+    },
+    {
+        host: "openclaw",
+        family: "Family-2 session host",
+        hardCompact: "unsupported",
+        softRebind: "required",
+        wire: "durable workspace skill via doctor/init; not file-host hooks alone",
+    },
+];
+/** Forbidden soft wording — soft must never invite skipping mutation ritual. */
+export const SOFT_REBIND_FORBIDDEN_PHRASES = [
+    "skip session:start for writes",
+    "skip the mutation ritual",
+    "you may skip session:start",
+    "ritual not required for writes",
+    "soft replaces hard",
+];
+/**
+ * Format the shared soft checklist for host injection / skill bodies.
+ */
+export function formatSoftAgentsRebindChecklist(options = {}) {
+    const includeHeader = options.includeHeader !== false;
+    const lines = [];
+    if (includeHeader) {
+        lines.push(SOFT_AGENTS_REBIND_MARKER);
+        lines.push("After compaction, resume, or long-session amnesia: restore AGENTS rule " +
+            "memory before product action. Soft complements hard compact re-arm; " +
+            "it does not complete or replace the gated mutation ritual.");
+        lines.push("");
+    }
+    lines.push("Soft AGENTS re-bind checklist:");
+    SOFT_AGENTS_REBIND_CHECKLIST.forEach((item, index) => {
+        lines.push(`${index + 1}. ${item.text}`);
+    });
+    return lines.join("\n");
+}
+/**
+ * Append soft checklist to a hard compact re-arm (or SessionStart) message.
+ * Hard text stays first so existing recoveries remain discoverable.
+ */
+export function appendSoftAgentsRebindToMessage(hardMessage) {
+    const hard = hardMessage.trim();
+    const soft = formatSoftAgentsRebindChecklist();
+    if (hard.length === 0)
+        return soft;
+    if (hard.includes(SOFT_AGENTS_REBIND_MARKER))
+        return hard;
+    return `${hard}\n\n${soft}`;
+}
+/** True when text carries the soft re-bind deposit (tests + doctor). */
+export function isSoftAgentsRebindText(text) {
+    return text.includes(SOFT_AGENTS_REBIND_MARKER);
+}
+/** Soft cue events that should inject checklist without requiring a write tool. */
+export function isSoftAgentsRebindEvent(event) {
+    return event === "session.start" || event === "session.compact";
+}
+/**
+ * Whether this decision should carry soft injection on the host wire.
+ * Disabled / opt-out codes stay hard-message only.
+ */
+export function decisionCarriesSoftAgentsRebind(input) {
+    if (!isSoftAgentsRebindEvent(input.event))
+        return false;
+    if (input.code === "session-start-disabled")
+        return false;
+    if (input.code === "directive-disabled")
+        return false;
+    return (input.code === "session-start" ||
+        input.code === "session-start-degraded" ||
+        input.code === "session-compact-rearm" ||
+        input.code === "session-compact-rearm-degraded" ||
+        input.code === "session-compact-noop");
+}
+/**
+ * Managed OpenClaw skill body generated from the same SoT checklist.
+ * Skill-shaped packaging; obligations identical to file-host soft text.
+ */
+export function formatOpenClawSoftRebindSkillMarkdown() {
+    const checklist = formatSoftAgentsRebindChecklist({ includeHeader: false });
+    return [
+        "---",
+        `name: ${OPENCLAW_SOFT_REBIND_SKILL_ID}`,
+        "description: >-",
+        "  Soft post-compact / post-amnesia AGENTS re-bind for OpenClaw (#3171 / #2769).",
+        "  Load after session start, gateway restart, or long-session amnesia.",
+        "  Complements hard file-host compact re-arm; does not replace mutation ritual.",
+        "---",
+        OPENCLAW_SOFT_REBIND_MANAGED_MARKER,
+        "",
+        "# Soft post-compact AGENTS re-bind (OpenClaw)",
+        "",
+        SOFT_AGENTS_REBIND_MARKER,
+        "",
+        "OpenClaw is a **Family-2** session host. It does **not** claim file-host",
+        "`PreCompact` / `PreToolUse` hard compact re-arm alone. This skill is the",
+        "**required** durable soft surface: same checklist obligations as Cursor,",
+        "Claude Code, and Grok Build.",
+        "",
+        "## When to load",
+        "",
+        "- Session start / resume after amnesia boundary",
+        "- Gateway restart or new OpenClaw session context",
+        "- Long-running session where AGENTS.md session routing may have dropped",
+        "- Operational asks after summary resume (start/open app, demo stack)",
+        "",
+        "## Checklist (shared SoT — do not invent host-only rules)",
+        "",
+        checklist,
+        "",
+        "## Hard path honesty",
+        "",
+        "- Soft **never** authorizes skipping `session:start` / `session:ready` /",
+        "  gated ritual for mutation (writes, implement, story start).",
+        "- Where OpenClaw lacks file-host compact PreToolUse, operators still run",
+        "  the mutation ritual via skills / CLI before gated writes.",
+        "- Pins present ≠ session ritual completed.",
+        "",
+        "## Operator recovery",
+        "",
+        "- Deposit / refresh: `deft doctor --fix` (OpenClaw detected) or",
+        "  `deft update` / `directive init` when OpenClaw signals are present.",
+        "- After deposit: restart the OpenClaw gateway or start a new session so",
+        "  skills reload.",
+        "- Docs: `docs/openclaw-agent-host.md` § Soft post-compact AGENTS re-bind.",
+        "",
+    ].join("\n");
+}
+/** True when skill body is the managed #3171 soft re-bind deposit. */
+export function isManagedOpenClawSoftRebindSkill(body) {
+    return body.includes(OPENCLAW_SOFT_REBIND_MANAGED_MARKER);
+}
+/**
+ * Assert soft text never invites skipping mutation ritual (unit + deposit tests).
+ * Returns empty array when clean.
+ */
+export function softAgentsRebindForbiddenHits(text) {
+    const lower = text.toLowerCase();
+    return SOFT_REBIND_FORBIDDEN_PHRASES.filter((phrase) => lower.includes(phrase.toLowerCase()));
+}
+//# sourceMappingURL=compact-ritual.js.map

package/dist/session/compact-ritual.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compact-ritual.spec.d.ts.map

package/dist/session/compact-ritual.spec.js

@@ -0,0 +1,21 @@
+/**
+ * Forward-coverage companion for new compact-ritual.ts (#3171 / #1310).
+ * Hard-path #2113 cases live in compact-ritual.test.ts (pre-existing).
+ */
+import { describe, expect, it } from "vitest";
+import { formatSoftAgentsRebindChecklist, isSoftAgentsRebindText, SOFT_AGENTS_REBIND_CHECKLIST, SOFT_AGENTS_REBIND_MARKER, SOFT_REBIND_HOST_MATRIX, softAgentsRebindForbiddenHits, } from "./compact-ritual.js";
+describe("compact-ritual soft SoT forward coverage (#3171)", () => {
+    it("exports a six-item shared checklist SoT", () => {
+        expect(SOFT_AGENTS_REBIND_CHECKLIST).toHaveLength(6);
+        const text = formatSoftAgentsRebindChecklist();
+        expect(isSoftAgentsRebindText(text)).toBe(true);
+        expect(text).toContain(SOFT_AGENTS_REBIND_MARKER);
+        expect(softAgentsRebindForbiddenHits(text)).toEqual([]);
+    });
+    it("lists five hosts with Codex gap and OpenClaw required soft", () => {
+        expect(SOFT_REBIND_HOST_MATRIX).toHaveLength(5);
+        expect(SOFT_REBIND_HOST_MATRIX.find((r) => r.host === "codex")?.softRebind).toBe("docs-best-effort");
+        expect(SOFT_REBIND_HOST_MATRIX.find((r) => r.host === "openclaw")?.softRebind).toBe("required");
+    });
+});
+//# sourceMappingURL=compact-ritual.spec.js.map

package/dist/session/index.d.ts

@@ -1,5 +1,7 @@
+export * from "./compact-ritual.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";

package/dist/session/index.js

@@ -1,5 +1,7 @@
+export * from "./compact-ritual.js";
 export * from "./git.js";
 export * from "./json.js";
+export * from "./openclaw-soft-rebind-deposit.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";

package/dist/session/openclaw-soft-rebind-deposit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OpenClaw durable soft AGENTS re-bind skill deposit (#3171 / #2769).
+ *
+ * Deposits a managed workspace skill generated from the shared checklist SoT
+ * in compact-ritual.ts. Fail-closed when OpenClaw is not detected (unless
+ * forceDeposit for tests). Real directory copy — not symlink-escape into npm.
+ */
+import { type OpenClawDetectResult } from "../doctor/openclaw-skills.js";
+export interface OpenClawSoftRebindDepositResult {
+    readonly changed: boolean;
+    readonly writtenPaths: string[];
+    readonly preservedCustomPaths: string[];
+    readonly skillsDirs: string[];
+    readonly skipped: boolean;
+    readonly skipReason?: string;
+    readonly detect: OpenClawDetectResult | null;
+    readonly present: boolean;
+}
+export interface OpenClawSoftRebindDepositOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDir?: string;
+    readonly allAgents?: boolean;
+    readonly forceDeposit?: boolean;
+    readonly skillsDirs?: readonly string[];
+    readonly isDir?: (path: string) => boolean;
+    readonly readDir?: (path: string) => string[];
+}
+/**
+ * Assess whether the managed soft re-bind skill is present and current.
+ *
+ * Unmanaged/custom content at the required slug is NOT present (#3171 P1 /
+ * Greptile): the soft checklist obligations are the health criterion, not
+ * merely occupying the skill directory name.
+ */
+export declare function assessOpenClawSoftRebindSkill(skillsDir: string, options?: {
+    readonly expectedBody?: string;
+}): {
+    readonly present: boolean;
+    readonly custom: boolean;
+    readonly path: string;
+};
+/**
+ * Deposit the managed OpenClaw soft re-bind skill into workspace skills roots.
+ */
+export declare function depositOpenClawSoftRebindSkill(options?: OpenClawSoftRebindDepositOptions): OpenClawSoftRebindDepositResult;
+//# sourceMappingURL=openclaw-soft-rebind-deposit.d.ts.map

package/dist/session/openclaw-soft-rebind-deposit.js

@@ -0,0 +1,165 @@
+/**
+ * OpenClaw durable soft AGENTS re-bind skill deposit (#3171 / #2769).
+ *
+ * Deposits a managed workspace skill generated from the shared checklist SoT
+ * in compact-ritual.ts. Fail-closed when OpenClaw is not detected (unless
+ * forceDeposit for tests). Real directory copy — not symlink-escape into npm.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { detectOpenClaw, isEscapingSkillSymlink, listInScopeSkillsDirs, } from "../doctor/openclaw-skills.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { formatOpenClawSoftRebindSkillMarkdown, isManagedOpenClawSoftRebindSkill, OPENCLAW_SOFT_REBIND_SKILL_ID, } from "./compact-ritual.js";
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultLstatKind(path) {
+    try {
+        const st = lstatSync(path);
+        if (st.isSymbolicLink())
+            return "symlink";
+        if (st.isDirectory())
+            return "dir";
+        if (st.isFile())
+            return "file";
+        return "other";
+    }
+    catch {
+        return "missing";
+    }
+}
+/**
+ * Assess whether the managed soft re-bind skill is present and current.
+ *
+ * Unmanaged/custom content at the required slug is NOT present (#3171 P1 /
+ * Greptile): the soft checklist obligations are the health criterion, not
+ * merely occupying the skill directory name.
+ */
+export function assessOpenClawSoftRebindSkill(skillsDir, options = {}) {
+    const path = join(skillsDir, OPENCLAW_SOFT_REBIND_SKILL_ID, "SKILL.md");
+    if (!existsSync(path)) {
+        return { present: false, custom: false, path };
+    }
+    let body;
+    try {
+        body = readFileSync(path, "utf8");
+    }
+    catch {
+        return { present: false, custom: false, path };
+    }
+    if (!isManagedOpenClawSoftRebindSkill(body)) {
+        // Occupying the slug with unrelated content fails health (#3171 Greptile P1).
+        return { present: false, custom: true, path };
+    }
+    const expected = options.expectedBody ?? formatOpenClawSoftRebindSkillMarkdown();
+    return { present: body === expected, custom: false, path };
+}
+/**
+ * Deposit the managed OpenClaw soft re-bind skill into workspace skills roots.
+ */
+export function depositOpenClawSoftRebindSkill(options = {}) {
+    const env = options.env ?? process.env;
+    const home = options.homeDir ?? homedir();
+    const isDir = options.isDir ?? defaultIsDir;
+    const detect = detectOpenClaw(env, { homeDir: home, isDir });
+    if (!detect.detected && !options.forceDeposit) {
+        return {
+            changed: false,
+            writtenPaths: [],
+            preservedCustomPaths: [],
+            skillsDirs: [],
+            skipped: true,
+            skipReason: "openclaw-not-detected",
+            detect,
+            present: false,
+        };
+    }
+    const skillsDirs = options.skillsDirs !== undefined
+        ? [...options.skillsDirs]
+        : listInScopeSkillsDirs(detect.stateDir, options.allAgents === true, {
+            isDir,
+            readDir: options.readDir,
+        });
+    const expected = formatOpenClawSoftRebindSkillMarkdown();
+    const writtenPaths = [];
+    const preservedCustomPaths = [];
+    let changed = false;
+    let presentCount = 0;
+    for (const skillsDir of skillsDirs) {
+        const skillDir = join(skillsDir, OPENCLAW_SOFT_REBIND_SKILL_ID);
+        const skillFile = join(skillDir, "SKILL.md");
+        const kind = defaultLstatKind(skillDir);
+        if (kind === "symlink" && isEscapingSkillSymlink(skillsDir, skillDir)) {
+            // Replace unusable escaping symlink with a real copy.
+            try {
+                rmSync(skillDir, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort
+            }
+        }
+        if (existsSync(skillFile)) {
+            let existing = "";
+            try {
+                existing = readFileSync(skillFile, "utf8");
+            }
+            catch {
+                existing = "";
+            }
+            // Required soft re-bind surface: unmanaged content at this slug is a gap,
+            // not a preserve-as-present path (Greptile P1 on #3171). Overwrite with
+            // the managed checklist so doctor/init/update cannot report success while
+            // the operational-ask obligations are absent.
+            if (existing === expected) {
+                presentCount += 1;
+                continue;
+            }
+        }
+        mkdirSync(skillDir, { recursive: true });
+        const tmpName = `SKILL.md.deft-${process.pid}-${Date.now().toString(36)}.tmp`;
+        const staging = join(skillDir, tmpName);
+        try {
+            // Contained write under skills root (#2951) — refuses symlink escape.
+            containedWrite({
+                root: skillsDir,
+                target: staging,
+                data: expected,
+                mode: "replace",
+            });
+            renameSync(staging, skillFile);
+        }
+        catch (err) {
+            try {
+                rmSync(staging, { force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/contained write refused|symlink|escape/i.test(msg)) {
+                preservedCustomPaths.push(skillFile);
+                continue;
+            }
+            throw err;
+        }
+        writtenPaths.push(skillFile);
+        changed = true;
+        presentCount += 1;
+    }
+    return {
+        changed,
+        writtenPaths,
+        preservedCustomPaths,
+        skillsDirs,
+        skipped: false,
+        detect,
+        present: presentCount === skillsDirs.length && skillsDirs.length > 0,
+    };
+}
+//# sourceMappingURL=openclaw-soft-rebind-deposit.js.map

package/dist/test-boundary/evaluate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * verify:test-boundary evaluation (#3145).
+ *
+ * Rejects recognized test artifacts under production roots and production
+ * references to test/fixture roots unless allowlisted or classified as
+ * production-liveness. Three-state exit: 0 clean / 1 violation / 2 config.
+ */
+import { type TestBoundaryPolicy } from "./policy.js";
+export type TestBoundaryViolationKind = "test-under-source-root" | "production-references-test-root";
+export interface TestBoundaryFinding {
+    readonly path: string;
+    readonly kind: TestBoundaryViolationKind;
+    readonly detail: string;
+    readonly remediation: string;
+}
+export interface TestBoundaryResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly findings: readonly TestBoundaryFinding[];
+    readonly message: string;
+    readonly policy: TestBoundaryPolicy | null;
+}
+export interface TestBoundaryOptions {
+    readonly policyPath?: string | null;
+    /** Inject policy for pure unit tests (skips disk load). */
+    readonly policy?: TestBoundaryPolicy;
+    /** Inject file list for pure unit tests. */
+    readonly files?: readonly string[];
+    /** Inject file contents for reference scanning (posix path -> text). */
+    readonly fileContents?: ReadonlyMap<string, string>;
+    /** Force enforcement mode override. */
+    readonly enforce?: boolean;
+    readonly quiet?: boolean;
+}
+/**
+ * Glob match with double-star as zero-or-more path segments.
+ * Plain fnmatchCase treats double-star as two greedy stars and fails nested
+ * colocated paths (e.g. packages/cli/src/foo/bar.test.ts vs packages star globs).
+ */
+export declare function matchPolicyGlob(relPath: string, pattern: string): boolean;
+/**
+ * Match repo-relative path against a policy root glob.
+ * Supports foo/**-style prefixes, packages star-src globs, and basename patterns.
+ */
+export declare function matchesRootGlob(relPath: string, rootGlob: string): boolean;
+/** True when basename/path matches a test-file pattern (fnmatch / ** globs). */
+export declare function matchesTestFilePattern(relPath: string, patterns: readonly string[]): boolean;
+/** Recognise conventional test basenames without full glob (fast path). */
+export declare function isRecognizedTestBasename(relPath: string): boolean;
+/**
+ * Evaluate test/source boundary for a project.
+ * Pure when `policy` + `files` (+ optional `fileContents`) are injected.
+ */
+export declare function evaluateTestBoundary(projectRoot: string, options?: TestBoundaryOptions): TestBoundaryResult;
+//# sourceMappingURL=evaluate.d.ts.map