@deftai/directive-core 0.104.0 → 0.106.0

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/orchestration/judgment-policy.d.ts

@@ -2,6 +2,19 @@ export declare const GATE_CLASSES: Set<string>;
 export declare const GATE_TIERS: Set<string>;
 export declare const GATE_MATCH_PREDICATES: Set<string>;
 export declare const GATE_MATCH_STATES: Set<string>;
+/** ADR-005 / #3434 Story 1 -- author-stamped marker vocabulary. */
+export declare const DESIGN_CRITIQUE_GATE_ID = "design-critique";
+/** List-visible mirror; this is what judgmentGates predicates match. */
+export declare const DESIGN_CRITIQUE_MARKER_LABEL = "design-critique:mechanism-shaped";
+/** Authoritative body-text field in the #1423 triage write-back comment. */
+export declare const DESIGN_CRITIQUE_MARKER_FIELD = "mechanism-shaped: true";
+/**
+ * Clearance line shape (ADR-005). Presence and shape only -- a non-empty
+ * because-clause is required; its semantic content is never evaluated.
+ */
+export declare const DESIGN_CRITIQUE_CLEARANCE_SHAPE: RegExp;
+/** True when `line` has clearance presence+shape. Never scores the reason text. */
+export declare function designCritiqueClearanceShapeOk(line: string): boolean;
 export interface JudgmentGate {
     readonly gate_id: string;
     readonly gate_class: string;

package/dist/orchestration/judgment-policy.js

@@ -7,6 +7,21 @@ export const GATE_CLASSES = new Set(["mechanical", "declared"]);
 export const GATE_TIERS = new Set(["auto", "review", "block"]);
 export const GATE_MATCH_PREDICATES = new Set(["labels", "body-text", "paths", "state", "age-days"]);
 export const GATE_MATCH_STATES = new Set(["open", "closed"]);
+/** ADR-005 / #3434 Story 1 -- author-stamped marker vocabulary. */
+export const DESIGN_CRITIQUE_GATE_ID = "design-critique";
+/** List-visible mirror; this is what judgmentGates predicates match. */
+export const DESIGN_CRITIQUE_MARKER_LABEL = "design-critique:mechanism-shaped";
+/** Authoritative body-text field in the #1423 triage write-back comment. */
+export const DESIGN_CRITIQUE_MARKER_FIELD = "mechanism-shaped: true";
+/**
+ * Clearance line shape (ADR-005). Presence and shape only -- a non-empty
+ * because-clause is required; its semantic content is never evaluated.
+ */
+export const DESIGN_CRITIQUE_CLEARANCE_SHAPE = /^design-critique:\s*(warranted|not warranted),\s*because\s+\S/i;
+/** True when `line` has clearance presence+shape. Never scores the reason text. */
+export function designCritiqueClearanceShapeOk(line) {
+    return DESIGN_CRITIQUE_CLEARANCE_SHAPE.test(line.trim());
+}
 function validateStrList(value, prefix, key) {
     if (!Array.isArray(value) || value.length === 0) {
         return [`${prefix}.${key} must be a non-empty list of strings`];

package/dist/orchestration/probe-session.js

@@ -12,6 +12,11 @@ export const SESSION_RELPATH = [".deft", "probe-session.json"];
 export const STATE_INTERROGATE = "interrogate";
 export const STATE_COMPLETE = "complete";
 export const VALID_DECISION_STATUSES = new Set(["locked", "deferred", "risk-accepted"]);
+/** Live CLI teach-string (#3556). The Python helper was deleted. */
+const PROBE_SESSION_START = "`deft probe-session start --target <scope>`";
+const PROBE_SESSION_RECORD = "`deft probe-session record ...`";
+const PROBE_SESSION_COMPLETE = "`deft probe-session complete`";
+const NO_SESSION_START = `No active probe session. Start one with ${PROBE_SESSION_START}.`;
 export class ProbeHandoffBlockedError extends Error {
     session;
     constructor(message, session = null) {
@@ -249,7 +254,7 @@ export function startSession(projectRoot, options) {
 export function recordDecision(projectRoot, options) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state !== STATE_INTERROGATE) {
         throw new ProbeHandoffBlockedError("Probe session is already complete; decisions cannot be appended.", session);
@@ -275,7 +280,7 @@ export function recordDecision(projectRoot, options) {
 export function setCurrentBranch(projectRoot, branch) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state !== STATE_INTERROGATE) {
         throw new ProbeHandoffBlockedError("Probe session is already complete; current branch cannot change.", session);
@@ -287,7 +292,7 @@ export function setCurrentBranch(projectRoot, branch) {
 export function markComplete(projectRoot, now) {
     const session = readSession(projectRoot);
     if (session === null) {
-        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+        throw new ProbeHandoffBlockedError(NO_SESSION_START);
     }
     if (session.state === STATE_COMPLETE) {
         return session;
@@ -307,7 +312,7 @@ function pythonRepr(value) {
 function blockedMessage(session, action) {
     if (session === null) {
         return (`Probe handoff blocked for ${action}: no active probe session. ` +
-            "Start interrogation with `uv run python scripts/probe_session.py start --target <scope>` " +
+            `Start interrogation with ${PROBE_SESSION_START} ` +
             "and finish with `... complete` only after transition criteria are met.");
     }
     return (`Probe handoff blocked for ${action}: session state is ` +
@@ -315,9 +320,9 @@ function blockedMessage(session, action) {
         `currentBranch=${pythonRepr(session.current_branch)}, ` +
         `resolvedDecisions=${session.resolved_decisions.length}). ` +
         "Continue interrogation until transition criteria are met, record decisions " +
-        "with `uv run python scripts/probe_session.py record ...`, then run " +
-        "`uv run python scripts/probe_session.py complete` before writing artifacts " +
-        "or updating completedStrategies.probe in plan.vbrief.json.");
+        `with ${PROBE_SESSION_RECORD}, then run ` +
+        `${PROBE_SESSION_COMPLETE} before writing artifacts ` +
+        "or updating completedStrategies.probe in plan.xbrief.json.");
 }
 export function requireHandoffAllowed(projectRoot, action) {
     const session = readSession(projectRoot);
@@ -330,7 +335,7 @@ export function guardProbeArtifact(projectRoot, artifactPath) {
     return requireHandoffAllowed(projectRoot, `probe artifact write (${artifactPath})`);
 }
 export function guardPlanProbeRegistration(projectRoot) {
-    return requireHandoffAllowed(projectRoot, "completedStrategies.probe registration in plan.vbrief.json");
+    return requireHandoffAllowed(projectRoot, "completedStrategies.probe registration in plan.xbrief.json");
 }
 export function sessionSummary(session) {
     return {

package/dist/orchestration/verify-judgment-gates.d.ts

@@ -2,6 +2,10 @@
  * Risk-tiered judgment-gate engine (#1419 Slice 3). Port of scripts/verify_judgment_gates.py.
  */
 import { type JudgmentGatesPolicy } from "./judgment-policy.js";
+/** Thrown when a design-critique clearance reason fails presence/shape (never content). */
+export declare class JudgmentClearanceShapeError extends Error {
+    constructor(message: string);
+}
 /** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export declare const AUDIT_DIR_REL = "vbrief/.audit";
 export declare const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";

package/dist/orchestration/verify-judgment-gates.js

@@ -7,8 +7,15 @@ import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, statSyn
 import { join, resolve } from "node:path";
 import { assertProjectionContained, assertWriteTargetSafe, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { resolveAuditDir } from "../layout/resolve.js";
-import { resolveJudgmentGates } from "./judgment-policy.js";
+import { DESIGN_CRITIQUE_GATE_ID, designCritiqueClearanceShapeOk, resolveJudgmentGates, } from "./judgment-policy.js";
 import { matchAny } from "./pathspec.js";
+/** Thrown when a design-critique clearance reason fails presence/shape (never content). */
+export class JudgmentClearanceShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JudgmentClearanceShapeError";
+    }
+}
 /** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export const AUDIT_DIR_REL = "vbrief/.audit";
 export const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";
@@ -163,6 +170,12 @@ export function readClearances(projectRoot, logPath) {
     return out;
 }
 export function recordClearance(projectRoot, options) {
+    if (options.gate_id === DESIGN_CRITIQUE_GATE_ID &&
+        !designCritiqueClearanceShapeOk(options.reason ?? "")) {
+        throw new JudgmentClearanceShapeError("design-critique clearance reason must match shape " +
+            "'design-critique: warranted | not warranted, because ...' " +
+            "(presence and shape only; the because-clause is not scored)");
+    }
     const path = options.log_path ?? clearanceLogPath(projectRoot);
     const auditDir = resolveAuditDir(projectRoot);
     assertProjectionContained(projectRoot, auditDir);
@@ -202,6 +215,15 @@ export function fingerprintScope(evidence) {
     const payload = JSON.stringify(sorted);
     return createHash("sha256").update(payload, "utf8").digest("hex");
 }
+function acceptClearanceShape(gateId, clearance) {
+    if (clearance === null) {
+        return null;
+    }
+    if (gateId !== DESIGN_CRITIQUE_GATE_ID) {
+        return clearance;
+    }
+    return designCritiqueClearanceShapeOk(String(clearance.reason ?? "")) ? clearance : null;
+}
 function lookupClearance(clearances, gateId, scope) {
     let valid = null;
     let stale = null;
@@ -383,7 +405,8 @@ export function buildReport(projectRoot, candidate, options = {}) {
             continue;
         }
         const scope = fingerprintScope(evidence);
-        const [valid, stale] = lookupClearance(records, String(gate.id), scope);
+        const [validRaw, stale] = lookupClearance(records, String(gate.id), scope);
+        const valid = acceptClearanceShape(String(gate.id), validRaw);
         outcomes.push({
             gate_id: String(gate.id),
             gate_class: String(gate.class),
@@ -605,15 +628,24 @@ function clearMain(argv) {
     if (args.updatedAt !== null)
         evidence["age-days"] = args.updatedAt;
     const scope = fingerprintScope(evidence);
-    const entry = recordClearance(projectRoot, {
-        gate_id: args.gateId,
-        cleared_scope: scope,
-        reviewers: args.reviewers,
-        actor: args.actor,
-        reason: args.reason,
-    });
-    process.stdout.write(`recorded clearance ${String(entry.clearance_id)} for gate ${JSON.stringify(args.gateId)} (cleared_scope=${scope.slice(0, 12)}...)\n`);
-    return 0;
+    try {
+        const entry = recordClearance(projectRoot, {
+            gate_id: args.gateId,
+            cleared_scope: scope,
+            reviewers: args.reviewers,
+            actor: args.actor,
+            reason: args.reason,
+        });
+        process.stdout.write(`recorded clearance ${String(entry.clearance_id)} for gate ${JSON.stringify(args.gateId)} (cleared_scope=${scope.slice(0, 12)}...)\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof JudgmentClearanceShapeError) {
+            process.stderr.write(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
 }
 function parseEvalArgs(argv) {
     const parsed = {

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: [],