@deftai/directive-core 0.106.0 → 0.108.0

package/dist/intake/platform-capabilities.js

@@ -1,4 +1,5 @@
 /** Minimal runtime capability probe for github_auth_modes (#1557a / #1784). */
+import { hasExplicitHostGhSelection, probeManagedRuntime, RUNTIME_REASON_CI_MARKER, RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS, RUNTIME_REASON_CURSOR_SANDBOX_MARKER, RUNTIME_REASON_EXPLICIT_HOST_GH, RUNTIME_REASON_MANAGED_RUNTIME_PROBE, RUNTIME_REASON_NO_RUNTIME_MARKER, } from "../platform/cursor-managed-runtime.js";
 export const RUNTIME_MODE_LOCAL_UNSANDBOXED = "local-unsandboxed";
 export const RUNTIME_MODE_CURSOR_NATIVE_SANDBOX = "cursor-native-sandbox";
 export const RUNTIME_MODE_CLOUD_HEADLESS = "cloud-headless";
@@ -11,24 +12,52 @@ const TRUTHY = new Set(["1", "true", "yes", "on"]);
 function isTruthy(value) {
     return value !== undefined && TRUTHY.has(value.trim().toLowerCase());
 }
-function classifyRuntimeMode(environ = process.env) {
+/**
+ * Classify the execution runtime.
+ *
+ * Ordering is load-bearing (#3859):
+ *   1. CI markers, so a CI runner is never reclassified by a Cursor signal.
+ *   2. A positive Cursor managed-runtime read, above every other Cursor signal.
+ *   3. Cursor native sandbox.
+ *   4. A Cursor marker with no managed read leaves the runtime AMBIGUOUS. Only
+ *      an explicit operator/dispatcher selection resolves it to local; absent
+ *      that, the verdict is unchanged from before #3859.
+ */
+function classifyRuntimeMode(environ = process.env, options = {}) {
     for (const key of ["GROK_BUILD", "GITHUB_ACTIONS", "CI", "BUILDKITE", "DEFT_AGENT_RUNTIME"]) {
         if (isTruthy(environ[key])) {
-            return RUNTIME_MODE_CLOUD_HEADLESS;
+            return { mode: RUNTIME_MODE_CLOUD_HEADLESS, reason: RUNTIME_REASON_CI_MARKER };
         }
     }
+    const managedProbe = options.managedRuntimeProbe ?? probeManagedRuntime;
+    if (managedProbe(environ).verdict === "managed") {
+        return {
+            mode: RUNTIME_MODE_CLOUD_HEADLESS,
+            reason: RUNTIME_REASON_MANAGED_RUNTIME_PROBE,
+        };
+    }
     if (isTruthy(environ.CURSOR_SANDBOX) || isTruthy(environ.CURSOR_SANDBOX_LANDLOCK_STATUS)) {
-        return RUNTIME_MODE_CURSOR_NATIVE_SANDBOX;
+        return {
+            mode: RUNTIME_MODE_CURSOR_NATIVE_SANDBOX,
+            reason: RUNTIME_REASON_CURSOR_SANDBOX_MARKER,
+        };
     }
     if (isTruthy(environ.CURSOR_AGENT) || isTruthy(environ.CURSOR_COMPOSER)) {
-        return RUNTIME_MODE_CLOUD_HEADLESS;
+        if (hasExplicitHostGhSelection(environ)) {
+            return { mode: RUNTIME_MODE_LOCAL_UNSANDBOXED, reason: RUNTIME_REASON_EXPLICIT_HOST_GH };
+        }
+        return {
+            mode: RUNTIME_MODE_CLOUD_HEADLESS,
+            reason: RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS,
+        };
     }
-    return RUNTIME_MODE_LOCAL_UNSANDBOXED;
+    return { mode: RUNTIME_MODE_LOCAL_UNSANDBOXED, reason: RUNTIME_REASON_NO_RUNTIME_MARKER };
 }
-export function probeRuntimeCapabilities(environ = process.env) {
-    return { runtimeMode: classifyRuntimeMode(environ) };
+export function probeRuntimeCapabilities(environ = process.env, options = {}) {
+    const { mode, reason } = classifyRuntimeMode(environ, options);
+    return { runtimeMode: mode, runtimeModeReason: reason };
 }
-export function getPlatformCapabilities() {
-    return probeRuntimeCapabilities();
+export function getPlatformCapabilities(options = {}) {
+    return probeRuntimeCapabilities(process.env, options);
 }
 //# sourceMappingURL=platform-capabilities.js.map

package/dist/lifecycle/completed-tracked-on-delivery.d.ts

@@ -35,7 +35,33 @@ export interface EvaluateCompletedTrackedOptions {
     readonly runGit?: GitRunner;
     /** Test seam: override issue state resolution. */
     readonly resolveIssueState?: (ref: IssueRef) => "open" | "closed" | null;
+    /**
+     * Progress hook (#3673). Fired after tip listing and after the batch
+     * blob read so a CLI can announce an up-front count only when elapsed
+     * time crosses a measured threshold.
+     */
+    readonly onProgress?: (event: CompletedTrackedProgress) => void;
+    /** Test seam: override wall clock for progress elapsedMs. */
+    readonly now?: () => number;
+}
+/** Default silence window so a ~2s batch read does not emit progress noise. */
+export declare const COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS = 3000;
+/**
+ * Up-front count floor (#3673 Greptile P2). Listing is cheap; the batch
+ * read is the remaining stall. Announce the blob count after listing
+ * (before `cat-file --batch`) when the corpus is large enough that a
+ * silent wait is the old DONE-path failure mode. Fixture-sized runs stay
+ * quiet unless the duration threshold is also crossed.
+ */
+export declare const COMPLETED_TRACKED_PROGRESS_MIN_BLOBS = 32;
+export interface CompletedTrackedProgress {
+    readonly phase: "listed" | "read";
+    readonly terminalCount: number;
+    readonly nonterminalCount: number;
+    readonly elapsedMs: number;
 }
+export declare function shouldAnnounceProgress(elapsedMs: number, thresholdMs?: number): boolean;
+export declare function shouldAnnounceUpFrontCount(terminalCount: number, nonterminalCount: number, minBlobs?: number): boolean;
 /**
  * Resolve the git tip to inspect for tracked completed/cancelled land.
  * Prefers origin/<deliveryBranch> when present.

package/dist/lifecycle/completed-tracked-on-delivery.js

@@ -16,7 +16,7 @@ import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveL
 import { collectGithubRefs } from "../orphan-active/refs.js";
 import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
 import { defaultRunGh } from "../pr-protected-issues/gh.js";
-import { defaultGitRunner } from "../session/git.js";
+import { defaultGitRunner, showBlobsBatch } from "../session/git.js";
 import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
 import { resolveRepo } from "../triage/queue/repo.js";
 /** Lifecycle folders scanned for local "known origin" xBRIEFs. */
@@ -31,6 +31,22 @@ export const LOCAL_ORIGIN_FOLDERS = [
 export const TIP_NONTERMINAL_FOLDERS = ["proposed", "pending", "active"];
 /** Terminal tip folders that satisfy the land rule. */
 export const TIP_TERMINAL_FOLDERS = ["completed", "cancelled"];
+/** Default silence window so a ~2s batch read does not emit progress noise. */
+export const COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS = 3_000;
+/**
+ * Up-front count floor (#3673 Greptile P2). Listing is cheap; the batch
+ * read is the remaining stall. Announce the blob count after listing
+ * (before `cat-file --batch`) when the corpus is large enough that a
+ * silent wait is the old DONE-path failure mode. Fixture-sized runs stay
+ * quiet unless the duration threshold is also crossed.
+ */
+export const COMPLETED_TRACKED_PROGRESS_MIN_BLOBS = 32;
+export function shouldAnnounceProgress(elapsedMs, thresholdMs = COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS) {
+    return elapsedMs >= thresholdMs;
+}
+export function shouldAnnounceUpFrontCount(terminalCount, nonterminalCount, minBlobs = COMPLETED_TRACKED_PROGRESS_MIN_BLOBS) {
+    return terminalCount + nonterminalCount >= minBlobs;
+}
 function readJson(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -223,13 +239,6 @@ function listTreePaths(projectRoot, tip, prefixes, runGit) {
         .map((line) => line.trim().replace(/\\/g, "/"))
         .filter((line) => line.length > 0 && hasArtifactSuffix(line));
 }
-function showBlob(projectRoot, tip, path, runGit) {
-    const result = runGit(projectRoot, ["show", `${tip}:${path}`]);
-    if (result.code !== 0) {
-        return null;
-    }
-    return result.stdout;
-}
 function terminalPrefixes() {
     const out = [];
     for (const root of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
@@ -248,11 +257,11 @@ function nonterminalPrefixes() {
     }
     return out;
 }
-function issuesFromBlobPaths(projectRoot, tip, paths, defaultRepo, runGit, originPrefix) {
+function issuesFromBlobBodies(paths, bodies, defaultRepo, originPrefix) {
     const hits = [];
     for (const path of paths) {
-        const body = showBlob(projectRoot, tip, path, runGit);
-        if (body === null) {
+        const body = bodies.get(path);
+        if (body === undefined || body === null) {
             continue;
         }
         let parsed;
@@ -375,17 +384,31 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
             tip: null,
         };
     }
+    const startedAt = (options.now ?? Date.now)();
+    const emitProgress = (phase, terminalCount, nonterminalCount) => {
+        options.onProgress?.({
+            phase,
+            terminalCount,
+            nonterminalCount,
+            elapsedMs: (options.now ?? Date.now)() - startedAt,
+        });
+    };
     const localHits = scanLocalOrigins(root, defaultRepo);
     const tipNonterminalPaths = listTreePaths(root, tip, nonterminalPrefixes(), runGit);
-    const tipNonterminalHits = issuesFromBlobPaths(root, tip, tipNonterminalPaths, defaultRepo, runGit, `tip:${tip}`);
-    let originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
     // Delivery tip only — the land invariant is post-merge tip truth (#3264 AC).
     // Lifecycle PRs that commit completed/ on a feature branch are not expected
     // to satisfy this gate until merge; run the verb with --tip HEAD when
     // validating an in-flight land PR. The gate is a standalone verify verb
     // (not wired into check:consumer) so product PRs are not deadlocked.
     const tipTerminalPaths = listTreePaths(root, tip, terminalPrefixes(), runGit);
-    const tipTerminalHits = issuesFromBlobPaths(root, tip, tipTerminalPaths, defaultRepo, runGit, `tip:${tip}`);
+    emitProgress("listed", tipTerminalPaths.length, tipNonterminalPaths.length);
+    // One process for every tip artifact. Issue identity still comes from
+    // parsed plan.references / plan.metadata["x-tracking"] — never the path.
+    const tipBodies = showBlobsBatch(root, tip, [...tipNonterminalPaths, ...tipTerminalPaths], runGit);
+    emitProgress("read", tipTerminalPaths.length, tipNonterminalPaths.length);
+    const tipNonterminalHits = issuesFromBlobBodies(tipNonterminalPaths, tipBodies, defaultRepo, `tip:${tip}`);
+    let originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    const tipTerminalHits = issuesFromBlobBodies(tipTerminalPaths, tipBodies, defaultRepo, `tip:${tip}`);
     const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
     const issueFilter = options.issue ?? null;
     if (issueFilter !== null) {

package/dist/lifecycle/completed-write-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Refuse newly added completed/ blobs that bypass runTransition (#3679).
+ *
+ * Historical corpus is advisory (doctor). New work in the change set is hard
+ * (verify:completed-write-guard). Does not read completionProvenance and does
+ * not change verify:completed-tracked.
+ *
+ * Disk reads are capped at COMPLETED_WRITE_GUARD_MAX_BYTES so a huge
+ * contributor-controlled completed/ add fails through the guard instead of
+ * exhausting memory on the required gate path.
+ */
+export type CompletedWriteGuardCode = 0 | 1 | 2;
+export interface CompletedWriteGuardFinding {
+    readonly relPath: string;
+    readonly detail: string;
+}
+export interface CompletedWriteGuardResult {
+    readonly code: CompletedWriteGuardCode;
+    readonly message: string;
+    readonly findings: readonly CompletedWriteGuardFinding[];
+}
+export interface CompletedWriteGuardOptions {
+    readonly baseRef?: string;
+    /** Inject added repo-relative POSIX paths (skips git). */
+    readonly addedFiles?: readonly string[];
+    /** Inject payloads: relPath -> raw JSON. */
+    readonly payloads?: ReadonlyMap<string, string>;
+}
+/**
+ * In-repo completed xBRIEFs average ~5.5 KiB and peak near 44 KiB.
+ * 1 MiB is ~23× that peak and still refuses a multi-hundred-MB add
+ * before the bytes are loaded.
+ */
+export declare const COMPLETED_WRITE_GUARD_MAX_BYTES = 1048576;
+/**
+ * Hard check: newly added completed/ artifacts must show runTransition evidence.
+ */
+export declare function evaluateCompletedWriteGuard(projectRoot: string, options?: CompletedWriteGuardOptions): CompletedWriteGuardResult;
+export interface CompletedWriteCorpusResult {
+    readonly findings: readonly CompletedWriteGuardFinding[];
+    readonly scanned: number;
+}
+/**
+ * Corpus scan for doctor: artifacts without transition evidence.
+ * Caller marks these advisory so historical pre-stamp files do not red doctor.
+ */
+export declare function scanCompletedWriteCorpus(projectRoot: string): CompletedWriteCorpusResult;
+//# sourceMappingURL=completed-write-guard.d.ts.map

package/dist/lifecycle/completed-write-guard.js

@@ -0,0 +1,373 @@
+/**
+ * Refuse newly added completed/ blobs that bypass runTransition (#3679).
+ *
+ * Historical corpus is advisory (doctor). New work in the change set is hard
+ * (verify:completed-write-guard). Does not read completionProvenance and does
+ * not change verify:completed-tracked.
+ *
+ * Disk reads are capped at COMPLETED_WRITE_GUARD_MAX_BYTES so a huge
+ * contributor-controlled completed/ add fails through the guard instead of
+ * exhausting memory on the required gate path.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { GitCommandError, GitNotFoundError } from "../encoding/git.js";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
+import { hasTransitionWrite, LEFTOVER_LAND_PR_REMEDIATION } from "../scope/lifecycle-write.js";
+import { resolveDefaultBaseRef, unquoteGitPath } from "../scope-provenance/evaluate.js";
+/**
+ * In-repo completed xBRIEFs average ~5.5 KiB and peak near 44 KiB.
+ * 1 MiB is ~23× that peak and still refuses a multi-hundred-MB add
+ * before the bytes are loaded.
+ */
+export const COMPLETED_WRITE_GUARD_MAX_BYTES = 1_048_576;
+const COMPLETED_REL_RE = /^(?:xbrief|vbrief)\/completed\/[^/]+$/;
+function normalizeRepoRelPath(raw) {
+    return raw.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isCompletedArtifactRel(relPath) {
+    const n = normalizeRepoRelPath(relPath);
+    if (!COMPLETED_REL_RE.test(n)) {
+        return false;
+    }
+    const base = n.split("/").pop() ?? "";
+    return hasArtifactSuffix(base);
+}
+function parsePlan(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return null;
+        }
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return null;
+        }
+        return plan;
+    }
+    catch {
+        return null;
+    }
+}
+function gitEnv(projectRoot) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    env.GIT_CEILING_DIRECTORIES = dirname(resolve(projectRoot));
+    return env;
+}
+function git(args, projectRoot) {
+    const result = spawnSync("git", args, {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: gitEnv(projectRoot),
+    });
+    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)}`);
+    }
+    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();
+    if (status !== 0 && stderr.length > 0) {
+        return { status, stdout: `${result.stdout ?? ""}\n${stderr}` };
+    }
+    return { status, stdout: result.stdout ?? "" };
+}
+function addedPathsFromNameStatus(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        const t = line.replace(/\r$/, "").trim();
+        if (t.length === 0) {
+            continue;
+        }
+        const parts = t.split("\t");
+        const status = parts[0] ?? "";
+        if (status.startsWith("A")) {
+            const path = parts[1];
+            if (path !== undefined) {
+                out.push(unquoteGitPath(path));
+            }
+        }
+        else if (status.startsWith("R")) {
+            const dest = parts[2] ?? parts[1];
+            if (dest !== undefined) {
+                out.push(unquoteGitPath(dest));
+            }
+        }
+    }
+    return out;
+}
+function discoverAddedFiles(projectRoot, baseRef) {
+    const inside = git(["rev-parse", "--is-inside-work-tree"], projectRoot);
+    if (inside.status !== 0) {
+        throw new GitCommandError("not a git working tree");
+    }
+    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)");
+        }
+        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`);
+    }
+    const out = new Set();
+    const range = resolved.includes("...") ? resolved : `${resolved}...HEAD`;
+    const committed = git(["diff", "--name-status", "--diff-filter=AR", range], projectRoot);
+    if (committed.status !== 0) {
+        const detail = committed.stdout.trim() || `git diff ${range} exited ${String(committed.status)}`;
+        throw new GitCommandError(`committed change-set unavailable for '${range}': ${detail}. ` +
+            "Pass --base-ref to a merge-base ancestor of HEAD.");
+    }
+    for (const p of addedPathsFromNameStatus(committed.stdout)) {
+        out.add(normalizeRepoRelPath(p));
+    }
+    const vsHead = git(["diff", "--name-status", "--diff-filter=AR", "HEAD"], projectRoot);
+    if (vsHead.status !== 0) {
+        const detail = vsHead.stdout.trim() || `git diff HEAD exited ${String(vsHead.status)}`;
+        throw new GitCommandError(`working-tree change-set unavailable: ${detail}`);
+    }
+    for (const p of addedPathsFromNameStatus(vsHead.stdout)) {
+        out.add(normalizeRepoRelPath(p));
+    }
+    const untracked = git(["ls-files", "--others", "--exclude-standard"], projectRoot);
+    if (untracked.status !== 0) {
+        const detail = untracked.stdout.trim() || `git ls-files exited ${String(untracked.status)}`;
+        throw new GitCommandError(`untracked change-set unavailable: ${detail}`);
+    }
+    for (const line of untracked.stdout.split("\n")) {
+        const p = normalizeRepoRelPath(unquoteGitPath(line));
+        if (p.length > 0) {
+            out.add(p);
+        }
+    }
+    return [...out];
+}
+function readPayload(projectRoot, relPath, payloads) {
+    const n = normalizeRepoRelPath(relPath);
+    const injected = payloads?.get(n);
+    if (injected !== undefined) {
+        if (injected.length > COMPLETED_WRITE_GUARD_MAX_BYTES) {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ artifact is ${String(injected.length)} bytes; ` +
+                    `exceeds the ${String(COMPLETED_WRITE_GUARD_MAX_BYTES)}-byte read limit`,
+            };
+        }
+        return { kind: "ok", raw: injected };
+    }
+    const parts = n.split("/").filter((part) => part.length > 0 && part !== ".");
+    let abs = resolve(projectRoot);
+    let st;
+    for (const part of parts) {
+        if (part === "..") {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ path escapes project root; refuse without following`,
+            };
+        }
+        abs = join(abs, part);
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            return { kind: "missing" };
+        }
+        if (st.isSymbolicLink()) {
+            return {
+                kind: "unsafe",
+                detail: `${n}: completed/ path contains a symlink; refuse without following`,
+            };
+        }
+    }
+    if (st === undefined || !st.isFile()) {
+        return {
+            kind: "unsafe",
+            detail: `${n}: completed/ add is not a regular file; refuse without reading`,
+        };
+    }
+    if (st.size > COMPLETED_WRITE_GUARD_MAX_BYTES) {
+        return {
+            kind: "unsafe",
+            detail: `${n}: completed/ artifact is ${String(st.size)} bytes; ` +
+                `exceeds the ${String(COMPLETED_WRITE_GUARD_MAX_BYTES)}-byte read limit`,
+        };
+    }
+    try {
+        return { kind: "ok", raw: readFileSync(abs, "utf8") };
+    }
+    catch {
+        return { kind: "missing" };
+    }
+}
+/**
+ * Hard check: newly added completed/ artifacts must show runTransition evidence.
+ */
+export function evaluateCompletedWriteGuard(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    let added;
+    try {
+        if (options.addedFiles !== undefined) {
+            added = options.addedFiles.map(normalizeRepoRelPath);
+        }
+        else {
+            const inside = git(["rev-parse", "--is-inside-work-tree"], root);
+            if (inside.status !== 0 || inside.stdout.trim() !== "true") {
+                return {
+                    code: 0,
+                    findings: [],
+                    message: "verify_completed_write_guard: skipped -- not a git working tree.",
+                };
+            }
+            let baseRef = options.baseRef ?? "";
+            if (baseRef.length === 0 || baseRef === "HEAD") {
+                const resolved = resolveDefaultBaseRef(root);
+                if (resolved === null) {
+                    return {
+                        code: 2,
+                        findings: [],
+                        message: "verify_completed_write_guard: no merge-base ref found " +
+                            "(origin/master|main, DEFT_BASE_REF, or GITHUB_BASE_REF). " +
+                            "Pass --base-ref. Unguarded completed/ adds cannot be skipped.",
+                    };
+                }
+                baseRef = resolved;
+            }
+            added = discoverAddedFiles(root, baseRef);
+        }
+    }
+    catch (err) {
+        if (err instanceof GitNotFoundError) {
+            return {
+                code: 2,
+                findings: [],
+                message: "verify_completed_write_guard: '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();
+            if (msg.includes("not a git repository") ||
+                msg.includes("outside repository") ||
+                msg.includes("not a git working tree")) {
+                return {
+                    code: 0,
+                    findings: [],
+                    message: `verify_completed_write_guard: skipped -- not a git working tree (${err.message}).`,
+                };
+            }
+            return {
+                code: 2,
+                findings: [],
+                message: `verify_completed_write_guard: git failed -- ${err.message}`,
+            };
+        }
+        throw err;
+    }
+    const findings = [];
+    for (const rel of added) {
+        if (!isCompletedArtifactRel(rel)) {
+            continue;
+        }
+        const payload = readPayload(root, rel, options.payloads);
+        if (payload.kind === "missing") {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ but unreadable`,
+            });
+            continue;
+        }
+        if (payload.kind === "unsafe") {
+            findings.push({
+                relPath: rel,
+                detail: payload.detail,
+            });
+            continue;
+        }
+        const plan = parsePlan(payload.raw);
+        if (plan === null) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ with unreadable plan`,
+            });
+            continue;
+        }
+        if (!hasTransitionWrite(plan)) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: added under completed/ without a runTransition write`,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        return {
+            code: 0,
+            findings: [],
+            message: "verify_completed_write_guard: clean -- no unguarded completed/ adds",
+        };
+    }
+    return {
+        code: 1,
+        findings,
+        message: `verify_completed_write_guard: ${findings.length} unguarded completed/ add(s) (#3679).\n` +
+            findings.map((f) => `  - ${f.detail}`).join("\n") +
+            `\n${LEFTOVER_LAND_PR_REMEDIATION}`,
+    };
+}
+function listCompletedArtifactRels(projectRoot) {
+    const out = [];
+    for (const dirName of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
+        const completedDir = join(projectRoot, dirName, "completed");
+        if (!existsSync(completedDir)) {
+            continue;
+        }
+        let names = [];
+        try {
+            names = readdirSync(completedDir).filter((n) => hasArtifactSuffix(n));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            out.push(`${dirName}/completed/${name}`);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Corpus scan for doctor: artifacts without transition evidence.
+ * Caller marks these advisory so historical pre-stamp files do not red doctor.
+ */
+export function scanCompletedWriteCorpus(projectRoot) {
+    const findings = [];
+    const rels = listCompletedArtifactRels(projectRoot);
+    for (const rel of rels) {
+        const payload = readPayload(resolve(projectRoot), rel, undefined);
+        if (payload.kind !== "ok") {
+            continue;
+        }
+        const plan = parsePlan(payload.raw);
+        if (plan === null) {
+            continue;
+        }
+        if (!hasTransitionWrite(plan)) {
+            findings.push({
+                relPath: rel,
+                detail: `${rel}: completed/ artifact has no runTransition write (historical advisory)`,
+            });
+        }
+    }
+    return { findings, scanned: rels.length };
+}
+//# sourceMappingURL=completed-write-guard.js.map

package/dist/lifecycle/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
+export * from "./completed-write-guard.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/lifecycle/index.js

@@ -1,5 +1,6 @@
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
+export * from "./completed-write-guard.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/literal-acceptance/capture.d.ts

@@ -9,6 +9,17 @@
  * so distinct execution contexts are not collapsed.
  */
 import type { LiteralAcceptanceCommand, RejectedLiteralCommand } from "./types.js";
+/** Reason stamped when an inline backtick is recorded as a mention, not AC (#3721). */
+export declare const INLINE_PROSE_MENTION_REASON = "inline backtick in prose is a mention, not a stated acceptance command (#3721)";
+/**
+ * True when a capture-only row came from an inline backtick in prose (#3721).
+ * Those mentions are not stated acceptance commands. Labeled, prompt, and fence
+ * spans stay stated.
+ */
+export declare function isInlineProseMention(cmd: {
+    readonly source?: string;
+    readonly sourceSpan?: string | null;
+}): boolean;
 /** Result of capture including the operator-visible rejected ledger. */
 export interface CaptureLiteralAcceptanceResult {
     readonly commands: readonly LiteralAcceptanceCommand[];
@@ -57,6 +68,11 @@ export declare function isProseDerivedRejection(rejected: RejectedLiteralCommand
  * prose-derived rejections no longer depends on this (#3511).
  */
 export declare function hasStructuredAcceptanceCommands(plan: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Command strings the operator recorded as not acceptance commands (#3721).
+ * Listing a string here dispositions a capture without asserting it is AC.
+ */
+export declare function readNotAcceptanceCommands(plan: Record<string, unknown> | null | undefined): ReadonlySet<string>;
 /** Format rejected ledger for CLI / complete-gate messages. */
 export declare function formatRejectedLedger(rejected: readonly RejectedLiteralCommand[]): string;
 //# sourceMappingURL=capture.d.ts.map