@deftai/directive-core 0.104.0 → 0.105.0

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

@@ -198,13 +198,16 @@ export function resolveDeliveryTip(projectRoot, tipOverride, runGit) {
             return { tip: candidate, error: null };
         }
     }
-    // Last resort: HEAD of current checkout (still a real tip for fixtures).
-    if (refExists(projectRoot, "HEAD", runGit)) {
-        return { tip: "HEAD", error: null };
-    }
+    // ⊗ HEAD fallback (#3478 review). This gate exists to prove an artifact landed
+    // on the delivery tip rather than on feature-worktree HEAD; falling back to
+    // HEAD when the delivery ref is missing (shallow clone, unfetched worktree,
+    // fetch-depth:1 checkout) checks the very branch whose land is in question and
+    // silently passes. Unresolvable delivery tip must fail closed -- pass an
+    // explicit --tip (e.g. --tip HEAD for an in-flight land PR) to opt in.
     return {
         tip: null,
-        error: `could not resolve delivery tip for branch '${branch}' (no origin/${branch}, ${branch}, or HEAD)`,
+        error: `could not resolve delivery tip for branch '${branch}' (no origin/${branch} or ${branch}); ` +
+            "fetch the delivery branch or pass an explicit --tip",
     };
 }
 function listTreePaths(projectRoot, tip, prefixes, runGit) {
@@ -270,6 +273,28 @@ function issuesFromBlobPaths(projectRoot, tip, paths, defaultRepo, runGit, origi
     }
     return hits;
 }
+/**
+ * Narrow the origin map to the requested issue.
+ *
+ * Matching is repo-scoped when the caller's repo is known (#3478 review): a
+ * corpus entry for another repository's same-numbered issue must NOT survive
+ * this filter. Letting it through leaves `originMap` non-empty, which suppresses
+ * the synthesis below and makes the gate resolve the wrong `repo#number` --
+ * a foreign open issue then green-skips an unlanded local one.
+ */
+function filterOriginsByIssue(originMap, issue, repo) {
+    const out = new Map();
+    for (const [key, entry] of originMap) {
+        if (entry.issue.number !== issue) {
+            continue;
+        }
+        if (repo !== null && entry.issue.repo !== repo) {
+            continue;
+        }
+        out.set(key, entry);
+    }
+    return out;
+}
 function mergeOrigins(hits) {
     const map = new Map();
     for (const hit of hits) {
@@ -353,7 +378,47 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
     const localHits = scanLocalOrigins(root, defaultRepo);
     const tipNonterminalPaths = listTreePaths(root, tip, nonterminalPrefixes(), runGit);
     const tipNonterminalHits = issuesFromBlobPaths(root, tip, tipNonterminalPaths, defaultRepo, runGit, `tip:${tip}`);
-    const originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    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}`);
+    const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
+    const issueFilter = options.issue ?? null;
+    if (issueFilter !== null) {
+        if (!Number.isInteger(issueFilter) || issueFilter <= 0) {
+            return {
+                code: 2,
+                message: `verify:completed-tracked: --issue must be a positive integer (got ${issueFilter})`,
+                stream: "stderr",
+                missing: [],
+                tip,
+            };
+        }
+        originMap = filterOriginsByIssue(originMap, issueFilter, defaultRepo);
+        // Drive-to DONE must not green-skip a named origin with no local brief
+        // (#3476). Synthesize the requested issue so closed+unlanded fails.
+        if (originMap.size === 0) {
+            if (defaultRepo === null) {
+                return {
+                    code: 2,
+                    message: `verify:completed-tracked: --issue ${issueFilter} requires --repo or a resolvable ` +
+                        "origin remote when no scoped xBRIEF origin is present.",
+                    stream: "stderr",
+                    missing: [],
+                    tip,
+                };
+            }
+            const synthetic = {
+                issue: { repo: defaultRepo, number: issueFilter },
+                origins: [`--issue ${issueFilter}`],
+            };
+            originMap.set(issueKey(synthetic.issue), synthetic);
+        }
+    }
     if (originMap.size === 0) {
         if (quiet) {
             return { code: 0, message: "", stream: "none", missing: [], tip };
@@ -366,14 +431,6 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
             tip,
         };
     }
-    // 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}`);
-    const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
     const missing = [];
     for (const [key, entry] of originMap) {
         if (landedKeys.has(key)) {
@@ -383,10 +440,20 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
         if (state === "open") {
             continue;
         }
-        // Closed: always fail. Unknown with live expected (!skipGh): also fail —
-        // cannot prove the issue is still open, so do not green-skip land debt
-        // (#3264 Greptile residual on live lookup failure).
-        if (state === "closed" || (state === null && !skipGh)) {
+        // Closed: always fail.
+        //
+        // Unknown: fail when live lookup was expected (!skipGh) -- cannot prove the
+        // issue is still open, so do not green-skip land debt (#3264 Greptile
+        // residual on live lookup failure).
+        //
+        // Unknown also fails for an explicitly named --issue even under --skip-gh
+        // (#3478 review): that is the drive-to DONE form, where the caller asserts
+        // this specific issue is done. An uncached issue must not exit 0 there --
+        // otherwise --skip-gh silently turns the DONE gate into a no-op. The
+        // unscoped corpus scan keeps the offline allowance, since a cold cache
+        // legitimately knows nothing about most scoped issues.
+        const unknownIsTerminal = !skipGh || issueFilter !== null;
+        if (state === "closed" || (state === null && unknownIsTerminal)) {
             missing.push(entry);
         }
     }

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

@@ -13,6 +13,8 @@ import type { LiteralAcceptanceCommand, RejectedLiteralCommand } from "./types.j
 export interface CaptureLiteralAcceptanceResult {
     readonly commands: readonly LiteralAcceptanceCommand[];
     readonly rejected: readonly RejectedLiteralCommand[];
+    /** Prompt lines skipped inside a transcript-shaped fence (#3511). */
+    readonly transcriptPromptSkipped: number;
 }
 /**
  * Capture literal acceptance commands from free-form task statement text.
@@ -47,6 +49,14 @@ export declare function captureAndAttachLiteralAcceptance(plan: Record<string, u
     readonly commands: readonly LiteralAcceptanceCommand[];
     readonly rejected: readonly RejectedLiteralCommand[];
 };
+/** True when a rejected ledger entry was scraped from narrative prose (#3484). */
+export declare function isProseDerivedRejection(rejected: RejectedLiteralCommand): boolean;
+/**
+ * True when the author stated acceptance commands structurally — `swarm.verify_commands`
+ * or `plan.acceptance.commands` (#3484). Still used by intake/tests; demotion of
+ * prose-derived rejections no longer depends on this (#3511).
+ */
+export declare function hasStructuredAcceptanceCommands(plan: Record<string, unknown> | null | undefined): boolean;
 /** Format rejected ledger for CLI / complete-gate messages. */
 export declare function formatRejectedLedger(rejected: readonly RejectedLiteralCommand[]): string;
 //# sourceMappingURL=capture.d.ts.map

package/dist/literal-acceptance/capture.js

@@ -167,22 +167,6 @@ function matchLabeledCommand(line) {
         return null;
     return line.slice(i).trimEnd();
 }
-/** Mid-line `verify: cmd` (e.g. "Also run: verify: task check"). */
-function matchMidlineLabeled(line) {
-    const low = line.toLowerCase();
-    for (const kw of LABELED_KEYWORDS) {
-        if (kw === "run" || kw === "check")
-            continue; // too ambiguous mid-line
-        const needle = `${kw}:`;
-        const idx = low.indexOf(needle);
-        if (idx < 0)
-            continue;
-        const rest = line.slice(idx + needle.length).trim();
-        if (rest.length > 0)
-            return rest;
-    }
-    return null;
-}
 /** `$ cmd` or `> cmd` prompt lines. */
 function matchPromptCommand(line) {
     let i = skipWs(line, 0);
@@ -195,60 +179,144 @@ function matchPromptCommand(line) {
         return null;
     return line.slice(i).trimEnd();
 }
+/** Box-drawing / block elements used in terminal UIs (━, │, …). */
+const BOX_DRAWING_RE = /[\u2500-\u257F\u2580-\u259F]/;
+/**
+ * Drop GNU-style long flags and their following value so `--filter fail`
+ * is not classified as FAIL transcript output (#3511).
+ * Covers `--flag`, `--flag=value`, and `--flag value` (value not another flag).
+ */
+function stripLongFlags(line) {
+    return line.replace(/(^|\s)--[\w-]+(?:=[^\s]+|\s+(?!-)[^\s]+)?/g, "$1");
+}
+/**
+ * True when a fence line is log/transcript, not a stated command (#3511).
+ * `[1/13]` / `[ts:check-lane]`, box drawing, or FAIL/FAILED/Error:.
+ * Flag tokens (--fail-fast, --failOnError, --no-fail) and flag values
+ * (`--filter fail`, `--grep FAIL`) are not FAIL output: `\bFAIL` matches
+ * between `-` and `f`, and leftover values still match after name-only strip.
+ */
+function isTranscriptOutputLine(line) {
+    const t = line.trim();
+    if (t.length === 0)
+        return false;
+    if (t.startsWith("#") || t.startsWith("//"))
+        return false;
+    if (/^\[[^\]]{1,80}\]/.test(t))
+        return true;
+    if (BOX_DRAWING_RE.test(t))
+        return true;
+    const withoutFlags = stripLongFlags(t);
+    if (/\b(?:FAILED|FAIL|Error:)/i.test(withoutFlags))
+        return true;
+    return false;
+}
+function isFenceCommentOrBlank(line) {
+    const t = line.trim();
+    return t.length === 0 || t.startsWith("#") || t.startsWith("//");
+}
+function isPromptLine(line) {
+    const t = line.trim();
+    return t.startsWith("$ ") || t.startsWith("> ");
+}
+/** Per-line mask: true for body lines inside ``` / ~~~ fences (not the markers). */
+function fenceBodyMask(lines) {
+    const mask = Array.from({ length: lines.length }, () => false);
+    let open = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        if (open === null) {
+            open = matchFenceOpen(line);
+            continue;
+        }
+        if (matchFenceClose(line, open)) {
+            open = null;
+            continue;
+        }
+        mask[i] = true;
+    }
+    return mask;
+}
+function captureFenceBodyLine(line, fenceLang, fenceStartLine, buckets) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed.startsWith("//")) {
+        return;
+    }
+    let body = trimmed;
+    if (body.startsWith("$ ") || body.startsWith("> ")) {
+        body = body.slice(2).trim();
+    }
+    const normalized = normalizeCommand(body);
+    if (normalized === null)
+        return;
+    const langOk = isShellFenceLang(fenceLang);
+    if (!looksLikeShellCommand(normalized) && (fenceLang === "" || !langOk))
+        return;
+    pushUnique(buckets, normalized, "task_statement", `fence@L${fenceStartLine}${fenceLang ? `:${fenceLang}` : ""}`);
+}
+function flushFenceBody(body, fenceLang, fenceStartLine, requireRegion, regionActive, buckets) {
+    if (requireRegion && !regionActive)
+        return;
+    if (!isShellFenceLang(fenceLang))
+        return;
+    // Transcript lines are skipped. `$`/`>` prompts inside a transcript fence are
+    // suggested-fixes (biome migrate), not stated AC (#3511). Comments do not
+    // mark a fence as transcript, so a genuine command next to `# Error:` still
+    // captures.
+    const transcript = body.some((line) => isTranscriptOutputLine(line));
+    for (const line of body) {
+        if (isFenceCommentOrBlank(line))
+            continue;
+        if (transcript && isPromptLine(line)) {
+            buckets.transcriptPromptSkipped += 1;
+            continue;
+        }
+        if (isTranscriptOutputLine(line))
+            continue;
+        captureFenceBodyLine(line, fenceLang, fenceStartLine, buckets);
+    }
+}
 /**
  * Walk fenced ``` / ~~~ blocks; keep fence body lines that look like shell.
  * When `requireRegion` is true, only fences under an acceptance/verify heading.
+ * Output-shaped fences (progress tags, box drawing, FAIL/Error:) are skipped (#3511).
  */
 function extractFromFences(text, requireRegion, buckets) {
     const lines = text.split(/\r?\n/);
-    let inFence = false;
-    let fenceLang = "";
+    let open = null;
     let regionActive = !requireRegion;
     let fenceStartLine = 0;
+    let fenceBody = [];
+    const flush = () => {
+        if (open === null)
+            return;
+        flushFenceBody(fenceBody, open.lang, fenceStartLine, requireRegion, regionActive, buckets);
+        open = null;
+        fenceBody = [];
+    };
     for (let i = 0; i < lines.length; i += 1) {
         const line = lines[i] ?? "";
         const heading = matchMarkdownHeading(line);
-        if (heading !== null && !inFence) {
+        if (heading !== null && open === null) {
             regionActive = requireRegion ? isRegionHeading(heading.text) : true;
             continue;
         }
         const fenceOpen = matchFenceOpen(line);
-        if (fenceOpen !== null && !inFence) {
-            inFence = true;
-            fenceLang = fenceOpen.lang;
+        if (fenceOpen !== null && open === null) {
+            open = fenceOpen;
             fenceStartLine = i + 1;
+            fenceBody = [];
             continue;
         }
-        if (inFence && matchFenceClose(line)) {
-            inFence = false;
-            fenceLang = "";
+        if (open !== null && matchFenceClose(line, open)) {
+            flush();
             continue;
         }
-        if (!inFence)
+        if (open === null)
             continue;
-        if (requireRegion && !regionActive)
-            continue;
-        // Skip comment-only fence lines.
-        const trimmed = line.trim();
-        if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed.startsWith("//")) {
-            continue;
-        }
-        // Shell-ish langs always accepted; unknown langs need CLI shape.
-        const langOk = isShellFenceLang(fenceLang);
-        if (!langOk && fenceLang !== "")
-            continue;
-        // Strip leading prompt markers inside fences.
-        let body = trimmed;
-        if (body.startsWith("$ ") || body.startsWith("> ")) {
-            body = body.slice(2).trim();
-        }
-        const normalized = normalizeCommand(body);
-        if (normalized === null)
-            continue;
-        if (!looksLikeShellCommand(normalized) && (fenceLang === "" || !langOk))
-            continue;
-        pushUnique(buckets, normalized, "task_statement", `fence@L${fenceStartLine}${fenceLang ? `:${fenceLang}` : ""}`);
+        fenceBody.push(line);
     }
+    flush();
 }
 function isShellFenceLang(lang) {
     return (lang === "" ||
@@ -262,26 +330,38 @@ function isShellFenceLang(lang) {
         lang === "cmd" ||
         lang === "text");
 }
-/** Linear fence open: ```lang or ~~~lang */
+/**
+ * CommonMark fence open: 3+ backticks or tildes, then an optional info string.
+ * Longer openers (````) must close with the same marker at >= that length (#3511 P1).
+ */
 function matchFenceOpen(line) {
-    const t = line.trimEnd();
-    if (t.startsWith("```")) {
-        const rest = t.slice(3).trim().toLowerCase();
-        if (rest.includes(" ") || rest.includes("\t"))
-            return null;
-        return { lang: rest };
-    }
-    if (t.startsWith("~~~")) {
-        const rest = t.slice(3).trim().toLowerCase();
-        if (rest.includes(" ") || rest.includes("\t"))
-            return null;
-        return { lang: rest };
-    }
-    return null;
+    const body = line.trimEnd().trimStart();
+    if (body.length < 3)
+        return null;
+    const first = body[0];
+    if (first !== "`" && first !== "~")
+        return null;
+    const marker = first;
+    let length = 0;
+    while (length < body.length && body[length] === marker)
+        length += 1;
+    if (length < 3)
+        return null;
+    const rest = body.slice(length).trim().toLowerCase();
+    if (rest.includes(" ") || rest.includes("\t"))
+        return null;
+    if (rest.includes(marker))
+        return null;
+    return { lang: rest, marker, length };
 }
-function matchFenceClose(line) {
+function matchFenceClose(line, open) {
     const t = line.trim();
-    return t === "```" || t === "~~~";
+    let length = 0;
+    while (length < t.length && t[length] === open.marker)
+        length += 1;
+    if (length < open.length)
+        return false;
+    return t.slice(length).trim().length === 0;
 }
 function matchMarkdownHeading(line) {
     if (!line.startsWith("#"))
@@ -295,17 +375,25 @@ function matchMarkdownHeading(line) {
         return null;
     return { level, text: line.slice(level + 1).trim() };
 }
-/** Extract from labeled lines and `$` prompts anywhere in the statement. */
+/**
+ * Extract from labeled lines and `$` prompts anywhere in the statement.
+ *
+ * A labeled command MUST start its own line (after an optional bullet / number
+ * marker). Mid-line label capture is deliberately not attempted (#3484): a
+ * `verify:<verb>` token inside ordinary prose has no terminator, so the capture
+ * swallowed the rest of the paragraph and the phantom then blocked completion on
+ * the safety ledger. Commands stated mid-sentence must live in a fence, a `$`
+ * prompt, or an inline backtick span — all of which have real delimiters.
+ */
 function extractFromLabeledLines(text, buckets) {
     const lines = text.split(/\r?\n/);
+    const inFence = fenceBodyMask(lines);
     for (let i = 0; i < lines.length; i += 1) {
+        if (inFence[i] === true)
+            continue;
         const line = lines[i] ?? "";
         let capturedLabeled = false;
-        let labeledBody = matchLabeledCommand(line);
-        if (labeledBody === null && matchPromptCommand(line) === null) {
-            // Avoid treating `$ task verify:branch` as labeled "branch".
-            labeledBody = matchMidlineLabeled(line);
-        }
+        const labeledBody = matchLabeledCommand(line);
         if (labeledBody !== null) {
             const normalized = normalizeCommand(labeledBody);
             if (normalized !== null && looksLikeShellCommand(normalized)) {
@@ -330,7 +418,10 @@ function extractFromLabeledLines(text, buckets) {
  */
 function extractInlineVerifySpans(text, buckets) {
     const lines = text.split(/\r?\n/);
+    const inFence = fenceBodyMask(lines);
     for (let i = 0; i < lines.length; i += 1) {
+        if (inFence[i] === true)
+            continue;
         const line = lines[i] ?? "";
         if (!/\b(verify|run|execute|acceptance)\b/i.test(line))
             continue;
@@ -359,6 +450,7 @@ function emptyBuckets() {
         seen: new Set(),
         rejected: [],
         rejectedSeen: new Set(),
+        transcriptPromptSkipped: 0,
     };
 }
 /**
@@ -367,7 +459,7 @@ function emptyBuckets() {
  */
 export function captureLiteralAcceptanceCommandsDetailed(taskStatement) {
     if (!isNonEmptyString(taskStatement)) {
-        return { commands: [], rejected: [] };
+        return { commands: [], rejected: [], transcriptPromptSkipped: 0 };
     }
     const buckets = emptyBuckets();
     // Prefer fences under acceptance/verify headings first.
@@ -376,7 +468,11 @@ export function captureLiteralAcceptanceCommandsDetailed(taskStatement) {
     extractFromFences(taskStatement, false, buckets);
     extractFromLabeledLines(taskStatement, buckets);
     extractInlineVerifySpans(taskStatement, buckets);
-    return { commands: buckets.out, rejected: buckets.rejected };
+    return {
+        commands: buckets.out,
+        rejected: buckets.rejected,
+        transcriptPromptSkipped: buckets.transcriptPromptSkipped,
+    };
 }
 /**
  * Capture literal acceptance commands from free-form task statement text.
@@ -395,7 +491,7 @@ export function readStoredLiteralAcceptanceCommands(plan) {
 /** Read stored commands plus any persisted rejected ledger. */
 export function readStoredLiteralAcceptanceDetailed(plan) {
     if (plan === null || plan === undefined || typeof plan !== "object") {
-        return { commands: [], rejected: [] };
+        return { commands: [], rejected: [], transcriptPromptSkipped: 0 };
     }
     const buckets = emptyBuckets();
     const metadata = asRecord(plan.metadata);
@@ -435,7 +531,11 @@ export function readStoredLiteralAcceptanceDetailed(plan) {
         }
     }
     walkPlanItems(plan.items, "items", buckets);
-    return { commands: buckets.out, rejected: buckets.rejected };
+    return {
+        commands: buckets.out,
+        rejected: buckets.rejected,
+        transcriptPromptSkipped: buckets.transcriptPromptSkipped,
+    };
 }
 function walkPlanItems(items, pathPrefix, buckets) {
     if (!Array.isArray(items))
@@ -644,6 +744,55 @@ function toSerializable(cmd) {
     }
     return row;
 }
+/**
+ * Provenance prefixes stamped by the free-text scrapers in this module.
+ * Anything carrying one of these spans came from prose, not from a structured
+ * acceptance field the author wrote on purpose (#3484).
+ */
+const PROSE_SPAN_PREFIXES = ["labeled@", "prompt@", "inline@", "fence@"];
+/** True when a rejected ledger entry was scraped from narrative prose (#3484). */
+export function isProseDerivedRejection(rejected) {
+    const span = rejected.sourceSpan;
+    if (span === null || span === undefined)
+        return false;
+    return PROSE_SPAN_PREFIXES.some((prefix) => span.startsWith(prefix));
+}
+function hasNonEmptyCommandList(raw) {
+    if (typeof raw === "string")
+        return raw.trim().length > 0;
+    if (!Array.isArray(raw))
+        return false;
+    for (const entry of raw) {
+        if (typeof entry === "string" && entry.trim().length > 0)
+            return true;
+        const rec = asRecord(entry);
+        if (rec === null)
+            continue;
+        if (isNonEmptyString(rec.command ?? rec.cmd ?? rec.shell))
+            return true;
+    }
+    return false;
+}
+/**
+ * True when the author stated acceptance commands structurally — `swarm.verify_commands`
+ * or `plan.acceptance.commands` (#3484). Still used by intake/tests; demotion of
+ * prose-derived rejections no longer depends on this (#3511).
+ */
+export function hasStructuredAcceptanceCommands(plan) {
+    const rec = asRecord(plan);
+    if (rec === null)
+        return false;
+    const acceptance = asRecord(rec.acceptance);
+    if (acceptance !== null && hasNonEmptyCommandList(acceptance.commands))
+        return true;
+    const metadata = asRecord(rec.metadata);
+    if (metadata === null)
+        return false;
+    const swarm = asRecord(metadata.swarm);
+    if (swarm === null)
+        return false;
+    return hasNonEmptyCommandList(swarm.verify_commands);
+}
 /** Format rejected ledger for CLI / complete-gate messages. */
 export function formatRejectedLedger(rejected) {
     if (rejected.length === 0)

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

@@ -13,6 +13,19 @@ export interface EvaluateLiteralAcceptanceOptions {
     /** Quiet success (empty message on pass). */
     readonly quiet?: boolean;
 }
+/** Resolved literal-AC view: executable commands plus the blocking / advisory ledgers. */
+export interface ResolvedLiteralAcceptance {
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    /** Safety-rejected entries that block completion. */
+    readonly rejected: readonly RejectedLiteralCommand[];
+    /**
+     * Prose/fence/inline-derived rejections demoted to advisory (#3484 / #3511).
+     * Reported, never blocking. Structured-field rejections stay on `rejected`.
+     */
+    readonly advisoryRejected: readonly RejectedLiteralCommand[];
+    /** Prompt lines skipped inside a transcript-shaped fence (#3511). */
+    readonly transcriptPromptSkipped: number;
+}
 /**
  * Resolve commands + rejected ledger.
  * Stored first; when captureFromNarratives is true (default), also re-scan narratives
@@ -21,16 +34,28 @@ export interface EvaluateLiteralAcceptanceOptions {
  */
 export declare function resolveLiteralAcceptanceDetailed(plan: Record<string, unknown>, options?: {
     readonly captureFromNarratives?: boolean;
-}): {
-    readonly commands: readonly LiteralAcceptanceCommand[];
-    readonly rejected: readonly RejectedLiteralCommand[];
-};
+}): ResolvedLiteralAcceptance;
 /**
  * Resolve commands: stored first; optional narrative re-capture when empty.
  */
 export declare function resolveLiteralAcceptanceCommands(plan: Record<string, unknown>, options?: {
     readonly captureFromNarratives?: boolean;
 }): LiteralAcceptanceCommand[];
+/**
+ * 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 declare const LITERAL_ACCEPTANCE_ADVISORY_MARKER = "Literal acceptance advisory (#3484):";
+/** Render the #3484 advisory block (reported, never blocking). */
+export declare function formatLiteralAcceptanceAdvisory(advisory: readonly RejectedLiteralCommand[]): string;
+/** Append the #3484 advisory block to a message tail. */
+export declare function appendLiteralAcceptanceAdvisory(message: string, advisory: readonly RejectedLiteralCommand[]): string;
+/**
+ * Drop the #3484 advisory block from a rendered message.
+ * The block is always the tail, so an index cut is exact.
+ */
+export declare function stripLiteralAcceptanceAdvisory(message: string): string;
 /**
  * Evaluate from an in-memory plan object.
  */