@deftai/directive-core 0.96.0 → 0.97.0

package/dist/scope-provenance/evaluate.js

@@ -0,0 +1,528 @@
+/**
+ * verify:scope-provenance evaluation (#3145).
+ *
+ * Detects same-PR active xBRIEF expansion that would self-authorize new
+ * implementation paths. Requires renewed human approval (updated digest record
+ * with human stamp); the modified xBRIEF alone is never sufficient.
+ *
+ * Three-state exit: 0 clean / 1 self-authorization / 2 config.
+ * Migration: missing approved-scope records → warn (exit 0) unless --enforce.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { GitCommandError, GitNotFoundError } from "../encoding/git.js";
+import { computeFileScopeDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, } from "./digest.js";
+function git(args, projectRoot) {
+    const result = spawnSync("git", args, {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error !== undefined) {
+        const e = result.error;
+        if (e.code === "ENOENT") {
+            throw new GitNotFoundError("'git' executable not found on PATH");
+        }
+        throw new GitCommandError(`git ${args.join(" ")} failed: ${String(e.message)}`);
+    }
+    // Signal-killed subprocesses report status=null; never treat as clean exit (SLizard P1).
+    if (result.signal !== null && result.signal !== undefined) {
+        throw new GitCommandError(`git ${args.join(" ")} killed by signal ${String(result.signal)}`);
+    }
+    const status = result.status ?? 1;
+    const stderr = String(result.stderr ?? "").trim();
+    // Surface stderr on failure so callers can distinguish "not a git repository".
+    if (status !== 0 && stderr.length > 0) {
+        return { status, stdout: `${result.stdout ?? ""}\n${stderr}` };
+    }
+    return { status, stdout: result.stdout ?? "" };
+}
+/**
+ * Resolve a PR-aware base ref. Bare `HEAD` only shows uncommitted changes, so
+ * CI/PR checkouts would miss committed active-xBRIEF expansion. Prefer
+ * origin/master (or main) for merge-base comparison.
+ * Returns null when no merge-base candidate exists (caller fails closed).
+ */
+export function resolveDefaultBaseRef(projectRoot) {
+    const envCandidates = [
+        process.env.DEFT_BASE_REF,
+        process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : undefined,
+        process.env.GITHUB_BASE_REF,
+    ].filter((x) => typeof x === "string" && x.trim().length > 0);
+    for (const cand of [...envCandidates, "origin/master", "origin/main", "master", "main"]) {
+        if (git(["rev-parse", "--verify", "-q", cand], projectRoot).status === 0) {
+            return cand;
+        }
+    }
+    return null;
+}
+/**
+ * Normalize git --name-only paths (including C-quoted paths).
+ * Decode C-quotes BEFORE converting remaining backslashes to `/` so escape
+ * sequences are not destroyed. Consecutive octal escapes decode as UTF-8
+ * bytes (e.g. \\303\\251 → é) so Unicode xBRIEF paths match filesystem names.
+ */
+export function unquoteGitPath(raw) {
+    const t = raw.replace(/\r$/, "").trim();
+    if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+        let inner = t.slice(1, -1);
+        // First: runs of octal bytes → UTF-8 (Git encodes non-ASCII this way)
+        inner = inner.replace(/(?:\\[0-7]{1,3})+/g, (seq) => {
+            const bytes = [];
+            for (const m of seq.matchAll(/\\([0-7]{1,3})/g)) {
+                bytes.push(parseInt(m[1] ?? "0", 8));
+            }
+            try {
+                return Buffer.from(bytes).toString("utf8");
+            }
+            catch {
+                return String.fromCharCode(...bytes);
+            }
+        });
+        // Then: standard single-char escapes
+        inner = inner.replace(/\\([abtnvfr"'\\])/g, (_m, ch) => {
+            const map = {
+                a: "\x07",
+                b: "\b",
+                t: "\t",
+                n: "\n",
+                v: "\v",
+                f: "\f",
+                r: "\r",
+                '"': '"',
+                "'": "'",
+                "\\": "\\",
+            };
+            return map[ch] ?? ch;
+        });
+        return inner.replace(/\\/g, "/");
+    }
+    return t.replace(/\\/g, "/");
+}
+/** Read a repo-relative path as of `ref` (null if missing). */
+function readRepoFileAtRef(projectRoot, ref, relPath) {
+    const path = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+    const result = git(["show", `${ref}:${path}`], projectRoot);
+    if (result.status !== 0)
+        return null;
+    return result.stdout;
+}
+function changedFilesVsBase(projectRoot, baseRef) {
+    const inside = git(["rev-parse", "--is-inside-work-tree"], projectRoot);
+    if (inside.status !== 0) {
+        throw new GitCommandError("not a git working tree");
+    }
+    // Normalize: if caller passed HEAD, upgrade to default branch so PR commits
+    // are visible (Greptile P1 / #3145). Never silently fall back to bare HEAD.
+    let resolved = baseRef;
+    if (baseRef === "HEAD" || baseRef === "") {
+        const upgraded = resolveDefaultBaseRef(projectRoot);
+        if (upgraded === null) {
+            throw new GitCommandError("no merge-base ref (origin/master|main or DEFT_BASE_REF/GITHUB_BASE_REF); " +
+                "cannot evaluate committed PR scope expansion against bare HEAD");
+        }
+        resolved = upgraded;
+    }
+    const hasBase = git(["rev-parse", "--verify", "-q", resolved], projectRoot).status === 0;
+    if (!hasBase) {
+        throw new GitCommandError(`base ref '${resolved}' not found; pass --base-ref or set DEFT_BASE_REF`);
+    }
+    const out = new Set();
+    const addPath = (raw) => {
+        const t = normalizeRepoRelPath(unquoteGitPath(raw));
+        if (t.length > 0)
+            out.add(t);
+    };
+    // Triple-dot includes all commits on the branch relative to merge-base.
+    const range = resolved === "HEAD" || resolved.includes("...") ? resolved : `${resolved}...HEAD`;
+    const diff = git(["diff", "--name-only", range], projectRoot);
+    if (diff.status === 0) {
+        for (const line of diff.stdout.split("\n")) {
+            addPath(line);
+        }
+    }
+    // Also include working-tree changes vs HEAD (unstaged / staged / untracked).
+    const vsHead = git(["diff", "--name-only", "HEAD"], projectRoot);
+    if (vsHead.status === 0) {
+        for (const line of vsHead.stdout.split("\n")) {
+            addPath(line);
+        }
+    }
+    const untracked = git(["ls-files", "--others", "--exclude-standard"], projectRoot);
+    if (untracked.status === 0) {
+        for (const line of untracked.stdout.split("\n")) {
+            addPath(line);
+        }
+    }
+    return [...out];
+}
+/** Normalize repo-relative paths for exact set membership (always POSIX separators). */
+export function normalizeRepoRelPath(p) {
+    return p
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/\/{2,}/g, "/");
+}
+/**
+ * True when `rel` appears in the changed-path set under any normalization that
+ * Git C-quoting / slash folding may produce (Greptile conf=4 residual).
+ */
+export function changedSetHasPath(changedSet, rel) {
+    const candidates = new Set([
+        normalizeRepoRelPath(rel),
+        normalizeRepoRelPath(unquoteGitPath(rel)),
+        rel.replace(/\\/g, "/"),
+    ]);
+    for (const c of candidates) {
+        if (changedSet.has(c))
+            return true;
+    }
+    const want = normalizeRepoRelPath(rel);
+    const wantBase = want.split("/").pop() ?? want;
+    for (const p of changedSet) {
+        const n = normalizeRepoRelPath(p);
+        if (candidates.has(n))
+            return true;
+        // Same leaf under xbrief/active/ (C-quote / escape divergence)
+        if (want.includes("xbrief/active/") &&
+            n.includes("xbrief/active/") &&
+            (n.split("/").pop() ?? n) === wantBase) {
+            return true;
+        }
+    }
+    return false;
+}
+function listActiveXbriefPaths(projectRoot) {
+    const activeDir = join(projectRoot, "xbrief", "active");
+    if (!existsSync(activeDir))
+        return [];
+    return readdirSync(activeDir)
+        .filter((n) => n.endsWith(".xbrief.json") || n.endsWith(".vbrief.json"))
+        .map((n) => `xbrief/active/${n}`);
+}
+function remediationForExpansion() {
+    return ("Renew human approval: re-record the approved-scope digest after operator review " +
+        "(`task scope:record-approved-scope` / write `.deft/approved-scope/<plan-id>.json` " +
+        "with humanApproval stamp). Editing the active xBRIEF alone does not authorize new " +
+        "paths (#3145). See content/docs/scope-provenance.md.");
+}
+function configError(message) {
+    return { exitCode: 2, findings: [], message };
+}
+/**
+ * Pure evaluation of one active xBRIEF against its approved baseline.
+ * Exported for unit tests without git.
+ */
+export function evaluateOneScopeProvenance(input) {
+    const planId = extractPlanId(input.currentPayload) ?? input.approved?.planId ?? input.xbriefRelPath;
+    const currentScope = normalizeFileScope(extractFileScope(input.currentPayload));
+    const currentDigest = computeFileScopeDigest(currentScope);
+    // Not modified in this change set → nothing to police for self-auth
+    if (!input.xbriefModifiedInChangeSet) {
+        return null;
+    }
+    // Renewed human approval present → accept expansion as re-baselined intent
+    if (isHumanApprovalStamp(input.renewedHumanApproval ?? null)) {
+        return null;
+    }
+    if (input.approved === null) {
+        // Non-empty file_scope without a path-bound approval is expansion risk
+        // (includes plan.id renames that drop the prior approval). Hard-fail so the
+        // default check path cannot soft-warn past AC "fails until renewed approval".
+        // Empty-scope body-only edits may still soft-warn under migration (no enforce).
+        const hard = input.enforce || currentScope.length > 0;
+        return {
+            xbriefRelPath: input.xbriefRelPath,
+            planId,
+            kind: "active-xbrief-modified-without-digest",
+            expandedPaths: currentScope,
+            detail: hard
+                ? "active xBRIEF modified in change set without a path-bound approved-scope digest " +
+                    "(expansion or plan-id reset not permitted without renewed human approval)"
+                : "active xBRIEF modified in change set but no approved-scope digest is recorded",
+            remediation: "Record an approved-scope digest at activation for this xBRIEF path. " +
+                remediationForExpansion(),
+        };
+    }
+    // Approved record exists with human stamp and matching digest → ok
+    if (input.approved.fileScopeDigest === currentDigest &&
+        isHumanApprovalStamp(input.approved.humanApproval)) {
+        return null;
+    }
+    const expanded = scopeExpansion(input.approved.fileScope, currentScope);
+    if (expanded.length === 0) {
+        // Scope shrink or identical after normalize — body edit without expansion is OK
+        if (input.approved.fileScopeDigest === currentDigest) {
+            return null;
+        }
+        // Digest mismatch without path expansion (reorder/noise) — still OK for v1
+        return null;
+    }
+    // Expansion without renewed human approval = self-authorization
+    return {
+        xbriefRelPath: input.xbriefRelPath,
+        planId,
+        kind: "self-authorizing-scope-expansion",
+        expandedPaths: expanded,
+        detail: `active xBRIEF expanded file_scope by ${expanded.length} path(s) in the same change set; ` +
+            "modified xBRIEF cannot authorize the new paths",
+        remediation: remediationForExpansion(),
+    };
+}
+/**
+ * Evaluate scope provenance for a project (or pure injected seams).
+ */
+export function evaluateScopeProvenance(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const enforce = options.enforce ?? false;
+    let changed;
+    /** Merge-base ref used for changed-file discovery (null when files injected). */
+    let discoveryBaseRef = null;
+    try {
+        if (options.changedFiles !== undefined) {
+            changed = [...options.changedFiles].map((p) => p.replace(/\\/g, "/"));
+            // Prefer explicit baseRef for base-scope comparisons; do not force git
+            // discovery on pure injected-seam tests (cwd may not be a repo).
+            if (options.baseRef !== undefined && options.baseRef !== "" && options.baseRef !== "HEAD") {
+                discoveryBaseRef = options.baseRef;
+            }
+            else {
+                try {
+                    discoveryBaseRef = resolveDefaultBaseRef(root);
+                }
+                catch {
+                    discoveryBaseRef = null;
+                }
+            }
+        }
+        else {
+            // Default is PR-aware (origin/master...), not bare HEAD — bare HEAD misses
+            // committed PR diffs on clean checkouts (#3145 Greptile P1).
+            let baseRef = options.baseRef;
+            if (baseRef === undefined || baseRef === "" || baseRef === "HEAD") {
+                const resolved = resolveDefaultBaseRef(root);
+                if (resolved === null) {
+                    return configError("verify_scope_provenance: no merge-base ref found (origin/master|main, " +
+                        "DEFT_BASE_REF, or GITHUB_BASE_REF).\n" +
+                        "  Recovery: fetch the default branch or pass --base-ref <ref>. " +
+                        "Bare HEAD cannot see committed PR scope expansion (#3145).");
+                }
+                baseRef = resolved;
+            }
+            discoveryBaseRef = baseRef;
+            changed = changedFilesVsBase(root, baseRef);
+        }
+    }
+    catch (err) {
+        if (err instanceof GitNotFoundError) {
+            return configError("verify_scope_provenance: 'git' executable not found on PATH.\n" +
+                "  Recovery: install git or run inside a git working tree.");
+        }
+        if (err instanceof GitCommandError) {
+            const msg = err.message.toLowerCase();
+            // Only non-repo trees skip clean (greenfield smoke). Other git failures
+            // fail closed so discovery errors cannot hide scope expansion (Greptile).
+            if (msg.includes("not a git repository") ||
+                msg.includes("outside repository") ||
+                msg.includes("not a git working tree")) {
+                return {
+                    exitCode: 0,
+                    findings: [],
+                    message: `verify_scope_provenance: skipped -- not a git working tree (${err.message}). ` +
+                        "Initialize git or pass --base-ref / inject changedFiles (#3145).",
+                };
+            }
+            return configError(`verify_scope_provenance: git failed -- ${err.message}\n` +
+                "  Recovery: ensure --project-root points at a healthy git working tree.");
+        }
+        throw err;
+    }
+    const changedSet = new Set(changed.map((p) => normalizeRepoRelPath(p)));
+    const findings = [];
+    const softFindings = [];
+    const approvedByPlan = new Map();
+    if (options.approvedRecords !== undefined) {
+        for (const r of options.approvedRecords) {
+            approvedByPlan.set(r.planId, r);
+        }
+    }
+    else {
+        for (const r of listApprovedScopeRecords(root)) {
+            approvedByPlan.set(r.planId, r);
+        }
+    }
+    let activeEntries;
+    if (options.activeXbriefs !== undefined) {
+        activeEntries = [...options.activeXbriefs.entries()].map(([rel, raw]) => ({
+            rel: normalizeRepoRelPath(rel),
+            raw,
+        }));
+    }
+    else {
+        activeEntries = [];
+        for (const rel of listActiveXbriefPaths(root)) {
+            const full = join(root, rel);
+            if (!existsSync(full))
+                continue;
+            try {
+                activeEntries.push({ rel: normalizeRepoRelPath(rel), raw: readFileSync(full, "utf8") });
+            }
+            catch {
+                // skip unreadable
+            }
+        }
+    }
+    for (const { rel, raw } of activeEntries) {
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const planId = extractPlanId(payload);
+        const approvedCandidate = (planId !== null ? approvedByPlan.get(planId) : undefined) ??
+            (planId !== null ? readApprovedScopeRecord(root, planId) : null) ??
+            null;
+        // Bind approval to this xBRIEF path — do not reuse another plan's stamp when
+        // plan.id was rewritten to match (Greptile conf=1).
+        const approved = approvedCandidate !== null &&
+            normalizeRepoRelPath(approvedCandidate.xbriefRelPath) === normalizeRepoRelPath(rel)
+            ? approvedCandidate
+            : null;
+        const modified = changedSetHasPath(changedSet, rel);
+        // Only an explicit renewed stamp from options (or a pre-existing on-disk
+        // digest that was NOT rewritten in this change set) may authorize expansion.
+        // Same-PR rewrite of .deft/approved-scope/<id>.json is NOT sufficient
+        // (Greptile P1: changed approval record self-authorizes scope).
+        const renewed = planId !== null ? (options.renewedApprovals?.get(planId) ?? null) : null;
+        const approvalRecordRel = planId !== null
+            ? `.deft/approved-scope/${planId.replace(/[^a-zA-Z0-9._-]/g, "_")}.json`
+            : null;
+        const approvalInGitChange = approvalRecordRel !== null &&
+            [...changedSet].some((p) => {
+                const n = normalizeRepoRelPath(p);
+                if (n === approvalRecordRel || n.endsWith(`/${approvalRecordRel}`))
+                    return true;
+                // Exact basename match only — no planId substring (Greptile / SLizard).
+                if (planId === null)
+                    return false;
+                const safe = planId.replace(/[^a-zA-Z0-9._-]/g, "_");
+                return (n.includes("/approved-scope/") &&
+                    (n.endsWith(`/${safe}.json`) || n.endsWith(`${safe}.json`)));
+            });
+        // Ignored / untracked approved-scope files never appear in git changedSet.
+        // Concurrent rewrite attack: scope *expanded* vs base AND an untracked disk
+        // approval was rewritten to match the *new* digest. Body-only xBRIEF edits
+        // with a pre-existing matching approval must NOT fail (Greptile conf=2).
+        let approvalDiskOnly = false;
+        if (modified &&
+            approved !== null &&
+            renewed === null &&
+            approvalRecordRel !== null &&
+            !approvalInGitChange &&
+            existsSync(join(root, approvalRecordRel)) &&
+            isHumanApprovalStamp(approved.humanApproval)) {
+            const currentDigest = computeFileScopeDigest(normalizeFileScope(extractFileScope(payload)));
+            if (approved.fileScopeDigest === currentDigest) {
+                const baseRaw = discoveryBaseRef !== null ? readRepoFileAtRef(root, discoveryBaseRef, rel) : null;
+                if (baseRaw === null) {
+                    // New active xBRIEF with untracked matching approval → fail closed.
+                    approvalDiskOnly = true;
+                }
+                else {
+                    try {
+                        const basePayload = JSON.parse(baseRaw);
+                        const baseDigest = computeFileScopeDigest(normalizeFileScope(extractFileScope(basePayload)));
+                        // Only concurrent-rewrite when file-scope actually grew/changed.
+                        if (baseDigest !== currentDigest) {
+                            approvalDiskOnly = true;
+                        }
+                    }
+                    catch {
+                        approvalDiskOnly = true;
+                    }
+                }
+            }
+        }
+        const approvalRecordRewritten = approvalInGitChange || approvalDiskOnly;
+        const recordMatchesCurrent = approved !== null &&
+            !approvalRecordRewritten &&
+            approved.fileScopeDigest ===
+                computeFileScopeDigest(normalizeFileScope(extractFileScope(payload))) &&
+            isHumanApprovalStamp(approved.humanApproval);
+        // Same-PR approval rewrite without independent renewal is hard-fail expansion,
+        // not a soft missing-digest migration warning (Greptile P1).
+        if (approvalRecordRewritten && modified && renewed === null) {
+            const currentScope = normalizeFileScope(extractFileScope(payload));
+            findings.push({
+                xbriefRelPath: rel,
+                planId: planId ?? rel,
+                kind: "self-authorizing-scope-expansion",
+                expandedPaths: currentScope,
+                detail: "approved-scope record rewritten in the same change set as the active xBRIEF; " +
+                    "cannot self-authorize via concurrent approval rewrite",
+                remediation: "Record renewed human approval outside the implementation PR (or pass an " +
+                    "independent renewed stamp). Same-PR approval rewrites do not authorize expansion (#3145).",
+            });
+            continue;
+        }
+        const finding = evaluateOneScopeProvenance({
+            xbriefRelPath: rel,
+            currentPayload: payload,
+            approved,
+            xbriefModifiedInChangeSet: modified,
+            enforce,
+            renewedHumanApproval: renewed ?? (recordMatchesCurrent ? approved?.humanApproval : null),
+        });
+        if (finding === null)
+            continue;
+        // Soft migration: body-only edits (empty file_scope) without digest when !enforce.
+        // Non-empty scope without path-bound approval hard-fails (plan-id reset / expansion).
+        if (finding.kind === "active-xbrief-modified-without-digest" &&
+            !enforce &&
+            finding.expandedPaths.length === 0) {
+            softFindings.push(finding);
+            continue;
+        }
+        // Self-auth expansion and non-empty scope without digest always hard-fail
+        findings.push(finding);
+    }
+    if (findings.length === 0 && softFindings.length === 0) {
+        return {
+            exitCode: 0,
+            findings: [],
+            message: `verify_scope_provenance: clean (${activeEntries.length} active xBRIEF(s), ` +
+                `${changed.length} changed file(s)) (#3145).`,
+        };
+    }
+    if (findings.length === 0) {
+        // Warn-only migration discoveries
+        const body = softFindings
+            .map((f) => `  ${f.xbriefRelPath} (${f.planId})\n    kind: ${f.kind}\n    detail: ${f.detail}`)
+            .join("\n");
+        return {
+            exitCode: 0,
+            findings: softFindings,
+            message: `verify_scope_provenance: WARN ${softFindings.length} migration finding(s) ` +
+                `(not failing; pass --enforce to fail closed) (#3145).\n${body}`,
+        };
+    }
+    const all = [...findings, ...softFindings];
+    const body = all
+        .map((f) => `  ${f.xbriefRelPath} (${f.planId})\n` +
+        `    kind: ${f.kind}\n` +
+        `    expanded: ${f.expandedPaths.join(", ") || "(none)"}\n` +
+        `    detail: ${f.detail}\n` +
+        `    remediation: ${f.remediation}`)
+        .join("\n");
+    return {
+        exitCode: 1,
+        findings: all,
+        message: `verify_scope_provenance: ${findings.length} self-authorization violation(s) (#3145).\n${body}`,
+    };
+}
+/** Re-export builder for activation hook callers. */
+export { buildApprovedScopeRecord, writeApprovedScopeRecord } from "./digest.js";
+//# sourceMappingURL=evaluate.js.map

package/dist/scope-provenance/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * scope-provenance package surface (#3145).
+ */
+export { APPROVED_SCOPE_DIR, type ApprovedScopeRecord, approvedScopeDir, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
+export { evaluateOneScopeProvenance, evaluateScopeProvenance, resolveDefaultBaseRef, type ScopeProvenanceFinding, type ScopeProvenanceOptions, type ScopeProvenanceResult, type ScopeProvenanceViolationKind, } from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/scope-provenance/index.js

@@ -0,0 +1,6 @@
+/**
+ * scope-provenance package surface (#3145).
+ */
+export { APPROVED_SCOPE_DIR, approvedScopeDir, approvedScopeRecordPath, buildApprovedScopeRecord, computeFileScopeDigest, computeTextDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, writeApprovedScopeRecord, } from "./digest.js";
+export { evaluateOneScopeProvenance, evaluateScopeProvenance, resolveDefaultBaseRef, } from "./evaluate.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,96 @@
+/**
+ * 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 declare const SOFT_AGENTS_REBIND_EPIC = 2769;
+export declare const SOFT_AGENTS_REBIND_ISSUE = 3171;
+export declare const SOFT_AGENTS_REBIND_EVIDENCE_ISSUE = 3161;
+/** Stable marker substring present in every host-facing soft deposit. */
+export declare const SOFT_AGENTS_REBIND_MARKER = "Directive soft post-compact AGENTS re-bind (#3171 / #2769)";
+/** Managed OpenClaw skill directory name (doctor/init deposit). */
+export declare const OPENCLAW_SOFT_REBIND_SKILL_ID = "deft-directive-post-compact-rebind";
+/** Sentinel inside managed OpenClaw skill bodies for rewrite detection. */
+export declare 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 declare const SOFT_AGENTS_REBIND_CHECKLIST: readonly [{
+    readonly id: "reread-agents";
+    readonly text: string;
+}, {
+    readonly id: "confirm-learned";
+    readonly text: string;
+}, {
+    readonly id: "deposit-integrity";
+    readonly text: string;
+}, {
+    readonly id: "summary-not-sot";
+    readonly text: string;
+}, {
+    readonly id: "operational-ask-trap";
+    readonly text: string;
+}, {
+    readonly id: "mutation-vs-readonly";
+    readonly text: string;
+}];
+export type SoftAgentsRebindChecklistId = (typeof SOFT_AGENTS_REBIND_CHECKLIST)[number]["id"];
+/** Per-host soft deposit posture for docs + tests (#3171 matrix). */
+export type SoftRebindHost = "cursor" | "claude" | "grok" | "codex" | "openclaw";
+export interface SoftRebindHostRow {
+    readonly host: SoftRebindHost;
+    readonly family: string;
+    readonly hardCompact: "deposited" | "unsupported";
+    readonly softRebind: "required" | "docs-best-effort";
+    readonly wire: string;
+}
+/**
+ * Five-row host matrix (Cursor / Claude / Grok / Codex / OpenClaw).
+ * Docs and deposit tests must stay aligned with this table.
+ */
+export declare const SOFT_REBIND_HOST_MATRIX: readonly SoftRebindHostRow[];
+/** Forbidden soft wording — soft must never invite skipping mutation ritual. */
+export declare const SOFT_REBIND_FORBIDDEN_PHRASES: readonly ["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 declare function formatSoftAgentsRebindChecklist(options?: {
+    readonly includeHeader?: boolean;
+}): string;
+/**
+ * Append soft checklist to a hard compact re-arm (or SessionStart) message.
+ * Hard text stays first so existing recoveries remain discoverable.
+ */
+export declare function appendSoftAgentsRebindToMessage(hardMessage: string): string;
+/** True when text carries the soft re-bind deposit (tests + doctor). */
+export declare function isSoftAgentsRebindText(text: string): boolean;
+/** Soft cue events that should inject checklist without requiring a write tool. */
+export declare function isSoftAgentsRebindEvent(event: string): event is "session.start" | "session.compact";
+/**
+ * Whether this decision should carry soft injection on the host wire.
+ * Disabled / opt-out codes stay hard-message only.
+ */
+export declare function decisionCarriesSoftAgentsRebind(input: {
+    readonly event: string;
+    readonly code: string;
+}): boolean;
+/**
+ * Managed OpenClaw skill body generated from the same SoT checklist.
+ * Skill-shaped packaging; obligations identical to file-host soft text.
+ */
+export declare function formatOpenClawSoftRebindSkillMarkdown(): string;
+/** True when skill body is the managed #3171 soft re-bind deposit. */
+export declare function isManagedOpenClawSoftRebindSkill(body: string): boolean;
+/**
+ * Assert soft text never invites skipping mutation ritual (unit + deposit tests).
+ * Returns empty array when clean.
+ */
+export declare function softAgentsRebindForbiddenHits(text: string): string[];
+//# sourceMappingURL=compact-ritual.d.ts.map