@deftai/directive 0.55.0

package/dist/triage-classify.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listProject, validateProject } from "../../core/dist/triage/classify/index.js";
+/** Parse triage-classify CLI args, mirroring the Python argparse surface. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        doList: false,
+        doValidate: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--list") {
+            parsed.doList = true;
+        }
+        else if (arg === "--validate") {
+            parsed.doValidate = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return parsed;
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized arguments: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the CLI and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`ERR: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    try {
+        const st = statSync(projectRoot);
+        if (!st.isDirectory()) {
+            process.stderr.write(`ERR: --project-root ${projectRoot} does not exist or is not a directory.\n`);
+            return 2;
+        }
+    }
+    catch {
+        process.stderr.write(`ERR: --project-root ${projectRoot} does not exist or is not a directory.\n`);
+        return 2;
+    }
+    if (args.doValidate) {
+        const result = validateProject(projectRoot);
+        if (result.stdout.length > 0) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr.length > 0) {
+            process.stderr.write(result.stderr);
+        }
+        return result.code;
+    }
+    process.stdout.write(listProject(projectRoot));
+    return 0;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=triage-classify.js.map

package/dist/triage-help.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=triage-help.d.ts.map

package/dist/triage-help.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { runHelp } from "../../core/dist/triage/help/index.js";
+export function run(argv) {
+    return runHelp(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=triage-help.js.map

package/dist/triage-queue-parity.d.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface QueueFixtureIssue {
+    readonly number: number;
+    readonly title?: string;
+    readonly state?: string;
+    readonly labels?: readonly string[];
+    readonly updatedAt?: string;
+    readonly createdAt?: string;
+}
+export interface QueueAuditEntry {
+    readonly issueNumber: number;
+    readonly decision: string;
+    readonly timestamp?: string;
+}
+export interface QueueFixtureOptions {
+    readonly repo?: string;
+    readonly issues?: readonly QueueFixtureIssue[];
+    readonly auditEntries?: readonly QueueAuditEntry[];
+    readonly rankingLabels?: readonly string[];
+    readonly activeIssueNumbers?: readonly number[];
+    readonly sliceRecords?: readonly Record<string, unknown>[];
+    readonly blockedIssueNumbers?: readonly number[];
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly argv: readonly string[];
+    readonly fixture?: QueueFixtureOptions;
+    readonly skipFixture?: boolean;
+}
+export interface ParityDiff {
+    readonly caseName: string;
+    readonly exitMismatch: boolean;
+    readonly stdoutMismatch: boolean;
+    readonly stderrMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: readonly ParityDiff[];
+}
+/** Strip volatile absolute paths before compare. */
+export declare function normalizeOutput(text: string): string;
+/** Build a throwaway project root with optional queue fixtures. */
+export declare function buildFixtureRepo(options?: QueueFixtureOptions): string;
+/** Diff one parity case between Python oracle and TS CLI. */
+export declare function diffCase(python: CommandCapture, ts: CommandCapture, caseName: string): ParityDiff;
+export declare const PARITY_CASES: readonly ParityCase[];
+/** Augment argv with fixture audit/slices hooks when present. */
+export declare function augmentParityArgv(testCase: ParityCase, root: string): readonly string[];
+/** Run all parity cases; returns aggregate result. */
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=triage-queue-parity.d.ts.map

package/dist/triage-queue-parity.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1725): builds throwaway fixture repos, runs
+ * BOTH the Python oracle (`scripts/triage_queue.py queue`) and the ported TS
+ * triage:queue CLI, and diffs exit codes + stdout/stderr (cache-off).
+ *
+ * Exit codes: 0 parity / 1 divergence / 2 harness setup error.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_REPO = "owner/repo";
+/** Strip volatile absolute paths before compare. */
+export function normalizeOutput(text) {
+    return text.replace(/project_root=[^\s)]+/g, "project_root=<ROOT>");
+}
+function runCapture(cmd, args, cwd, env = {}) {
+    const merged = { ...process.env, ...env };
+    for (const key of Object.keys(merged)) {
+        if (merged[key] === undefined) {
+            delete merged[key];
+        }
+    }
+    const result = spawnSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        env: merged,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status ?? 2,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function writeCachedIssue(root, repo, issue) {
+    const parts = repo.split("/", 2);
+    const owner = parts[0];
+    const name = parts[1];
+    if (owner === undefined || name === undefined) {
+        throw new Error(`invalid repo slug: ${repo}`);
+    }
+    const dir = join(root, ".deft-cache", "github-issue", owner, name, String(issue.number));
+    mkdirSync(dir, { recursive: true });
+    const raw = {
+        number: issue.number,
+        title: issue.title ?? `Issue ${issue.number}`,
+        state: issue.state ?? "open",
+        labels: (issue.labels ?? []).map((label) => ({ name: label })),
+        updated_at: issue.updatedAt ?? "2026-05-17T20:00:00Z",
+        ...(issue.createdAt !== undefined ? { created_at: issue.createdAt } : {}),
+    };
+    writeFileSync(join(dir, "raw.json"), `${JSON.stringify(raw)}\n`, { encoding: "utf8" });
+}
+function writeAuditLog(root, repo, entries) {
+    const dir = join(root, "vbrief", ".eval");
+    mkdirSync(dir, { recursive: true });
+    const lines = entries.map((entry) => JSON.stringify({
+        decision_id: `id-${entry.issueNumber}-${entry.decision}`,
+        timestamp: entry.timestamp ?? "2026-05-17T20:00:00Z",
+        repo,
+        issue_number: entry.issueNumber,
+        decision: entry.decision,
+        actor: "parity",
+    }));
+    writeFileSync(join(dir, "candidates.jsonl"), `${lines.join("\n")}\n`, { encoding: "utf8" });
+}
+function writeProjectDefinition(root, rankingLabels) {
+    const dir = join(root, "vbrief");
+    mkdirSync(dir, { recursive: true });
+    const plan = { title: "T", status: "running", items: [] };
+    if (rankingLabels !== undefined && rankingLabels.length > 0) {
+        plan.policy = { triageRankingLabels: [...rankingLabels] };
+    }
+    writeFileSync(join(dir, "PROJECT-DEFINITION.vbrief.json"), `${JSON.stringify({ vBRIEFInfo: { version: "0.6" }, plan }, null, 2)}\n`, { encoding: "utf8" });
+}
+function writeActiveScope(root, repo, issueNumber, filename) {
+    const dir = join(root, "vbrief", "active");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, filename), `${JSON.stringify({
+        vBRIEFInfo: { version: "0.6" },
+        plan: {
+            title: "Active scope",
+            status: "running",
+            references: [
+                {
+                    uri: `https://github.com/${repo}/issues/${issueNumber}`,
+                    type: "x-vbrief/github-issue",
+                    title: `Issue #${issueNumber}`,
+                },
+            ],
+        },
+    })}\n`, { encoding: "utf8" });
+}
+function writeBlockedScope(root, repo, issueNumber, filename) {
+    const dir = join(root, "vbrief", "active");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, filename), `${JSON.stringify({
+        vBRIEFInfo: { version: "0.6" },
+        plan: {
+            title: "Blocked scope",
+            status: "blocked",
+            references: [
+                {
+                    uri: `https://github.com/${repo}/issues/${issueNumber}`,
+                    type: "x-vbrief/github-issue",
+                    title: `Issue #${issueNumber}`,
+                },
+            ],
+        },
+    })}\n`, { encoding: "utf8" });
+}
+function writeSliceRecords(root, records) {
+    const dir = join(root, "vbrief", ".eval");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "slices.jsonl"), `${records.map((record) => JSON.stringify(record)).join("\n")}\n`, { encoding: "utf8" });
+}
+/** Build a throwaway project root with optional queue fixtures. */
+export function buildFixtureRepo(options = {}) {
+    const root = mkdtempSync(join(tmpdir(), "deft-triage-queue-parity-"));
+    const repo = options.repo ?? DEFAULT_REPO;
+    mkdirSync(join(root, "vbrief"), { recursive: true });
+    writeProjectDefinition(root, options.rankingLabels);
+    for (const issue of options.issues ?? []) {
+        writeCachedIssue(root, repo, issue);
+    }
+    if (options.auditEntries !== undefined && options.auditEntries.length > 0) {
+        writeAuditLog(root, repo, options.auditEntries);
+    }
+    for (const issueNumber of options.activeIssueNumbers ?? []) {
+        writeActiveScope(root, repo, issueNumber, `active-${issueNumber}.vbrief.json`);
+    }
+    for (const issueNumber of options.blockedIssueNumbers ?? []) {
+        writeBlockedScope(root, repo, issueNumber, `blocked-${issueNumber}.vbrief.json`);
+    }
+    if (options.sliceRecords !== undefined && options.sliceRecords.length > 0) {
+        writeSliceRecords(root, options.sliceRecords);
+    }
+    return root;
+}
+function resolveDeftRoot() {
+    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
+        return resolve(process.env.DEFT_ROOT);
+    }
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+function runPythonQueue(deftRoot, _repo, argv) {
+    const cap = runCapture("uv", ["run", "python", join(deftRoot, "scripts", "triage_queue.py"), "queue", ...argv], deftRoot, { DEFT_TRIAGE_REPO: undefined, PYTHONUTF8: "1" });
+    return { exitCode: cap.status, stdout: cap.stdout, stderr: cap.stderr };
+}
+function runTsQueue(deftRoot, _repo, argv) {
+    const cap = runCapture("node", [join(deftRoot, "packages", "cli", "dist", "triage-queue.js"), "queue", ...argv], deftRoot, { DEFT_TRIAGE_REPO: undefined });
+    return { exitCode: cap.status, stdout: cap.stdout, stderr: cap.stderr };
+}
+/** Diff one parity case between Python oracle and TS CLI. */
+export function diffCase(python, ts, caseName) {
+    const pyOut = normalizeOutput(python.stdout);
+    const tsOut = normalizeOutput(ts.stdout);
+    const pyErr = normalizeOutput(python.stderr);
+    const tsErr = normalizeOutput(ts.stderr);
+    return {
+        caseName,
+        exitMismatch: python.exitCode !== ts.exitCode,
+        stdoutMismatch: pyOut !== tsOut,
+        stderrMismatch: pyErr !== tsErr,
+        pythonExit: python.exitCode,
+        tsExit: ts.exitCode,
+    };
+}
+export const PARITY_CASES = [
+    {
+        name: "missing-repo",
+        argv: ["--project-root", "<ROOT>"],
+        skipFixture: true,
+    },
+    {
+        name: "empty-cache",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {},
+    },
+    {
+        name: "group-order",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {
+            issues: [
+                { number: 1, title: "Untriaged", updatedAt: "2026-05-17T12:00:00Z" },
+                { number: 2, title: "Resume", updatedAt: "2026-05-17T11:00:00Z" },
+                { number: 3, title: "Urgent", updatedAt: "2026-05-15T10:00:00Z" },
+                { number: 4, title: "Other", updatedAt: "2026-05-14T10:00:00Z" },
+            ],
+            auditEntries: [
+                { issueNumber: 3, decision: "needs-ac", timestamp: "2026-05-15T11:00:00Z" },
+                { issueNumber: 4, decision: "defer", timestamp: "2026-05-14T11:00:00Z" },
+            ],
+            activeIssueNumbers: [2],
+        },
+    },
+    {
+        name: "orphan-above-resume",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {
+            issues: [
+                { number: 10, title: "Umbrella closed", state: "closed" },
+                { number: 11, title: "Orphan child", state: "open", updatedAt: "2026-05-16T10:00:00Z" },
+                { number: 12, title: "Resume child", state: "open", updatedAt: "2026-05-17T10:00:00Z" },
+            ],
+            activeIssueNumbers: [12],
+            sliceRecords: [
+                {
+                    slice_id: "slice-1",
+                    umbrella: 10,
+                    umbrella_url: "https://github.com/owner/repo/issues/10",
+                    children: [
+                        { n: 11, url: "https://github.com/owner/repo/issues/11", wave: 1, role: "child" },
+                    ],
+                },
+            ],
+        },
+    },
+    {
+        name: "resume-eligible",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {
+            issues: [
+                { number: 20, title: "Resume eligible", updatedAt: "2026-05-17T10:00:00Z" },
+                { number: 21, title: "Untriaged", updatedAt: "2026-05-17T11:00:00Z" },
+            ],
+            auditEntries: [
+                { issueNumber: 20, decision: "resume-eligible", timestamp: "2026-05-17T09:00:00Z" },
+            ],
+        },
+    },
+    {
+        name: "ranking-labels",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {
+            rankingLabels: ["urgent", "breaking-change"],
+            issues: [
+                { number: 30, title: "Unranked", updatedAt: "2026-05-17T10:00:00Z" },
+                {
+                    number: 31,
+                    title: "Breaking",
+                    labels: ["breaking-change"],
+                    updatedAt: "2026-05-15T10:00:00Z",
+                },
+                { number: 32, title: "Urgent", labels: ["urgent"], updatedAt: "2026-05-16T10:00:00Z" },
+            ],
+        },
+    },
+    {
+        name: "limit-cap",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "2"],
+        fixture: {
+            issues: [
+                { number: 40, updatedAt: "2026-05-17T10:00:00Z" },
+                { number: 41, updatedAt: "2026-05-16T10:00:00Z" },
+                { number: 42, updatedAt: "2026-05-15T10:00:00Z" },
+            ],
+        },
+    },
+    {
+        name: "blocked-demoted",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0"],
+        fixture: {
+            issues: [
+                { number: 50, title: "Blocked", updatedAt: "2026-05-17T10:00:00Z" },
+                { number: 51, title: "Open", updatedAt: "2026-05-16T10:00:00Z" },
+            ],
+            blockedIssueNumbers: [50],
+        },
+    },
+    {
+        name: "include-blocked",
+        argv: ["--project-root", "<ROOT>", "--repo", DEFAULT_REPO, "--limit", "0", "--include-blocked"],
+        fixture: {
+            issues: [
+                { number: 60, title: "Blocked", updatedAt: "2026-05-17T10:00:00Z" },
+                { number: 61, title: "Open", updatedAt: "2026-05-16T10:00:00Z" },
+            ],
+            blockedIssueNumbers: [60],
+        },
+    },
+];
+/** Augment argv with fixture audit/slices hooks when present. */
+export function augmentParityArgv(testCase, root) {
+    const argv = testCase.argv.map((arg) => (arg === "<ROOT>" ? root : arg));
+    if (testCase.skipFixture || testCase.fixture === undefined) {
+        return argv;
+    }
+    const extras = [];
+    if (testCase.fixture.auditEntries !== undefined && testCase.fixture.auditEntries.length > 0) {
+        extras.push("--audit-log", join(root, "vbrief", ".eval", "candidates.jsonl"));
+    }
+    if (testCase.fixture.sliceRecords !== undefined && testCase.fixture.sliceRecords.length > 0) {
+        extras.push("--slices-log", join(root, "vbrief", ".eval", "slices.jsonl"));
+    }
+    return [...argv, ...extras];
+}
+/** Run all parity cases; returns aggregate result. */
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = [];
+    for (const testCase of PARITY_CASES) {
+        const pyRepo = testCase.skipFixture
+            ? mkdtempSync(join(tmpdir(), "deft-triage-queue-parity-"))
+            : buildFixtureRepo(testCase.fixture);
+        const tsRepo = testCase.skipFixture
+            ? mkdtempSync(join(tmpdir(), "deft-triage-queue-parity-"))
+            : buildFixtureRepo(testCase.fixture);
+        const pyArgv = augmentParityArgv(testCase, pyRepo);
+        const tsArgv = augmentParityArgv(testCase, tsRepo);
+        try {
+            const python = runPythonQueue(deftRoot, pyRepo, pyArgv);
+            const ts = runTsQueue(deftRoot, tsRepo, tsArgv);
+            diffs.push(diffCase(python, ts, testCase.name));
+        }
+        finally {
+            rmSync(pyRepo, { recursive: true, force: true });
+            rmSync(tsRepo, { recursive: true, force: true });
+        }
+    }
+    const ok = diffs.every((diff) => !diff.exitMismatch && !diff.stdoutMismatch && !diff.stderrMismatch);
+    return { ok, diffs };
+}
+export function renderReport(result) {
+    if (result.ok) {
+        return `triage:queue parity: CLEAN -- Python and TS agree on ${PARITY_CASES.length} cases.`;
+    }
+    const lines = ["triage:queue parity: DIVERGENCE"];
+    for (const diff of result.diffs) {
+        if (diff.exitMismatch || diff.stdoutMismatch || diff.stderrMismatch) {
+            lines.push(`  case: ${diff.caseName}`);
+            if (diff.exitMismatch) {
+                lines.push(`    exit: python=${diff.pythonExit} ts=${diff.tsExit}`);
+            }
+            if (diff.stdoutMismatch) {
+                lines.push("    stdout mismatch");
+            }
+            if (diff.stderrMismatch) {
+                lines.push("    stderr mismatch");
+            }
+        }
+    }
+    return lines.join("\n");
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    try {
+        const result = runParity();
+        if (result.ok) {
+            process.stdout.write(`${renderReport(result)}\n`);
+            process.exit(0);
+        }
+        process.stderr.write(`${renderReport(result)}\n`);
+        process.exit(1);
+    }
+    catch (err) {
+        process.stderr.write(`triage:queue parity: harness error -- ${String(err)}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=triage-queue-parity.js.map

package/dist/triage-queue.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    repo: string | null;
+    limit: number;
+    includeBlocked: boolean;
+    cacheRoot: string | null;
+    auditLog: string | null;
+    slicesLog: string | null;
+    error?: string;
+}
+/** Parse triage-queue CLI args for the queue subcommand. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run triage:queue and return process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=triage-queue.d.ts.map