@deftai/directive-core 0.106.0 → 0.108.0

package/dist/orphan-active/evaluate.js

@@ -1,9 +1,9 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
-import { defaultRunGh } from "../pr-protected-issues/gh.js";
-import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
+import { ScmStubError } from "../scm/errors.js";
 import { resolveRepo } from "../triage/queue/repo.js";
+import { AGGREGATE_LATENCY_BUDGET_MS, formatAge, makeGateRunner, OpenIssueInventory, resolveIssueStateAggregate, resolveIssueStateScoped, SCOPED_LATENCY_BUDGET_MS, } from "./issue-state.js";
 import { collectGithubRefs } from "./refs.js";
 function readJson(path) {
     try {
@@ -60,61 +60,62 @@ function listActiveRunningBriefs(projectRoot) {
     }
     return out.sort((a, b) => a.path.localeCompare(b.path));
 }
-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") {
-        return "closed";
-    }
-    if (state === "open") {
-        return "open";
+/**
+ * Records how each verdict was reached so the summary can distinguish a
+ * verified pass from an unverified one (#3767).
+ */
+class BasisTally {
+    inventory = 0;
+    live = 0;
+    cache = 0;
+    maxCacheAgeMs = 0;
+    unverifiedReasons = [];
+    record(ref, resolution) {
+        switch (resolution.basis) {
+            case "inventory":
+                this.inventory += 1;
+                break;
+            case "live":
+                this.live += 1;
+                break;
+            case "cache":
+                this.cache += 1;
+                this.maxCacheAgeMs = Math.max(this.maxCacheAgeMs, resolution.cacheAgeMs);
+                break;
+            default: {
+                const line = `#${ref.number} (${resolution.detail})`;
+                if (!this.unverifiedReasons.includes(line)) {
+                    this.unverifiedReasons.push(line);
+                }
+            }
+        }
     }
-    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;
+    get unverified() {
+        return this.unverifiedReasons.length;
     }
-    try {
-        const payload = JSON.parse(result.stdout);
-        if (payload === null || typeof payload !== "object") {
-            return null;
+    summary() {
+        const parts = [];
+        if (this.inventory > 0) {
+            parts.push(`inventory ${this.inventory}`);
         }
-        const state = payload.state;
-        if (state === "closed") {
-            return "closed";
+        if (this.live > 0) {
+            parts.push(`live ${this.live}`);
         }
-        if (state === "open") {
-            return "open";
+        if (this.cache > 0) {
+            parts.push(`cache ${this.cache} (max age ${formatAge(this.maxCacheAgeMs)})`);
         }
-        return null;
-    }
-    catch {
-        return null;
+        if (this.unverified > 0) {
+            parts.push(`unverified ${this.unverified}`);
+        }
+        return parts.length === 0 ? "no GitHub lookups" : parts.join(", ");
     }
 }
-function resolveIssueState(ref, projectRoot, runGh, skipGh) {
-    const cached = readCachedIssueState(projectRoot, ref);
-    if (cached !== null) {
-        return cached;
-    }
-    if (skipGh) {
-        return null;
-    }
-    return fetchIssueStateLive(ref, runGh);
+function resolveIssueState(ref, ctx, scoped, tally) {
+    const resolution = scoped
+        ? resolveIssueStateScoped(ref, ctx)
+        : resolveIssueStateAggregate(ref, ctx);
+    tally.record(ref, resolution);
+    return resolution.state;
 }
 function fetchPrMerged(ref, runGh) {
     const path = `repos/${ref.repo}/pulls/${ref.number}`;
@@ -144,11 +145,18 @@ function shipped(reason) {
 function unresolved(reason) {
     return { orphaned: true, reason, kind: "unresolved" };
 }
-function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh, selectedIssue) {
+function assessOrphanSignature(issueRefs, prRefs, ctx, selectedIssue, tally) {
+    const runGh = ctx.runGh;
+    const skipGh = ctx.skipGh;
+    const scoped = selectedIssue !== null;
     if (selectedIssue !== null) {
-        // Confirmed closed origin is shipped even if a linked PR lookup fails.
         const selectedRef = issueRefs.find((ref) => ref.number === selectedIssue);
-        const selectedState = selectedRef === undefined ? null : resolveIssueState(selectedRef, projectRoot, runGh, skipGh);
+        if (selectedRef === undefined) {
+            // evaluate() only reaches here for briefs that name the issue.
+            return PASS;
+        }
+        // Confirmed closed origin is shipped even if a linked PR lookup fails.
+        const selectedState = resolveIssueState(selectedRef, ctx, scoped, tally);
         if (selectedState === "closed") {
             return shipped(`issue #${selectedIssue} is closed`);
         }
@@ -165,25 +173,8 @@ function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh, se
             }
         }
         // --issue N is one origin: sibling open/unknown must not mask it (#3429).
-        if (selectedRef !== undefined) {
-            if (selectedState === null) {
-                return unresolved(`issue #${selectedIssue} state could not be resolved`);
-            }
-            return PASS;
-        }
-        const issueStates = issueRefs.map((ref) => ({
-            ref,
-            state: resolveIssueState(ref, projectRoot, runGh, skipGh),
-        }));
-        const unknownIssue = issueStates.find((row) => row.state === null);
-        if (unknownIssue !== undefined) {
-            return unresolved(`issue #${unknownIssue.ref.number} state could not be resolved`);
-        }
-        if (issueStates.some((row) => row.state === "closed")) {
-            return shipped("all referenced issues are closed");
-        }
-        if (prRefs.length > 0 && skipGh) {
-            return unresolved(`linked PR #${prRefs[0]?.number} state could not be resolved`);
+        if (selectedState === null) {
+            return unresolved(`issue #${selectedIssue} state could not be resolved`);
         }
         return PASS;
     }
@@ -199,26 +190,37 @@ function assessOrphanSignature(issueRefs, prRefs, projectRoot, runGh, skipGh, se
     if (issueRefs.length === 0) {
         return PASS;
     }
-    let resolved = 0;
     for (const ref of issueRefs) {
-        const state = resolveIssueState(ref, projectRoot, runGh, skipGh);
-        if (state === null) {
-            return PASS;
-        }
-        resolved += 1;
+        const state = resolveIssueState(ref, ctx, scoped, tally);
+        // Unknown keeps the sweep fail-open so offline work is not network-authorized;
+        // the unverified basis line stops the pass reading as verified evidence (#3767).
         if (state !== "closed") {
             return PASS;
         }
     }
-    if (resolved > 0) {
-        return shipped("all referenced issues are closed");
-    }
-    return PASS;
+    return shipped("all referenced issues are closed");
 }
 function briefReferencesIssue(issues, issue) {
     return issues.some((ref) => ref.number === issue);
 }
-function formatRefusal(orphans, projectRoot, issueFilter) {
+/** Basis, ghx caveat, and budget lines shared by the pass and refusal messages (#3767). */
+function basisLines(tally, basis) {
+    const lines = [`  Basis: ${tally.summary()}.`];
+    if (tally.unverified > 0) {
+        lines.push("  UNVERIFIED: state could not be established for the references below, so this run is", "  not evidence that they are unshipped:");
+        for (const reason of tally.unverifiedReasons) {
+            lines.push(`    - ${reason}`);
+        }
+    }
+    if (basis.proxied) {
+        lines.push("  Note: reads resolved through `ghx`, a cached GET proxy; freshness is bounded by that", "  proxy, which this gate cannot inspect (#3737).");
+    }
+    if (basis.elapsedMs > basis.budgetMs) {
+        lines.push(`  Budget: took ${formatAge(basis.elapsedMs)} against a ${formatAge(basis.budgetMs)} budget (#3767).`);
+    }
+    return lines;
+}
+function formatRefusal(orphans, projectRoot, issueFilter, tally, basis) {
     const shippedOrphans = orphans.filter((orphan) => orphan.kind === "shipped");
     const unresolvedOrphans = orphans.filter((orphan) => orphan.kind === "unresolved");
     const noun = orphans.length === 1 ? "" : "s";
@@ -250,27 +252,49 @@ function formatRefusal(orphans, projectRoot, issueFilter) {
     for (const orphan of orphans) {
         lines.push(`    - ${orphan.path} (${orphan.reason})`);
     }
+    lines.push(...basisLines(tally, basis));
     return lines.join("\n");
 }
+function emptyBasis(budgetMs) {
+    return {
+        inventory: 0,
+        live: 0,
+        cache: 0,
+        unverified: 0,
+        maxCacheAgeMs: null,
+        proxied: false,
+        elapsedMs: 0,
+        budgetMs,
+    };
+}
 /**
  * Pure evaluator for orphaned active/running xBRIEF detection (#2321 / #3429).
  * Fails when active/ briefs with plan.status==running reference only closed
  * issues and/or a merged PR — the stop-at:pr-open orphan signature.
  * Pass `issue` to scan one origin after merge. Confirmed shipped prints
  * scope:complete; unresolved lookup still exits 1 with a retry remediation.
+ *
+ * Issue state resolves by query shape (#3767): scoped `--issue N` takes an
+ * authoritative read and stays fail-closed on unknown; the unscoped sweep uses
+ * one complete, fail-closed open-issue inventory and stays fail-open on
+ * unknown so offline work is not network-authorized. A cache hit is honoured
+ * only inside `ISSUE_CACHE_MAX_AGE_MS`, and every verdict reports its basis.
  */
 export function evaluate(projectRoot, options = {}) {
     const root = resolve(projectRoot);
     const quiet = options.quiet ?? false;
     const skipGh = options.skipGh ?? false;
-    const runGh = options.runGh ?? defaultRunGh;
-    const defaultRepo = resolveRepo(options.repo, root);
+    const issueFilter = options.issue ?? null;
+    const budgetMs = issueFilter === null ? AGGREGATE_LATENCY_BUDGET_MS : SCOPED_LATENCY_BUDGET_MS;
+    const clock = options.nowMs ?? Date.now;
+    const startedMs = clock();
     if (!existsSync(root)) {
         return {
             code: 2,
             message: `verify:orphan-active: project root does not exist: ${root}`,
             stream: "stderr",
             orphans: [],
+            basis: emptyBasis(budgetMs),
         };
     }
     let lifecycleRoot;
@@ -282,14 +306,12 @@ export function evaluate(projectRoot, options = {}) {
         // Consumer/greenfield fixtures may still use legacy vbrief/ only (#2112).
         // Orphan detection applies only to xbrief/active/ — skip cleanly, not config fail.
         if (message.includes("No xbrief/ layout found")) {
-            if (quiet) {
-                return { code: 0, message: "", stream: "none", orphans: [] };
-            }
             return {
                 code: 0,
-                message: "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
-                stream: "stdout",
+                message: quiet ? "" : "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
+                stream: quiet ? "none" : "stdout",
                 orphans: [],
+                basis: emptyBasis(budgetMs),
             };
         }
         return {
@@ -297,58 +319,101 @@ export function evaluate(projectRoot, options = {}) {
             message: `verify:orphan-active: ${message}`,
             stream: "stderr",
             orphans: [],
+            basis: emptyBasis(budgetMs),
         };
     }
     if (!existsSync(lifecycleRoot)) {
-        if (quiet) {
-            return { code: 0, message: "", stream: "none", orphans: [] };
-        }
         return {
             code: 0,
-            message: "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
-            stream: "stdout",
+            message: quiet ? "" : "verify:orphan-active: no xbrief/ lifecycle root; nothing to scan.",
+            stream: quiet ? "none" : "stdout",
             orphans: [],
+            basis: emptyBasis(budgetMs),
         };
     }
-    const issueFilter = options.issue ?? null;
-    const orphans = [];
-    for (const brief of listActiveRunningBriefs(root)) {
-        const { issues, prs } = collectGithubRefs(brief.plan, defaultRepo);
-        // --issue N is one origin: briefs that name that issue. PR-only briefs stay on the unscoped scan (#3429).
-        if (issueFilter !== null && !briefReferencesIssue(issues, issueFilter)) {
-            continue;
+    const defaultRepo = resolveRepo(options.repo, root);
+    // Resolve the SCM binary lazily: an offline `--skip-gh` run or an empty
+    // active/ must not pay for (or fail on) binary resolution it never uses.
+    let runner = options.runGh === undefined ? null : { runGh: options.runGh, proxied: false };
+    const runGh = (cmd) => {
+        runner ??= makeGateRunner();
+        return runner.runGh(cmd);
+    };
+    const tally = new BasisTally();
+    const ctx = {
+        projectRoot: root,
+        runGh,
+        skipGh,
+        nowMs: clock(),
+        inventory: new OpenIssueInventory(runGh),
+    };
+    try {
+        // #3774: missing gh/ghx is config (code 2), not an uncaught throw.
+        const orphans = [];
+        let scanned = 0;
+        for (const brief of listActiveRunningBriefs(root)) {
+            scanned += 1;
+            const { issues, prs } = collectGithubRefs(brief.plan, defaultRepo);
+            // --issue N is one origin: briefs that name that issue. PR-only briefs stay on the unscoped scan (#3429).
+            if (issueFilter !== null && !briefReferencesIssue(issues, issueFilter)) {
+                continue;
+            }
+            if (issues.length === 0 && prs.length === 0) {
+                continue;
+            }
+            const assessment = assessOrphanSignature(issues, prs, ctx, issueFilter, tally);
+            if (assessment.orphaned && assessment.reason !== null && assessment.kind !== null) {
+                orphans.push({
+                    path: relBriefPath(brief.path, root),
+                    reason: assessment.reason,
+                    kind: assessment.kind,
+                });
+            }
         }
-        if (issues.length === 0 && prs.length === 0) {
-            continue;
+        const basis = {
+            inventory: tally.inventory,
+            live: tally.live,
+            cache: tally.cache,
+            unverified: tally.unverified,
+            maxCacheAgeMs: tally.cache > 0 ? tally.maxCacheAgeMs : null,
+            proxied: runner?.proxied ?? false,
+            elapsedMs: Math.max(0, clock() - startedMs),
+            budgetMs,
+        };
+        if (orphans.length > 0) {
+            return {
+                code: 1,
+                message: formatRefusal(orphans, root, issueFilter, tally, basis),
+                stream: "stderr",
+                orphans,
+                basis,
+            };
         }
-        const assessment = assessOrphanSignature(issues, prs, root, runGh, skipGh, issueFilter);
-        if (assessment.orphaned && assessment.reason !== null && assessment.kind !== null) {
-            orphans.push({
-                path: relBriefPath(brief.path, root),
-                reason: assessment.reason,
-                kind: assessment.kind,
-            });
+        if (quiet) {
+            return { code: 0, message: "", stream: "none", orphans: [], basis };
         }
-    }
-    if (orphans.length > 0) {
+        const issueNote = issueFilter === null ? "" : ` for issue #${issueFilter}`;
+        const headline = `verify:orphan-active: no orphaned active/running xBRIEFs${issueNote} ` +
+            `(scanned ${scanned} running brief${scanned === 1 ? "" : "s"} in active/).`;
         return {
-            code: 1,
-            message: formatRefusal(orphans, root, issueFilter),
-            stream: "stderr",
-            orphans,
+            code: 0,
+            message: [headline, ...basisLines(tally, basis)].join("\n"),
+            stream: "stdout",
+            orphans: [],
+            basis,
         };
     }
-    if (quiet) {
-        return { code: 0, message: "", stream: "none", orphans: [] };
+    catch (err) {
+        if (err instanceof ScmStubError) {
+            return {
+                code: 2,
+                message: `verify:orphan-active: ${err.message}`,
+                stream: "stderr",
+                orphans: [],
+                basis: emptyBasis(budgetMs),
+            };
+        }
+        throw err;
     }
-    const scanned = listActiveRunningBriefs(root).length;
-    const issueNote = issueFilter === null ? "" : ` for issue #${issueFilter}`;
-    return {
-        code: 0,
-        message: `verify:orphan-active: no orphaned active/running xBRIEFs${issueNote} ` +
-            `(scanned ${scanned} running brief${scanned === 1 ? "" : "s"} in active/).`,
-        stream: "stdout",
-        orphans: [],
-    };
 }
 //# sourceMappingURL=evaluate.js.map

package/dist/orphan-active/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./evaluate.js";
+export * from "./issue-state.js";
 export * from "./refs.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/orphan-active/index.js

@@ -1,3 +1,4 @@
 export * from "./evaluate.js";
+export * from "./issue-state.js";
 export * from "./refs.js";
 //# sourceMappingURL=index.js.map

package/dist/orphan-active/issue-state.d.ts

@@ -0,0 +1,121 @@
+import type { RunGhFn } from "../pr-protected-issues/types.js";
+import type { IssueRef } from "./refs.js";
+export type IssueState = "open" | "closed";
+/**
+ * How a verdict was reached (#3767). `unverified` means the gate could not
+ * establish state, so a pass on that reference proves nothing.
+ */
+export type StateBasis = "inventory" | "live" | "cache" | "unverified";
+export type StateResolution = 
+/** Resolved from the complete open-issue inventory or an authoritative read. */
+{
+    readonly state: IssueState;
+    readonly basis: "inventory" | "live";
+}
+/** Resolved from a triage-cache entry inside the freshness bound. */
+ | {
+    readonly state: IssueState;
+    readonly basis: "cache";
+    readonly cacheAgeMs: number;
+}
+/** State could not be established; a pass on this reference proves nothing. */
+ | {
+    readonly state: null;
+    readonly basis: "unverified";
+    readonly detail: string;
+};
+/**
+ * A cache hit older than this is no longer evidence (#3767). The measured
+ * defect was a ~12 h old cached `open` suppressing the live read that would
+ * have corrected it; 15 min keeps warm-cache offline runs working while making
+ * an overnight entry non-authoritative.
+ */
+export declare const ISSUE_CACHE_MAX_AGE_MS: number;
+/**
+ * Latency budget for scoped `--issue N`: one authoritative issue read plus at
+ * most one linked-PR read. Measured ~0.75 s per `gh api` read; the headroom
+ * covers a slow network or a `ghx` proxy hop.
+ */
+export declare const SCOPED_LATENCY_BUDGET_MS = 5000;
+/**
+ * Latency budget for the unscoped aggregate sweep. One complete open-issue
+ * inventory measured 4.2 s constant on deftai/directive (560 open issues),
+ * against 14.2 s and 76.6 s for per-brief reads at the WIP cap of 20 on two
+ * hosts. The budget is sized for the inventory plus a few confirming reads and
+ * keeps the gate inside the fast-preflight tier.
+ */
+export declare const AGGREGATE_LATENCY_BUDGET_MS = 15000;
+export interface GateRunner {
+    readonly runGh: RunGhFn;
+    /**
+     * True when reads resolve through `ghx`, a cached GET proxy. The freshness
+     * guarantee is then bounded by that proxy, which this gate cannot inspect.
+     */
+    readonly proxied: boolean;
+}
+/**
+ * Pin plain `gh` for this gate's authoritative reads (#3767). `resolveBinary`
+ * prefers `ghx` — a cached GET proxy — so an unpinned "live" read is itself a
+ * cache. When `gh` is absent we still run, and report the proxy caveat rather
+ * than claiming freshness we cannot deliver. Whether `ghx` should be preferred
+ * at all is #3737.
+ */
+export declare function makeGateRunner(): GateRunner;
+interface CachedIssue {
+    readonly state: IssueState | null;
+    readonly ageMs: number | null;
+}
+/** Read the triage-cache issue state together with the entry's age (#3767). */
+export declare function readCachedIssue(projectRoot: string, ref: IssueRef, nowMs: number): CachedIssue;
+/** Authoritative single-issue REST read. Returns `null` on any failure. */
+export declare function fetchIssueStateLive(ref: IssueRef, runGh: RunGhFn): IssueState | null;
+type InventoryLookup = {
+    numbers: ReadonlySet<number>;
+} | {
+    error: string;
+};
+/**
+ * One complete open-issue inventory per repo per run (#3767, reusing #3752).
+ * `restIssueListOpenInventory` fails closed on command failure, non-array JSON,
+ * malformed rows, buffer exhaustion, and pagination cap — so absence from a
+ * successful inventory really does mean "not open", and a truncated read is an
+ * error rather than a silent "closed".
+ */
+export declare class OpenIssueInventory {
+    private readonly runGh;
+    private readonly byRepo;
+    private readonly confirmations;
+    constructor(runGh: RunGhFn);
+    lookup(repo: string): InventoryLookup;
+    /**
+     * Confirm an inventory absence with one authoritative read, reused for the
+     * rest of this run when several briefs name the same issue (#3767).
+     */
+    confirm(ref: IssueRef): IssueState | null;
+    private fetch;
+}
+export interface ResolveContext {
+    readonly projectRoot: string;
+    readonly runGh: RunGhFn;
+    readonly skipGh: boolean;
+    readonly nowMs: number;
+    readonly inventory: OpenIssueInventory;
+}
+/** Human-readable duration for basis reporting: `42s`, `9m`, `12h`, `3d`. */
+export declare function formatAge(ms: number): string;
+/**
+ * Scoped `--issue N`: a proof obligation before DONE, so read authoritatively
+ * first and accept a cache hit only inside the freshness bound. Unknown stays
+ * fail-closed at the call site.
+ */
+export declare function resolveIssueStateScoped(ref: IssueRef, ctx: ResolveContext): StateResolution;
+/**
+ * Unscoped aggregate: resolve every reference from one complete open-issue
+ * inventory rather than a live read per brief. Membership means open. Absence
+ * means "not open", which is the direction that tells an operator to run
+ * `scope:complete`, so it is confirmed by one authoritative read before the
+ * gate acts on it.
+ */
+export declare function resolveIssueStateAggregate(ref: IssueRef, ctx: ResolveContext): StateResolution;
+export {};
+//# sourceMappingURL=issue-state.d.ts.map