@deftai/directive-core 0.99.0 → 0.100.0

package/dist/lifecycle/completed-consistency.js

@@ -0,0 +1,443 @@
+/**
+ * Completed lifecycle consistency verifier (#3242 / epic #3237 Q4).
+ *
+ * Simple fail-closed rule for stories:
+ * 1. File in `completed/` must have plan.status matching a completed-folder
+ *    terminal status (`completed` or `failed` per D2/D13).
+ * 2. Every plan.items entry (and nested items/subItems) must be terminal
+ *    (not pending/proposed/running).
+ *
+ * Used by doctor (corpus scan) and scope:complete (post-reconcile assert).
+ * Does not couple history/changes ledgers.
+ */
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
+import { FOLDER_ALLOWED_STATUSES, VALID_ITEM_STATUSES } from "../vbrief-validate/constants.js";
+/** Item statuses that still represent unfinished checklist work (#2862 / #3240 / #3242). */
+export const NON_TERMINAL_ITEM_STATUSES = new Set(["pending", "proposed", "running"]);
+/**
+ * Terminal checklist statuses for completed-folder fail-closed (#3242).
+ * Align with #3240 non-terminal set: any valid item status that is not
+ * pending|proposed|running is terminal; unknown/invalid statuses fail closed.
+ */
+export const TERMINAL_ITEM_STATUSES = new Set([...VALID_ITEM_STATUSES].filter((s) => !NON_TERMINAL_ITEM_STATUSES.has(s)));
+/** Statuses allowed under completed/ (D2/D13). */
+export const COMPLETED_FOLDER_PLAN_STATUSES = FOLDER_ALLOWED_STATUSES.completed;
+function asRecord(value) {
+    /* v8 ignore next 3 -- non-object / array inputs */
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function itemLabel(item, path) {
+    if (typeof item.title === "string" && item.title.trim().length > 0) {
+        return item.title.trim();
+    }
+    if (typeof item.id === "string" && item.id.trim().length > 0) {
+        return item.id.trim();
+    }
+    return path;
+}
+/**
+ * Collect non-terminal plan.items / subItems / nested items.
+ * Fail-closed on malformed slots: non-object entries and present non-array
+ * nested collections are reported so completed corpus cannot green-skip them.
+ */
+export function collectOpenPlanItems(items, pathPrefix = "plan.items") {
+    const hits = [];
+    if (!Array.isArray(items)) {
+        return hits;
+    }
+    items.forEach((item, index) => {
+        const path = `${pathPrefix}[${index}]`;
+        const rec = asRecord(item);
+        if (rec === null) {
+            hits.push({
+                path,
+                status: "(non-object)",
+                title: path,
+            });
+            return;
+        }
+        const status = String(rec.status ?? "").trim();
+        if (status.length === 0) {
+            hits.push({
+                path,
+                status: "(empty)",
+                title: itemLabel(rec, path),
+            });
+        }
+        else if (NON_TERMINAL_ITEM_STATUSES.has(status)) {
+            hits.push({
+                path,
+                status,
+                title: itemLabel(rec, path),
+            });
+        }
+        else if (!TERMINAL_ITEM_STATUSES.has(status)) {
+            // Unknown/invalid status is not verified terminal — fail closed (#3242).
+            hits.push({
+                path,
+                status: `(unknown:${status})`,
+                title: itemLabel(rec, path),
+            });
+        }
+        for (const nestedKey of ["subItems", "items"]) {
+            const nested = rec[nestedKey];
+            const nestedPath = `${path}.${nestedKey}`;
+            if (nested === undefined)
+                continue;
+            if (!Array.isArray(nested)) {
+                hits.push({
+                    path: nestedPath,
+                    status: "(non-array)",
+                    title: nestedPath,
+                });
+                continue;
+            }
+            hits.push(...collectOpenPlanItems(nested, nestedPath));
+        }
+    });
+    return hits;
+}
+/**
+ * Evaluate Q4 consistency for a single plan that claims completed lifecycle.
+ *
+ * @param plan - plan object
+ * @param options.relPath - artifact path for messages (default `plan`)
+ * @param options.requireStatus - when set, plan.status must equal this exactly
+ *   (scope:complete uses `completed`). When omitted, any completed-folder
+ *   terminal status (completed|failed) is accepted.
+ */
+export function evaluateCompletedPlanConsistency(plan, options = {}) {
+    const relPath = options.relPath ?? "plan";
+    const rawStatus = plan.status;
+    const planStatus = typeof rawStatus === "string" && rawStatus.trim().length > 0 ? rawStatus.trim() : "(empty)";
+    const findings = [];
+    const statusOk = options.requireStatus !== undefined
+        ? planStatus === options.requireStatus
+        : COMPLETED_FOLDER_PLAN_STATUSES.has(planStatus);
+    if (!statusOk) {
+        const expected = options.requireStatus !== undefined
+            ? options.requireStatus
+            : [...COMPLETED_FOLDER_PLAN_STATUSES].sort().join("|");
+        findings.push({
+            relPath,
+            planStatus,
+            folder: "completed",
+            kind: "status_mismatch",
+            detail: `${relPath}: folder=completed plan.status=${planStatus} ` + `expected=${expected} (#3242)`,
+        });
+    }
+    // Fail closed when plan.items is present but not a checklist array (incl. null).
+    // Omitted (undefined) items = empty terminal checklist; null is malformed shape.
+    if (plan.items !== undefined && !Array.isArray(plan.items)) {
+        findings.push({
+            relPath,
+            planStatus,
+            folder: "completed",
+            kind: "unreadable",
+            detail: `${relPath}: folder=completed plan.status=${planStatus} ` +
+                `plan.items is non-array (cannot verify terminal checklist) (#3242)`,
+        });
+    }
+    else {
+        const openItems = collectOpenPlanItems(plan.items);
+        // Structural malformations + unknown statuses are hard unreadable findings —
+        // not advisory open_items — so doctor exit fails closed.
+        const structural = openItems.filter((h) => h.status === "(non-object)" ||
+            h.status === "(non-array)" ||
+            h.status.startsWith("(unknown:"));
+        const checklistOpen = openItems.filter((h) => h.status !== "(non-object)" &&
+            h.status !== "(non-array)" &&
+            !h.status.startsWith("(unknown:"));
+        if (structural.length > 0) {
+            const itemLines = structural
+                .map((h) => `${h.path} "${h.title}" status=${h.status}`)
+                .join("; ");
+            findings.push({
+                relPath,
+                planStatus,
+                folder: "completed",
+                kind: "unreadable",
+                detail: `${relPath}: folder=completed plan.status=${planStatus} has ` +
+                    `${structural.length} malformed plan.items shape(s): ${itemLines} (#3242)`,
+                openItems: structural,
+            });
+        }
+        if (checklistOpen.length > 0) {
+            const itemLines = checklistOpen
+                .map((h) => `${h.path} "${h.title}" status=${h.status}`)
+                .join("; ");
+            findings.push({
+                relPath,
+                planStatus,
+                folder: "completed",
+                kind: "open_items",
+                detail: `${relPath}: folder=completed plan.status=${planStatus} has ` +
+                    `${checklistOpen.length} non-terminal plan.items: ${itemLines} (#3242)`,
+                openItems: checklistOpen,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        return {
+            ok: true,
+            findings: [],
+            message: `Completed lifecycle consistency OK (#3242): ${relPath} ` +
+                `folder=completed plan.status=${planStatus} items=terminal`,
+        };
+    }
+    return {
+        ok: false,
+        findings,
+        message: formatCompletedConsistencyFailure(findings),
+    };
+}
+/** Format fail-closed doctor/complete message with exact paths and statuses. */
+export function formatCompletedConsistencyFailure(findings) {
+    const lines = findings.map((f) => `  - ${f.detail}`);
+    return (`Completed lifecycle consistency failed (#3242). ` +
+        `${findings.length} finding(s):\n${lines.join("\n")}\n` +
+        `Rule: completed/ requires plan.status in ` +
+        `[${[...COMPLETED_FOLDER_PLAN_STATUSES].sort().join("|")}] and every ` +
+        `plan.items entry terminal (not pending|proposed|running).`);
+}
+/**
+ * Lifecycle inventory roots that may host completed/ artifacts.
+ * Scans both canonical xbrief/ and read-accepted legacy vbrief/ when present
+ * (mixed roots must not green-skip retained legacy completed corpus).
+ * Existing roots that cannot be inspected produce unreadable findings (fail closed).
+ */
+function listConsistencyLifecycleRoots(projectRoot) {
+    const root = resolve(projectRoot);
+    const ordered = [];
+    const seen = new Set();
+    const consider = (absRoot, dirName) => {
+        const key = absRoot.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        let exists;
+        try {
+            exists = existsSync(absRoot);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ordered.push({
+                kind: "unreadable",
+                dirName,
+                detail: `lifecycle root existsSync failed: ${msg}`,
+            });
+            return;
+        }
+        if (!exists)
+            return;
+        try {
+            const st = lstatSync(absRoot);
+            if (st.isSymbolicLink()) {
+                ordered.push({
+                    kind: "unreadable",
+                    dirName,
+                    detail: `lifecycle root is a symlink (refusing to follow; cannot inventory completed/)`,
+                });
+                return;
+            }
+            if (!st.isDirectory()) {
+                ordered.push({
+                    kind: "unreadable",
+                    dirName,
+                    detail: `lifecycle root exists but is not a directory (cannot inventory completed/)`,
+                });
+                return;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ordered.push({
+                kind: "unreadable",
+                dirName,
+                detail: `lifecycle root unreadable (lstat failed): ${msg}`,
+            });
+            return;
+        }
+        ordered.push({ kind: "dir", absRoot, dirName });
+    };
+    // Always probe both layout dirs so mixed roots cannot green-skip legacy completed/.
+    consider(join(root, MIGRATED_ARTIFACT_DIR), MIGRATED_ARTIFACT_DIR);
+    consider(join(root, LEGACY_ARTIFACT_DIR), LEGACY_ARTIFACT_DIR);
+    return ordered;
+}
+function unreadableFinding(relPath, detail) {
+    return {
+        relPath,
+        planStatus: "(unreadable)",
+        folder: "completed",
+        kind: "unreadable",
+        detail: `${relPath}: ${detail} (#3242)`,
+    };
+}
+function scanCompletedDir(completedDir, pathPrefix) {
+    let completedPresent = false;
+    try {
+        if (!existsSync(completedDir)) {
+            return { findings: [], scanned: 0, completedPresent: false };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            findings: [
+                unreadableFinding(`${pathPrefix}/completed`, `completed/ existsSync failed (cannot inventory): ${msg}`),
+            ],
+            scanned: 0,
+            completedPresent: true,
+        };
+    }
+    try {
+        const st = lstatSync(completedDir);
+        if (st.isSymbolicLink()) {
+            return {
+                findings: [
+                    unreadableFinding(`${pathPrefix}/completed`, "completed/ is a symlink (refusing to follow; cannot inventory)"),
+                ],
+                scanned: 0,
+                completedPresent: true,
+            };
+        }
+        if (!st.isDirectory()) {
+            return {
+                findings: [
+                    unreadableFinding(`${pathPrefix}/completed`, "completed path exists but is not a directory (cannot inventory)"),
+                ],
+                scanned: 0,
+                completedPresent: true,
+            };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            findings: [
+                unreadableFinding(`${pathPrefix}/completed`, `completed/ unreadable (lstat failed): ${msg}`),
+            ],
+            scanned: 0,
+            completedPresent: true,
+        };
+    }
+    completedPresent = true;
+    let names;
+    try {
+        names = readdirSync(completedDir)
+            .filter((n) => hasArtifactSuffix(n))
+            .sort();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            findings: [
+                unreadableFinding(`${pathPrefix}/completed`, `completed/ readdir failed (cannot inventory): ${msg}`),
+            ],
+            scanned: 0,
+            completedPresent: true,
+        };
+    }
+    const findings = [];
+    for (const name of names) {
+        const relPath = `${pathPrefix}/completed/${name}`;
+        const abs = join(completedDir, name);
+        try {
+            const st = lstatSync(abs);
+            if (st.isSymbolicLink()) {
+                findings.push(unreadableFinding(relPath, "symlink under completed/ (refusing to follow; cannot verify status/items)"));
+                continue;
+            }
+            if (!st.isFile()) {
+                findings.push(unreadableFinding(relPath, "non-file entry under completed/ (cannot verify status/items)"));
+                continue;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            findings.push(unreadableFinding(relPath, `lstat failed: ${msg}`));
+            continue;
+        }
+        let data;
+        try {
+            data = JSON.parse(readFileSync(abs, "utf8"));
+        }
+        catch {
+            findings.push(unreadableFinding(relPath, "malformed JSON under completed/ (cannot verify status/items)"));
+            continue;
+        }
+        const root = asRecord(data);
+        if (root === null) {
+            findings.push(unreadableFinding(relPath, "non-object root under completed/ (cannot verify status/items)"));
+            continue;
+        }
+        const plan = asRecord(root.plan);
+        if (plan === null) {
+            findings.push(unreadableFinding(relPath, "missing or non-object plan under completed/"));
+            continue;
+        }
+        const result = evaluateCompletedPlanConsistency(plan, { relPath });
+        findings.push(...result.findings);
+    }
+    return { findings, scanned: names.length, completedPresent };
+}
+/**
+ * Scan `xbrief/completed/` and/or legacy `vbrief/completed/` for Q4 mismatches.
+ * Offline / filesystem only. Missing completed/ is green (nothing to check).
+ * Malformed completed artifacts and unreadable roots fail closed (no silent skip).
+ * Mixed roots scan both.
+ */
+export function scanCompletedLifecycleConsistency(projectRoot) {
+    const roots = listConsistencyLifecycleRoots(projectRoot);
+    if (roots.length === 0) {
+        return {
+            ok: true,
+            findings: [],
+            message: "Completed lifecycle consistency OK (#3242): no lifecycle root",
+        };
+    }
+    const findings = [];
+    let scanned = 0;
+    let anyCompletedPresent = false;
+    for (const probe of roots) {
+        if (probe.kind === "unreadable") {
+            findings.push(unreadableFinding(probe.dirName, probe.detail));
+            continue;
+        }
+        const completedDir = join(probe.absRoot, "completed");
+        // Always prefix with layout dir so mixed roots and exact paths are unambiguous.
+        const part = scanCompletedDir(completedDir, probe.dirName);
+        if (part.completedPresent) {
+            anyCompletedPresent = true;
+        }
+        findings.push(...part.findings);
+        scanned += part.scanned;
+    }
+    if (!anyCompletedPresent && findings.length === 0) {
+        return {
+            ok: true,
+            findings: [],
+            message: "Completed lifecycle consistency OK (#3242): completed/ absent",
+        };
+    }
+    if (findings.length === 0) {
+        return {
+            ok: true,
+            findings: [],
+            message: `Completed lifecycle consistency OK (#3242): scanned ${scanned} ` +
+                `completed/ artifact(s)`,
+        };
+    }
+    return {
+        ok: false,
+        findings,
+        message: formatCompletedConsistencyFailure(findings),
+    };
+}
+//# sourceMappingURL=completed-consistency.js.map

package/dist/lifecycle/completed-tracked-on-delivery.d.ts

@@ -0,0 +1,47 @@
+import { type IssueRef } from "../orphan-active/refs.js";
+import type { RunGhFn } from "../pr-protected-issues/types.js";
+import { type GitRunner } from "../session/git.js";
+export type OutputStream = "stdout" | "stderr" | "none";
+/** Lifecycle folders scanned for local "known origin" xBRIEFs. */
+export declare const LOCAL_ORIGIN_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+/** Non-terminal tip folders: closed issues still here need completed land. */
+export declare const TIP_NONTERMINAL_FOLDERS: readonly ["proposed", "pending", "active"];
+/** Terminal tip folders that satisfy the land rule. */
+export declare const TIP_TERMINAL_FOLDERS: readonly ["completed", "cancelled"];
+export interface MissingCompletedLand {
+    readonly issue: IssueRef;
+    /** Where the detector learned about this scoped issue (local and/or tip paths). */
+    readonly origins: readonly string[];
+}
+export interface EvaluateCompletedTrackedResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly missing: readonly MissingCompletedLand[];
+    readonly tip: string | null;
+}
+export interface EvaluateCompletedTrackedOptions {
+    readonly quiet?: boolean;
+    readonly repo?: string | null;
+    /** Explicit delivery tip ref (e.g. origin/master). Overrides policy/git default. */
+    readonly tip?: string | null;
+    readonly runGh?: RunGhFn;
+    readonly skipGh?: boolean;
+    readonly runGit?: GitRunner;
+    /** Test seam: override issue state resolution. */
+    readonly resolveIssueState?: (ref: IssueRef) => "open" | "closed" | null;
+}
+/**
+ * Resolve the git tip to inspect for tracked completed/cancelled land.
+ * Prefers origin/<deliveryBranch> when present.
+ */
+export declare function resolveDeliveryTip(projectRoot: string, tipOverride: string | null | undefined, runGit: GitRunner): {
+    tip: string | null;
+    error: string | null;
+};
+/**
+ * Pure evaluator: closed scoped issues must have tracked completed/cancelled
+ * on the delivery tip (#3264).
+ */
+export declare function evaluateCompletedTracked(projectRoot: string, options?: EvaluateCompletedTrackedOptions): EvaluateCompletedTrackedResult;
+//# sourceMappingURL=completed-tracked-on-delivery.d.ts.map