@deftai/directive-core 0.106.0 → 0.108.0

package/dist/triage/evaluate/evaluate.d.ts

@@ -0,0 +1,11 @@
+import { type EvaluateOptions, type EvaluateResult } from "./types.js";
+export declare class EvaluateError extends Error {
+    name: string;
+}
+/**
+ * Stage A parent: WIP census + GitHub REST + worktree fan-out + sink write.
+ * Evaluators never receive the WIP census.
+ */
+export declare function evaluateIssues(options: EvaluateOptions): Promise<EvaluateResult>;
+export declare function renderEvaluateText(result: EvaluateResult): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/triage/evaluate/evaluate.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { runText } from "../../swarm/subprocess.js";
+import { defaultGitRunner } from "../../swarm/worktrees.js";
+import { defaultGithubReader, pullsMentioning } from "./github.js";
+import { sha12Of, sinkDir } from "./paths.js";
+import { gcStaleSha12Dirs, writeInvocationSink } from "./sink.js";
+import { DEFAULT_CONCURRENCY, ORIGIN_MASTER, } from "./types.js";
+import { evaluateValidity, joinValidityWithGithub } from "./validity.js";
+import { buildValueAdvice } from "./value.js";
+import { collectWipCensus, wipHitsForIssue } from "./wip-census.js";
+import { addEvaluatorWorktree, removeEvaluatorWorktree } from "./worktrees.js";
+export class EvaluateError extends Error {
+    name = "EvaluateError";
+}
+function resolveOriginSha(projectRoot, git) {
+    const proc = git(["rev-parse", ORIGIN_MASTER], projectRoot);
+    if (proc.returncode !== 0) {
+        throw new EvaluateError(`could not resolve ${ORIGIN_MASTER}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    return proc.stdout.trim();
+}
+function defaultSessionStart(worktreePath) {
+    const proc = runText(["deft", "session:start", "--read-only"], { cwd: worktreePath });
+    if (proc.returncode !== 0) {
+        throw new EvaluateError(`session:start --read-only failed in ${worktreePath}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+}
+async function mapPool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (true) {
+            const index = next;
+            next += 1;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await fn(items[index], index);
+        }
+    };
+    const n = Math.max(1, Math.min(limit, Math.max(items.length, 1)));
+    await Promise.all(Array.from({ length: n }, () => worker()));
+    return results;
+}
+function collectGithubForRepo(repo, issues, reader) {
+    const views = issues.map((n) => reader.viewIssue(repo, n));
+    const openPulls = reader.listOpenPulls(repo);
+    reader.listOpenIssues(repo);
+    return { issues: views, openPulls };
+}
+/**
+ * Stage A parent: WIP census + GitHub REST + worktree fan-out + sink write.
+ * Evaluators never receive the WIP census.
+ */
+export async function evaluateIssues(options) {
+    const issues = [...new Set(options.issues)].filter((n) => Number.isInteger(n) && n > 0);
+    if (issues.length === 0) {
+        throw new EvaluateError("triage:evaluate requires one or more issue numbers");
+    }
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new EvaluateError("--concurrency must be a positive integer");
+    }
+    const git = options.git ?? defaultGitRunner;
+    const sessionStart = options.sessionStart ?? defaultSessionStart;
+    const github = options.github ?? defaultGithubReader();
+    const originSha = resolveOriginSha(options.projectRoot, git);
+    const sha12 = sha12Of(originSha);
+    const invocationId = options.invocationId ?? randomUUID();
+    const wip = collectWipCensus(options.projectRoot, issues);
+    const githubViews = collectGithubForRepo(options.repo, issues, github);
+    const viewByIssue = new Map(githubViews.issues.map((snap) => [snap.number, snap]));
+    const runOne = async (issue) => {
+        let worktreePath = null;
+        let teardownError = null;
+        const snap = viewByIssue.get(issue) ?? null;
+        const pulls = pullsMentioning(githubViews.openPulls, issue);
+        let verdict;
+        try {
+            worktreePath = addEvaluatorWorktree(options.projectRoot, issue, invocationId, originSha, git);
+            sessionStart(worktreePath);
+            const validity = evaluateValidity(worktreePath, issue);
+            const joined = joinValidityWithGithub(validity, snap?.state ?? null);
+            const duplicates = snap?.duplicateOf !== null && snap?.duplicateOf !== undefined ? [snap.duplicateOf] : [];
+            verdict = {
+                issue,
+                sha12,
+                invocationId,
+                validity: joined,
+                wip: wipHitsForIssue(wip, issue),
+                github: snap,
+                openPulls: pulls,
+                duplicates,
+                value: buildValueAdvice(snap),
+                error: null,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            verdict = {
+                issue,
+                sha12,
+                invocationId,
+                validity: null,
+                wip: wipHitsForIssue(wip, issue),
+                github: snap,
+                openPulls: pulls,
+                duplicates: [],
+                value: buildValueAdvice(snap),
+                error: message,
+            };
+        }
+        finally {
+            if (worktreePath !== null) {
+                try {
+                    removeEvaluatorWorktree(options.projectRoot, worktreePath, git);
+                }
+                catch (teardownErr) {
+                    teardownError = teardownErr instanceof Error ? teardownErr.message : String(teardownErr);
+                }
+            }
+        }
+        if (teardownError !== null) {
+            verdict = {
+                ...verdict,
+                error: verdict.error !== null ? `${verdict.error}; teardown: ${teardownError}` : teardownError,
+            };
+        }
+        return verdict;
+    };
+    try {
+        const verdicts = await mapPool(issues, concurrency, (issue) => runOne(issue));
+        const result = {
+            sha12,
+            invocationId,
+            originSha,
+            sinkDir: sinkDir(options.projectRoot, sha12, invocationId),
+            concurrency,
+            verdicts,
+        };
+        writeInvocationSink(options.projectRoot, result);
+        gcStaleSha12Dirs(options.projectRoot, sha12);
+        return result;
+    }
+    catch (err) {
+        gcStaleSha12Dirs(options.projectRoot, sha12);
+        throw err;
+    }
+}
+export function renderEvaluateText(result) {
+    const lines = [
+        `triage:evaluate sha12=${result.sha12} invocation=${result.invocationId} concurrency=${result.concurrency}`,
+        `sink: ${result.sinkDir}`,
+    ];
+    for (const verdict of result.verdicts) {
+        const state = verdict.validity?.state ?? "error";
+        const evidence = verdict.validity?.evidence ?? verdict.error ?? "";
+        const wip = verdict.wip.length > 0 ? ` wip=${verdict.wip.length}` : " wip=0";
+        lines.push(`#${verdict.issue} validity=${state}${wip} critique-recommend: ${verdict.value["critique-recommend"]}`);
+        if (evidence.length > 0) {
+            lines.push(`  ${evidence}`);
+        }
+        if (verdict.error !== null) {
+            lines.push(`  error: ${verdict.error}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/triage/evaluate/github.d.ts

@@ -0,0 +1,16 @@
+import { type RunGhApiFn } from "../../scm/gh-rest.js";
+import type { GithubCensus, GithubIssueSnapshot, GithubPullSnapshot } from "./types.js";
+export declare function snapshotFromIssuePayload(raw: Record<string, unknown>): GithubIssueSnapshot;
+export declare function snapshotFromPullPayload(raw: Record<string, unknown>): GithubPullSnapshot;
+export interface GithubSeams {
+    readonly runGhApiFn?: RunGhApiFn;
+}
+/** GET-only GitHub census. Parent-owned. Never POST/PATCH/PUT/DELETE. */
+export declare function collectGithubCensus(repo: string, issues: readonly number[], seams?: GithubSeams): GithubCensus;
+export declare function defaultGithubReader(seams?: GithubSeams): {
+    viewIssue: (repo: string, n: number) => GithubIssueSnapshot;
+    listOpenIssues: (repo: string) => GithubIssueSnapshot[];
+    listOpenPulls: (repo: string) => GithubPullSnapshot[];
+};
+export declare function pullsMentioning(pulls: readonly GithubPullSnapshot[], issue: number): GithubPullSnapshot[];
+//# sourceMappingURL=github.d.ts.map

package/dist/triage/evaluate/github.js

@@ -0,0 +1,153 @@
+import { GhRestError, restIssueListPaginated, restIssueView, runGhApi, splitRepo, } from "../../scm/gh-rest.js";
+const DUPLICATE_RE = /duplicate of\s+#(\d+)/iu;
+const MENTION_RE = /(?:#|issues\/)(\d+)\b/gu;
+function labelsOf(raw) {
+    const labels = raw.labels;
+    if (!Array.isArray(labels)) {
+        return [];
+    }
+    const out = [];
+    for (const item of labels) {
+        if (typeof item === "string") {
+            out.push(item);
+            continue;
+        }
+        if (item !== null && typeof item === "object" && "name" in item) {
+            const name = item.name;
+            if (typeof name === "string") {
+                out.push(name);
+            }
+        }
+    }
+    return out;
+}
+function duplicateOf(title, body, labels) {
+    const match = DUPLICATE_RE.exec(`${title}\n${body}`);
+    if (match?.[1] !== undefined) {
+        return Number.parseInt(match[1], 10);
+    }
+    if (labels.some((label) => label.toLowerCase().includes("duplicate"))) {
+        const hash = /#(\d+)/u.exec(title);
+        if (hash?.[1] !== undefined) {
+            return Number.parseInt(hash[1], 10);
+        }
+    }
+    return null;
+}
+export function snapshotFromIssuePayload(raw) {
+    const number = typeof raw.number === "number" ? raw.number : Number.parseInt(String(raw.number), 10);
+    const state = raw.state === "closed" ? "closed" : "open";
+    const title = typeof raw.title === "string" ? raw.title : "";
+    const body = typeof raw.body === "string" ? raw.body : "";
+    const labels = labelsOf(raw);
+    const htmlUrl = typeof raw.html_url === "string" ? raw.html_url : null;
+    return {
+        number,
+        state,
+        title,
+        body,
+        labels,
+        htmlUrl,
+        pullRequest: raw.pull_request !== undefined && raw.pull_request !== null,
+        duplicateOf: duplicateOf(title, body, labels),
+    };
+}
+function mentionsFrom(text) {
+    const found = new Set();
+    for (const match of text.matchAll(MENTION_RE)) {
+        if (match[1] !== undefined) {
+            found.add(Number.parseInt(match[1], 10));
+        }
+    }
+    return [...found];
+}
+export function snapshotFromPullPayload(raw) {
+    const number = typeof raw.number === "number" ? raw.number : Number.parseInt(String(raw.number), 10);
+    const title = typeof raw.title === "string" ? raw.title : "";
+    const body = typeof raw.body === "string" ? raw.body : "";
+    return {
+        number,
+        title,
+        body,
+        htmlUrl: typeof raw.html_url === "string" ? raw.html_url : null,
+        mentions: mentionsFrom(`${title}\n${body}`),
+    };
+}
+const OPEN_PULLS_PER_PAGE = 100;
+const OPEN_PULLS_MAX_PAGES = 50;
+function parsePullPage(stdout) {
+    const parsed = JSON.parse(stdout.trim() || "[]");
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    return parsed
+        .filter((item) => item !== null && typeof item === "object")
+        .map((item) => snapshotFromPullPayload(item));
+}
+function fetchPullPage(runner, endpoint, page) {
+    const result = runner([
+        endpoint,
+        "--method",
+        "GET",
+        "--raw-field",
+        "state=open",
+        "--raw-field",
+        `per_page=${OPEN_PULLS_PER_PAGE}`,
+        "--raw-field",
+        `page=${page}`,
+    ]);
+    if (result.returncode !== 0) {
+        throw new Error(`GET ${endpoint} failed: ${result.stderr.trim() || "no stderr"}`);
+    }
+    return parsePullPage(result.stdout);
+}
+function listOpenPulls(repo, seams) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/pulls`;
+    const runner = seams.runGhApiFn ?? runGhApi;
+    const out = [];
+    for (let page = 1; page <= OPEN_PULLS_MAX_PAGES; page += 1) {
+        const pageItems = fetchPullPage(runner, endpoint, page);
+        out.push(...pageItems);
+        if (pageItems.length < OPEN_PULLS_PER_PAGE) {
+            return out;
+        }
+    }
+    // Full last collected page: probe one more page to distinguish exactly-at-cap
+    // from a truncated census. Do not collect past the cap.
+    const overflow = fetchPullPage(runner, endpoint, OPEN_PULLS_MAX_PAGES + 1);
+    if (overflow.length === 0) {
+        return out;
+    }
+    throw new GhRestError({
+        stderr: `open-pull census truncated: last page ${OPEN_PULLS_MAX_PAGES} was full (${OPEN_PULLS_PER_PAGE} items) and page ${OPEN_PULLS_MAX_PAGES + 1} has more; later PRs are omitted`,
+        exitCode: 0,
+        endpoint,
+        payload: null,
+        hint: "census is incomplete; fail the evaluation rather than treating a truncated list as complete",
+    });
+}
+/** GET-only GitHub census. Parent-owned. Never POST/PATCH/PUT/DELETE. */
+export function collectGithubCensus(repo, issues, seams = {}) {
+    const views = {};
+    for (const n of issues) {
+        const raw = restIssueView(repo, n, { runGhApiFn: seams.runGhApiFn });
+        views[n] = snapshotFromIssuePayload(raw);
+    }
+    const openIssues = restIssueListPaginated(repo, { state: "open", excludePulls: true, perPage: 100 }, { runGhApiFn: seams.runGhApiFn }).map((raw) => snapshotFromIssuePayload(raw));
+    const openPulls = listOpenPulls(repo, seams);
+    return { issues: views, openIssues, openPulls };
+}
+export function defaultGithubReader(seams = {}) {
+    return {
+        viewIssue: (repo, n) => snapshotFromIssuePayload(restIssueView(repo, n, { runGhApiFn: seams.runGhApiFn })),
+        listOpenIssues: (repo) => restIssueListPaginated(repo, { state: "open", excludePulls: true, perPage: 100 }, {
+            runGhApiFn: seams.runGhApiFn,
+        }).map((raw) => snapshotFromIssuePayload(raw)),
+        listOpenPulls: (repo) => listOpenPulls(repo, seams),
+    };
+}
+export function pullsMentioning(pulls, issue) {
+    return pulls.filter((pull) => pull.mentions.includes(issue) || pull.number === issue);
+}
+//# sourceMappingURL=github.js.map

package/dist/triage/evaluate/index.d.ts

@@ -0,0 +1,9 @@
+export { EvaluateError, evaluateIssues, renderEvaluateText } from "./evaluate.js";
+export { evaluatorWorktreePath, sha12Of, sinkDir } from "./paths.js";
+export type { EvaluateOptions, EvaluateResult, GithubReader, IssueEvalVerdict, ValidityState, ValueAdvice, WipCensus, } from "./types.js";
+export { CRITIQUE_RECOMMEND_FIELD, DEFAULT_CONCURRENCY, RESERVED_CLEARANCE_RE } from "./types.js";
+export { evaluateValidity } from "./validity.js";
+export { buildValueAdvice, formatValueField, ReservedClearanceError } from "./value.js";
+export { collectWipCensus } from "./wip-census.js";
+export { addEvaluatorWorktree, removeEvaluatorWorktree } from "./worktrees.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/triage/evaluate/index.js

@@ -0,0 +1,8 @@
+export { EvaluateError, evaluateIssues, renderEvaluateText } from "./evaluate.js";
+export { evaluatorWorktreePath, sha12Of, sinkDir } from "./paths.js";
+export { CRITIQUE_RECOMMEND_FIELD, DEFAULT_CONCURRENCY, RESERVED_CLEARANCE_RE } from "./types.js";
+export { evaluateValidity } from "./validity.js";
+export { buildValueAdvice, formatValueField, ReservedClearanceError } from "./value.js";
+export { collectWipCensus } from "./wip-census.js";
+export { addEvaluatorWorktree, removeEvaluatorWorktree } from "./worktrees.js";
+//# sourceMappingURL=index.js.map

package/dist/triage/evaluate/paths.d.ts

@@ -0,0 +1,7 @@
+export declare function sha12Of(fullSha: string): string;
+export declare function issueEvalScratchRoot(projectRoot: string): string;
+export declare function sinkDir(projectRoot: string, sha12: string, invocationId: string): string;
+export declare function sinkVerdictPath(projectRoot: string, sha12: string, invocationId: string, issue: number): string;
+export declare function sinkManifestPath(projectRoot: string, sha12: string, invocationId: string): string;
+export declare function evaluatorWorktreePath(projectRoot: string, issue: number, invocationId: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/triage/evaluate/paths.js

@@ -0,0 +1,25 @@
+import { join, resolve } from "node:path";
+import { SHA12_LENGTH } from "./types.js";
+export function sha12Of(fullSha) {
+    const trimmed = fullSha.trim().toLowerCase();
+    if (!/^[0-9a-f]{12,40}$/u.test(trimmed)) {
+        throw new Error(`origin/master SHA is not a git object id: ${fullSha.trim()}`);
+    }
+    return trimmed.slice(0, SHA12_LENGTH);
+}
+export function issueEvalScratchRoot(projectRoot) {
+    return join(resolve(projectRoot), ".deft-scratch", "issue-eval");
+}
+export function sinkDir(projectRoot, sha12, invocationId) {
+    return join(issueEvalScratchRoot(projectRoot), sha12, invocationId);
+}
+export function sinkVerdictPath(projectRoot, sha12, invocationId, issue) {
+    return join(sinkDir(projectRoot, sha12, invocationId), `issue-${issue}.json`);
+}
+export function sinkManifestPath(projectRoot, sha12, invocationId) {
+    return join(sinkDir(projectRoot, sha12, invocationId), "manifest.json");
+}
+export function evaluatorWorktreePath(projectRoot, issue, invocationId) {
+    return join(resolve(projectRoot), ".deft-scratch", "worktrees", `issue-eval-${issue}-${invocationId}`).replace(/\\/g, "/");
+}
+//# sourceMappingURL=paths.js.map

package/dist/triage/evaluate/sink.d.ts

@@ -0,0 +1,5 @@
+import type { EvaluateResult } from "./types.js";
+export declare function writeInvocationSink(projectRoot: string, result: EvaluateResult): string;
+export declare function gcStaleSha12Dirs(projectRoot: string, currentSha12: string): string[];
+export declare function teardownSink(projectRoot: string, sha12: string, invocationId: string): void;
+//# sourceMappingURL=sink.d.ts.map

package/dist/triage/evaluate/sink.js

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { containedRemove, containedWrite } from "../../fs/contained-write.js";
+import { issueEvalScratchRoot, sinkDir, sinkManifestPath, sinkVerdictPath } from "./paths.js";
+import { assertNoReservedClearance } from "./value.js";
+export function writeInvocationSink(projectRoot, result) {
+    const root = resolve(projectRoot);
+    const serialized = JSON.stringify(result, null, 2);
+    assertNoReservedClearance(serialized, "verdict sink");
+    containedWrite({
+        root,
+        target: sinkManifestPath(projectRoot, result.sha12, result.invocationId),
+        data: `${serialized}\n`,
+        mode: "replace",
+    });
+    for (const verdict of result.verdicts) {
+        const body = JSON.stringify(verdict, null, 2);
+        assertNoReservedClearance(body, `verdict issue-${verdict.issue}`);
+        containedWrite({
+            root,
+            target: sinkVerdictPath(projectRoot, result.sha12, result.invocationId, verdict.issue),
+            data: `${body}\n`,
+            mode: "replace",
+        });
+    }
+    return sinkDir(projectRoot, result.sha12, result.invocationId);
+}
+export function gcStaleSha12Dirs(projectRoot, currentSha12) {
+    const root = resolve(projectRoot);
+    const scratch = issueEvalScratchRoot(projectRoot);
+    if (!existsSync(scratch)) {
+        return [];
+    }
+    const removed = [];
+    for (const name of readdirSync(scratch)) {
+        if (name === currentSha12) {
+            continue;
+        }
+        const target = `${scratch.replace(/\\/g, "/")}/${name}`;
+        containedRemove({ root, target, recursive: true });
+        removed.push(name);
+    }
+    return removed;
+}
+export function teardownSink(projectRoot, sha12, invocationId) {
+    const dir = sinkDir(projectRoot, sha12, invocationId);
+    if (!existsSync(dir)) {
+        return;
+    }
+    containedRemove({ root: resolve(projectRoot), target: dir, recursive: true });
+}
+//# sourceMappingURL=sink.js.map

package/dist/triage/evaluate/types.d.ts

@@ -0,0 +1,93 @@
+/** Stage A issue-eval types (#3648). */
+export declare const DEFAULT_CONCURRENCY = 4;
+export declare const ORIGIN_MASTER = "origin/master";
+export declare const SHA12_LENGTH = 12;
+export declare const CRITIQUE_RECOMMEND_FIELD = "critique-recommend";
+export declare const RESERVED_CLEARANCE_RE: RegExp;
+export declare const VALIDITY_STATES: readonly ["still-open", "partial", "likely-shipped", "needs-re-scope"];
+export type ValidityState = (typeof VALIDITY_STATES)[number];
+export interface ValidityVerdict {
+    readonly state: ValidityState;
+    readonly evidence: string;
+    readonly worktreePath: string;
+    readonly sessionStartReadOnly: true;
+}
+export interface WipHit {
+    readonly kind: "active-xbrief" | "pending-xbrief" | "plan-sequence";
+    readonly path: string;
+    readonly issue: number;
+}
+export interface WipCensus {
+    readonly active: readonly WipHit[];
+    readonly pending: readonly WipHit[];
+    readonly planSequence: readonly WipHit[];
+}
+export interface GithubIssueSnapshot {
+    readonly number: number;
+    readonly state: "open" | "closed";
+    readonly title: string;
+    readonly body: string;
+    readonly labels: readonly string[];
+    readonly htmlUrl: string | null;
+    readonly pullRequest: boolean;
+    readonly duplicateOf: number | null;
+}
+export interface GithubPullSnapshot {
+    readonly number: number;
+    readonly title: string;
+    readonly body: string;
+    readonly htmlUrl: string | null;
+    readonly mentions: readonly number[];
+}
+export interface GithubCensus {
+    readonly issues: Readonly<Record<number, GithubIssueSnapshot>>;
+    readonly openIssues: readonly GithubIssueSnapshot[];
+    readonly openPulls: readonly GithubPullSnapshot[];
+}
+export interface ValueAdvice {
+    readonly [CRITIQUE_RECOMMEND_FIELD]: boolean;
+    readonly reason: string;
+}
+export interface IssueEvalVerdict {
+    readonly issue: number;
+    readonly sha12: string;
+    readonly invocationId: string;
+    readonly validity: ValidityVerdict | null;
+    readonly wip: readonly WipHit[];
+    readonly github: GithubIssueSnapshot | null;
+    readonly openPulls: readonly GithubPullSnapshot[];
+    readonly duplicates: readonly number[];
+    readonly value: ValueAdvice;
+    readonly error: string | null;
+}
+export interface EvaluateResult {
+    readonly sha12: string;
+    readonly invocationId: string;
+    readonly originSha: string;
+    readonly sinkDir: string;
+    readonly concurrency: number;
+    readonly verdicts: readonly IssueEvalVerdict[];
+}
+export interface GitRunnerResult {
+    readonly returncode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type GitRunner = (args: readonly string[], cwd: string) => GitRunnerResult;
+export type SessionStartFn = (worktreePath: string) => void;
+export type GithubReader = {
+    readonly viewIssue: (repo: string, n: number) => GithubIssueSnapshot;
+    readonly listOpenIssues: (repo: string) => readonly GithubIssueSnapshot[];
+    readonly listOpenPulls: (repo: string) => readonly GithubPullSnapshot[];
+};
+export interface EvaluateOptions {
+    readonly projectRoot: string;
+    readonly repo: string;
+    readonly issues: readonly number[];
+    readonly concurrency?: number;
+    readonly invocationId?: string;
+    readonly git?: GitRunner;
+    readonly sessionStart?: SessionStartFn;
+    readonly github?: GithubReader;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/triage/evaluate/types.js

@@ -0,0 +1,13 @@
+/** Stage A issue-eval types (#3648). */
+export const DEFAULT_CONCURRENCY = 4;
+export const ORIGIN_MASTER = "origin/master";
+export const SHA12_LENGTH = 12;
+export const CRITIQUE_RECOMMEND_FIELD = "critique-recommend";
+export const RESERVED_CLEARANCE_RE = /design-critique:\s*(?:warranted|not warranted)(?:\s*\|\s*(?:warranted|not warranted))?\s*,\s*because/iu;
+export const VALIDITY_STATES = [
+    "still-open",
+    "partial",
+    "likely-shipped",
+    "needs-re-scope",
+];
+//# sourceMappingURL=types.js.map

package/dist/triage/evaluate/validity.d.ts

@@ -0,0 +1,8 @@
+import type { ValidityVerdict } from "./types.js";
+/**
+ * Evaluator-owned. Reads only `worktreeRoot` (detached origin/master).
+ * Must not accept a WIP census argument.
+ */
+export declare function evaluateValidity(worktreeRoot: string, issue: number): ValidityVerdict;
+export declare function joinValidityWithGithub(validity: ValidityVerdict, githubState: "open" | "closed" | null): ValidityVerdict;
+//# sourceMappingURL=validity.d.ts.map

package/dist/triage/evaluate/validity.js

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listXbriefHits } from "./xbrief-refs.js";
+const ADR_DIR = join("docs", "decisions");
+const CONTRACT_DIR = join("content", "contracts");
+function filesMentionIssue(dir, issue) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const needle = `#${issue}`;
+    const hits = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".md")) {
+            continue;
+        }
+        const path = join(dir, name);
+        try {
+            const text = readFileSync(path, "utf8");
+            if (text.includes(needle) || text.includes(`/issues/${issue}`)) {
+                hits.push(path);
+            }
+        }
+        catch { }
+    }
+    return hits;
+}
+/**
+ * Evaluator-owned. Reads only `worktreeRoot` (detached origin/master).
+ * Must not accept a WIP census argument.
+ */
+export function evaluateValidity(worktreeRoot, issue) {
+    const completed = listXbriefHits(worktreeRoot, "completed").filter((hit) => hit.issue === issue);
+    const pending = listXbriefHits(worktreeRoot, "pending").filter((hit) => hit.issue === issue);
+    const active = listXbriefHits(worktreeRoot, "active").filter((hit) => hit.issue === issue);
+    const proposed = listXbriefHits(worktreeRoot, "proposed").filter((hit) => hit.issue === issue);
+    const adrHits = filesMentionIssue(join(worktreeRoot, ADR_DIR), issue);
+    const contractHits = filesMentionIssue(join(worktreeRoot, CONTRACT_DIR), issue);
+    if (completed.length > 0) {
+        return {
+            state: "likely-shipped",
+            evidence: `completed xbrief on origin/master: ${completed[0]?.path}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    if (pending.length > 0 || active.length > 0 || proposed.length > 0) {
+        const hit = pending[0] ?? active[0] ?? proposed[0];
+        return {
+            state: "partial",
+            evidence: `committed lifecycle xbrief on origin/master: ${hit?.path}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    if (adrHits.length > 0 || contractHits.length > 0) {
+        return {
+            state: "partial",
+            evidence: `ADR/contract mention on origin/master: ${adrHits[0] ?? contractHits[0] ?? ""}`,
+            worktreePath: worktreeRoot,
+            sessionStartReadOnly: true,
+        };
+    }
+    return {
+        state: "still-open",
+        evidence: "no origin/master lifecycle coverage, ADR, or contract mention",
+        worktreePath: worktreeRoot,
+        sessionStartReadOnly: true,
+    };
+}
+export function joinValidityWithGithub(validity, githubState) {
+    if (githubState === "closed" && validity.state === "still-open") {
+        return {
+            ...validity,
+            state: "likely-shipped",
+            evidence: `${validity.evidence}; GitHub issue state=closed`,
+        };
+    }
+    if (githubState === "open" && validity.state === "likely-shipped") {
+        return {
+            ...validity,
+            state: "needs-re-scope",
+            evidence: `${validity.evidence}; GitHub issue still open`,
+        };
+    }
+    return validity;
+}
+//# sourceMappingURL=validity.js.map