@deftai/directive-core 0.104.0 → 0.105.0

package/dist/literal-acceptance/evaluate.js

@@ -3,7 +3,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
+import { captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, isProseDerivedRejection, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
 import { runLiteralAcceptanceCommands } from "./run.js";
 function asRecord(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
@@ -14,6 +14,24 @@ function asRecord(value) {
 function planOf(data) {
     return asRecord(data.plan);
 }
+/**
+ * Prose-derived rejections are advisory (#3484 / #3511). A scraper misread must
+ * not block completion, whether or not the plan states structured commands —
+ * blocking on a capture the extractor itself rejected is backwards. Rejections
+ * from structured fields (`swarm.verify_commands`, plan items, explicit metadata)
+ * keep blocking — those are real commands the author asked for.
+ */
+function partitionRejected(rejected) {
+    const blocking = [];
+    const advisory = [];
+    for (const r of rejected) {
+        if (isProseDerivedRejection(r))
+            advisory.push(r);
+        else
+            blocking.push(r);
+    }
+    return { blocking, advisory };
+}
 /**
  * Resolve commands + rejected ledger.
  * Stored first; when captureFromNarratives is true (default), also re-scan narratives
@@ -21,6 +39,16 @@ function planOf(data) {
  * (Greptile conf residual).
  */
 export function resolveLiteralAcceptanceDetailed(plan, options = {}) {
+    const raw = resolveRawLiteralAcceptance(plan, options);
+    const split = partitionRejected(raw.rejected);
+    return {
+        commands: raw.commands,
+        rejected: split.blocking,
+        advisoryRejected: split.advisory,
+        transcriptPromptSkipped: raw.transcriptPromptSkipped,
+    };
+}
+function resolveRawLiteralAcceptance(plan, options = {}) {
     const stored = readStoredLiteralAcceptanceDetailed(plan);
     if (options.captureFromNarratives === false) {
         return stored;
@@ -74,7 +102,11 @@ export function resolveLiteralAcceptanceDetailed(plan, options = {}) {
         rejectedSeen.add(k);
         rejected.push(r);
     }
-    return { commands, rejected };
+    return {
+        commands,
+        rejected,
+        transcriptPromptSkipped: captured.transcriptPromptSkipped,
+    };
 }
 /**
  * Resolve commands: stored first; optional narrative re-capture when empty.
@@ -82,6 +114,36 @@ export function resolveLiteralAcceptanceDetailed(plan, options = {}) {
 export function resolveLiteralAcceptanceCommands(plan, options = {}) {
     return [...resolveLiteralAcceptanceDetailed(plan, options).commands];
 }
+/**
+ * Marker that opens the #3484 advisory block. Consumers strip from here to the end
+ * before any free-text inspection of a literal-AC message: the block quotes refusal
+ * reasons that were explicitly demoted and must not be read back as blocking (#3497).
+ */
+export const LITERAL_ACCEPTANCE_ADVISORY_MARKER = "Literal acceptance advisory (#3484):";
+/** Render the #3484 advisory block (reported, never blocking). */
+export function formatLiteralAcceptanceAdvisory(advisory) {
+    if (advisory.length === 0)
+        return "";
+    return (`${LITERAL_ACCEPTANCE_ADVISORY_MARKER} ${advisory.length} ` +
+        `prose/fence-derived capture(s) were safety-rejected but do NOT block — ` +
+        `the extractor is not confident these are stated acceptance commands (#3511).\n` +
+        formatRejectedLedger(advisory));
+}
+/** Append the #3484 advisory block to a message tail. */
+export function appendLiteralAcceptanceAdvisory(message, advisory) {
+    const block = formatLiteralAcceptanceAdvisory(advisory);
+    if (block.length === 0)
+        return message;
+    return message.length > 0 ? `${message}\n${block}` : block;
+}
+/**
+ * Drop the #3484 advisory block from a rendered message.
+ * The block is always the tail, so an index cut is exact.
+ */
+export function stripLiteralAcceptanceAdvisory(message) {
+    const at = message.indexOf(LITERAL_ACCEPTANCE_ADVISORY_MARKER);
+    return at === -1 ? message : message.slice(0, at);
+}
 function appendRejectedNote(message, rejected) {
     const ledger = formatRejectedLedger(rejected);
     if (ledger.length === 0)
@@ -120,11 +182,17 @@ export function evaluateLiteralAcceptanceFromPlan(plan, options = {}) {
                 ledger +
                 (result.message.length > 0 ? `\n${result.message}` : "");
     }
+    // Prose/fence-derived rejections (#3484 / #3511) are reported, never blocking.
+    if (resolved.advisoryRejected.length > 0) {
+        message = appendLiteralAcceptanceAdvisory(message, resolved.advisoryRejected);
+    }
     const withRejected = {
         ...result,
         ok,
         code,
         rejected: resolved.rejected,
+        advisoryRejected: resolved.advisoryRejected,
+        transcriptPromptSkipped: resolved.transcriptPromptSkipped,
         message,
     };
     if (options.quiet === true && withRejected.ok) {

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

@@ -4,9 +4,9 @@
  * Capture exact stated shell commands at intake; run them verbatim before done.
  * Extends #973; survives ceremony dial rapid/minimal (#3214).
  */
-export { attachLiteralAcceptanceCommands, type CaptureLiteralAcceptanceResult, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
-export { type EvaluateLiteralAcceptanceOptions, evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, isLiteralAcceptanceRequiredAtCeremonyDepth, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, } from "./evaluate.js";
+export { attachLiteralAcceptanceCommands, type CaptureLiteralAcceptanceResult, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, hasStructuredAcceptanceCommands, isProseDerivedRejection, 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 { type CommandSafetyResult, evaluateCommandSafety, isExecutableLiteralSource, } from "./safety.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_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

@@ -4,9 +4,9 @@
  * Capture exact stated shell commands at intake; run them verbatim before done.
  * Extends #973; survives ceremony dial rapid/minimal (#3214).
  */
-export { attachLiteralAcceptanceCommands, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
-export { evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, isLiteralAcceptanceRequiredAtCeremonyDepth, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, } from "./evaluate.js";
+export { attachLiteralAcceptanceCommands, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, hasStructuredAcceptanceCommands, isProseDerivedRejection, 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 { evaluateCommandSafety, isExecutableLiteralSource, } from "./safety.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_REJECTED_METADATA_KEY, } from "./types.js";
 //# sourceMappingURL=index.js.map

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

@@ -10,10 +10,51 @@
  * mutations cannot ride an acceptance command (#3267 residual).
  */
 import type { LiteralAcceptanceSource } from "./types.js";
+/** One remediation when a command cannot fail (#3396). */
+export declare const NOOP_ACCEPTANCE_REMEDIATION = "acceptance commands must be able to fail; name a command that exercises the artifact";
+/** Capture/stamp outcome recorded on the acceptance event (#3396). */
+export declare const REJECTED_NOOP_OUTCOME: "rejected-noop";
+export type RejectedNoopOutcome = typeof REJECTED_NOOP_OUTCOME;
 export interface CommandSafetyResult {
     readonly ok: boolean;
     readonly reason: string | null;
+    /** Set when the command is a denylisted no-op (#3396). */
+    readonly outcome?: RejectedNoopOutcome;
 }
+/**
+ * Unconditional no-ops cannot be acceptance oracles (#3396).
+ * `test` with only constant args is a no-op; `test -f path` is an assertion.
+ */
+export declare function evaluateNoopDenylist(command: string): CommandSafetyResult;
+/** True when a refusal reason is the #3396 no-op remediation. */
+export declare function isNoopRefusalReason(reason: string | null | undefined): boolean;
+/**
+ * Capture records verbatim statement spans as fence@ / labeled@ / prompt@ / inline@.
+ * Metadata and plan.acceptance mirrors are not statement provenance.
+ */
+export declare function isVerbatimStatementSpan(sourceSpan: string | null | undefined): boolean;
+export type StampSourceRung = "stated" | "derived" | "project_floor";
+export interface StampAcceptanceCommand {
+    readonly command: string;
+    readonly source?: string;
+    readonly sourceSpan?: string | null;
+}
+export interface StampAcceptanceSafetyInput {
+    readonly commands: readonly StampAcceptanceCommand[];
+    readonly previousRung?: StampSourceRung | null;
+}
+export interface StampAcceptanceSafetyResult {
+    readonly ok: boolean;
+    readonly reason: string | null;
+    readonly outcome?: RejectedNoopOutcome;
+    readonly sourceRung: StampSourceRung;
+    readonly hasVerbatimStatementSpan: boolean;
+}
+/**
+ * Stamp-time no-op refuse + stated-only-with-span (#3396).
+ * A restamp cannot raise the rung to stated without a recorded statement span.
+ */
+export declare function evaluateStampAcceptanceSafety(input: StampAcceptanceSafetyInput): StampAcceptanceSafetyResult;
 /** Whether this provenance is allowed to spawn a shell (#3267). */
 export declare function isExecutableLiteralSource(source: LiteralAcceptanceSource | string): boolean;
 /**

package/dist/literal-acceptance/safety.js

@@ -43,8 +43,6 @@ const ALLOWED_FIRST_TOKENS = new Set([
     "yarn",
     "bun",
     "vitest",
-    "true",
-    "false",
 ]);
 /**
  * Exact wrapper subcommands that are verification-shaped (no scope/policy/scm/swarm
@@ -65,6 +63,128 @@ const ALLOWED_WRAPPER_SUBCOMMANDS = new Set([
  * `verify:` / `verify-` cover task verify:* family; bare `verify ` is the space form.
  */
 const ALLOWED_WRAPPER_PREFIXES = ["verify:", "verify-", "verify "];
+/** One remediation when a command cannot fail (#3396). */
+export const NOOP_ACCEPTANCE_REMEDIATION = "acceptance commands must be able to fail; name a command that exercises the artifact";
+/** Capture/stamp outcome recorded on the acceptance event (#3396). */
+export const REJECTED_NOOP_OUTCOME = "rejected-noop";
+/** First tokens that always succeed or always fail without exercising an artifact. */
+const NOOP_FIRST_TOKENS = new Set(["true", "false", ":", "echo", "printf"]);
+/** `test` operators that inspect a path (not a constant comparison). */
+const TEST_FILE_OPERATORS = new Set([
+    "-b",
+    "-c",
+    "-d",
+    "-e",
+    "-f",
+    "-g",
+    "-h",
+    "-k",
+    "-L",
+    "-p",
+    "-r",
+    "-S",
+    "-s",
+    "-t",
+    "-u",
+    "-w",
+    "-x",
+]);
+function firstTokenAndRest(trimmed) {
+    let end = 0;
+    while (end < trimmed.length && trimmed[end] !== " " && trimmed[end] !== "\t") {
+        end += 1;
+    }
+    return { first: trimmed.slice(0, end).toLowerCase(), rest: trimmed.slice(end).trim() };
+}
+function noopRefusal() {
+    return {
+        ok: false,
+        reason: NOOP_ACCEPTANCE_REMEDIATION,
+        outcome: REJECTED_NOOP_OUTCOME,
+    };
+}
+/**
+ * Unconditional no-ops cannot be acceptance oracles (#3396).
+ * `test` with only constant args is a no-op; `test -f path` is an assertion.
+ */
+export function evaluateNoopDenylist(command) {
+    if (typeof command !== "string") {
+        return { ok: true, reason: null };
+    }
+    const trimmed = command.trim();
+    if (trimmed.length === 0) {
+        return { ok: true, reason: null };
+    }
+    const { first, rest } = firstTokenAndRest(trimmed);
+    if (NOOP_FIRST_TOKENS.has(first)) {
+        return noopRefusal();
+    }
+    if (first === "exit" && rest.length === 0) {
+        return noopRefusal();
+    }
+    if (first === "test") {
+        const tokens = rest.length === 0 ? [] : rest.split(/\s+/);
+        if (!tokens.some((token) => TEST_FILE_OPERATORS.has(token))) {
+            return noopRefusal();
+        }
+    }
+    return { ok: true, reason: null };
+}
+/** True when a refusal reason is the #3396 no-op remediation. */
+export function isNoopRefusalReason(reason) {
+    return typeof reason === "string" && reason.includes("acceptance commands must be able to fail");
+}
+/**
+ * Capture records verbatim statement spans as fence@ / labeled@ / prompt@ / inline@.
+ * Metadata and plan.acceptance mirrors are not statement provenance.
+ */
+export function isVerbatimStatementSpan(sourceSpan) {
+    if (typeof sourceSpan !== "string" || sourceSpan.trim().length === 0) {
+        return false;
+    }
+    return /^(fence|labeled|prompt|inline)@/i.test(sourceSpan.trim());
+}
+function commandHasStatementProvenance(cmd) {
+    if (cmd.source !== undefined && cmd.source !== "task_statement") {
+        return false;
+    }
+    return isVerbatimStatementSpan(cmd.sourceSpan ?? null);
+}
+/**
+ * Stamp-time no-op refuse + stated-only-with-span (#3396).
+ * A restamp cannot raise the rung to stated without a recorded statement span.
+ */
+export function evaluateStampAcceptanceSafety(input) {
+    const hasVerbatimStatementSpan = input.commands.some(commandHasStatementProvenance);
+    let sourceRung;
+    if (input.commands.length === 0) {
+        sourceRung = input.previousRung ?? "project_floor";
+    }
+    else if (hasVerbatimStatementSpan) {
+        sourceRung = "stated";
+    }
+    else {
+        sourceRung = "derived";
+    }
+    for (const cmd of input.commands) {
+        const noop = evaluateNoopDenylist(cmd.command);
+        if (!noop.ok) {
+            return {
+                ok: false,
+                reason: noop.reason,
+                outcome: REJECTED_NOOP_OUTCOME,
+                sourceRung,
+                hasVerbatimStatementSpan,
+            };
+        }
+    }
+    return {
+        ok: true,
+        reason: null,
+        sourceRung,
+        hasVerbatimStatementSpan,
+    };
+}
 /** Whether this provenance is allowed to spawn a shell (#3267). */
 export function isExecutableLiteralSource(source) {
     return EXECUTABLE_LITERAL_SOURCES.includes(source);
@@ -81,6 +201,10 @@ export function evaluateCommandSafety(command) {
     if (trimmed.length > 500) {
         return { ok: false, reason: "command exceeds 500 characters" };
     }
+    const noop = evaluateNoopDenylist(trimmed);
+    if (!noop.ok) {
+        return noop;
+    }
     for (let i = 0; i < trimmed.length; i += 1) {
         const ch = trimmed[i];
         if (SHELL_META_CHARS.has(ch)) {

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

@@ -63,6 +63,14 @@ export interface LiteralAcceptanceGateResult {
     readonly runs: readonly LiteralAcceptanceRunResult[];
     /** Safety-rejected shell-shaped lines (fail-loud ledger; may be empty). */
     readonly rejected?: readonly RejectedLiteralCommand[];
+    /**
+     * Prose/fence/inline-derived rejections demoted to advisory (#3484 / #3511).
+     * Reported, never blocking — consumers MUST NOT read these back as a blocking
+     * ledger, and must not sniff the rendered message for their reasons (#3497).
+     */
+    readonly advisoryRejected?: readonly RejectedLiteralCommand[];
+    /** Prompt lines skipped inside a transcript-shaped fence (#3511). */
+    readonly transcriptPromptSkipped?: number;
 }
 /** Metadata key for operator-visible rejected command ledger (#3267). */
 export declare const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY: "literal_acceptance_rejected";

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

@@ -1,8 +1,10 @@
 import type { RunGhFn } from "../pr-protected-issues/types.js";
 export type OutputStream = "stdout" | "stderr" | "none";
+export type OrphanKind = "shipped" | "unresolved";
 export interface OrphanActiveBrief {
     readonly path: string;
     readonly reason: string;
+    readonly kind: OrphanKind;
 }
 export interface EvaluateResult {
     readonly code: 0 | 1 | 2;
@@ -15,11 +17,15 @@ export interface EvaluateOptions {
     readonly repo?: string | null;
     readonly runGh?: RunGhFn;
     readonly skipGh?: boolean;
+    /** When set, scan only active/running briefs that reference this issue (#3429). */
+    readonly issue?: number | null;
 }
 /**
- * Pure evaluator for orphaned active/running xBRIEF detection (#2321).
+ * Pure evaluator for orphaned active/running xBRIEF detection (#2321 / #3429).
  * Fails when active/ briefs with plan.status==running reference only closed
  * issues and/or a merged PR — the stop-at:pr-open orphan signature.
+ * Pass `issue` to scan one origin after merge. Confirmed shipped prints
+ * scope:complete; unresolved lookup still exits 1 with a retry remediation.
  */
 export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
 //# sourceMappingURL=evaluate.d.ts.map

package/dist/orphan-active/evaluate.js

@@ -137,55 +137,127 @@ function fetchPrMerged(ref, runGh) {
         return null;
     }
 }
-function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh) {
+const PASS = { orphaned: false, reason: null, kind: null };
+function shipped(reason) {
+    return { orphaned: true, reason, kind: "shipped" };
+}
+function unresolved(reason) {
+    return { orphaned: true, reason, kind: "unresolved" };
+}
+function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh, selectedIssue) {
+    if (selectedIssue !== null) {
+        // Confirmed closed origin is shipped even if a linked PR lookup fails.
+        const selectedRef = issueRefs.find((ref) => ref.number === selectedIssue);
+        const selectedState = selectedRef === undefined ? null : resolveIssueState(selectedRef, projectRoot, runGh, skipGh);
+        if (selectedState === "closed") {
+            return shipped(`issue #${selectedIssue} is closed`);
+        }
+        for (const pr of prRefs) {
+            if (skipGh) {
+                return unresolved(`linked PR #${pr.number} state could not be resolved`);
+            }
+            const merged = fetchPrMerged(pr, runGh);
+            if (merged === true) {
+                return shipped(`linked PR #${pr.number} is merged`);
+            }
+            if (merged === null) {
+                return unresolved(`linked PR #${pr.number} state could not be resolved`);
+            }
+        }
+        // --issue N is one origin: sibling open/unknown must not mask it (#3429).
+        if (selectedRef !== undefined) {
+            if (selectedState === null) {
+                return unresolved(`issue #${selectedIssue} state could not be resolved`);
+            }
+            return PASS;
+        }
+        const issueStates = issueRefs.map((ref) => ({
+            ref,
+            state: resolveIssueState(ref, projectRoot, runGh, skipGh),
+        }));
+        const unknownIssue = issueStates.find((row) => row.state === null);
+        if (unknownIssue !== undefined) {
+            return unresolved(`issue #${unknownIssue.ref.number} state could not be resolved`);
+        }
+        if (issueStates.some((row) => row.state === "closed")) {
+            return shipped("all referenced issues are closed");
+        }
+        if (prRefs.length > 0 && skipGh) {
+            return unresolved(`linked PR #${prRefs[0]?.number} state could not be resolved`);
+        }
+        return PASS;
+    }
     for (const pr of prRefs) {
         if (skipGh) {
             continue;
         }
         const merged = fetchPrMerged(pr, runGh);
         if (merged === true) {
-            return { orphaned: true, reason: `linked PR #${pr.number} is merged` };
+            return shipped(`linked PR #${pr.number} is merged`);
         }
     }
     if (issueRefs.length === 0) {
-        return { orphaned: false, reason: null };
+        return PASS;
     }
     let resolved = 0;
     for (const ref of issueRefs) {
         const state = resolveIssueState(ref, projectRoot, runGh, skipGh);
         if (state === null) {
-            return { orphaned: false, reason: null };
+            return PASS;
         }
         resolved += 1;
         if (state !== "closed") {
-            return { orphaned: false, reason: null };
+            return PASS;
         }
     }
     if (resolved > 0) {
-        return { orphaned: true, reason: "all referenced issues are closed" };
+        return shipped("all referenced issues are closed");
     }
-    return { orphaned: false, reason: null };
+    return PASS;
 }
-function formatRefusal(orphans, projectRoot) {
-    const lines = [
-        `verify:orphan-active: ${orphans.length} active/running xBRIEF${orphans.length === 1 ? "" : "s"} look shipped but still consume WIP (project_root=${projectRoot}).`,
-        "  Remediation: move each brief out of active/ with lifecycle ownership:",
-        "    task scope:complete -- xbrief/active/<file>.xbrief.json",
-        "    task scope:cancel -- xbrief/active/<file>.xbrief.json   # when abandoning",
-        "  For stop-at:pr-open workers the orchestrator owns post-merge complete/cancel;",
-        "  for drive-to:merge-ready workers scope:complete is part of the worker unit (#2321).",
-        "  Or run task swarm:finalize-cohort / task swarm:complete-cohort after cohort merge.",
-        "  Offending briefs:",
-    ];
+function briefReferencesIssue(issues, issue) {
+    return issues.some((ref) => ref.number === issue);
+}
+function formatRefusal(orphans, projectRoot, issueFilter) {
+    const shippedOrphans = orphans.filter((orphan) => orphan.kind === "shipped");
+    const unresolvedOrphans = orphans.filter((orphan) => orphan.kind === "unresolved");
+    const noun = orphans.length === 1 ? "" : "s";
+    let headline;
+    if (unresolvedOrphans.length > 0 && shippedOrphans.length === 0) {
+        headline = `verify:orphan-active: ${unresolvedOrphans.length} active/running xBRIEF${unresolvedOrphans.length === 1 ? "" : "s"} have unresolved GitHub state (cannot confirm shipped) (project_root=${projectRoot}).`;
+    }
+    else if (shippedOrphans.length > 0 && unresolvedOrphans.length === 0) {
+        headline = `verify:orphan-active: ${shippedOrphans.length} active/running xBRIEF${shippedOrphans.length === 1 ? "" : "s"} look shipped but still consume WIP (project_root=${projectRoot}).`;
+    }
+    else {
+        headline = `verify:orphan-active: ${orphans.length} active/running xBRIEF${noun} failed the after-merge check (project_root=${projectRoot}).`;
+    }
+    const lines = [headline];
+    if (shippedOrphans.length > 0) {
+        lines.push("  Remediation: move each confirmed-shipped brief out of active/ with lifecycle ownership:");
+        for (const orphan of shippedOrphans) {
+            lines.push(`    task scope:complete -- ${orphan.path}`);
+        }
+        lines.push("    task scope:cancel -- xbrief/active/<file>.xbrief.json   # when abandoning", "  For stop-at:pr-open workers the orchestrator owns post-merge complete/cancel;", "  for drive-to:merge-ready workers scope:complete is part of the worker unit (#2321 / #3429).", "  Or run task swarm:finalize-cohort / task swarm:complete-cohort after cohort merge.");
+    }
+    if (unresolvedOrphans.length > 0) {
+        const retry = issueFilter === null
+            ? "task verify:orphan-active"
+            : `task verify:orphan-active -- --issue ${issueFilter}`;
+        lines.push("  Remediation: retry the GitHub lookup (auth, rate-limit, network, skipGh) then re-run:", `    ${retry}`, "  Do not run task scope:complete until the origin is confirmed closed or the linked PR is confirmed merged.");
+    }
+    lines.push("  Offending briefs:");
     for (const orphan of orphans) {
         lines.push(`    - ${orphan.path} (${orphan.reason})`);
     }
     return lines.join("\n");
 }
 /**
- * Pure evaluator for orphaned active/running xBRIEF detection (#2321).
+ * Pure evaluator for orphaned active/running xBRIEF detection (#2321 / #3429).
  * Fails when active/ briefs with plan.status==running reference only closed
  * issues and/or a merged PR — the stop-at:pr-open orphan signature.
+ * Pass `issue` to scan one origin after merge. Confirmed shipped prints
+ * scope:complete; unresolved lookup still exits 1 with a retry remediation.
  */
 export function evaluate(projectRoot, options = {}) {
     const root = resolve(projectRoot);
@@ -238,24 +310,30 @@ export function evaluate(projectRoot, options = {}) {
             orphans: [],
         };
     }
+    const issueFilter = options.issue ?? null;
     const orphans = [];
     for (const brief of listActiveRunningBriefs(root)) {
         const { issues, prs } = collectGithubRefs(brief.plan, defaultRepo);
+        // --issue N is one origin: briefs that name that issue. PR-only briefs stay on the unscoped scan (#3429).
+        if (issueFilter !== null && !briefReferencesIssue(issues, issueFilter)) {
+            continue;
+        }
         if (issues.length === 0 && prs.length === 0) {
             continue;
         }
-        const assessment = assessOrphanSignature(issues, prs, root, runGh, skipGh);
-        if (assessment.orphaned && assessment.reason !== null) {
+        const assessment = assessOrphanSignature(issues, prs, root, runGh, skipGh, issueFilter);
+        if (assessment.orphaned && assessment.reason !== null && assessment.kind !== null) {
             orphans.push({
                 path: relBriefPath(brief.path, root),
                 reason: assessment.reason,
+                kind: assessment.kind,
             });
         }
     }
     if (orphans.length > 0) {
         return {
             code: 1,
-            message: formatRefusal(orphans, root),
+            message: formatRefusal(orphans, root, issueFilter),
             stream: "stderr",
             orphans,
         };
@@ -264,9 +342,10 @@ export function evaluate(projectRoot, options = {}) {
         return { code: 0, message: "", stream: "none", orphans: [] };
     }
     const scanned = listActiveRunningBriefs(root).length;
+    const issueNote = issueFilter === null ? "" : ` for issue #${issueFilter}`;
     return {
         code: 0,
-        message: `verify:orphan-active: no orphaned active/running xBRIEFs ` +
+        message: `verify:orphan-active: no orphaned active/running xBRIEFs${issueNote} ` +
             `(scanned ${scanned} running brief${scanned === 1 ? "" : "s"} in active/).`,
         stream: "stdout",
         orphans: [],

package/dist/platform/platform-capabilities.js

@@ -72,10 +72,9 @@ export function classifyIdentityKind(options) {
 function isCloudHeadless(environ) {
     if (envTruthy(environ, "CURSOR_AGENT"))
         return true;
-    if (envTruthy(environ, "GROK_BUILD"))
-        return true;
+    // GROK_BUILD / DEFT_AGENT_RUNTIME=grok-build identify a local TUI, not CI (#3469).
     const runtime = (environ.DEFT_AGENT_RUNTIME ?? "").trim().toLowerCase();
-    if (runtime === "grok-build" || runtime === "cloud" || runtime === "headless")
+    if (runtime === "cloud" || runtime === "headless")
         return true;
     if (envTruthy(environ, "GITHUB_ACTIONS") || envTruthy(environ, "BUILDKITE"))
         return true;

package/dist/policy/base-branch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed plan.policy.baseBranch (#3388).
+ *
+ * Integration-branch source for the shared branch-sync detector. Distinct from
+ * deliveryBranch (dest). Unset or invalid baseBranch resolves to dest so sync
+ * is a no-op. origin/develop is never identity; it may only emit a hint.
+ */
+import { type GitRunner } from "../session/git.js";
+export declare const FIELD_BASE_BRANCH = "plan.policy.baseBranch";
+export declare const FIELD_BASE_BRANCH_CLI_ALIAS = "baseBranch";
+/** Nudge only — never used as dest or source identity (#3388 / #3377 Q1). */
+export declare const ORIGIN_DEVELOP_HINT = "origin/develop exists; set plan.policy.baseBranch if this repo uses an integration branch";
+export type BaseBranchSource = "typed" | "equals-dest" | "default-on-error";
+export interface BaseBranchResult {
+    readonly branch: string;
+    readonly dest: string;
+    readonly source: BaseBranchSource;
+    readonly typed: boolean;
+    readonly error: string | null;
+    readonly developHint: string | null;
+}
+/**
+ * Resolve plan.policy.baseBranch (#3388).
+ *
+ * Unset or invalid values equal dest (deliveryBranch). origin/develop is never
+ * substituted as the source.
+ */
+export declare function resolveBaseBranch(projectRoot: string, runGit?: GitRunner): BaseBranchResult;
+export interface BaseBranchPolicyField {
+    readonly name: string;
+    readonly current: string;
+    readonly default: string;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=baseBranch` (#3388). */
+export declare function inspectBaseBranch(_data: Record<string, unknown> | null, projectRoot?: string): BaseBranchPolicyField;
+//# sourceMappingURL=base-branch.d.ts.map