@deftai/directive-core 0.55.0

package/dist/triage/actions/index.js

@@ -0,0 +1,305 @@
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { call } from "../../scm/call.js";
+import { ScmStubError } from "../../scm/errors.js";
+import { createCandidatesLog, resolveAuditLogPath, rollbackAuditEntry } from "./candidates-log.js";
+import { TriageError, UpstreamCloseError } from "./errors.js";
+import { parseResumeOn } from "./resume-on.js";
+export { AUDIT_LOG_REL_PATH, createCandidatesLog, resolveAuditLogPath, rollbackAuditEntry, } from "./candidates-log.js";
+export { CandidatesLogError, ResumeGrammarError, TriageError, UpstreamCloseError, } from "./errors.js";
+export { parseResumeOn } from "./resume-on.js";
+export const REJECTED_LABEL = "triage-rejected";
+export const REJECTED_LABEL_COLOR = "B60205";
+export const REJECTED_LABEL_DESCRIPTION = "Issue rejected during deft triage";
+const TERMINAL_DECISIONS = new Set(["accept", "reject", "mark-duplicate"]);
+const DEFAULT_ACTOR = "agent:triage";
+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 defaultNowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function resolveActor(actor) {
+    if (actor)
+        return actor;
+    return process.env.USER ?? process.env.USERNAME ?? DEFAULT_ACTOR;
+}
+function defaultScmRunner() {
+    return {
+        call(source, verb, args, options = {}) {
+            try {
+                const result = call(source, verb, args, {
+                    check: options.check ?? false,
+                    captureOutput: true,
+                });
+                if ((options.check ?? false) && result.returncode !== 0) {
+                    const stderr = result.stderr.trim();
+                    throw new UpstreamCloseError(`gh ${verb} ${args.join(" ")} failed: ${stderr}`);
+                }
+                return {
+                    returncode: result.returncode,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                };
+            }
+            catch (err) {
+                if (err instanceof UpstreamCloseError)
+                    throw err;
+                if (err instanceof ScmStubError) {
+                    throw new UpstreamCloseError(`gh resolution failed: ${err.message}`);
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                throw new UpstreamCloseError(message);
+            }
+        },
+    };
+}
+function defaultIssueIngest(deftRoot) {
+    return {
+        ingestSingleForAccept(issueNumber, repo, options = {}) {
+            const projectRoot = options.projectRoot ?? process.cwd();
+            const script = [
+                "import sys",
+                "from pathlib import Path",
+                `sys.path.insert(0, ${JSON.stringify(join(deftRoot, "scripts"))})`,
+                "import issue_ingest",
+                "issue_ingest.ingest_single_for_accept(",
+                `${issueNumber},`,
+                `${JSON.stringify(repo)},`,
+                `project_root=Path(${JSON.stringify(projectRoot)}),`,
+                ")",
+            ].join("\n");
+            const result = spawnSync("uv", ["run", "python", "-c", script], {
+                cwd: deftRoot,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            if (result.status !== 0) {
+                const stderr = (result.stderr ?? "").trim();
+                throw new Error(stderr || "issue:ingest delegation failed");
+            }
+        },
+    };
+}
+/** Default dependency bundle for production CLI use. */
+export function createDefaultDeps(projectRoot) {
+    const deftRoot = resolveDeftRoot();
+    return {
+        candidatesLog: createCandidatesLog(projectRoot),
+        issueIngest: defaultIssueIngest(deftRoot),
+        scm: defaultScmRunner(),
+        nowIso: defaultNowIso,
+        stderr: (message) => process.stderr.write(`${message}\n`),
+    };
+}
+function buildEntry(deps, decision, issueNumber, repo, actor, extras = {}) {
+    const entry = {
+        decision_id: deps.candidatesLog.newDecisionId(),
+        timestamp: (deps.nowIso ?? defaultNowIso)(),
+        repo,
+        issue_number: issueNumber,
+        decision,
+        actor,
+        ...extras,
+    };
+    return entry;
+}
+function logPathFor(projectRoot) {
+    return resolveAuditLogPath(projectRoot);
+}
+function isIdempotentRepeat(deps, issueNumber, repo, decision, projectRoot, linkedTo) {
+    if (!TERMINAL_DECISIONS.has(decision))
+        return null;
+    const prior = deps.candidatesLog.latestDecision(issueNumber, repo, {
+        path: logPathFor(projectRoot),
+    });
+    if (prior === null || prior.decision !== decision)
+        return null;
+    if (decision === "mark-duplicate" && prior.linked_to !== linkedTo)
+        return null;
+    return prior;
+}
+function runGh(deps, args) {
+    if (args.length === 0) {
+        throw new UpstreamCloseError("scm.call requires at least a verb; got empty args");
+    }
+    const verb = args[0];
+    if (verb === undefined) {
+        throw new UpstreamCloseError("scm.call requires at least a verb; got empty args");
+    }
+    try {
+        const result = deps.scm.call("github-issue", verb, args.slice(1), { check: true });
+        return result;
+    }
+    catch (err) {
+        if (err instanceof UpstreamCloseError)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("ENOENT") || message.toLowerCase().includes("not found on path")) {
+            throw new UpstreamCloseError(`gh CLI not found on PATH: ${message}`);
+        }
+        throw new UpstreamCloseError(`gh ${args.join(" ")} failed: ${message.trim()}`);
+    }
+}
+function looksLikeMissingLabel(exc) {
+    const text = exc.message.toLowerCase();
+    return text.includes("not found") || text.includes("could not add label");
+}
+function ensureLabelExists(deps, repo) {
+    try {
+        runGh(deps, [
+            "label",
+            "create",
+            REJECTED_LABEL,
+            "--repo",
+            repo,
+            "--description",
+            REJECTED_LABEL_DESCRIPTION,
+            "--color",
+            REJECTED_LABEL_COLOR,
+        ]);
+    }
+    catch (err) {
+        if (err instanceof UpstreamCloseError && err.message.toLowerCase().includes("already exists")) {
+            return;
+        }
+        throw err;
+    }
+}
+function ensureRejectedLabelApplied(deps, issueNumber, repo) {
+    const writeErr = deps.stderr ?? ((message) => process.stderr.write(`${message}\n`));
+    try {
+        runGh(deps, [
+            "issue",
+            "edit",
+            String(issueNumber),
+            "--repo",
+            repo,
+            "--add-label",
+            REJECTED_LABEL,
+        ]);
+        return;
+    }
+    catch (addExc) {
+        if (!(addExc instanceof UpstreamCloseError) || !looksLikeMissingLabel(addExc)) {
+            writeErr(`triage_actions: reject #${issueNumber} (${repo}) closed successfully but the '${REJECTED_LABEL}' label could not be applied: ${addExc instanceof Error ? addExc.message : String(addExc)}`);
+            return;
+        }
+    }
+    try {
+        ensureLabelExists(deps, repo);
+        runGh(deps, [
+            "issue",
+            "edit",
+            String(issueNumber),
+            "--repo",
+            repo,
+            "--add-label",
+            REJECTED_LABEL,
+        ]);
+    }
+    catch (healExc) {
+        writeErr(`triage_actions: reject #${issueNumber} (${repo}) closed successfully but the '${REJECTED_LABEL}' label is missing and auto-create/re-add failed: ${healExc instanceof Error ? healExc.message : String(healExc)}`);
+    }
+}
+/** Record an accept audit entry and delegate vBRIEF authoring to issue_ingest. */
+export function accept(issueNumber, repo, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const actor = resolveActor(options.actor);
+    const prior = isIdempotentRepeat(deps, issueNumber, repo, "accept", projectRoot);
+    if (prior !== null) {
+        return prior.decision_id;
+    }
+    const entry = buildEntry(deps, "accept", issueNumber, repo, actor);
+    const logPath = logPathFor(projectRoot);
+    const decisionId = deps.candidatesLog.append(entry, { path: logPath });
+    try {
+        deps.issueIngest.ingestSingleForAccept(issueNumber, repo, { projectRoot });
+    }
+    catch (exc) {
+        rollbackAuditEntry(decisionId, projectRoot, logPath);
+        throw new TriageError(`accept #${issueNumber} (${repo}): issue:ingest delegation failed; audit entry rolled back. Cause: ${exc instanceof Error ? exc.message : String(exc)}`);
+    }
+    return decisionId;
+}
+/** Close upstream, best-effort label, record reject audit entry. */
+export function reject(issueNumber, repo, reason, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const actor = resolveActor(options.actor);
+    const prior = isIdempotentRepeat(deps, issueNumber, repo, "reject", projectRoot);
+    if (prior !== null) {
+        return prior.decision_id;
+    }
+    const entry = buildEntry(deps, "reject", issueNumber, repo, actor, { reason });
+    const logPath = logPathFor(projectRoot);
+    const decisionId = deps.candidatesLog.append(entry, { path: logPath });
+    try {
+        runGh(deps, [
+            "issue",
+            "close",
+            String(issueNumber),
+            "--repo",
+            repo,
+            "--comment",
+            reason,
+            "--reason",
+            "not planned",
+        ]);
+    }
+    catch (err) {
+        rollbackAuditEntry(decisionId, projectRoot, logPath);
+        throw err;
+    }
+    ensureRejectedLabelApplied(deps, issueNumber, repo);
+    return decisionId;
+}
+/** Record a defer audit entry (#1123 -- structured reason + resume_on). */
+export function deferAction(issueNumber, repo, reason, deps, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const resumeOn = options.resumeOn ?? null;
+    if (resumeOn !== null) {
+        try {
+            parseResumeOn(resumeOn);
+        }
+        catch (exc) {
+            throw new TriageError(`defer #${issueNumber} (${repo}): invalid --resume-on expression -- ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+    }
+    const actor = resolveActor(options.actor);
+    const entry = buildEntry(deps, "defer", issueNumber, repo, actor, {
+        ...(reason !== null && reason !== undefined ? { reason } : {}),
+        ...(resumeOn !== null ? { resume_on: resumeOn } : {}),
+    });
+    const logPath = logPathFor(projectRoot);
+    return deps.candidatesLog.append(entry, { path: logPath });
+}
+/** Format a decision entry for CLI ``status`` / ``history`` output. */
+export function formatDecision(entry) {
+    if (entry === null) {
+        return "(no decision recorded)";
+    }
+    const parts = [
+        `decision=${entry.decision}`,
+        `issue=#${entry.issue_number}`,
+        `repo=${entry.repo}`,
+        `actor=${entry.actor}`,
+        `timestamp=${entry.timestamp}`,
+        `decision_id=${entry.decision_id}`,
+    ];
+    if (entry.reason !== undefined) {
+        const escaped = String(entry.reason).replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        parts.push(`reason='${escaped}'`);
+    }
+    if (entry.linked_to !== undefined) {
+        parts.push(`linked_to=#${entry.linked_to}`);
+    }
+    if (entry.prior_decision_id !== undefined) {
+        parts.push(`prior_decision_id=${entry.prior_decision_id}`);
+    }
+    return `  ${parts.join(" | ")}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/triage/actions/resume-on.d.ts

@@ -0,0 +1,3 @@
+/** Parse a resume-condition expression (mirrors ``resume_conditions.parse``). */
+export declare function parseResumeOn(expr: string): void;
+//# sourceMappingURL=resume-on.d.ts.map

package/dist/triage/actions/resume-on.js

@@ -0,0 +1,65 @@
+import { ResumeGrammarError } from "./errors.js";
+const REF_CLOSED_RE = /^ref:closed:#(\d+)$/;
+const REF_MERGED_RE = /^ref:merged:#(\d+)$/;
+const DATE_GE_RE = /^date:>=(\d{4}-\d{2}-\d{2})$/;
+const PENDING_GE_RE = /^pending-count:>=(\d+)$/;
+const PENDING_LE_RE = /^pending-count:<=(\d+)$/;
+const SLICE_WAVE_READY_RE = /^slice-wave-ready:([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}):(\d+)$/;
+const COMPOSITION_RE = /\s+(AND|OR)\s+/;
+function parseAtomic(raw) {
+    const text = raw.trim();
+    if (!text) {
+        throw new ResumeGrammarError("empty atomic condition");
+    }
+    if (REF_CLOSED_RE.test(text))
+        return;
+    if (REF_MERGED_RE.test(text))
+        return;
+    const dateMatch = DATE_GE_RE.exec(text);
+    if (dateMatch !== null) {
+        const iso = dateMatch[1];
+        if (iso === undefined || Number.isNaN(Date.parse(`${iso}T00:00:00Z`))) {
+            throw new ResumeGrammarError(`invalid date in '${text}': invalid isoformat`);
+        }
+        return;
+    }
+    if (PENDING_GE_RE.test(text))
+        return;
+    if (PENDING_LE_RE.test(text))
+        return;
+    const sliceMatch = SLICE_WAVE_READY_RE.exec(text);
+    if (sliceMatch !== null) {
+        const wave = Number.parseInt(sliceMatch[2] ?? "0", 10);
+        if (wave < 1) {
+            throw new ResumeGrammarError(`slice-wave-ready wave must be a positive int, got ${wave}`);
+        }
+        return;
+    }
+    throw new ResumeGrammarError(`unrecognised atomic condition '${text}'; expected one of: ref:closed:#N, ref:merged:#N, date:>=YYYY-MM-DD, pending-count:>=N, pending-count:<=N, slice-wave-ready:<slice_id>:<wave>`);
+}
+/** Parse a resume-condition expression (mirrors ``resume_conditions.parse``). */
+export function parseResumeOn(expr) {
+    if (typeof expr !== "string") {
+        throw new ResumeGrammarError(`resume_on must be a string, got ${typeof expr}`);
+    }
+    const text = expr.trim();
+    if (!text) {
+        throw new ResumeGrammarError("resume_on must be a non-empty string");
+    }
+    const parts = text.split(COMPOSITION_RE);
+    if (parts.length === 1) {
+        parseAtomic(parts[0] ?? "");
+        return;
+    }
+    if (parts.length === 3) {
+        const op = parts[1];
+        if (op !== "AND" && op !== "OR") {
+            throw new ResumeGrammarError(`unknown composition operator '${op}'; expected AND or OR`);
+        }
+        parseAtomic(parts[0] ?? "");
+        parseAtomic(parts[2] ?? "");
+        return;
+    }
+    throw new ResumeGrammarError(`resume_on supports a single top-level AND/OR in v1; got '${text}'`);
+}
+//# sourceMappingURL=resume-on.js.map

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

@@ -0,0 +1,57 @@
+/** One audit-log row matching ``vbrief/schemas/candidates.schema.json``. */
+export interface AuditEntry {
+    decision_id: string;
+    timestamp: string;
+    repo: string;
+    issue_number: number;
+    decision: string;
+    actor: string;
+    reason?: string;
+    linked_to?: number;
+    prior_decision_id?: string;
+    resume_on?: string;
+}
+export interface CandidatesLog {
+    append(entry: AuditEntry, options?: {
+        path?: string;
+    }): string;
+    latestDecision(issueNumber: number, repo: string, options?: {
+        path?: string;
+    }): AuditEntry | null;
+    newDecisionId(): string;
+}
+export interface IssueIngest {
+    ingestSingleForAccept(issueNumber: number, repo: string, options?: {
+        projectRoot?: string;
+    }): void;
+}
+export interface ScmRunner {
+    call(source: string, verb: string, args: readonly string[], options?: {
+        check?: boolean;
+    }): {
+        returncode: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+export interface TriageActionsDeps {
+    candidatesLog: CandidatesLog;
+    issueIngest: IssueIngest;
+    scm: ScmRunner;
+    nowIso?: () => string;
+    stderr?: (message: string) => void;
+}
+export interface AcceptOptions {
+    actor?: string | null;
+    projectRoot?: string;
+}
+export interface RejectOptions {
+    actor?: string | null;
+    projectRoot?: string;
+}
+export interface DeferOptions {
+    actor?: string | null;
+    resumeOn?: string | null;
+    projectRoot?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/triage/actions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/triage/bootstrap/gitignore.d.ts

@@ -0,0 +1,16 @@
+import type { StepOutcome } from "./types.js";
+export declare const GITIGNORE_LINE = ".deft-cache/";
+export declare const GITIGNORE_DEFT_RUNTIME_SENTINELS: readonly string[];
+export declare const GITIGNORE_EVAL_ENTRIES: readonly string[];
+export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.eval/*.jsonl  merge=union";
+export declare const FORBIDDEN_BLANKET_EVAL_LINES: readonly string[];
+export declare const EVAL_README_BODY = "# `vbrief/.eval/` -- triage + slicing evaluation artefacts\n\nThis directory holds the append-only JSON-lines logs that the triage and\nslicing skills emit. The framework governs which files in here are tracked\nby git versus gitignored using a **hybrid policy** (#1144, child of #1119).\n\n## Tracking policy\n\n| File | Tracked? | Why |\n| --- | --- | --- |\n| `slices.jsonl` | Yes -- **committed** | Team-shared cohort records produced by slicing skills (D13 / #1132). New operators joining the team need to see prior cohort outputs to detect orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No -- **gitignored** | Operator-private triage decisions (#845 Story 2). Each operator's local accept / defer / reject stream is per-machine state; sharing it would conflate operators' timing + identity across the team. Re-derive on a fresh clone via `task triage:bootstrap`. |\n| `summary-history.jsonl` | No -- **gitignored** | Operator-private observability for `task triage:summary` output time-series. Not load-bearing for any decision. |\n| `scope-lifecycle.jsonl` | No -- **gitignored** | Operator-private scope-lifecycle audit decisions (D1 / #1121). Each demote (`task scope:demote`) appends one entry including a `demote_meta` block (`was_promoted`, `original_promotion_decision_id`, `days_in_pending`, `demote_reason`, `demoted_from`). Per-operator stream; sharing would conflate operators' demote timing across the team. Lightweight metrics over this log are tracked separately at #1180. |\n| `decompositions/` | No -- **gitignored** | Temporary story-decomposition proposal drafts. These JSON drafts are local scratch artifacts, not vBRIEFs; generated child story vBRIEFs are created by `task scope:decompose` in lifecycle folders, defaulting to `vbrief/pending/`. |\n| `doctor-state.json` | No -- **gitignored** | Per-machine `task doctor` throttle state (last exit code + timestamps) persisted to gate the 24h/4h re-probe window (#1308 / #1464). Local to each clone; never committed. |\n\nThe gitignore lines live in the repo-root `.gitignore` (`vbrief/.eval/candidates.jsonl`,\n`vbrief/.eval/summary-history.jsonl`, `vbrief/.eval/scope-lifecycle.jsonl`,\n`vbrief/.eval/decompositions/`, and `vbrief/.eval/doctor-state.json`). All paths\nnot listed above remain committed by default.\n\n## Fresh-clone regeneration\n\nOn a fresh clone (or any machine that has never run triage), `candidates.jsonl`\nis absent. Regenerate it with:\n\n```\ntask triage:bootstrap\n```\n\nThe bootstrap path detects the missing file, runs the auto-classifier, and\nwrites a fresh `vbrief/.eval/candidates.jsonl`. It does NOT touch the tracked\n`slices.jsonl`; cohort records remain a team-shared resource.\n\n## `merge=union` policy for `*.jsonl`\n\nThe repo-root `.gitattributes` declares:\n\n```\nvbrief/.eval/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on\nauto-merge, so two branches that each appended a different record to the\nsame JSON-lines file rebase cleanly without operator surgery. Two things\noperators should know:\n\n- **Concatenation, not set-union.** When two branches append DIFFERENT\n  records to the file, the merge driver concatenates both sides' lines\n  -- there is no smart deduplication of \"semantically similar\" records.\n  (Identical line-for-line appends collapse because git's three-way\n  merge sees them as the same change, but distinct records always\n  survive verbatim, even if a downstream reader would consider them\n  redundant.) The append-only writers in `scripts/candidates_log.py`\n  mint a fresh `decision_id` per call, so genuinely duplicate records\n  are not the expected case, but downstream readers MUST tolerate\n  multiple records describing the same logical decision.\n- **Single-operator scope only.** This is the foundational rebase\n  ergonomic for the single-operator case (operator A rebases their\n  feature branch onto a master that grew while they were AFK).\n  Multi-operator merge-conflict resolution is explicitly out of scope per\n  #1119 R4 (tracked separately as M1-M4 in #1183).\n\n## See also\n\n- Current Shape comment on #1144 for the canonical decisions (the source\n  of truth this README documents).\n- `.gitignore` -- selective gitignore entries for the operator-private\n  files.\n- `.gitattributes` -- the `merge=union` rule.\n- `scripts/candidates_log.py` -- the writer for `candidates.jsonl`.\n";
+/** Strip an inline `# ...` comment from a gitignore line. */
+export declare function stripGitignoreInlineComment(line: string): string;
+/** Append `.deft-cache/` to `.gitignore` when absent. */
+export declare function stepEnsureGitignoreEntry(projectRoot: string): StepOutcome;
+/** Ensure the #1144 hybrid policy is encoded in the repo (idempotent). */
+export declare function stepEnsureGitignoreEvalEntries(projectRoot: string): StepOutcome;
+/** Ensure `vbrief/.eval/candidates.jsonl` exists (#1240 option A). */
+export declare function stepSeedCandidatesLog(projectRoot: string): StepOutcome;
+//# sourceMappingURL=gitignore.d.ts.map