@deftai/directive-core 0.98.1 → 0.99.0

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

package/dist/decision/schema.js

@@ -0,0 +1,293 @@
+/**
+ * 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 const DECISION_SCHEMA_VERSION = "deft.decision.v1";
+/** Directory under project root for standalone (cross-cutting) decision files. */
+export const DECISIONS_DIR_REL = "xbrief/decisions";
+/** Filename suffix for decision records. */
+export const DECISION_FILE_SUFFIX = ".decision.json";
+const CONFIDENCE_VALUES = new Set(["low", "medium", "high"]);
+const RFC_VALUES = new Set([
+    "MUST",
+    "SHOULD",
+    "MAY",
+    "MUST NOT",
+    "SHOULD NOT",
+]);
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Normalize timestamps to second-precision UTC with trailing Z. */
+export function normalizeTimestamp(raw) {
+    if (raw !== undefined && raw !== null && raw.trim().length > 0) {
+        const parsed = new Date(raw.trim());
+        if (!Number.isNaN(parsed.getTime())) {
+            return parsed.toISOString().replace(/\.\d{3}Z$/, "Z");
+        }
+    }
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Derive a kebab-case slug from free text (max 64 chars).
+ * Linear-time (no polynomial regex) for CodeQL safety on library input.
+ */
+export function slugifyDecision(text) {
+    const lower = text.trim().toLowerCase();
+    let out = "";
+    let pendingHyphen = false;
+    for (let i = 0; i < lower.length && out.length < 64; i += 1) {
+        const ch = lower[i];
+        const code = ch.charCodeAt(0);
+        const isAlnum = (code >= 48 && code <= 57) || // 0-9
+            (code >= 97 && code <= 122); // a-z
+        if (isAlnum) {
+            if (pendingHyphen && out.length > 0) {
+                out += "-";
+                if (out.length >= 64)
+                    break;
+            }
+            out += ch;
+            pendingHyphen = false;
+        }
+        else {
+            pendingHyphen = true;
+        }
+    }
+    return out.length > 0 ? out : "decision";
+}
+/**
+ * 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 function sanitizeForTerminal(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        // Tab / LF / CR → space (never pass raw control layout to the terminal).
+        if (code === 9 || code === 10 || code === 13) {
+            out += " ";
+            continue;
+        }
+        // C0 + DEL
+        if (code < 32 || code === 127) {
+            continue;
+        }
+        // C1 controls (including when encoded as U+0080–U+009F)
+        if (code >= 0x80 && code <= 0x9f) {
+            continue;
+        }
+        // Bidi control characters (deceptive reordering)
+        // LRE/RLE/PDF/LRO/RLO, LRI/RLI/FSI/PDI, and related marks.
+        if (code === 0x061c || // ALM
+            code === 0x200e || // LRM
+            code === 0x200f || // RLM
+            (code >= 0x202a && code <= 0x202e) || // LRE..RLO
+            (code >= 0x2066 && code <= 0x2069) // LRI..PDI
+        ) {
+            continue;
+        }
+        out += text[i];
+    }
+    return out;
+}
+/** Date prefix YYYY-MM-DD from an ISO timestamp. */
+export function datePrefixFromTimestamp(timestamp) {
+    const m = timestamp.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m?.[1] ?? new Date().toISOString().slice(0, 10);
+}
+/** Build standalone filename: YYYY-MM-DD-<slug>.decision.json */
+export function decisionFilename(id, timestamp) {
+    const date = datePrefixFromTimestamp(timestamp);
+    const slug = slugifyDecision(id);
+    return `${date}-${slug}${DECISION_FILE_SUFFIX}`;
+}
+/** Validate and normalize an unknown JSON value into a DecisionRecord. */
+export function validateDecisionRecord(input) {
+    const errors = [];
+    if (!isPlainObject(input)) {
+        return { ok: false, errors: [{ field: "", message: "decision record must be a JSON object" }] };
+    }
+    const schemaVersion = input.schemaVersion;
+    if (schemaVersion !== undefined && schemaVersion !== DECISION_SCHEMA_VERSION) {
+        errors.push({
+            field: "schemaVersion",
+            message: `expected ${DECISION_SCHEMA_VERSION}, got ${String(schemaVersion)}`,
+        });
+    }
+    const decision = input.decision;
+    if (!nonEmptyString(decision)) {
+        errors.push({ field: "decision", message: "required non-empty string" });
+    }
+    let governingRule = null;
+    if (!isPlainObject(input.governingRule) && !nonEmptyString(input.governingRule)) {
+        errors.push({
+            field: "governingRule",
+            message: "required object { description, path?, rfc2119? } or non-empty string",
+        });
+    }
+    else if (nonEmptyString(input.governingRule)) {
+        governingRule = { description: input.governingRule.trim() };
+    }
+    else if (isPlainObject(input.governingRule)) {
+        const gr = input.governingRule;
+        if (!nonEmptyString(gr.description)) {
+            errors.push({ field: "governingRule.description", message: "required non-empty string" });
+        }
+        else {
+            let rfc2119 = null;
+            if (gr.rfc2119 !== undefined && gr.rfc2119 !== null) {
+                if (typeof gr.rfc2119 === "string" && RFC_VALUES.has(gr.rfc2119)) {
+                    rfc2119 = gr.rfc2119;
+                }
+                else {
+                    errors.push({
+                        field: "governingRule.rfc2119",
+                        message: `must be one of ${[...RFC_VALUES].join(", ")}`,
+                    });
+                }
+            }
+            governingRule = {
+                description: gr.description.trim(),
+                path: typeof gr.path === "string" && gr.path.trim().length > 0 ? gr.path.trim() : null,
+                rfc2119,
+            };
+        }
+    }
+    const alternativesRaw = input.alternativesConsidered ?? input.alternatives;
+    const alternatives = [];
+    if (!Array.isArray(alternativesRaw)) {
+        errors.push({
+            field: "alternativesConsidered",
+            message: "required array of { option, whyNot? } or strings",
+        });
+    }
+    else if (alternativesRaw.length === 0) {
+        errors.push({
+            field: "alternativesConsidered",
+            message: 'must include at least one alternative (use [{option:"none"}] if truly sole path)',
+        });
+    }
+    else {
+        for (let i = 0; i < alternativesRaw.length; i += 1) {
+            const alt = alternativesRaw[i];
+            if (nonEmptyString(alt)) {
+                alternatives.push({ option: alt.trim() });
+            }
+            else if (isPlainObject(alt) && nonEmptyString(alt.option)) {
+                alternatives.push({
+                    option: alt.option.trim(),
+                    whyNot: typeof alt.whyNot === "string" && alt.whyNot.trim().length > 0
+                        ? alt.whyNot.trim()
+                        : null,
+                });
+            }
+            else {
+                errors.push({
+                    field: `alternativesConsidered[${i}]`,
+                    message: "must be a non-empty string or { option, whyNot? }",
+                });
+            }
+        }
+    }
+    const whyWinner = input.whyWinner ?? input.why_winner;
+    if (!nonEmptyString(whyWinner)) {
+        errors.push({ field: "whyWinner", message: "required non-empty string" });
+    }
+    const confidenceRaw = input.confidence;
+    let confidence = null;
+    if (!nonEmptyString(confidenceRaw) ||
+        !CONFIDENCE_VALUES.has(confidenceRaw.trim().toLowerCase())) {
+        errors.push({ field: "confidence", message: "required: low | medium | high" });
+    }
+    else {
+        confidence = confidenceRaw.trim().toLowerCase();
+    }
+    const scopeRaw = input.activeScopeRefs ?? input.active_scope_refs ?? input.scopeRefs;
+    const activeScopeRefs = [];
+    if (scopeRaw === undefined || scopeRaw === null) {
+        // optional
+    }
+    else if (Array.isArray(scopeRaw)) {
+        for (let i = 0; i < scopeRaw.length; i += 1) {
+            const s = scopeRaw[i];
+            if (nonEmptyString(s)) {
+                activeScopeRefs.push(s.trim().replace(/\\/g, "/"));
+            }
+            else {
+                errors.push({ field: `activeScopeRefs[${i}]`, message: "must be a non-empty path string" });
+            }
+        }
+    }
+    else if (nonEmptyString(scopeRaw)) {
+        activeScopeRefs.push(scopeRaw.trim().replace(/\\/g, "/"));
+    }
+    else {
+        errors.push({
+            field: "activeScopeRefs",
+            message: "must be a string path, array of paths, or omitted",
+        });
+    }
+    const revisitTrigger = input.revisitTrigger ?? input.revisit_trigger;
+    if (!nonEmptyString(revisitTrigger)) {
+        errors.push({ field: "revisitTrigger", message: "required non-empty string" });
+    }
+    let timestamp = normalizeTimestamp(typeof input.timestamp === "string" ? input.timestamp : null);
+    if (typeof input.timestamp === "string" && input.timestamp.trim().length > 0) {
+        const parsed = new Date(input.timestamp.trim());
+        if (Number.isNaN(parsed.getTime())) {
+            errors.push({ field: "timestamp", message: "invalid ISO-8601 timestamp" });
+        }
+        else {
+            timestamp = normalizeTimestamp(input.timestamp);
+        }
+    }
+    const id = typeof input.id === "string" && input.id.trim().length > 0
+        ? slugifyDecision(input.id)
+        : slugifyDecision(typeof decision === "string" ? decision : "decision");
+    const tags = [];
+    if (Array.isArray(input.tags)) {
+        for (const t of input.tags) {
+            if (nonEmptyString(t))
+                tags.push(t.trim());
+        }
+    }
+    const relatedIssues = [];
+    if (Array.isArray(input.relatedIssues)) {
+        for (const n of input.relatedIssues) {
+            if (typeof n === "number" && Number.isInteger(n) && n > 0)
+                relatedIssues.push(n);
+            else if (typeof n === "string" && /^\d+$/.test(n.trim()))
+                relatedIssues.push(Number(n.trim()));
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const record = {
+        schemaVersion: DECISION_SCHEMA_VERSION,
+        id,
+        decision: decision.trim(),
+        governingRule: governingRule,
+        alternativesConsidered: alternatives,
+        whyWinner: whyWinner.trim(),
+        confidence: confidence,
+        activeScopeRefs,
+        timestamp,
+        revisitTrigger: revisitTrigger.trim(),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(relatedIssues.length > 0 ? { relatedIssues } : {}),
+    };
+    return { ok: true, errors: [], record };
+}
+/** Format validation errors for CLI stderr. */
+export function formatDecisionValidationErrors(errors) {
+    return errors.map((e) => (e.field ? `${e.field}: ${e.message}` : e.message)).join("\n");
+}
+//# sourceMappingURL=schema.js.map