@deftai/directive-core 0.98.1 → 0.100.0

package/dist/decision/write.js

@@ -0,0 +1,427 @@
+/**
+ * decision:write — create a lightweight structured decision record (#1396).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
+import { resolveProjectRoot } from "../scope/project-context.js";
+import { DECISIONS_DIR_REL, decisionFilename, formatDecisionValidationErrors, normalizeTimestamp, slugifyDecision, validateDecisionRecord, } from "./schema.js";
+function loadBodyFile(bodyFile, projectRoot) {
+    const abs = resolve(bodyFile.startsWith(".") ? join(projectRoot, bodyFile) : bodyFile);
+    const text = readFileSync(abs, "utf8");
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("body file must contain a JSON object");
+    }
+    return parsed;
+}
+function mergeInput(options, projectRoot) {
+    let base = {};
+    if (options.bodyFile !== undefined && options.bodyFile.trim().length > 0) {
+        base = loadBodyFile(options.bodyFile.trim(), projectRoot);
+    }
+    const out = { ...base };
+    if (options.decision !== undefined)
+        out.decision = options.decision;
+    if (options.governingRule !== undefined)
+        out.governingRule = options.governingRule;
+    if (options.alternatives !== undefined)
+        out.alternativesConsidered = options.alternatives;
+    if (options.whyWinner !== undefined)
+        out.whyWinner = options.whyWinner;
+    if (options.confidence !== undefined)
+        out.confidence = options.confidence;
+    if (options.revisitTrigger !== undefined)
+        out.revisitTrigger = options.revisitTrigger;
+    if (options.id !== undefined)
+        out.id = options.id;
+    if (options.timestamp !== undefined)
+        out.timestamp = options.timestamp;
+    if (options.tags !== undefined)
+        out.tags = options.tags;
+    if (options.relatedIssues !== undefined)
+        out.relatedIssues = options.relatedIssues;
+    if (options.scope !== undefined) {
+        const scopes = Array.isArray(options.scope) ? options.scope : [options.scope];
+        out.activeScopeRefs = scopes.map((s) => s.replace(/\\/g, "/"));
+    }
+    return out;
+}
+/**
+ * Append a pointer line to plan.narratives.Decisions on a scope xBRIEF without
+ * removing existing narratives (validators accept unknown narrative keys as strings).
+ *
+ * Concurrent writers: read-modify-replace with post-write verify + retry so a
+ * later attach does not silently drop an earlier decision pointer.
+ */
+export function appendScopeDecisionPointer(projectRoot, scopeRelPath, decisionRelPath, decisionSummary) {
+    const scopeAbs = resolve(projectRoot, scopeRelPath);
+    if (!existsSync(scopeAbs)) {
+        throw new Error(`scope xBRIEF not found: ${scopeRelPath}`);
+    }
+    const pointerNeedle = decisionRelPath;
+    const maxAttempts = 4;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const raw = readFileSync(scopeAbs, "utf8");
+        const doc = JSON.parse(raw);
+        if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+            throw new Error(`invalid scope xBRIEF JSON: ${scopeRelPath}`);
+        }
+        const plan = doc.plan;
+        if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+            throw new Error(`scope xBRIEF missing plan: ${scopeRelPath}`);
+        }
+        const narrativesRaw = plan.narratives;
+        const narratives = narrativesRaw !== null && typeof narrativesRaw === "object" && !Array.isArray(narrativesRaw)
+            ? { ...narrativesRaw }
+            : {};
+        const pointer = `- ${decisionRelPath} — ${decisionSummary}`;
+        const existing = typeof narratives.Decisions === "string" ? narratives.Decisions.trim() : "";
+        if (existing.includes(pointerNeedle)) {
+            return;
+        }
+        narratives.Decisions = existing.length > 0 ? `${existing}\n${pointer}` : pointer;
+        plan.narratives = narratives;
+        const data = `${JSON.stringify(doc, null, 2)}\n`;
+        containedWrite({
+            root: resolve(projectRoot),
+            target: scopeAbs,
+            data,
+            mode: "replace",
+        });
+        // Verify pointer survived concurrent replace.
+        try {
+            const verifyRaw = readFileSync(scopeAbs, "utf8");
+            const verifyDoc = JSON.parse(verifyRaw);
+            const vPlan = verifyDoc?.plan;
+            const vNarr = vPlan?.narratives;
+            const vDec = typeof vNarr?.Decisions === "string" ? vNarr.Decisions : "";
+            if (vDec.includes(pointerNeedle)) {
+                return;
+            }
+        }
+        catch {
+            // retry
+        }
+    }
+    throw new Error(`failed to attach decision pointer to ${scopeRelPath} after ${maxAttempts} attempts ` +
+        `(concurrent writers may be contending on plan.narratives.Decisions)`);
+}
+/** Write a validated decision record to disk (standalone + optional scope pointer). */
+export function runDecisionWrite(options) {
+    const projectRootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
+    if (projectRootRaw === null) {
+        return {
+            outcome: "error-config",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: "Error: could not resolve project root. Pass --project-root or run from a directive repo.\n",
+        };
+    }
+    const projectRoot = resolve(projectRootRaw);
+    let merged;
+    try {
+        merged = mergeInput(options, projectRoot);
+    }
+    catch (err) {
+        return {
+            outcome: "error-bad-args",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: `Error: failed to load body file: ${err instanceof Error ? err.message : String(err)}\n`,
+        };
+    }
+    const validated = validateDecisionRecord(merged);
+    if (!validated.ok || validated.record === undefined) {
+        return {
+            outcome: "error-bad-args",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: `Error: invalid decision record:\n${formatDecisionValidationErrors(validated.errors)}\n`,
+        };
+    }
+    const record = validated.record;
+    const filename = decisionFilename(record.id, record.timestamp);
+    const relPath = join(DECISIONS_DIR_REL, filename).replace(/\\/g, "/");
+    const absPath = resolve(projectRoot, relPath);
+    const recordOut = {
+        ...record,
+        path: relPath,
+    };
+    if (options.dryRun) {
+        return {
+            outcome: "written",
+            exitCode: 0,
+            path: relPath,
+            scopePath: record.activeScopeRefs[0] ?? null,
+            record: recordOut,
+            message: `[dry-run] would write ${relPath}\n`,
+        };
+    }
+    try {
+        mkdirSync(dirname(absPath), { recursive: true });
+        if (existsSync(absPath) && options.force !== true) {
+            return {
+                outcome: "error-io",
+                exitCode: 2,
+                path: relPath,
+                scopePath: null,
+                record: recordOut,
+                message: `Error: decision file already exists: ${relPath}\n` +
+                    "  Refusing to overwrite (would destroy prior rationale). " +
+                    "Pass --force to replace, or use a distinct --id / decision text.\n",
+            };
+        }
+        const data = `${JSON.stringify({
+            schemaVersion: recordOut.schemaVersion,
+            id: recordOut.id,
+            decision: recordOut.decision,
+            governingRule: recordOut.governingRule,
+            alternativesConsidered: recordOut.alternativesConsidered,
+            whyWinner: recordOut.whyWinner,
+            confidence: recordOut.confidence,
+            activeScopeRefs: recordOut.activeScopeRefs,
+            timestamp: recordOut.timestamp,
+            revisitTrigger: recordOut.revisitTrigger,
+            ...(recordOut.tags !== undefined ? { tags: recordOut.tags } : {}),
+            ...(recordOut.relatedIssues !== undefined
+                ? { relatedIssues: recordOut.relatedIssues }
+                : {}),
+        }, null, 2)}\n`;
+        // Prefer exclusive create unless --force. Concurrent writers that both
+        // pass the pre-check still fail closed via create/EXISTS instead of replace.
+        containedWrite({
+            root: projectRoot,
+            target: absPath,
+            data,
+            mode: options.force === true ? "replace" : "create",
+        });
+        let scopePath = null;
+        if (record.activeScopeRefs.length > 0 && options.standalone !== true) {
+            const scopeRel = record.activeScopeRefs[0];
+            try {
+                appendScopeDecisionPointer(projectRoot, scopeRel, relPath, record.decision);
+                scopePath = scopeRel;
+            }
+            catch (err) {
+                return {
+                    outcome: "error-io",
+                    exitCode: 2,
+                    path: relPath,
+                    scopePath: null,
+                    record: recordOut,
+                    message: `[deft decision] Wrote ${relPath} but failed to attach scope pointer: ` +
+                        `${err instanceof Error ? err.message : String(err)}\n`,
+                };
+            }
+        }
+        const scopeNote = scopePath !== null ? ` (linked from ${scopePath})` : "";
+        return {
+            outcome: "written",
+            exitCode: 0,
+            path: relPath,
+            scopePath,
+            record: recordOut,
+            message: `[deft decision] Wrote ${relPath}${scopeNote}\n`,
+        };
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError || err instanceof ProjectionContainmentError) {
+            return {
+                outcome: "error-io",
+                exitCode: 2,
+                path: null,
+                scopePath: null,
+                record: recordOut,
+                message: `Error: contained write refused: ${err.message}\n`,
+            };
+        }
+        return {
+            outcome: "error-io",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: recordOut,
+            message: `Error: write failed: ${err instanceof Error ? err.message : String(err)}\n`,
+        };
+    }
+}
+/** Parse argv for decision:write. */
+export function parseDecisionWriteArgs(argv) {
+    const out = {};
+    const positionals = [];
+    const takeValue = (i, flag, eqPrefix) => {
+        const arg = argv[i];
+        if (arg === flag) {
+            return [argv[i + 1], i + 1];
+        }
+        if (arg.startsWith(eqPrefix)) {
+            return [arg.slice(eqPrefix.length), i];
+        }
+        return [undefined, i];
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run")
+            out.dryRun = true;
+        else if (arg === "--json")
+            out.json = true;
+        else if (arg === "--standalone")
+            out.standalone = true;
+        else if (arg === "--force")
+            out.force = true;
+        else if (arg === "--decision" || arg.startsWith("--decision=")) {
+            const [v, ni] = takeValue(i, "--decision", "--decision=");
+            out.decision = v;
+            i = ni;
+        }
+        else if (arg === "--governing-rule" || arg.startsWith("--governing-rule=")) {
+            const [v, ni] = takeValue(i, "--governing-rule", "--governing-rule=");
+            out.governingRule = v;
+            i = ni;
+        }
+        else if (arg === "--governing-path" || arg.startsWith("--governing-path=")) {
+            const [v, ni] = takeValue(i, "--governing-path", "--governing-path=");
+            out.governingPath = v;
+            i = ni;
+        }
+        else if (arg === "--governing-rfc" || arg.startsWith("--governing-rfc=")) {
+            const [v, ni] = takeValue(i, "--governing-rfc", "--governing-rfc=");
+            out.governingRfc = v;
+            i = ni;
+        }
+        else if (arg === "--alternative" || arg.startsWith("--alternative=")) {
+            const [v, ni] = takeValue(i, "--alternative", "--alternative=");
+            if (v !== undefined) {
+                out.alternatives = [...(out.alternatives ?? []), v];
+            }
+            i = ni;
+        }
+        else if (arg === "--why-winner" || arg.startsWith("--why-winner=")) {
+            const [v, ni] = takeValue(i, "--why-winner", "--why-winner=");
+            out.whyWinner = v;
+            i = ni;
+        }
+        else if (arg === "--confidence" || arg.startsWith("--confidence=")) {
+            const [v, ni] = takeValue(i, "--confidence", "--confidence=");
+            out.confidence = v;
+            i = ni;
+        }
+        else if (arg === "--scope" || arg.startsWith("--scope=")) {
+            const [v, ni] = takeValue(i, "--scope", "--scope=");
+            if (v !== undefined) {
+                out.scope = [...(out.scope ?? []), v];
+            }
+            i = ni;
+        }
+        else if (arg === "--revisit-trigger" || arg.startsWith("--revisit-trigger=")) {
+            const [v, ni] = takeValue(i, "--revisit-trigger", "--revisit-trigger=");
+            out.revisitTrigger = v;
+            i = ni;
+        }
+        else if (arg === "--id" || arg.startsWith("--id=")) {
+            const [v, ni] = takeValue(i, "--id", "--id=");
+            out.id = v;
+            i = ni;
+        }
+        else if (arg === "--timestamp" || arg.startsWith("--timestamp=")) {
+            const [v, ni] = takeValue(i, "--timestamp", "--timestamp=");
+            out.timestamp = v;
+            i = ni;
+        }
+        else if (arg === "--tag" || arg.startsWith("--tag=")) {
+            const [v, ni] = takeValue(i, "--tag", "--tag=");
+            if (v !== undefined)
+                out.tags = [...(out.tags ?? []), v];
+            i = ni;
+        }
+        else if (arg === "--related-issue" || arg.startsWith("--related-issue=")) {
+            const [v, ni] = takeValue(i, "--related-issue", "--related-issue=");
+            if (v !== undefined && /^\d+$/.test(v.trim())) {
+                out.relatedIssues = [...(out.relatedIssues ?? []), Number(v.trim())];
+            }
+            i = ni;
+        }
+        else if (arg === "--body-file" || arg.startsWith("--body-file=")) {
+            const [v, ni] = takeValue(i, "--body-file", "--body-file=");
+            out.bodyFile = v;
+            i = ni;
+        }
+        else if (arg === "--project-root" || arg.startsWith("--project-root=")) {
+            const [v, ni] = takeValue(i, "--project-root", "--project-root=");
+            out.projectRoot = v;
+            i = ni;
+        }
+        else if (arg.startsWith("-")) {
+            return { ...out, error: `unrecognized argument: ${arg}` };
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if ((out.decision === undefined || out.decision.trim().length === 0) && positionals.length > 0) {
+        out.decision = positionals.join(" ");
+    }
+    return out;
+}
+/** CLI entry for decision:write. */
+export function decisionWriteMain(argv) {
+    const args = parseDecisionWriteArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`decision:write: ${args.error}\n`);
+        return 2;
+    }
+    const governingRule = args.governingRule !== undefined
+        ? {
+            description: args.governingRule,
+            path: args.governingPath,
+            rfc2119: args.governingRfc,
+        }
+        : undefined;
+    const result = runDecisionWrite({
+        decision: args.decision,
+        governingRule,
+        alternatives: args.alternatives,
+        whyWinner: args.whyWinner,
+        confidence: args.confidence,
+        scope: args.scope,
+        revisitTrigger: args.revisitTrigger,
+        id: args.id,
+        timestamp: args.timestamp ?? normalizeTimestamp(),
+        tags: args.tags,
+        relatedIssues: args.relatedIssues,
+        bodyFile: args.bodyFile,
+        standalone: args.standalone,
+        force: args.force,
+        dryRun: args.dryRun,
+        json: args.json,
+        projectRoot: args.projectRoot,
+    });
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify({
+            outcome: result.outcome,
+            exit_code: result.exitCode,
+            path: result.path,
+            scope_path: result.scopePath,
+            record: result.record,
+            message: result.message.trim(),
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(result.message);
+    }
+    return result.exitCode;
+}
+/** Relative path helper for tests. */
+export function relativeToProject(projectRoot, absPath) {
+    return relative(projectRoot, absPath).replace(/\\/g, "/");
+}
+export { slugifyDecision };
+//# sourceMappingURL=write.js.map

package/dist/doctor/checks.d.ts

@@ -1,9 +1,42 @@
+import type { XbriefSchemaDistance } from "../staleness-tickler/types.js";
 import type { CheckResult } from "./types.js";
+/** Remediation verb for project envelope behind-major (#2971 / #3243 / #3236). */
+export declare const XBRIEF_ENVELOPE_MIGRATE_COMMAND: "deft migrate:xbrief";
+/** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
+export declare const XBRIEF_ENVELOPE_MAJOR_CHECK: "xbrief-envelope-version";
 export interface CheckSeams {
     readonly readText?: (path: string) => string | null;
     readonly isFile?: (path: string) => boolean;
     readonly isDir?: (path: string) => boolean;
+    /** List directory entries; throws on enum failure (fail-closed for live lifecycle dirs). */
+    readonly readdir?: (path: string) => string[];
 }
+/** One scanned project envelope and its schema distance vs the framework target. */
+export interface XbriefEnvelopeScanEntry {
+    readonly relativePath: string;
+    readonly declaredVersion: string | null;
+    readonly distance: XbriefSchemaDistance;
+}
+/**
+ * Scan live project xbrief envelopes (PROJECT-DEFINITION + pending/active) for
+ * schema distance vs the installed framework envelope major (#3243). Complements
+ * #2971 PROJECT-DEFINITION-only probe; remediation aligns with migrate hybrid
+ * rewrite (#3236).
+ */
+export declare function scanXbriefEnvelopeVersions(projectRoot: string, seams?: CheckSeams, targetVersion?: string): {
+    readonly targetVersion: string;
+    readonly entries: readonly XbriefEnvelopeScanEntry[];
+    readonly worstDistance: XbriefSchemaDistance | null;
+    readonly behindMajor: readonly XbriefEnvelopeScanEntry[];
+};
+/**
+ * Fail closed when any scanned project xBRIEF envelope declares a major behind
+ * the framework target (#3243 / epic #3237 Q5 Option 2). Behind-minor does not
+ * fail this check. Remediation: `deft migrate:xbrief` (rewrites hybrid 0.6 on
+ * already-xbrief trees — #3236). Distinct from `stale-xbrief-schema-deposit`
+ * which routes schema-only drift to `directive update`.
+ */
+export declare function checkXbriefEnvelopeMajorVersion(projectRoot: string, seams?: CheckSeams): CheckResult;
 export declare function checkQuickStartResolves(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function checkSkillPathsResolve(projectRoot: string, agentsMdText: string, seams?: CheckSeams): CheckResult;
 export declare function checkManifestAgreement(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
@@ -60,6 +93,17 @@ export declare function checkGitignoreCoverage(projectRoot: string, seams?: Chec
  * Decided-off is quiet; dismiss-with-reason is pass with reason in detail.
  * Invalid typed blocks resolve fail-closed and surface via source=default-on-error.
  */
+/**
+ * Fail closed when completed/ plan.status disagrees with the folder (#3242 AC1 / epic #3237 Q4).
+ * Open plan.items under completed/ are reported by `checkCompletedOpenItems` (exit-exempt
+ * until historical corpora are backfilled; scope:complete enforces items hard).
+ */
+export declare function checkCompletedLifecycleConsistency(projectRoot: string): CheckResult;
+/**
+ * Surface non-terminal plan.items under completed/ (#3242). Exit-exempt so
+ * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
+ */
+export declare function checkCompletedOpenItems(projectRoot: string): CheckResult;
 export declare function checkCoverageCheckResumePolicy(projectRoot: string): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {