@deftai/directive-core 0.108.0 → 0.109.0

package/dist/intake/reconcile-issues.js

@@ -3,12 +3,12 @@ import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSy
 import { join, resolve } from "node:path";
 import { assertProjectionContained, assertWriteTargetSafe, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { missingEnvelopeMessage, stampExistingEnvelopes } from "../lifecycle/brief-envelope.js";
 import { call } from "../scm/call.js";
 import { updateDecomposedChildBackReferences } from "../scope/decomposed-refs.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 import { FOLDER_ALLOWED_STATUSES } from "../vbrief-validate/constants.js";
-import { LEGACY_INFO_ROOT_KEY, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 export const LIFECYCLE_FOLDERS = [
     "proposed",
     "pending",
@@ -713,14 +713,13 @@ export function applyLifecycleFixes(vbriefDir, report, projectRoot = null) {
         plan.status = terminalStatus;
         const stamp = utcNowIso();
         // Stamp `updated` into whichever info envelope the file already uses (#2346).
-        // Canonical v0.8 briefs use `xBRIEFInfo`; stamping `vBRIEFInfo` unconditionally
-        // appended a stray, version-less `vBRIEFInfo` block that then failed
-        // `vbrief:validate` ('vBRIEFInfo.version' must be one of ..., got 'undefined').
-        // Legacy briefs (or files without either envelope) keep the `vBRIEFInfo` key.
-        const infoKey = MIGRATED_INFO_ROOT_KEY in data ? MIGRATED_INFO_ROOT_KEY : LEGACY_INFO_ROOT_KEY;
-        const info = (data[infoKey] ?? {});
-        data[infoKey] = info;
-        info.updated = stamp;
+        // A file carrying neither envelope is already invalid; creating one here hid
+        // that cause behind a manufactured version-less `vBRIEFInfo` (#3933), so the
+        // sweep now refuses it by name and leaves the artifact in place.
+        if (stampExistingEnvelopes(data, stamp).length === 0) {
+            failures.push(missingEnvelopeMessage(relPath));
+            continue;
+        }
         plan.updated = stamp;
         propagateItemStatus(plan.items, terminalStatus, stamp);
         try {
@@ -780,12 +779,13 @@ export function repairCompletedStatusDrift(vbriefDir, drift, projectRoot = null)
             continue;
         }
         const stamp = utcNowIso();
+        // Same envelope policy as the closed-issue sweep above (#3933).
+        if (stampExistingEnvelopes(data, stamp).length === 0) {
+            failures.push(missingEnvelopeMessage(entry.rel_path));
+            continue;
+        }
         plan.status = "completed";
         plan.updated = stamp;
-        const infoKey = MIGRATED_INFO_ROOT_KEY in data ? MIGRATED_INFO_ROOT_KEY : LEGACY_INFO_ROOT_KEY;
-        const info = (data[infoKey] ?? {});
-        data[infoKey] = info;
-        info.updated = stamp;
         propagateItemStatus(plan.items, "completed", stamp);
         try {
             writeFileSync(src, `${JSON.stringify(data, null, 2)}\n`, "utf8");

package/dist/lifecycle/brief-envelope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared document-envelope policy for lifecycle mutators (#3933).
+ *
+ * A brief carries one document envelope: `xBRIEFInfo` on canonical v0.8
+ * artifacts, `vBRIEFInfo` on legacy v0.6 ones. A mutator stamps whichever
+ * envelope the artifact already has and creates none. Creating one on a v0.8
+ * brief appends a version-less `vBRIEFInfo`, and `validateVbriefSchema`
+ * resolves `vBRIEFInfo` first, so the manufactured block wins and the brief the
+ * mutator just wrote fails validation (#2346 / #2862 / #3933).
+ */
+import { LEGACY_INFO_ROOT_KEY, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
+export type BriefEnvelopeKey = typeof MIGRATED_INFO_ROOT_KEY | typeof LEGACY_INFO_ROOT_KEY;
+/** Envelope keys in canonical order: v0.8 first, legacy v0.6 second. */
+export declare const BRIEF_ENVELOPE_KEYS: readonly BriefEnvelopeKey[];
+/** Envelope keys the artifact already carries as JSON objects. */
+export declare function presentEnvelopeKeys(data: Record<string, unknown>): BriefEnvelopeKey[];
+/**
+ * Stamp `updated` on every envelope the artifact already carries; create none.
+ * Returns the stamped keys so a caller can refuse an envelope-less artifact by
+ * name instead of manufacturing one.
+ */
+export declare function stampExistingEnvelopes(data: Record<string, unknown>, nowIso: string): BriefEnvelopeKey[];
+/** Refusal naming both accepted envelopes, for a caller-supplied subject (#3933). */
+export declare function missingEnvelopeMessage(subject: string): string;
+//# sourceMappingURL=brief-envelope.d.ts.map

package/dist/lifecycle/brief-envelope.js

@@ -0,0 +1,42 @@
+/**
+ * Shared document-envelope policy for lifecycle mutators (#3933).
+ *
+ * A brief carries one document envelope: `xBRIEFInfo` on canonical v0.8
+ * artifacts, `vBRIEFInfo` on legacy v0.6 ones. A mutator stamps whichever
+ * envelope the artifact already has and creates none. Creating one on a v0.8
+ * brief appends a version-less `vBRIEFInfo`, and `validateVbriefSchema`
+ * resolves `vBRIEFInfo` first, so the manufactured block wins and the brief the
+ * mutator just wrote fails validation (#2346 / #2862 / #3933).
+ */
+import { LEGACY_INFO_ROOT_KEY, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
+/** Envelope keys in canonical order: v0.8 first, legacy v0.6 second. */
+export const BRIEF_ENVELOPE_KEYS = [
+    MIGRATED_INFO_ROOT_KEY,
+    LEGACY_INFO_ROOT_KEY,
+];
+/** Envelope keys the artifact already carries as JSON objects. */
+export function presentEnvelopeKeys(data) {
+    return BRIEF_ENVELOPE_KEYS.filter((key) => {
+        const env = data[key];
+        return typeof env === "object" && env !== null && !Array.isArray(env);
+    });
+}
+/**
+ * Stamp `updated` on every envelope the artifact already carries; create none.
+ * Returns the stamped keys so a caller can refuse an envelope-less artifact by
+ * name instead of manufacturing one.
+ */
+export function stampExistingEnvelopes(data, nowIso) {
+    const stamped = presentEnvelopeKeys(data);
+    for (const key of stamped) {
+        data[key].updated = nowIso;
+    }
+    return stamped;
+}
+/** Refusal naming both accepted envelopes, for a caller-supplied subject (#3933). */
+export function missingEnvelopeMessage(subject) {
+    return (`${subject} carries neither \`${MIGRATED_INFO_ROOT_KEY}\` (v0.8) nor ` +
+        `\`${LEGACY_INFO_ROOT_KEY}\` (v0.6) -- malformed. Lifecycle mutators refuse ` +
+        "rather than create one (#3933).");
+}
+//# sourceMappingURL=brief-envelope.js.map

package/dist/lifecycle/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./brief-envelope.js";
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
 export * from "./completed-write-guard.js";

package/dist/lifecycle/index.js

@@ -1,3 +1,4 @@
+export * from "./brief-envelope.js";
 export * from "./completed-consistency.js";
 export * from "./completed-tracked-on-delivery.js";
 export * from "./completed-write-guard.js";

package/dist/literal-acceptance/evaluate.js

@@ -189,16 +189,25 @@ export function evaluateLiteralAcceptanceFromPlan(plan, options = {}) {
     // Rejected stated commands are fail-closed for completion (#3267 Greptile conf residual).
     // A safety-rejected shell-shaped acceptance line is not "optional diagnostic" — operators
     // must promote a safe alternative or remove the stated command from the task statement.
+    const mergedRejected = [];
+    const seenRejected = new Set();
+    for (const row of [...(result.rejected ?? []), ...resolved.rejected]) {
+        const key = `${row.command}\0${row.reason}`;
+        if (seenRejected.has(key))
+            continue;
+        seenRejected.add(key);
+        mergedRejected.push(row);
+    }
     let ok = result.ok;
     let code = result.code;
-    let message = appendRejectedNote(result.message, resolved.rejected);
-    if (resolved.rejected.length > 0) {
+    let message = appendRejectedNote(result.message, mergedRejected);
+    if (mergedRejected.length > 0) {
         ok = false;
         if (code === 0)
             code = 1;
-        const ledger = formatRejectedLedger(resolved.rejected);
+        const ledger = formatRejectedLedger(mergedRejected);
         message =
-            `Literal acceptance-command gate FAILED (#3267): ${resolved.rejected.length} ` +
+            `Literal acceptance-command gate FAILED (#3267): ${mergedRejected.length} ` +
                 `safety-rejected stated command(s) block completion until resolved ` +
                 `(promote a safe alternative or remove from the task statement).\n` +
                 ledger +
@@ -212,7 +221,7 @@ export function evaluateLiteralAcceptanceFromPlan(plan, options = {}) {
         ...result,
         ok,
         code,
-        rejected: resolved.rejected,
+        rejected: mergedRejected,
         advisoryRejected: resolved.advisoryRejected,
         transcriptPromptSkipped: resolved.transcriptPromptSkipped,
         message,

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

@@ -6,7 +6,7 @@
  */
 export { attachLiteralAcceptanceCommands, type CaptureLiteralAcceptanceResult, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, hasStructuredAcceptanceCommands, INLINE_PROSE_MENTION_REASON, isInlineProseMention, isProseDerivedRejection, readNotAcceptanceCommands, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
 export { appendLiteralAcceptanceAdvisory, type EvaluateLiteralAcceptanceOptions, evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, formatLiteralAcceptanceAdvisory, isLiteralAcceptanceRequiredAtCeremonyDepth, LITERAL_ACCEPTANCE_ADVISORY_MARKER, type ResolvedLiteralAcceptance, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, stripLiteralAcceptanceAdvisory, } from "./evaluate.js";
-export { defaultLiteralAcceptanceRunner, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
+export { defaultLiteralAcceptanceRunner, isSafetyRefusalRun, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
 export { type CommandSafetyResult, evaluateCommandSafety, evaluateNoopDenylist, evaluateStampAcceptanceSafety, isExecutableLiteralSource, isNoopRefusalReason, isVerbatimStatementSpan, NOOP_ACCEPTANCE_REMEDIATION, REJECTED_NOOP_OUTCOME, type RejectedNoopOutcome, type StampAcceptanceCommand, type StampAcceptanceSafetyInput, type StampAcceptanceSafetyResult, type StampSourceRung, } from "./safety.js";
 export { EXECUTABLE_LITERAL_SOURCES, LITERAL_ACCEPTANCE_METADATA_KEY, LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL, LITERAL_ACCEPTANCE_NOT_COMMANDS_METADATA_KEY, LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY, type LiteralAcceptanceCommand, type LiteralAcceptanceGateResult, type LiteralAcceptanceRunner, type LiteralAcceptanceRunResult, type LiteralAcceptanceSource, type RejectedLiteralCommand, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/literal-acceptance/index.js

@@ -6,7 +6,7 @@
  */
 export { attachLiteralAcceptanceCommands, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, hasStructuredAcceptanceCommands, INLINE_PROSE_MENTION_REASON, isInlineProseMention, isProseDerivedRejection, readNotAcceptanceCommands, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
 export { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, formatLiteralAcceptanceAdvisory, isLiteralAcceptanceRequiredAtCeremonyDepth, LITERAL_ACCEPTANCE_ADVISORY_MARKER, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, stripLiteralAcceptanceAdvisory, } from "./evaluate.js";
-export { defaultLiteralAcceptanceRunner, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
+export { defaultLiteralAcceptanceRunner, isSafetyRefusalRun, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
 export { evaluateCommandSafety, evaluateNoopDenylist, evaluateStampAcceptanceSafety, isExecutableLiteralSource, isNoopRefusalReason, isVerbatimStatementSpan, NOOP_ACCEPTANCE_REMEDIATION, REJECTED_NOOP_OUTCOME, } from "./safety.js";
 export { EXECUTABLE_LITERAL_SOURCES, LITERAL_ACCEPTANCE_METADATA_KEY, LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL, LITERAL_ACCEPTANCE_NOT_COMMANDS_METADATA_KEY, LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY, } from "./types.js";
 //# sourceMappingURL=index.js.map

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

@@ -6,6 +6,8 @@
  * Self-chosen verification is supplementary — this gate only runs stored literals.
  */
 import type { LiteralAcceptanceCommand, LiteralAcceptanceGateResult, LiteralAcceptanceRunner, LiteralAcceptanceRunResult } from "./types.js";
+/** True when the row is a pre-execution safety refusal, not a product measurement (#3615). */
+export declare function isSafetyRefusalRun(run: Pick<LiteralAcceptanceRunResult, "exitCode" | "detail">): boolean;
 /** Default shell runner: exact command string via platform shell. */
 export declare function defaultLiteralAcceptanceRunner(input: {
     readonly command: string;

package/dist/literal-acceptance/run.js

@@ -9,6 +9,13 @@ import { spawnSync } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
 import { isInlineProseMention } from "./capture.js";
 import { evaluateCommandSafety, isExecutableLiteralSource } from "./safety.js";
+/** True when the row is a pre-execution safety refusal, not a product measurement (#3615). */
+export function isSafetyRefusalRun(run) {
+    return run.exitCode === 2 && /^refused:\s*/i.test(run.detail);
+}
+function safetyRefusalReason(run) {
+    return run.detail.replace(/^refused:\s*/i, "").trim();
+}
 /** Default shell runner: exact command string via platform shell. */
 export function defaultLiteralAcceptanceRunner(input) {
     // Windows: cmd.exe /c; POSIX: shell true uses sh -c. Exact string preserved.
@@ -173,6 +180,7 @@ export function runLiteralAcceptanceCommands(commands, options) {
         };
     }
     const runs = [];
+    const rejected = [];
     for (const cmd of executable) {
         if (typeof cmd.command !== "string" || cmd.command.trim().length === 0) {
             return {
@@ -181,9 +189,18 @@ export function runLiteralAcceptanceCommands(commands, options) {
                 message: "Literal acceptance-command gate config error: empty command entry (#3267)",
                 commands,
                 runs,
+                rejected: rejected.length > 0 ? rejected : undefined,
             };
         }
-        runs.push(runLiteralAcceptanceCommand(cmd, options));
+        const run = runLiteralAcceptanceCommand(cmd, options);
+        runs.push(run);
+        if (isSafetyRefusalRun(run)) {
+            rejected.push({
+                command: run.command,
+                reason: safetyRefusalReason(run),
+                sourceSpan: cmd.sourceSpan ?? null,
+            });
+        }
     }
     const failed = runs.filter((r) => !r.ok);
     if (failed.length === 0) {
@@ -213,6 +230,7 @@ export function runLiteralAcceptanceCommands(commands, options) {
             lines.join("\n"),
         commands,
         runs,
+        rejected: rejected.length > 0 ? rejected : undefined,
     };
 }
 function truncate(s, max) {

package/dist/orphan-active/candidate-scope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Candidate diff ownership for the merge-chokepoint orphan run (#3893).
+ *
+ * The unscoped sweep enumerates every running brief under `active/`. Composed
+ * on `check:merge` that gives one stranded brief merge authority over every
+ * open PR, and N stranded briefs make N single-brief lifecycle PRs mutually
+ * unmergeable — each leaves the other orphan. The pre-merge run cannot see the
+ * residue its own candidate is about to create either: that candidate's linked
+ * PR still reads `merged_at: null` while the gate runs.
+ *
+ * Scoping the merge run to the candidate's own diff removes the coupling
+ * without touching the detector. Repo-wide truth stays enforced at the
+ * delivery tip (HEAD on the delivery line falls back to the full sweep) and
+ * after merge (`--issue N`, #3429).
+ */
+import { type GitRunner } from "../session/git.js";
+export type CandidateScope = {
+    readonly kind: "diff";
+    /** Ref the candidate was diffed against (e.g. `origin/master`). */
+    readonly baseRef: string;
+    /** Absolute, platform-normalized brief paths this candidate owns. */
+    readonly paths: ReadonlySet<string>;
+} | {
+    readonly kind: "sweep";
+    /** Why this run stayed repo-wide; always printed with the verdict. */
+    readonly reason: string;
+};
+export interface CandidateScopeOptions {
+    /** Explicit base ref; defaults to `origin/<deliveryBranch>` then the branch. */
+    readonly baseRef?: string | null;
+    readonly runGit?: GitRunner;
+}
+/**
+ * One comparable form for a git path and a readdir path.
+ *
+ * Only the directory is canonicalized: the file itself may be a deletion in
+ * the candidate diff and no longer exist on disk.
+ */
+export declare function normalizeScopePath(path: string): string;
+/**
+ * Base ref for the candidate diff: explicit override, else `origin/<branch>`,
+ * else the local delivery branch. Null when none resolves.
+ */
+export declare function resolveCandidateBaseRef(projectRoot: string, override: string | null | undefined, runGit: GitRunner): string | null;
+/**
+ * Brief paths under `activeDir` that the candidate's own diff touches.
+ *
+ * Falls back to the repo-wide sweep — never to a narrower scan — when git,
+ * the base ref, or the diff is unavailable, so the flag cannot silently
+ * shrink what a merge gate looks at.
+ */
+export declare function resolveCandidateScope(projectRoot: string, activeDir: string, options?: CandidateScopeOptions): CandidateScope;
+//# sourceMappingURL=candidate-scope.d.ts.map

package/dist/orphan-active/candidate-scope.js

@@ -0,0 +1,157 @@
+/**
+ * Candidate diff ownership for the merge-chokepoint orphan run (#3893).
+ *
+ * The unscoped sweep enumerates every running brief under `active/`. Composed
+ * on `check:merge` that gives one stranded brief merge authority over every
+ * open PR, and N stranded briefs make N single-brief lifecycle PRs mutually
+ * unmergeable — each leaves the other orphan. The pre-merge run cannot see the
+ * residue its own candidate is about to create either: that candidate's linked
+ * PR still reads `merged_at: null` while the gate runs.
+ *
+ * Scoping the merge run to the candidate's own diff removes the coupling
+ * without touching the detector. Repo-wide truth stays enforced at the
+ * delivery tip (HEAD on the delivery line falls back to the full sweep) and
+ * after merge (`--issue N`, #3429).
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
+import { defaultGitRunner } from "../session/git.js";
+/** Symlink-resolved path, or the input when it cannot be resolved. */
+function realpathOrSelf(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return path;
+        }
+    }
+}
+/**
+ * Canonical directory: symlinks resolved, then precomposed. Git reports the
+ * canonical worktree root while the lifecycle root keeps the caller's
+ * spelling, and git precomposes Unicode (`core.precomposeunicode`) while some
+ * filesystems hand `readdir` the decomposed form.
+ */
+function canonicalDir(path) {
+    return realpathOrSelf(resolve(path)).normalize("NFC");
+}
+/**
+ * One comparable form for a git path and a readdir path.
+ *
+ * Only the directory is canonicalized: the file itself may be a deletion in
+ * the candidate diff and no longer exist on disk.
+ */
+export function normalizeScopePath(path) {
+    const abs = resolve(path);
+    const full = join(canonicalDir(dirname(abs)), basename(abs)).normalize("NFC");
+    return process.platform === "win32" ? full.toLowerCase() : full;
+}
+function sweep(reason) {
+    return { kind: "sweep", reason };
+}
+/**
+ * Split `-z` git output. NUL-delimited paths are never C-quoted, so a brief
+ * whose name git would quote (non-ASCII, quotes, backslashes) still compares
+ * equal to the readdir path instead of silently falling outside the candidate
+ * scope. `GitRunner` returns `-z` output as latin1 bytes, so decode to UTF-8.
+ */
+function splitNulPaths(stdout) {
+    return stdout
+        .split("\0")
+        .map((entry) => Buffer.from(entry, "latin1").toString("utf8"))
+        .filter((entry) => entry.length > 0);
+}
+function refExists(cwd, ref, runGit) {
+    return runGit(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).code === 0;
+}
+/**
+ * Base ref for the candidate diff: explicit override, else `origin/<branch>`,
+ * else the local delivery branch. Null when none resolves.
+ */
+export function resolveCandidateBaseRef(projectRoot, override, runGit) {
+    const explicit = override?.trim() ?? "";
+    if (explicit.length > 0) {
+        return refExists(projectRoot, explicit, runGit) ? explicit : null;
+    }
+    const branch = resolveDeliveryBranch(projectRoot, runGit).branch;
+    for (const candidate of [`origin/${branch}`, branch]) {
+        if (refExists(projectRoot, candidate, runGit)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Brief paths under `activeDir` that the candidate's own diff touches.
+ *
+ * Falls back to the repo-wide sweep — never to a narrower scan — when git,
+ * the base ref, or the diff is unavailable, so the flag cannot silently
+ * shrink what a merge gate looks at.
+ */
+export function resolveCandidateScope(projectRoot, activeDir, options = {}) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const root = resolve(projectRoot);
+    const topLevel = runGit(root, ["rev-parse", "--show-toplevel"]);
+    if (topLevel.code !== 0) {
+        return sweep("not a git worktree, so no candidate diff exists");
+    }
+    const gitRoot = topLevel.stdout.trim();
+    if (gitRoot.length === 0) {
+        return sweep("git worktree root could not be resolved");
+    }
+    const baseRef = resolveCandidateBaseRef(root, options.baseRef, runGit);
+    if (baseRef === null) {
+        const requested = options.baseRef?.trim() ?? "";
+        return sweep(requested.length > 0
+            ? `base ref '${requested}' not found; fetch it or pass a resolvable --base-ref`
+            : "no delivery base ref found (no origin/<deliveryBranch> or local branch); fetch it or pass --base-ref");
+    }
+    // HEAD at or behind the delivery line is the delivery tip itself, not a
+    // candidate: keep repo-wide truth there.
+    if (runGit(root, ["merge-base", "--is-ancestor", "HEAD", baseRef]).code === 0) {
+        return sweep(`HEAD is on the ${baseRef} delivery line, so this run is the delivery-tip check`);
+    }
+    const mergeBase = runGit(root, ["merge-base", "HEAD", baseRef]);
+    if (mergeBase.code !== 0) {
+        return sweep(`could not compute the merge base with ${baseRef}`);
+    }
+    const base = mergeBase.stdout.trim();
+    if (base.length === 0) {
+        return sweep(`merge base with ${baseRef} is empty`);
+    }
+    // Canonicalize both sides before the relative: a symlinked checkout or an
+    // unequal Unicode spelling of the same root would otherwise read as `..`
+    // and restore the repo-wide sweep.
+    const activeRel = relative(canonicalDir(gitRoot), canonicalDir(activeDir)).replace(/\\/g, "/");
+    if (activeRel.length === 0 || activeRel.startsWith("..")) {
+        return sweep("active/ is outside the git worktree");
+    }
+    // Diff against the working tree, not HEAD: a locally activated brief is a
+    // pre-commit `task check` candidate too.
+    const changed = runGit(gitRoot, ["diff", "--name-only", "-z", base, "--", activeRel]);
+    if (changed.code !== 0) {
+        return sweep(`could not diff active/ against ${baseRef}`);
+    }
+    const untracked = runGit(gitRoot, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+        "--",
+        activeRel,
+    ]);
+    if (untracked.code !== 0) {
+        return sweep("could not list untracked briefs under active/");
+    }
+    const paths = new Set();
+    for (const rel of [...splitNulPaths(changed.stdout), ...splitNulPaths(untracked.stdout)]) {
+        paths.add(normalizeScopePath(resolve(gitRoot, rel)));
+    }
+    return { kind: "diff", baseRef, paths };
+}
+//# sourceMappingURL=candidate-scope.js.map

package/dist/orphan-active/evaluate.d.ts

@@ -1,4 +1,5 @@
 import type { RunGhFn } from "../pr-protected-issues/types.js";
+import type { GitRunner } from "../session/git.js";
 export type OutputStream = "stdout" | "stderr" | "none";
 export type OrphanKind = "shipped" | "unresolved";
 export interface OrphanActiveBrief {
@@ -22,12 +23,24 @@ export interface OrphanActiveBasis {
     readonly elapsedMs: number;
     readonly budgetMs: number;
 }
+/** What merge-chokepoint scoping decided for this run (#3893). */
+export interface OrphanActiveScopeSummary {
+    readonly kind: "diff" | "sweep";
+    /** Ref the candidate diff was taken against; null on a sweep. */
+    readonly baseRef: string | null;
+    /** Why the run stayed repo-wide; null on a candidate diff. */
+    readonly reason: string | null;
+    /** Running briefs left unevaluated because this candidate does not own them. */
+    readonly skipped: number;
+}
 export interface EvaluateResult {
     readonly code: 0 | 1 | 2;
     readonly message: string;
     readonly stream: OutputStream;
     readonly orphans: readonly OrphanActiveBrief[];
     readonly basis: OrphanActiveBasis;
+    /** Null unless `changedOnly` was requested. */
+    readonly scope: OrphanActiveScopeSummary | null;
 }
 export interface EvaluateOptions {
     readonly quiet?: boolean;
@@ -38,6 +51,15 @@ export interface EvaluateOptions {
     readonly issue?: number | null;
     /** Monotonic clock seam so basis ages and budget checks are testable. */
     readonly nowMs?: () => number;
+    /**
+     * Merge-chokepoint scoping (#3893): evaluate only active/running briefs the
+     * candidate's own diff touches. Ignored with `issue`, which is already one
+     * origin. Falls back to the repo-wide sweep when the base ref is unresolvable.
+     */
+    readonly changedOnly?: boolean;
+    /** Base ref for `changedOnly`; defaults to `origin/<deliveryBranch>`. */
+    readonly baseRef?: string | null;
+    readonly runGit?: GitRunner;
 }
 /**
  * Pure evaluator for orphaned active/running xBRIEF detection (#2321 / #3429).
@@ -51,6 +73,11 @@ export interface EvaluateOptions {
  * one complete, fail-closed open-issue inventory and stays fail-open on
  * unknown so offline work is not network-authorized. A cache hit is honoured
  * only inside `ISSUE_CACHE_MAX_AGE_MS`, and every verdict reports its basis.
+ *
+ * `changedOnly` is the merge-chokepoint form (#3893): only briefs the
+ * candidate's own diff touches are evaluated, so a brief stranded by another
+ * merge cannot fail this candidate. It falls back to the repo-wide sweep at
+ * the delivery tip and whenever the base ref is unresolvable.
  */
 export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
 //# sourceMappingURL=evaluate.d.ts.map