@deftai/directive-core 0.98.1 → 0.100.0

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

package/dist/decision/list.js

@@ -0,0 +1,250 @@
+/**
+ * decision:list — find structured decision records (#1396).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveProjectRoot } from "../scope/project-context.js";
+import { DECISION_FILE_SUFFIX, DECISIONS_DIR_REL, sanitizeForTerminal, validateDecisionRecord, } from "./schema.js";
+function isDecisionFile(name) {
+    return name.endsWith(DECISION_FILE_SUFFIX);
+}
+function loadRecord(absPath, relPath) {
+    try {
+        const raw = readFileSync(absPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const validated = validateDecisionRecord(parsed);
+        if (!validated.ok || validated.record === undefined) {
+            return {
+                path: relPath,
+                id: "(invalid)",
+                decision: `unparseable: ${validated.errors.map((e) => e.message).join("; ")}`,
+                confidence: "?",
+                timestamp: "",
+                revisitTrigger: "",
+                activeScopeRefs: [],
+                tags: [],
+                relatedIssues: [],
+            };
+        }
+        const r = validated.record;
+        return {
+            path: relPath,
+            id: r.id,
+            decision: r.decision,
+            confidence: r.confidence,
+            timestamp: r.timestamp,
+            revisitTrigger: r.revisitTrigger,
+            activeScopeRefs: r.activeScopeRefs,
+            tags: r.tags ?? [],
+            relatedIssues: r.relatedIssues ?? [],
+        };
+    }
+    catch (err) {
+        return {
+            path: relPath,
+            id: "(error)",
+            decision: err instanceof Error ? err.message : String(err),
+            confidence: "?",
+            timestamp: "",
+            revisitTrigger: "",
+            activeScopeRefs: [],
+            tags: [],
+            relatedIssues: [],
+        };
+    }
+}
+function scanDecisionsDir(projectRoot) {
+    const dir = resolve(projectRoot, DECISIONS_DIR_REL);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    let names;
+    try {
+        names = readdirSync(dir).filter(isDecisionFile);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const abs = join(dir, name);
+        try {
+            if (!statSync(abs).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const rel = `${DECISIONS_DIR_REL}/${name}`.replace(/\\/g, "/");
+        const entry = loadRecord(abs, rel);
+        if (entry !== null)
+            entries.push(entry);
+    }
+    entries.sort((a, b) => {
+        if (a.timestamp === b.timestamp)
+            return a.path.localeCompare(b.path);
+        return a.timestamp < b.timestamp ? 1 : -1;
+    });
+    return entries;
+}
+function matchesFilters(entry, options) {
+    if (options.query !== undefined && options.query !== null && options.query.trim().length > 0) {
+        const q = options.query.trim().toLowerCase();
+        const hay = [
+            entry.id,
+            entry.decision,
+            entry.revisitTrigger,
+            ...entry.tags,
+            ...entry.activeScopeRefs,
+        ]
+            .join(" ")
+            .toLowerCase();
+        if (!hay.includes(q))
+            return false;
+    }
+    if (options.scope !== undefined && options.scope !== null && options.scope.trim().length > 0) {
+        const s = options.scope.trim().replace(/\\/g, "/").toLowerCase();
+        if (!entry.activeScopeRefs.some((r) => r.toLowerCase().includes(s)))
+            return false;
+    }
+    if (options.issue !== undefined && options.issue !== null) {
+        if (!entry.relatedIssues.includes(options.issue))
+            return false;
+    }
+    return true;
+}
+/** List decision records under xbrief/decisions/. */
+export function runDecisionList(options = {}) {
+    const projectRootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
+    if (projectRootRaw === null) {
+        return {
+            exitCode: 2,
+            entries: [],
+            message: "Error: could not resolve project root. Pass --project-root or run from a directive repo.\n",
+        };
+    }
+    const projectRoot = resolve(projectRootRaw);
+    let entries = scanDecisionsDir(projectRoot).filter((e) => matchesFilters(e, options));
+    if (options.limit !== undefined && options.limit !== null && options.limit > 0) {
+        entries = entries.slice(0, options.limit);
+    }
+    if (entries.length === 0) {
+        return {
+            exitCode: 0,
+            entries: [],
+            message: `No decision records under ${DECISIONS_DIR_REL}/.\n`,
+        };
+    }
+    const lines = entries.map((e) => {
+        const scopes = e.activeScopeRefs.length > 0
+            ? ` scope=${sanitizeForTerminal(e.activeScopeRefs.join(","))}`
+            : "";
+        const tags = e.tags.length > 0 ? ` tags=${sanitizeForTerminal(e.tags.join(","))}` : "";
+        return (`${sanitizeForTerminal(e.path)}\n` +
+            `  ${sanitizeForTerminal(e.decision)}\n` +
+            `  confidence=${sanitizeForTerminal(e.confidence)} ts=${sanitizeForTerminal(e.timestamp)}` +
+            `${scopes}${tags}\n` +
+            `  revisit: ${sanitizeForTerminal(e.revisitTrigger)}`);
+    });
+    return {
+        exitCode: 0,
+        entries,
+        message: `${lines.join("\n\n")}\n`,
+    };
+}
+/** Parse argv for decision:list. */
+export function parseDecisionListArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json")
+            out.json = true;
+        else if (arg === "--query" || arg.startsWith("--query=")) {
+            if (arg === "--query")
+                out.query = argv[++i];
+            else
+                out.query = arg.slice("--query=".length);
+        }
+        else if (arg === "--scope" || arg.startsWith("--scope=")) {
+            if (arg === "--scope")
+                out.scope = argv[++i];
+            else
+                out.scope = arg.slice("--scope=".length);
+        }
+        else if (arg === "--issue" || arg.startsWith("--issue=")) {
+            const raw = arg === "--issue" ? argv[++i] : arg.slice("--issue=".length);
+            if (raw === undefined || raw.trim().length === 0 || raw.startsWith("-")) {
+                return { ...out, error: "--issue requires a positive integer" };
+            }
+            if (!/^\d+$/.test(raw.trim())) {
+                return { ...out, error: `--issue must be a positive integer, got: ${raw}` };
+            }
+            const n = Number(raw.trim());
+            if (!Number.isSafeInteger(n) || n <= 0) {
+                return {
+                    ...out,
+                    error: `--issue must be a safe positive integer (<= ${Number.MAX_SAFE_INTEGER}), got: ${raw}`,
+                };
+            }
+            out.issue = n;
+        }
+        else if (arg === "--limit" || arg.startsWith("--limit=")) {
+            const raw = arg === "--limit" ? argv[++i] : arg.slice("--limit=".length);
+            if (raw === undefined || raw.trim().length === 0 || raw.startsWith("-")) {
+                return { ...out, error: "--limit requires a positive integer" };
+            }
+            if (!/^\d+$/.test(raw.trim())) {
+                return { ...out, error: `--limit must be a positive integer, got: ${raw}` };
+            }
+            const n = Number(raw.trim());
+            if (!Number.isSafeInteger(n) || n <= 0) {
+                return {
+                    ...out,
+                    error: `--limit must be a safe positive integer (<= ${Number.MAX_SAFE_INTEGER}), got: ${raw}`,
+                };
+            }
+            out.limit = n;
+        }
+        else if (arg === "--project-root" || arg.startsWith("--project-root=")) {
+            if (arg === "--project-root")
+                out.projectRoot = argv[++i];
+            else
+                out.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg.startsWith("-")) {
+            return { ...out, error: `unrecognized argument: ${arg}` };
+        }
+        else if (out.query === undefined) {
+            out.query = arg;
+        }
+    }
+    return out;
+}
+/** CLI entry for decision:list. */
+export function decisionListMain(argv) {
+    const args = parseDecisionListArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`decision:list: ${args.error}\n`);
+        return 2;
+    }
+    const result = runDecisionList({
+        projectRoot: args.projectRoot,
+        query: args.query,
+        scope: args.scope,
+        issue: args.issue,
+        limit: args.limit,
+        json: args.json,
+    });
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify({
+            exit_code: result.exitCode,
+            count: result.entries.length,
+            entries: result.entries,
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(result.message);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=list.js.map

package/dist/decision/schema.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Lightweight structured agent decision log schema (#1396).
+ *
+ * Intent-debt records for significant choices only. Not a full lifecycle xBRIEF
+ * and not a replacement for docs/decisions/ADR-*.md.
+ */
+export declare const DECISION_SCHEMA_VERSION: "deft.decision.v1";
+/** Directory under project root for standalone (cross-cutting) decision files. */
+export declare const DECISIONS_DIR_REL = "xbrief/decisions";
+/** Filename suffix for decision records. */
+export declare const DECISION_FILE_SUFFIX = ".decision.json";
+export type DecisionConfidence = "low" | "medium" | "high";
+/** Governing rule or constraint that informed the decision. */
+export interface DecisionGoverningRule {
+    /** Human-readable description of the rule/constraint. */
+    readonly description: string;
+    /** Path to the rule source (skill, docs, AGENTS.md section, issue). */
+    readonly path?: string | null;
+    /** RFC2119 tier when the rule is MUST/SHOULD/MAY style. */
+    readonly rfc2119?: "MUST" | "SHOULD" | "MAY" | "MUST NOT" | "SHOULD NOT" | null;
+}
+/** One alternative considered and not chosen. */
+export interface DecisionAlternative {
+    readonly option: string;
+    readonly whyNot?: string | null;
+}
+/**
+ * Validated decision record (v1).
+ *
+ * Required fields per #1396 design lock: decision, governing rule/constraint,
+ * alternatives considered, why winner, confidence, active scope ref(s) if any,
+ * timestamp, revisit trigger.
+ */
+export interface DecisionRecord {
+    readonly schemaVersion: typeof DECISION_SCHEMA_VERSION;
+    /** Stable slug used in the filename (kebab-case). */
+    readonly id: string;
+    /** One-line or short paragraph of what was decided. */
+    readonly decision: string;
+    readonly governingRule: DecisionGoverningRule;
+    readonly alternativesConsidered: readonly DecisionAlternative[];
+    /** Why the chosen option won over the alternatives. */
+    readonly whyWinner: string;
+    readonly confidence: DecisionConfidence;
+    /** Relative path(s) to related scope xBRIEF(s), if any. */
+    readonly activeScopeRefs: readonly string[];
+    /** ISO-8601 UTC timestamp (second precision preferred). */
+    readonly timestamp: string;
+    /** When/why a later agent should re-open this decision. */
+    readonly revisitTrigger: string;
+    /** Optional tags for list filtering. */
+    readonly tags?: readonly string[];
+    /** Optional related issue numbers (without #). */
+    readonly relatedIssues?: readonly number[];
+    /** Relative path of the written file (filled after write). */
+    readonly path?: string;
+}
+export interface DecisionValidationError {
+    readonly field: string;
+    readonly message: string;
+}
+export interface DecisionValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly DecisionValidationError[];
+    readonly record?: DecisionRecord;
+}
+/** Normalize timestamps to second-precision UTC with trailing Z. */
+export declare function normalizeTimestamp(raw?: string | null): string;
+/**
+ * Derive a kebab-case slug from free text (max 64 chars).
+ * Linear-time (no polynomial regex) for CodeQL safety on library input.
+ */
+export declare function slugifyDecision(text: string): string;
+/**
+ * Strip terminal / bidi control chars for safe plaintext list rendering.
+ * Drops C0 (except tab/LF/CR → space), DEL, C1 (U+0080–U+009F), and
+ * Unicode bidi overrides / isolates / embeddings used for deceptive reordering.
+ */
+export declare function sanitizeForTerminal(text: string): string;
+/** Date prefix YYYY-MM-DD from an ISO timestamp. */
+export declare function datePrefixFromTimestamp(timestamp: string): string;
+/** Build standalone filename: YYYY-MM-DD-<slug>.decision.json */
+export declare function decisionFilename(id: string, timestamp: string): string;
+/** Validate and normalize an unknown JSON value into a DecisionRecord. */
+export declare function validateDecisionRecord(input: unknown): DecisionValidationResult;
+/** Format validation errors for CLI stderr. */
+export declare function formatDecisionValidationErrors(errors: readonly DecisionValidationError[]): string;
+//# sourceMappingURL=schema.d.ts.map