@deftai/directive-core 0.98.1 → 0.99.0

package/dist/consumer-check-contract/evaluate.js

@@ -17,6 +17,157 @@ export const REQUIRED_CONSUMER_ENFORCEMENT_GATES = [
     "verify:scope-provenance",
     "verify:consumer-check-contract",
 ];
+/**
+ * Relative path forms accepted for the deft-install canonical Taskfile include
+ * (init-deposit `MINIMAL_TASKFILE` / `CANONICAL_TASKFILE_INCLUDE`).
+ * Use only as a path-value matcher — never as a whole-file text search (Greptile P1 #3218).
+ */
+export const CANONICAL_DEFT_TASKFILE_PATH_RE = /^(?:\.\.?\/)?\.deft\/core\/Taskfile\.yml$/i;
+/** `taskfile: ./.deft/core/Taskfile.yml` under an includes: child (object form). */
+const INCLUDE_TASKFILE_KEY_RE = /^taskfile:\s*['"]?((?:\.\.?\/)?\.deft\/core\/Taskfile\.yml)['"]?\s*(?:#.*)?$/i;
+/**
+ * Short form under includes: — **must** be namespace `deft` so `task deft:check`
+ * remains the documented greenfield entrypoint (Greptile conf residual #3218).
+ */
+const INCLUDE_DEFT_SHORT_FORM_RE = /^deft:\s*['"]?((?:\.\.?\/)?\.deft\/core\/Taskfile\.yml)['"]?\s*(?:#.*)?$/i;
+/** Object-form entry start for the `deft` namespace only. */
+const INCLUDE_DEFT_ENTRY_START_RE = /^deft\s*:\s*(?:#.*)?$/i;
+/** @deprecated Prefer path/line parsers; kept for export stability. */
+export const CANONICAL_DEFT_TASKFILE_INCLUDE_RE = INCLUDE_TASKFILE_KEY_RE;
+/**
+ * Return the relative path of the canonical `.deft/core/Taskfile.yml` include when
+ * present as an **active, direct** go-task `includes:` entry; otherwise null.
+ *
+ * Greenfield `directive init` deposits an include-only Taskfile (#3218); composition
+ * lives in the included framework graph, not in root `check` deps.
+ *
+ * Greptile P1 (#3218):
+ * - Path text in comments / cmds / vars / non-include keys must not match.
+ * - Only **direct** include entries count: short form `deft: path` or object form
+ *   `deft: { taskfile: path }` (immediate property). Nested
+ *   `includes.some.nested.taskfile` is not an executable go-task include.
+ * - Namespace must be `deft` so the documented `task deft:check` entrypoint exists.
+ */
+export function resolveCanonicalDeftTaskfileInclude(rootTaskfileText) {
+    const lines = rootTaskfileText.replace(/\r\n/g, "\n").split("\n");
+    let inIncludes = false;
+    let includesIndent = 0;
+    /** Indent of direct children under `includes:` (include entry keys). */
+    let directChildIndent = null;
+    /** Indent of immediate properties under the current object-form include entry. */
+    let entryBodyIndent = null;
+    /** True while inside the body of the `deft:` include entry. */
+    let inDeftEntryBody = false;
+    for (const raw of lines) {
+        const stripped = raw.trim();
+        if (!stripped || stripped.startsWith("#"))
+            continue;
+        // Full-line list comment: - # ...
+        if (/^-\s+#/.test(stripped))
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        if (!inIncludes) {
+            // Top-level includes: only (indent 0 or document-level).
+            if (/^includes\s*:/.test(stripped) && indent <= 1) {
+                inIncludes = true;
+                includesIndent = indent;
+                directChildIndent = null;
+                entryBodyIndent = null;
+                inDeftEntryBody = false;
+            }
+            continue;
+        }
+        // Left the includes block: another key at the same or shallower indent.
+        if (indent <= includesIndent && /^[\w.-]+\s*:/.test(stripped)) {
+            if (/^includes\s*:/.test(stripped)) {
+                includesIndent = indent;
+                directChildIndent = null;
+                entryBodyIndent = null;
+                inDeftEntryBody = false;
+                continue;
+            }
+            inIncludes = false;
+            directChildIndent = null;
+            entryBodyIndent = null;
+            inDeftEntryBody = false;
+            continue;
+        }
+        if (indent <= includesIndent)
+            continue;
+        if (directChildIndent === null) {
+            directChildIndent = indent;
+        }
+        // Direct include entry line (namespace key under includes:).
+        if (indent === directChildIndent) {
+            entryBodyIndent = null;
+            inDeftEntryBody = false;
+            const short = INCLUDE_DEFT_SHORT_FORM_RE.exec(stripped);
+            if (short?.[1] !== undefined && CANONICAL_DEFT_TASKFILE_PATH_RE.test(short[1])) {
+                return short[1].replace(/\\/g, "/");
+            }
+            // Object-form `deft:` entry — only this namespace exposes task deft:check.
+            if (INCLUDE_DEFT_ENTRY_START_RE.test(stripped)) {
+                inDeftEntryBody = true;
+            }
+            continue;
+        }
+        // Nested under a direct include entry: only immediate props of `deft:` count.
+        if (indent > directChildIndent && inDeftEntryBody) {
+            if (entryBodyIndent === null) {
+                entryBodyIndent = indent;
+            }
+            // Deeper than one property level → not an executable include taskfile key.
+            if (indent !== entryBodyIndent)
+                continue;
+            const m = INCLUDE_TASKFILE_KEY_RE.exec(stripped);
+            if (m?.[1] !== undefined && CANONICAL_DEFT_TASKFILE_PATH_RE.test(m[1])) {
+                return m[1].replace(/\\/g, "/");
+            }
+        }
+    }
+    return null;
+}
+/**
+ * True when a framework (included) Taskfile composes every required gate via
+ * `check` / `check:consumer` / `check:framework-source` deps or an orchestrator body,
+ * and `tasks/verify.yml` defines the local task keys.
+ */
+export function frameworkTaskfileComposesRequiredGates(frameworkTaskfileText, verifyTaskfileText, required = REQUIRED_CONSUMER_ENFORCEMENT_GATES) {
+    if (verifyTaskfileText === null || frameworkTaskfileText.trim().length === 0) {
+        return false;
+    }
+    for (const gateId of required) {
+        if (!gateId.startsWith("verify:"))
+            continue;
+        if (!taskDefinedInTaskfileYaml(verifyTaskfileText, gateId.slice("verify:".length))) {
+            return false;
+        }
+    }
+    const checkTargets = ["check", "check:consumer", "check:framework-source"];
+    for (const target of checkTargets) {
+        const deps = extractCheckDeps(frameworkTaskfileText, target);
+        const body = extractTaskBody(frameworkTaskfileText, target);
+        const defined = deps.length > 0 || body.trim().length > 0;
+        if (!defined)
+            continue;
+        if (taskBodyInvokesCheckOrchestrator(body)) {
+            return true;
+        }
+        const allListed = required.every((gateId) => {
+            for (const d of deps) {
+                const name = d.trim();
+                if (name === gateId)
+                    return true;
+                if (name === `task ${gateId}` || name === `task:${gateId}`)
+                    return true;
+            }
+            return false;
+        });
+        if (allListed)
+            return true;
+    }
+    return false;
+}
 function readText(path) {
     try {
         if (!existsSync(path))
@@ -583,12 +734,46 @@ export function evaluateConsumerCheckContract(projectRoot, options = {}) {
             }
         }
     }
+    // Include-only greenfield (#3218): root Taskfile from `directive init` only wires
+    // `includes.deft → ./.deft/core/Taskfile.yml`. Composition lives in the included
+    // framework Taskfile + tasks/verify.yml. Trust that graph when no local check
+    // aggregates are defined. A partial local check aggregate still fails closed —
+    // the include must not conceal incomplete root deps.
+    let includeComposes = false;
+    const includeRel = resolveCanonicalDeftTaskfileInclude(rootTaskfile);
+    if (includeRel !== null) {
+        let includedTf;
+        if (options.includedFrameworkTaskfileText !== undefined) {
+            includedTf = options.includedFrameworkTaskfileText;
+        }
+        else {
+            const absInclude = join(root, includeRel.replace(/^\.\//, ""));
+            includedTf = readText(absInclude);
+        }
+        let includedVerify;
+        if (options.includedVerifyTaskfileText !== undefined) {
+            includedVerify = options.includedVerifyTaskfileText;
+        }
+        else if (includedTf !== null) {
+            const includeDir = join(root, includeRel.replace(/^\.\//, "").replace(/[/\\]Taskfile\.yml$/i, ""));
+            includedVerify = readText(join(includeDir, "tasks", "verify.yml"));
+        }
+        else {
+            includedVerify = null;
+        }
+        if (includedTf !== null) {
+            includeComposes = frameworkTaskfileComposesRequiredGates(includedTf, includedVerify, required);
+        }
+    }
     // No check aggregates defined at all — still a composition gap when enforce
-    // (unless trust via whole-file orchestrator is impossible without a body).
+    // (unless trust via whole-file orchestrator, or canonical deft include composition).
     if (!anyAggregateDefined) {
-        // Preserve prior behavior for empty/missing check tasks: fail each required gate.
         const invokesAny = taskfileInvokesCheckOrchestrator(rootTaskfile);
-        if (!(invokesAny && verifyDefinesRequired)) {
+        if (includeComposes || (invokesAny && verifyDefinesRequired)) {
+            // Include-only greenfield or root orchestrator body — clean for check-task.
+        }
+        else {
+            // Preserve prior behavior for empty/missing check tasks: fail each required gate.
             for (const gateId of required) {
                 findings.push({
                     gateId,

package/dist/consumer-check-contract/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * consumer-check-contract package surface (#3145).
  */
-export { type ConsumerCheckContractFinding, type ConsumerCheckContractOptions, type ConsumerCheckContractResult, evaluateConsumerCheckContract, extractCheckDeps, REQUIRED_CONSUMER_ENFORCEMENT_GATES, requiredGatesFromConsumerList, taskfileInvokesCheckOrchestrator, textReferencesGate, workflowExecutesCheck, } from "./evaluate.js";
+export { CANONICAL_DEFT_TASKFILE_INCLUDE_RE, CANONICAL_DEFT_TASKFILE_PATH_RE, type ConsumerCheckContractFinding, type ConsumerCheckContractOptions, type ConsumerCheckContractResult, evaluateConsumerCheckContract, extractCheckDeps, frameworkTaskfileComposesRequiredGates, REQUIRED_CONSUMER_ENFORCEMENT_GATES, requiredGatesFromConsumerList, resolveCanonicalDeftTaskfileInclude, taskfileInvokesCheckOrchestrator, textReferencesGate, workflowExecutesCheck, } from "./evaluate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/consumer-check-contract/index.js

@@ -1,5 +1,5 @@
 /**
  * consumer-check-contract package surface (#3145).
  */
-export { evaluateConsumerCheckContract, extractCheckDeps, REQUIRED_CONSUMER_ENFORCEMENT_GATES, requiredGatesFromConsumerList, taskfileInvokesCheckOrchestrator, textReferencesGate, workflowExecutesCheck, } from "./evaluate.js";
+export { CANONICAL_DEFT_TASKFILE_INCLUDE_RE, CANONICAL_DEFT_TASKFILE_PATH_RE, evaluateConsumerCheckContract, extractCheckDeps, frameworkTaskfileComposesRequiredGates, REQUIRED_CONSUMER_ENFORCEMENT_GATES, requiredGatesFromConsumerList, resolveCanonicalDeftTaskfileInclude, taskfileInvokesCheckOrchestrator, textReferencesGate, workflowExecutesCheck, } from "./evaluate.js";
 //# sourceMappingURL=index.js.map

package/dist/content-contracts/skills/greptile-detector.d.ts

@@ -12,11 +12,53 @@ interface DetectResult {
     has_blocking: boolean;
 }
 export declare function parseConfidence(body: string): number | null;
+/**
+ * Extract verdict-bearing text windows from a bot rolling-summary body (#3225).
+ * Prefers Confidence Score sections and Summary:/Decision: lines over whole-body
+ * Overview tables that may *describe* advisory phrases without issuing them.
+ */
+export declare function extractAdvisoryVerdictRegions(body: string): string;
+/**
+ * True when comment body prose records an advisory should-not-merge / not-safe
+ * verdict (#3225). Code-fence regions are stripped first so detector docs do
+ * not self-trigger (#1004).
+ *
+ * Line-anchored hybrid scan (PR #3227 residuals):
+ * 1. Soft + high-signal **line-anchored** phrases in Confidence / Summary /
+ *    Decision regions (and whole body)
+ * 2. Same line-anchored high-signal set on whole body (standalone warnings)
+ * Mid-sentence residual discussion does not hard-block; conf floor still does (#3095).
+ */
+export declare function hasShouldNotMergeProse(body: string): boolean;
+/**
+ * Structured advisory verdict from bot comment body (#3225 / #1282 style).
+ * Confidence is independent of formal GitHub review state; compose with
+ * `minGreptileConfidence` (#3095) at the clean gate.
+ */
+export interface AdvisoryReviewerVerdict {
+    readonly confidence: number | null;
+    readonly shouldNotMerge: boolean;
+    readonly hasBlocking: boolean;
+}
+export declare function parseAdvisoryReviewerVerdict(body: string): AdvisoryReviewerVerdict;
 export declare function detect(body: string): DetectResult;
 export declare function parseLastReviewedShaMarkdownLink(body: string): string | null;
 export declare function parseLastReviewedShaNaiveInline(body: string): string | null;
 export declare const BODY_TIER2_P1_ONLY = "Greptile review of head 1234567\n\nConfidence Score: 4/5\n\nLast reviewed commit: [fix: foo bar](https://github.com/deftai/directive/commit/abcdef1234567)\n\nComments:\n\n- **P1 -- wrong exception type for state/limit validation in populate()**\n  The current code raises ValueError but the contract calls for InvalidRepoError.\n- **P2 -- minor wording in error message**\n  Consider `--repo` instead of `the repo flag`.\n";
 export declare const BODY_TIER3_NOT_SAFE_ONLY = "Greptile review of head 7654321\n\nConfidence Score: 3/5\n\nLast reviewed commit: [refactor: thing](https://github.com/deftai/directive/commit/0011223344556)\n\nSummary: Not safe to merge until the mocked-import test defect and the two\npreviously filed P1s are resolved.\n";
+/** #3225 live-case shape: conf 3/5 + should-not-merge prose, zero badges. */
+export declare const BODY_ADVISORY_SHOULD_NOT_MERGE_CONF3 = "Greptile review of head advisory01\n\n## Confidence Score: 3/5\n\nSummary: should-not-merge \u2014 residual risk on the auth path is too high for\nthis change set. Formal review state is still Comment (not Changes Requested).\n\nLast reviewed commit: [feat: advisory](https://github.com/deftai/directive/commit/advisory01abcdef12)\n";
+/** Green mechanical path trap: high conf but explicit do-not-merge prose. */
+export declare const BODY_ADVISORY_DO_NOT_MERGE_HIGH_CONF = "Greptile review of head advisory02\n\nConfidence Score: 5/5\n\nNo P0 or P1 issues found via badges.\n\nSummary: Do not merge until the operator documents residual risk.\n\nLast reviewed commit: [docs: note](https://github.com/deftai/directive/commit/advisory02abcdef12)\n";
+/**
+ * Overview prose names the detector phrase without issuing a verdict (#3225 residual).
+ * Confidence section is clean — must NOT set shouldNotMerge.
+ */
+export declare const BODY_ADVISORY_DESCRIPTIVE_ONLY = "Greptile review of head advisory03\n\n<details><summary><h3>Greptile Summary</h3></summary>\n\nThis PR adds should-not-merge prose detection and Not safe to merge matching to\nmerge-ready. Descriptive overview only \u2014 no blocking residual on the product path.\n\n</details>\n\n<details open><summary><h3>Confidence Score: 5/5</h3></summary>\n\nNo P0 or P1 issues found. The change looks clean and well-tested.\n\n</details>\n\nLast reviewed commit: [feat: detector](https://github.com/deftai/directive/commit/advisory03abcdef12)\n";
+/** Standalone high-signal warning outside Confidence section must still block. */
+export declare const BODY_ADVISORY_STANDALONE_NOT_SAFE = "Greptile review of head advisory04\n\n<details open><summary><h3>Confidence Score: 5/5</h3></summary>\n\nLooks solid from a findings perspective.\n\n</details>\n\nNot safe to merge until the operator confirms residual risk handling.\n\nLast reviewed commit: [feat: residual](https://github.com/deftai/directive/commit/advisory04abcdef12)\n";
+/** Subject-prefixed verdict Greptile commonly emits (#3225 residual). */
+export declare const BODY_ADVISORY_SUBJECT_PREFIXED = "Greptile review of head advisory05\n\n## Confidence Score: 4/5\n\nThe PR is not safe to merge until residual risk is documented on the auth path.\n\nLast reviewed commit: [feat: subject](https://github.com/deftai/directive/commit/advisory05abcdef12)\n";
 export declare const BODY_TIER3_COUNT_PROSE_ONLY = "Greptile review of head deadbeef\n\nConfidence Score: 4/5\n\nLast reviewed commit: [chore: bump](https://github.com/deftai/directive/commit/deadbeefcafe123)\n\nThree P1 findings (two from prior review, one new): wrong exception type for\nstate/limit validation in populate(), misleading skip message, and an\nunguarded import that will fail on Windows.\n";
 export declare const BODY_NEGATION_GUARDED = "Greptile review of head ffffffff\n\nConfidence Score: 5/5\n\nLast reviewed commit: [feat: clean](https://github.com/deftai/directive/commit/ffffffffabc1234)\n\nSummary: No P0 findings. Zero P1 findings. The PR is ready for merge.\n";
 export declare const BODY_CLEAN = "Greptile review of head 1111111\n\nConfidence Score: 5/5\n\nLast reviewed commit: [docs: tweak](https://github.com/deftai/directive/commit/1111111aaa2222b)\n\nNo P0 or P1 issues found. The change looks clean and well-tested.\n";

package/dist/content-contracts/skills/greptile-detector.js

@@ -13,6 +13,38 @@ const TIER3_LINE_RE = /^\s*P[01]\s+--\s/gm;
 const TIER3_NEGATIONS = ["No ", "Zero ", "no ", "NO "];
 const CONFIDENCE_INLINE_RE = /Confidence Score:\s*(\d+)\s*\/\s*5/;
 const CONFIDENCE_HEADING_RE = /^#{1,6}\s*Confidence Score:\s*(\d+)\s*\/\s*5\s*$/m;
+/**
+ * Advisory should-not-merge prose (#3225) — reviewer bots often record a block
+ * only in comment body text without formal Changes-Requested. Patterns are
+ * applied after code-fence strip; case-insensitive. Composes with
+ * minGreptileConfidence (#3095): either signal alone is blocking.
+ *
+ * Matching is scoped to **verdict-bearing regions** (Confidence Score detail /
+ * heading sections, Summary:/Decision: lines) so descriptive overview prose
+ * that names the detector phrases ("adds should-not-merge parsing") does not
+ * false-block a clean review (Greptile residual on PR #3227 / #1004 class).
+ */
+const ADVISORY_SHOULD_NOT_MERGE_RES = [
+    // "not safe to merge" | "not yet safe to merge"
+    /\bnot\s+(?:yet\s+)?safe\s+to\s+merge\b/i,
+    // should-not-merge | should not merge | should–not–merge (hyphen optional each side)
+    /\bshould\s*[-–—]?\s*not\s*[-–—]?\s*merge\b/i,
+    /\bsafe\s+to\s+merge\s+once\s+corrected\b/i,
+    /\bdo\s+not\s+merge\b/i,
+    /\bnot\s+ready\s+to\s+merge\b/i,
+    /\bnot\s+ready\s+for\s+merge\b/i,
+];
+/**
+ * High-signal phrases scanned outside Overview tables after fence strip.
+ * Soft phrases (do not merge / should not merge with spaces) stay region-only
+ * so explanatory Confidence residual prose naming the detector does not thrash
+ * indefinitely (#2881 / PR #3227 conf 4 residual).
+ */
+const ADVISORY_HIGH_SIGNAL_RES = [
+    /\bnot\s+(?:yet\s+)?safe\s+to\s+merge\b/i,
+    /\bshould-not-merge\b/i,
+    /\bsafe\s+to\s+merge\s+once\s+corrected\b/i,
+];
 const NAIVE_INLINE_SHA_RE = /Last reviewed commit:\s*([0-9a-f]{7,40})/;
 const MARKDOWN_LINK_SHA_RE = /Last reviewed commit:\s*\[.*?\]\(https?:\/\/github\.com\/[^/]+\/[^/]+\/commit\/(?<sha>[0-9a-f]{7,40})/;
 function lineFor(body, pos) {
@@ -27,6 +59,109 @@ export function parseConfidence(body) {
     }
     return m ? Number.parseInt(m[1] ?? "0", 10) : null;
 }
+/**
+ * Extract verdict-bearing text windows from a bot rolling-summary body (#3225).
+ * Prefers Confidence Score sections and Summary:/Decision: lines over whole-body
+ * Overview tables that may *describe* advisory phrases without issuing them.
+ */
+export function extractAdvisoryVerdictRegions(body) {
+    const text = stripCodeFences(body);
+    const regions = [];
+    // Per-details blocks only — do not span from Overview into Confidence Score.
+    for (const m of text.matchAll(/<details\b[^>]*>[\s\S]*?<\/details>/gi)) {
+        const block = m[0] ?? "";
+        if (/Confidence\s+Score/i.test(block)) {
+            regions.push(block);
+        }
+    }
+    for (const m of text.matchAll(/(?:^|\n)#{1,6}\s*Confidence\s+Score\s*:[^\n]*\n([\s\S]*?)(?=\n#{1,6}\s|\n<details\b|\n---\s*$|\n\*?\*?Last reviewed|\z)/gi)) {
+        regions.push(m[0] ?? "");
+    }
+    for (const m of text.matchAll(/(?:^|\n)(?:\*\*)?Confidence\s+Score(?:\*\*)?\s*:\s*\d+\s*\/\s*5[^\n]*\n([\s\S]{0,800})/gi)) {
+        regions.push(m[0] ?? "");
+    }
+    for (const m of text.matchAll(/(?:^|\n)(?:Summary|Decision|Verdict)\s*:\s*([^\n]+(?:\n(?![A-Z][^\n]{0,40}:)[^\n]+)*)/gi)) {
+        regions.push(m[0] ?? "");
+    }
+    return regions.filter((r) => r.trim().length > 0).join("\n\n");
+}
+function anyPatternMatches(text, patterns) {
+    return patterns.some((re) => {
+        re.lastIndex = 0;
+        return re.test(text);
+    });
+}
+/**
+ * True when a line is a **verdict-shaped** advisory phrase (#3225 residual).
+ * Requires the match near the start of the line (after optional Summary:/Decision:
+ * label, bullet, or bold). Mid-sentence descriptive mentions
+ * ("adds should-not-merge parsing", "The PR is not yet safe to merge because…")
+ * do not count — those are residual discussion, not the bot's verdict line.
+ */
+function lineHasAnchoredAdvisory(line, patterns) {
+    let bare = line.trim();
+    // Blockquote / common markdown wrappers Greptile residual (PR #3227 conf 4).
+    bare = bare.replace(/^>\s*/, "");
+    bare = bare.replace(/^(?:Summary|Decision|Verdict)\s*[:\-–—]\s*/i, "");
+    bare = bare.replace(/^(?:[-*•]\s+)+/, "");
+    bare = bare.replace(/^\*\*/, "").replace(/\*\*$/, "");
+    bare = bare.replace(/^_/, "").replace(/_$/, "");
+    // Explicit subject-prefixed verdicts Greptile uses: "The PR is not safe to merge…"
+    bare = bare.replace(/^(?:the\s+pr|this\s+pr|this\s+change|the\s+change|this\s+diff)\s+is\s+/i, "");
+    bare = bare.trim();
+    if (bare.length === 0) {
+        return false;
+    }
+    for (const re of patterns) {
+        re.lastIndex = 0;
+        const m = re.exec(bare);
+        // Allow small lead-in after wrappers (em-dash residual, thin markdown).
+        if (m !== null && (m.index ?? 0) <= 4) {
+            return true;
+        }
+    }
+    return false;
+}
+function textHasAnchoredAdvisory(text, patterns) {
+    for (const line of text.split(/\r?\n/)) {
+        if (lineHasAnchoredAdvisory(line, patterns)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when comment body prose records an advisory should-not-merge / not-safe
+ * verdict (#3225). Code-fence regions are stripped first so detector docs do
+ * not self-trigger (#1004).
+ *
+ * Line-anchored hybrid scan (PR #3227 residuals):
+ * 1. Soft + high-signal **line-anchored** phrases in Confidence / Summary /
+ *    Decision regions (and whole body)
+ * 2. Same line-anchored high-signal set on whole body (standalone warnings)
+ * Mid-sentence residual discussion does not hard-block; conf floor still does (#3095).
+ */
+export function hasShouldNotMergeProse(body) {
+    const text = stripCodeFences(body);
+    const regions = extractAdvisoryVerdictRegions(body);
+    if (regions.length > 0 && textHasAnchoredAdvisory(regions, ADVISORY_SHOULD_NOT_MERGE_RES)) {
+        return true;
+    }
+    // Soft + high line-anchored anywhere (covers standalone spaced Do not merge /
+    // should not merge outside Confidence regions without Overview mid-sentence hits).
+    if (textHasAnchoredAdvisory(text, ADVISORY_SHOULD_NOT_MERGE_RES)) {
+        return true;
+    }
+    return false;
+}
+export function parseAdvisoryReviewerVerdict(body) {
+    const findings = detect(body);
+    return {
+        confidence: parseConfidence(body),
+        shouldNotMerge: hasShouldNotMergeProse(body),
+        hasBlocking: findings.has_blocking,
+    };
+}
 export function detect(body) {
     body = stripCodeFences(body);
     const tier1_p0 = (body.match(/<img alt="P0"/g) ?? []).length;
@@ -59,10 +194,9 @@ export function detect(body) {
             tier25_p1 += 1;
         }
     }
-    let tier3_sentinel = false;
-    if (body.includes("Not safe to merge")) {
-        tier3_sentinel = true;
-    }
+    // Tier 3: advisory should-not-merge prose (#3225 extends "Not safe to merge")
+    // plus count-prose and line-anchored P0/P1 sentinels (#910).
+    let tier3_sentinel = hasShouldNotMergeProse(body);
     if (!tier3_sentinel) {
         for (const m of body.matchAll(TIER3_COUNT_RE)) {
             const line = lineFor(body, m.index ?? 0);
@@ -133,6 +267,70 @@ Last reviewed commit: [refactor: thing](https://github.com/deftai/directive/comm
 Summary: Not safe to merge until the mocked-import test defect and the two
 previously filed P1s are resolved.
 `;
+/** #3225 live-case shape: conf 3/5 + should-not-merge prose, zero badges. */
+export const BODY_ADVISORY_SHOULD_NOT_MERGE_CONF3 = `Greptile review of head advisory01
+
+## Confidence Score: 3/5
+
+Summary: should-not-merge — residual risk on the auth path is too high for
+this change set. Formal review state is still Comment (not Changes Requested).
+
+Last reviewed commit: [feat: advisory](https://github.com/deftai/directive/commit/advisory01abcdef12)
+`;
+/** Green mechanical path trap: high conf but explicit do-not-merge prose. */
+export const BODY_ADVISORY_DO_NOT_MERGE_HIGH_CONF = `Greptile review of head advisory02
+
+Confidence Score: 5/5
+
+No P0 or P1 issues found via badges.
+
+Summary: Do not merge until the operator documents residual risk.
+
+Last reviewed commit: [docs: note](https://github.com/deftai/directive/commit/advisory02abcdef12)
+`;
+/**
+ * Overview prose names the detector phrase without issuing a verdict (#3225 residual).
+ * Confidence section is clean — must NOT set shouldNotMerge.
+ */
+export const BODY_ADVISORY_DESCRIPTIVE_ONLY = `Greptile review of head advisory03
+
+<details><summary><h3>Greptile Summary</h3></summary>
+
+This PR adds should-not-merge prose detection and Not safe to merge matching to
+merge-ready. Descriptive overview only — no blocking residual on the product path.
+
+</details>
+
+<details open><summary><h3>Confidence Score: 5/5</h3></summary>
+
+No P0 or P1 issues found. The change looks clean and well-tested.
+
+</details>
+
+Last reviewed commit: [feat: detector](https://github.com/deftai/directive/commit/advisory03abcdef12)
+`;
+/** Standalone high-signal warning outside Confidence section must still block. */
+export const BODY_ADVISORY_STANDALONE_NOT_SAFE = `Greptile review of head advisory04
+
+<details open><summary><h3>Confidence Score: 5/5</h3></summary>
+
+Looks solid from a findings perspective.
+
+</details>
+
+Not safe to merge until the operator confirms residual risk handling.
+
+Last reviewed commit: [feat: residual](https://github.com/deftai/directive/commit/advisory04abcdef12)
+`;
+/** Subject-prefixed verdict Greptile commonly emits (#3225 residual). */
+export const BODY_ADVISORY_SUBJECT_PREFIXED = `Greptile review of head advisory05
+
+## Confidence Score: 4/5
+
+The PR is not safe to merge until residual risk is documented on the auth path.
+
+Last reviewed commit: [feat: subject](https://github.com/deftai/directive/commit/advisory05abcdef12)
+`;
 export const BODY_TIER3_COUNT_PROSE_ONLY = `Greptile review of head deadbeef
 
 Confidence Score: 4/5

package/dist/decision/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Structured agent decision log (#1396).
+ *
+ * CLI surface: task decision:write / task decision:list
+ */
+export { type DecisionListCliArgs, type DecisionListEntry, type DecisionListOptions, type DecisionListResult, decisionListMain, parseDecisionListArgs, runDecisionList, } from "./list.js";
+export { DECISION_FILE_SUFFIX, DECISION_SCHEMA_VERSION, DECISIONS_DIR_REL, type DecisionAlternative, type DecisionConfidence, type DecisionGoverningRule, type DecisionRecord, type DecisionValidationError, type DecisionValidationResult, datePrefixFromTimestamp, decisionFilename, formatDecisionValidationErrors, normalizeTimestamp, sanitizeForTerminal, slugifyDecision, validateDecisionRecord, } from "./schema.js";
+export { appendScopeDecisionPointer, type DecisionWriteCliArgs, type DecisionWriteInput, type DecisionWriteOutcome, type DecisionWriteResult, decisionWriteMain, parseDecisionWriteArgs, runDecisionWrite, } from "./write.js";
+/**
+ * Unified CLI entry for dispatch when verb is decision-write / decision-list.
+ * Expects first argv token to be the subcommand (write|list) when routed via
+ * a single decision stem; dispatch registers separate stems per verb.
+ */
+export declare function mainEntry(argv?: string[]): number;
+export declare function writeMainEntry(argv?: string[]): number;
+export declare function listMainEntry(argv?: string[]): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/decision/index.js

@@ -0,0 +1,35 @@
+/**
+ * Structured agent decision log (#1396).
+ *
+ * CLI surface: task decision:write / task decision:list
+ */
+import { decisionListMain } from "./list.js";
+import { decisionWriteMain } from "./write.js";
+export { decisionListMain, parseDecisionListArgs, runDecisionList, } from "./list.js";
+export { DECISION_FILE_SUFFIX, DECISION_SCHEMA_VERSION, DECISIONS_DIR_REL, datePrefixFromTimestamp, decisionFilename, formatDecisionValidationErrors, normalizeTimestamp, sanitizeForTerminal, slugifyDecision, validateDecisionRecord, } from "./schema.js";
+export { appendScopeDecisionPointer, decisionWriteMain, parseDecisionWriteArgs, runDecisionWrite, } from "./write.js";
+/**
+ * Unified CLI entry for dispatch when verb is decision-write / decision-list.
+ * Expects first argv token to be the subcommand (write|list) when routed via
+ * a single decision stem; dispatch registers separate stems per verb.
+ */
+export function mainEntry(argv = process.argv.slice(2)) {
+    const [head, ...rest] = argv;
+    if (head === "write" || head === "decision:write") {
+        return decisionWriteMain(rest);
+    }
+    if (head === "list" || head === "decision:list") {
+        return decisionListMain(rest);
+    }
+    // When dispatch loads decision-write / decision-list stems, argv has no head.
+    // Callers use decisionWriteMain / decisionListMain directly from loadCoreModuleHandler.
+    process.stderr.write("decision: unknown subcommand. Use decision:write or decision:list.\n");
+    return 2;
+}
+export function writeMainEntry(argv = process.argv.slice(2)) {
+    return decisionWriteMain(argv);
+}
+export function listMainEntry(argv = process.argv.slice(2)) {
+    return decisionListMain(argv);
+}
+//# sourceMappingURL=index.js.map

package/dist/decision/list.d.ts

@@ -0,0 +1,47 @@
+/**
+ * decision:list — find structured decision records (#1396).
+ */
+export interface DecisionListOptions {
+    readonly projectRoot?: string | null;
+    /** Filter by substring match on id, decision text, or tags. */
+    readonly query?: string | null;
+    /** Filter by scope path substring. */
+    readonly scope?: string | null;
+    /** Filter by related issue number. */
+    readonly issue?: number | null;
+    /** Max rows (default unlimited). */
+    readonly limit?: number | null;
+    readonly json?: boolean;
+}
+export interface DecisionListEntry {
+    readonly path: string;
+    readonly id: string;
+    readonly decision: string;
+    readonly confidence: string;
+    readonly timestamp: string;
+    readonly revisitTrigger: string;
+    readonly activeScopeRefs: readonly string[];
+    readonly tags: readonly string[];
+    readonly relatedIssues: readonly number[];
+}
+export interface DecisionListResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly entries: readonly DecisionListEntry[];
+    readonly message: string;
+}
+/** List decision records under xbrief/decisions/. */
+export declare function runDecisionList(options?: DecisionListOptions): DecisionListResult;
+export interface DecisionListCliArgs {
+    query?: string;
+    scope?: string;
+    issue?: number;
+    limit?: number;
+    json?: boolean;
+    projectRoot?: string;
+    error?: string;
+}
+/** Parse argv for decision:list. */
+export declare function parseDecisionListArgs(argv: readonly string[]): DecisionListCliArgs;
+/** CLI entry for decision:list. */
+export declare function decisionListMain(argv: readonly string[]): number;
+//# sourceMappingURL=list.d.ts.map