@deftai/directive-core 0.99.0 → 0.101.0

package/dist/lifecycle/completed-tracked-on-delivery.js

@@ -0,0 +1,415 @@
+/**
+ * Fail-closed land check (#3264 / #1358 recurrence).
+ *
+ * Rule: if a GitHub issue is closed and Directive has a known lifecycle
+ * xBRIEF origin for it, the delivery branch tip must contain a *tracked*
+ * artifact under xbrief/completed/ or xbrief/cancelled/ that references
+ * that issue. Else fail with a single remediation path
+ * (`task swarm:finalize-cohort` or a lifecycle PR).
+ *
+ * Complements verify:orphan-active (#2321), which watches active/running
+ * residue — not completed-but-untracked laptop residue.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
+import { collectGithubRefs } from "../orphan-active/refs.js";
+import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
+import { defaultRunGh } from "../pr-protected-issues/gh.js";
+import { defaultGitRunner } from "../session/git.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
+import { resolveRepo } from "../triage/queue/repo.js";
+/** Lifecycle folders scanned for local "known origin" xBRIEFs. */
+export const LOCAL_ORIGIN_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+/** Non-terminal tip folders: closed issues still here need completed land. */
+export const TIP_NONTERMINAL_FOLDERS = ["proposed", "pending", "active"];
+/** Terminal tip folders that satisfy the land rule. */
+export const TIP_TERMINAL_FOLDERS = ["completed", "cancelled"];
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function planOf(data) {
+    const plan = data?.plan;
+    return typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? plan
+        : null;
+}
+function issueKey(ref) {
+    return `${ref.repo}#${ref.number}`;
+}
+function formatIssue(ref) {
+    return `${ref.repo}#${ref.number}`;
+}
+function relPath(path, projectRoot) {
+    try {
+        return relative(resolve(projectRoot), resolve(path)).replace(/\\/g, "/");
+    }
+    catch {
+        return path.replace(/\\/g, "/");
+    }
+}
+function readCachedIssueState(projectRoot, ref) {
+    const [owner, name] = ref.repo.split("/", 2);
+    if (!owner || !name) {
+        return null;
+    }
+    const rawPath = join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE, owner, name, String(ref.number), "raw.json");
+    if (!existsSync(rawPath)) {
+        return null;
+    }
+    const raw = readJson(rawPath);
+    if (raw === null) {
+        return null;
+    }
+    const state = typeof raw.state === "string" ? raw.state.toLowerCase() : "";
+    if (state === "closed" || state === "open") {
+        return state;
+    }
+    return null;
+}
+function fetchIssueStateLive(ref, runGh) {
+    const path = `repos/${ref.repo}/issues/${ref.number}`;
+    const result = runGh(["gh", "api", path]);
+    if (result.returncode !== 0) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(result.stdout);
+        if (payload === null || typeof payload !== "object") {
+            return null;
+        }
+        const state = payload.state;
+        if (state === "closed" || state === "open") {
+            return state;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultResolveIssueState(ref, projectRoot, runGh, skipGh) {
+    const cached = readCachedIssueState(projectRoot, ref);
+    // Closed cache is fail-closed evidence (safe to trust without live).
+    if (cached === "closed") {
+        return "closed";
+    }
+    if (skipGh) {
+        // Offline / fixture mode: honor cache open|null as-is.
+        return cached;
+    }
+    // Prefer live when network is allowed. Stale open cache must not suppress a
+    // later close when live succeeds (#3264 Greptile P1). When live fails, do
+    // NOT fall back to cached open — treat as unknown so we fail closed only on
+    // positive closed evidence (cached closed above, or live closed).
+    const live = fetchIssueStateLive(ref, runGh);
+    if (live !== null) {
+        return live;
+    }
+    return null;
+}
+function collectIssuesFromPlan(plan, defaultRepo, originPath, out) {
+    const { issues } = collectGithubRefs(plan, defaultRepo);
+    for (const issue of issues) {
+        out.push({ issue, originPath });
+    }
+}
+function scanLocalOrigins(projectRoot, defaultRepo) {
+    const hits = [];
+    const roots = [];
+    try {
+        roots.push(resolveLifecycleRoot(projectRoot));
+    }
+    catch {
+        // no xbrief layout
+    }
+    // Read-accepted legacy vbrief/ root when present (same class as #3242 scans).
+    const legacyRoot = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    if (existsSync(legacyRoot) && !roots.includes(legacyRoot)) {
+        roots.push(legacyRoot);
+    }
+    // Canonical path even when resolveLifecycleRoot fell back elsewhere.
+    const migrated = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    if (existsSync(migrated) && !roots.includes(migrated)) {
+        roots.push(migrated);
+    }
+    for (const root of roots) {
+        for (const folder of LOCAL_ORIGIN_FOLDERS) {
+            const dir = join(root, folder);
+            if (!existsSync(dir)) {
+                continue;
+            }
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of entries.sort()) {
+                if (!hasArtifactSuffix(name)) {
+                    continue;
+                }
+                const path = join(dir, name);
+                const plan = planOf(readJson(path));
+                if (plan === null) {
+                    continue;
+                }
+                collectIssuesFromPlan(plan, defaultRepo, relPath(path, projectRoot), hits);
+            }
+        }
+    }
+    return hits;
+}
+function refExists(projectRoot, ref, runGit) {
+    const result = runGit(projectRoot, ["rev-parse", "--verify", "-q", ref]);
+    return result.code === 0;
+}
+/**
+ * Resolve the git tip to inspect for tracked completed/cancelled land.
+ * Prefers origin/<deliveryBranch> when present.
+ */
+export function resolveDeliveryTip(projectRoot, tipOverride, runGit) {
+    if (tipOverride !== null && tipOverride !== undefined && tipOverride.trim().length > 0) {
+        const tip = tipOverride.trim();
+        if (!refExists(projectRoot, tip, runGit)) {
+            return { tip: null, error: `delivery tip ref not found: ${tip}` };
+        }
+        return { tip, error: null };
+    }
+    const delivery = resolveDeliveryBranch(projectRoot, runGit);
+    const branch = delivery.branch;
+    for (const candidate of [`origin/${branch}`, branch]) {
+        if (refExists(projectRoot, candidate, runGit)) {
+            return { tip: candidate, error: null };
+        }
+    }
+    // Last resort: HEAD of current checkout (still a real tip for fixtures).
+    if (refExists(projectRoot, "HEAD", runGit)) {
+        return { tip: "HEAD", error: null };
+    }
+    return {
+        tip: null,
+        error: `could not resolve delivery tip for branch '${branch}' (no origin/${branch}, ${branch}, or HEAD)`,
+    };
+}
+function listTreePaths(projectRoot, tip, prefixes, runGit) {
+    if (prefixes.length === 0) {
+        return [];
+    }
+    const result = runGit(projectRoot, ["ls-tree", "-r", "--name-only", tip, "--", ...prefixes]);
+    if (result.code !== 0) {
+        return [];
+    }
+    return result.stdout
+        .split("\n")
+        .map((line) => line.trim().replace(/\\/g, "/"))
+        .filter((line) => line.length > 0 && hasArtifactSuffix(line));
+}
+function showBlob(projectRoot, tip, path, runGit) {
+    const result = runGit(projectRoot, ["show", `${tip}:${path}`]);
+    if (result.code !== 0) {
+        return null;
+    }
+    return result.stdout;
+}
+function terminalPrefixes() {
+    const out = [];
+    for (const root of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
+        for (const folder of TIP_TERMINAL_FOLDERS) {
+            out.push(`${root}/${folder}`);
+        }
+    }
+    return out;
+}
+function nonterminalPrefixes() {
+    const out = [];
+    for (const root of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
+        for (const folder of TIP_NONTERMINAL_FOLDERS) {
+            out.push(`${root}/${folder}`);
+        }
+    }
+    return out;
+}
+function issuesFromBlobPaths(projectRoot, tip, paths, defaultRepo, runGit, originPrefix) {
+    const hits = [];
+    for (const path of paths) {
+        const body = showBlob(projectRoot, tip, path, runGit);
+        if (body === null) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            continue;
+        }
+        const plan = planOf(parsed);
+        if (plan === null) {
+            continue;
+        }
+        collectIssuesFromPlan(plan, defaultRepo, `${originPrefix}:${path}`, hits);
+    }
+    return hits;
+}
+function mergeOrigins(hits) {
+    const map = new Map();
+    for (const hit of hits) {
+        const key = issueKey(hit.issue);
+        let entry = map.get(key);
+        if (entry === undefined) {
+            entry = { issue: hit.issue, origins: new Set() };
+            map.set(key, entry);
+        }
+        entry.origins.add(hit.originPath);
+    }
+    const out = new Map();
+    for (const [key, value] of map) {
+        out.set(key, {
+            issue: value.issue,
+            origins: [...value.origins].sort(),
+        });
+    }
+    return out;
+}
+function formatRefusal(missing, projectRoot, tip) {
+    const lines = [
+        `verify:completed-tracked: ${missing.length} closed scoped issue${missing.length === 1 ? "" : "s"} lack a tracked xbrief/completed/ or xbrief/cancelled/ artifact on delivery tip ${tip} (project_root=${projectRoot}).`,
+        "  Remediation: task swarm:finalize-cohort (or open a lifecycle PR that lands the completed/cancelled xBRIEFs).",
+        "  Missing:",
+    ];
+    for (const item of missing) {
+        const originSample = item.origins.slice(0, 3).join(", ");
+        const more = item.origins.length > 3 ? ` (+${item.origins.length - 3} more origin path(s))` : "";
+        lines.push(`    - ${formatIssue(item.issue)} (origin: ${originSample}${more})`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Pure evaluator: closed scoped issues must have tracked completed/cancelled
+ * on the delivery tip (#3264).
+ */
+export function evaluateCompletedTracked(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const quiet = options.quiet ?? false;
+    const skipGh = options.skipGh ?? false;
+    const runGh = options.runGh ?? defaultRunGh;
+    const runGit = options.runGit ?? defaultGitRunner;
+    const defaultRepo = resolveRepo(options.repo, root);
+    const resolveState = options.resolveIssueState ??
+        ((ref) => defaultResolveIssueState(ref, root, runGh, skipGh));
+    if (!existsSync(root)) {
+        return {
+            code: 2,
+            message: `verify:completed-tracked: project root does not exist: ${root}`,
+            stream: "stderr",
+            missing: [],
+            tip: null,
+        };
+    }
+    // Not a git worktree → nothing to assert about tracked tip (greenfield /
+    // temp consumer fixtures). Soft-skip like orphan-active's empty-root path.
+    const gitProbe = runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (gitProbe.code !== 0) {
+        if (quiet) {
+            return { code: 0, message: "", stream: "none", missing: [], tip: null };
+        }
+        return {
+            code: 0,
+            message: `verify:completed-tracked: not a git worktree; skip tracked-land check (${root}).`,
+            stream: "stdout",
+            missing: [],
+            tip: null,
+        };
+    }
+    const { tip, error: tipError } = resolveDeliveryTip(root, options.tip, runGit);
+    if (tip === null) {
+        return {
+            code: 2,
+            message: `verify:completed-tracked: ${tipError ?? "could not resolve delivery tip"}`,
+            stream: "stderr",
+            missing: [],
+            tip: null,
+        };
+    }
+    const localHits = scanLocalOrigins(root, defaultRepo);
+    const tipNonterminalPaths = listTreePaths(root, tip, nonterminalPrefixes(), runGit);
+    const tipNonterminalHits = issuesFromBlobPaths(root, tip, tipNonterminalPaths, defaultRepo, runGit, `tip:${tip}`);
+    const originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    if (originMap.size === 0) {
+        if (quiet) {
+            return { code: 0, message: "", stream: "none", missing: [], tip };
+        }
+        return {
+            code: 0,
+            message: "verify:completed-tracked: no scoped lifecycle origins found; nothing to check.",
+            stream: "stdout",
+            missing: [],
+            tip,
+        };
+    }
+    // Delivery tip only — the land invariant is post-merge tip truth (#3264 AC).
+    // Lifecycle PRs that commit completed/ on a feature branch are not expected
+    // to satisfy this gate until merge; run the verb with --tip HEAD when
+    // validating an in-flight land PR. The gate is a standalone verify verb
+    // (not wired into check:consumer) so product PRs are not deadlocked.
+    const tipTerminalPaths = listTreePaths(root, tip, terminalPrefixes(), runGit);
+    const tipTerminalHits = issuesFromBlobPaths(root, tip, tipTerminalPaths, defaultRepo, runGit, `tip:${tip}`);
+    const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
+    const missing = [];
+    for (const [key, entry] of originMap) {
+        if (landedKeys.has(key)) {
+            continue;
+        }
+        const state = resolveState(entry.issue);
+        if (state === "open") {
+            continue;
+        }
+        // Closed: always fail. Unknown with live expected (!skipGh): also fail —
+        // cannot prove the issue is still open, so do not green-skip land debt
+        // (#3264 Greptile residual on live lookup failure).
+        if (state === "closed" || (state === null && !skipGh)) {
+            missing.push(entry);
+        }
+    }
+    missing.sort((a, b) => issueKey(a.issue).localeCompare(issueKey(b.issue)));
+    if (missing.length > 0) {
+        return {
+            code: 1,
+            message: formatRefusal(missing, root, tip),
+            stream: "stderr",
+            missing,
+            tip,
+        };
+    }
+    if (quiet) {
+        return { code: 0, message: "", stream: "none", missing: [], tip };
+    }
+    return {
+        code: 0,
+        message: `verify:completed-tracked: all closed scoped issues have tracked completed/cancelled ` +
+            `on tip ${tip} (scoped origins checked: ${originMap.size}).`,
+        stream: "stdout",
+        missing: [],
+        tip,
+    };
+}
+//# sourceMappingURL=completed-tracked-on-delivery.js.map

package/dist/lifecycle/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./completed-consistency.js";
+export * from "./completed-tracked-on-delivery.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/lifecycle/index.js

@@ -1,3 +1,5 @@
+export * from "./completed-consistency.js";
+export * from "./completed-tracked-on-delivery.js";
 export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";

package/dist/literal-acceptance/capture.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Capture exact stated acceptance commands from a task statement (#3267).
+ *
+ * Only extracts commands that appear literally in the text — never invents
+ * or paraphrases. Prefer fenced blocks and labeled lines (verify:/command:/run:).
+ *
+ * Safety-rejected shell-shaped lines are recorded on a rejected ledger so they
+ * do not vanish silently (#3267 residual). Dedup keys include cwd/expectedExitCode
+ * so distinct execution contexts are not collapsed.
+ */
+import type { LiteralAcceptanceCommand, RejectedLiteralCommand } from "./types.js";
+/** Result of capture including the operator-visible rejected ledger. */
+export interface CaptureLiteralAcceptanceResult {
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    readonly rejected: readonly RejectedLiteralCommand[];
+}
+/**
+ * Capture literal acceptance commands from free-form task statement text.
+ * Returns commands + rejected ledger — never invents commands.
+ */
+export declare function captureLiteralAcceptanceCommandsDetailed(taskStatement: string): CaptureLiteralAcceptanceResult;
+/**
+ * Capture literal acceptance commands from free-form task statement text.
+ * Returns [] when none are stated — never invents commands.
+ */
+export declare function captureLiteralAcceptanceCommands(taskStatement: string): LiteralAcceptanceCommand[];
+/**
+ * Read already-stored commands from plan.metadata / swarm.verify_commands / item.command.
+ * Preserves exact strings and execution context (cwd / expectedStdout / expectedExitCode).
+ */
+export declare function readStoredLiteralAcceptanceCommands(plan: Record<string, unknown> | null | undefined): LiteralAcceptanceCommand[];
+/** Read stored commands plus any persisted rejected ledger. */
+export declare function readStoredLiteralAcceptanceDetailed(plan: Record<string, unknown> | null | undefined): CaptureLiteralAcceptanceResult;
+/**
+ * Attach captured commands onto plan.metadata without paraphrasing.
+ * Merges with existing literal_acceptance_commands.
+ * Only agent-executable sources (not task_statement) are mirrored into
+ * swarm.verify_commands — issue text must be promoted explicitly (#3267).
+ * Returns a shallow-cloned plan with updated metadata.
+ */
+export declare function attachLiteralAcceptanceCommands(plan: Record<string, unknown>, commands: readonly LiteralAcceptanceCommand[], rejected?: readonly RejectedLiteralCommand[]): Record<string, unknown>;
+/**
+ * Capture from task statement text and attach onto a plan (intake helper).
+ */
+export declare function captureAndAttachLiteralAcceptance(plan: Record<string, unknown>, taskStatement: string): {
+    readonly plan: Record<string, unknown>;
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    readonly rejected: readonly RejectedLiteralCommand[];
+};
+/** Format rejected ledger for CLI / complete-gate messages. */
+export declare function formatRejectedLedger(rejected: readonly RejectedLiteralCommand[]): string;
+//# sourceMappingURL=capture.d.ts.map