@gevezex/gdt 0.2.0

package/dist/contract.js

@@ -0,0 +1,133 @@
+import { SECTION_KEYS } from "./locale.js";
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const AC_HEADING = /^\s*(?:#{3,6}\s+|\*\*)AC-(\d+)\b/;
+const UNCHECKED = /^\s*[-*+]\s+\[ \]\s+(.*)$/;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Marks lines inside fenced code blocks, so headings and phrases in code are ignored. */
+function classify(body) {
+    const lines = [];
+    let fence = null;
+    for (const text of body.replace(/\r\n?/g, "\n").split("\n")) {
+        const match = FENCE.exec(text);
+        if (fence === null) {
+            if (match?.[1] !== undefined)
+                fence = match[1];
+            lines.push({ text, code: fence !== null });
+        }
+        else {
+            const closing = match?.[1];
+            if (closing !== undefined && closing[0] === fence[0] && closing.length >= fence.length && text.trim() === closing) {
+                fence = null;
+            }
+            lines.push({ text, code: true });
+        }
+    }
+    return lines;
+}
+function splitSections(body) {
+    const sections = [];
+    let current = null;
+    for (const line of classify(body)) {
+        const heading = line.code ? null : /^## (.*)$/.exec(line.text);
+        if (heading?.[1] !== undefined) {
+            current = { heading: heading[1].trim(), lines: [] };
+            sections.push(current);
+        }
+        else {
+            current?.lines.push(line);
+        }
+    }
+    return sections;
+}
+function prose(lines) {
+    return lines.filter((line) => !line.code).map((line) => line.text);
+}
+function acceptanceCriteria(section, locale, options) {
+    const blocks = [];
+    for (const text of prose(section.lines)) {
+        const heading = AC_HEADING.exec(text);
+        if (heading?.[1] !== undefined)
+            blocks.push({ number: Number(heading[1]), lines: [] });
+        else
+            blocks.at(-1)?.lines.push(text);
+    }
+    const ids = blocks.map((block) => `AC-${block.number}`);
+    if (blocks.length === 0) {
+        return { ids, errors: [`No acceptance criteria found in section "${section.heading}"`] };
+    }
+    const errors = [];
+    if (blocks.some((block, i) => block.number !== i + 1)) {
+        errors.push(`Acceptance criteria must be numbered consecutively from AC-1; found ${ids.join(", ")}`);
+    }
+    if (blocks.length > options.maxAcceptanceCriteria) {
+        errors.push(`${blocks.length} acceptance criteria; maximum is ${options.maxAcceptanceCriteria}`);
+    }
+    const fields = [locale.ac_fields.given, locale.ac_fields.when, locale.ac_fields.then, locale.ac_fields.example];
+    for (const [i, block] of blocks.entries()) {
+        for (const field of fields) {
+            // "- Given: ...", also "- **Given:** ..." and "- **Given**: ...".
+            const pattern = new RegExp(`^\\s*[-*+]\\s+(?:\\*\\*)?${escapeRegExp(field)}(?::|\\*\\*\\s*:|\\s+:)`);
+            if (!block.lines.some((line) => pattern.test(line)))
+                errors.push(`${ids[i]}: missing "${field}"`);
+        }
+    }
+    return { ids, errors };
+}
+function withoutInlineCode(text) {
+    return text.replace(/(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g, " ");
+}
+function vaguePhraseErrors(sections, phrases) {
+    const patterns = phrases.map((phrase) => ({
+        phrase,
+        // Word boundaries that also hold for non-ASCII letters and for phrases ending in punctuation ("etc.").
+        regex: new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegExp(phrase)}(?![\\p{L}\\p{N}_])`, "iu"),
+    }));
+    const errors = [];
+    for (const section of sections) {
+        const text = withoutInlineCode([section.heading, ...prose(section.lines)].join("\n"));
+        for (const { phrase, regex } of patterns) {
+            if (regex.test(text))
+                errors.push(`Vague phrase "${phrase}" in section "${section.heading}"`);
+        }
+    }
+    return errors;
+}
+/** The trimmed text of the first section with `heading`, or undefined when the body has none. */
+export function sectionText(body, heading) {
+    const section = splitSections(body).find((s) => s.heading === heading);
+    return section?.lines.map((line) => line.text).join("\n").trim();
+}
+/** Validates an issue body against the contract for `locale`. Pure: no I/O. */
+export function validateContract(body, locale, options) {
+    const sections = splitSections(body);
+    const find = (heading) => sections.find((section) => section.heading === heading);
+    const errors = [];
+    for (const key of SECTION_KEYS) {
+        const heading = locale.sections[key];
+        if (find(heading) === undefined)
+            errors.push(`Missing section: ${heading}`);
+    }
+    let ids = [];
+    const acSection = find(locale.sections.acceptance_criteria);
+    if (acSection !== undefined) {
+        const result = acceptanceCriteria(acSection, locale, options);
+        ids = result.ids;
+        errors.push(...result.errors);
+    }
+    const openQuestions = find(locale.sections.open_questions);
+    if (openQuestions !== undefined && openQuestions.lines.map((line) => line.text).join("\n").trim() !== locale.markers.none) {
+        errors.push(`${locale.sections.open_questions} must be exactly "${locale.markers.none}"`);
+    }
+    errors.push(...vaguePhraseErrors(sections, locale.vague_phrases));
+    const readiness = find(locale.sections.readiness);
+    if (readiness !== undefined) {
+        for (const text of prose(readiness.lines)) {
+            const item = UNCHECKED.exec(text)?.[1];
+            if (item !== undefined)
+                errors.push(`Readiness item not checked: ${item.trim()}`);
+        }
+    }
+    return { valid: errors.length === 0, acceptance_criteria: ids, errors };
+}

package/dist/decision.js

@@ -0,0 +1,175 @@
+export const CHECK_STATES = ["success", "pending", "failure"];
+const ROLE_OF = { handoff: "developer", test: "tester", review: "reviewer" };
+function time(iso) {
+    return Date.parse(iso);
+}
+function isRoleRecord(record) {
+    return record.kind === "handoff" || record.kind === "test" || record.kind === "review";
+}
+/** Keeps records that are trusted and belong to this issue and, where they carry one, the current body hash. */
+function relevant(snapshot) {
+    const trusted = new Set(snapshot.trusted_authors);
+    return snapshot.records
+        .filter((record) => trusted.has(record.author))
+        .filter((record) => record.data.repository === snapshot.repository && record.data.issue === snapshot.issue)
+        .filter((record) => !("issue_body_sha256" in record.data) || record.data.issue_body_sha256 === snapshot.issue_body_sha256)
+        .toSorted((a, b) => time(a.created_at) - time(b.created_at) || a.comment_id - b.comment_id);
+}
+function latest(records, match) {
+    return records.filter(match).at(-1);
+}
+function questionDecision(records) {
+    const questions = records.filter((r) => r.kind === "question");
+    const answers = records.filter((r) => r.kind === "answer");
+    const answerOf = (q) => answers.find((a) => a.data.question_id === q.data.question_id && time(a.created_at) >= time(q.created_at));
+    const open = questions.filter((q) => answerOf(q) === undefined);
+    if (open.length > 0) {
+        return { action: "awaiting_human", reason: `waiting for an answer to ${open.map((q) => q.data.question_id).join(", ")}` };
+    }
+    // The most recently answered question resumes its role, unless that role has published since the answer.
+    const answered = questions.map((q) => ({ q, a: answerOf(q) })).sort((x, y) => time(x.a.created_at) - time(y.a.created_at));
+    const last = answered.at(-1);
+    if (last === undefined)
+        return undefined;
+    const role = last.q.data.resume_role;
+    const resumed = records.some((r) => isRoleRecord(r) && ROLE_OF[r.kind] === role && time(r.created_at) > time(last.a.created_at));
+    if (resumed)
+        return undefined;
+    return {
+        action: "dispatch",
+        role,
+        round: last.q.data.round,
+        reason: `${last.q.data.question_id} answered; resuming ${role}`,
+        question_id: last.q.data.question_id,
+    };
+}
+function correction(snapshot, records, record, round) {
+    // A verifier record with a stale or wrong round must not reset the budget.
+    const next = Math.max(round, record.data.round) + 1;
+    const granted = records.some((r) => r.kind === "round" && r.data.round === next);
+    const open = record.data.findings.map((f) => f.id);
+    if (next > snapshot.config.max_correction_rounds && !granted) {
+        return { action: "blocked", reason: `round budget exhausted; open findings: ${open.length > 0 ? open.join(", ") : "none"}` };
+    }
+    return {
+        action: "dispatch",
+        role: "developer",
+        round: next,
+        reason: `${ROLE_OF[record.kind]} requested changes${open.length > 0 ? `: ${open.join(", ")}` : ""}`,
+    };
+}
+function gates(snapshot, pr, approvals) {
+    for (const record of approvals) {
+        const role = ROLE_OF[record.kind];
+        const results = new Map(record.data.ac_results.map((r) => [r.ac, r.result]));
+        const unpassed = snapshot.acceptance_criteria.filter((ac) => results.get(ac) !== "passed");
+        if (unpassed.length > 0)
+            return { action: "blocked", reason: `${role} approved but not passed: ${unpassed.join(", ")}` };
+        const blocking = record.data.findings.filter((f) => f.blocking).map((f) => f.id);
+        if (blocking.length > 0)
+            return { action: "blocked", reason: `open blocking findings: ${blocking.join(", ")}` };
+    }
+    if (pr.mergeable === "conflicting")
+        return { action: "blocked", reason: "pull request has conflicts" };
+    if (pr.mergeable === "unknown")
+        return { action: "waiting_for_checks", reason: "mergeability not yet known" };
+    const required = snapshot.config.required_checks;
+    if (required.length === 0) {
+        return snapshot.config.allow_no_required_checks
+            ? { action: "ready_to_merge", reason: "approved; no required checks configured (allowed by config)" }
+            : { action: "blocked", reason: "no required checks configured" };
+    }
+    const state = (name) => (Object.hasOwn(pr.checks, name) ? pr.checks[name] : undefined);
+    const missing = required.filter((name) => state(name) === undefined);
+    if (missing.length > 0)
+        return { action: "blocked", reason: `required check missing: ${missing.join(", ")}` };
+    const failed = required.filter((name) => state(name) === "failure");
+    if (failed.length > 0)
+        return { action: "blocked", reason: `required check failed: ${failed.join(", ")}` };
+    const pending = required.filter((name) => state(name) === "pending");
+    if (pending.length > 0)
+        return { action: "waiting_for_checks", reason: `waiting for required checks: ${pending.join(", ")}` };
+    return { action: "ready_to_merge", reason: "all gates passed" };
+}
+/** Evidence for the current head, created after both the head transition and `after`. */
+function evidence(records, kind, pr, after) {
+    return latest(records, (r) => r.kind === kind && r.data.head === pr.head && time(r.created_at) > after);
+}
+/** Design 8: a verifier block counts only for the current head and after the latest head transition. */
+function staleVerifierBlock(snapshot, record) {
+    const pr = snapshot.pr;
+    // Without a current head there is nothing to lift the block against; keep it.
+    if (pr === null)
+        return false;
+    const transition = snapshot.head_transition_at === null ? Number.NEGATIVE_INFINITY : time(snapshot.head_transition_at);
+    return record.data.head !== pr.head || time(record.created_at) <= transition;
+}
+/** A verifier record that is not an approval ends the chain here. */
+function verdict(snapshot, records, record, round) {
+    const role = ROLE_OF[record.kind];
+    switch (record.data.status) {
+        case "approved":
+            return undefined;
+        case "changes_requested":
+            return correction(snapshot, records, record, round);
+        case "awaiting_human":
+            return { action: "awaiting_human", reason: `${role} is waiting for a human decision` };
+        case "blocked":
+            return { action: "blocked", reason: `${role} reported blocked` };
+    }
+}
+/** Ids of the blocking findings in the tester/reviewer evidence for the current head. */
+export function openFindings(snapshot) {
+    const records = relevant(snapshot);
+    const pr = snapshot.pr;
+    if (pr === null)
+        return [];
+    const handoff = latest(records, (r) => r.kind === "handoff" && r.data.status === "ready");
+    if (handoff === undefined)
+        return [];
+    const transition = snapshot.head_transition_at === null ? Number.NEGATIVE_INFINITY : time(snapshot.head_transition_at);
+    const after = Math.max(transition, time(handoff.created_at));
+    const test = evidence(records, "test", pr, after);
+    const review = evidence(records, "review", pr, Math.max(after, test === undefined ? after : time(test.created_at)));
+    return [test, review].flatMap((record) => record === undefined ? [] : record.data.findings.filter((f) => f.blocking).map((f) => f.id));
+}
+/** The pure decision engine: no I/O, no clock. */
+export function decide(snapshot) {
+    const records = relevant(snapshot);
+    const question = questionDecision(records);
+    if (question !== undefined)
+        return question;
+    const last = latest(records, isRoleRecord);
+    if (last !== undefined && last.data.status === "blocked") {
+        // AC-1/AC-4: a new head lifts a tester or reviewer block without consuming a round.
+        // AC-2: for the same head the block stays. AC-3: a developer block always stays.
+        const lifted = last.kind !== "handoff" && staleVerifierBlock(snapshot, last);
+        if (!lifted)
+            return { action: "blocked", reason: `${ROLE_OF[last.kind]} reported blocked` };
+    }
+    if (last !== undefined && last.data.status === "awaiting_human") {
+        return { action: "awaiting_human", reason: `${ROLE_OF[last.kind]} is waiting for a human decision` };
+    }
+    const handoff = latest(records, (r) => r.kind === "handoff" && r.data.status === "ready");
+    if (handoff === undefined)
+        return { action: "dispatch", role: "developer", round: 0, reason: "no developer handoff yet" };
+    const round = handoff.data.round;
+    const pr = snapshot.pr;
+    if (pr === null)
+        return { action: "blocked", reason: "developer handoff without a pull request" };
+    const transition = snapshot.head_transition_at === null ? Number.NEGATIVE_INFINITY : time(snapshot.head_transition_at);
+    const after = Math.max(transition, time(handoff.created_at));
+    const test = evidence(records, "test", pr, after);
+    if (test === undefined)
+        return { action: "dispatch", role: "tester", round, reason: `no tester evidence for head ${pr.head}` };
+    const afterTest = verdict(snapshot, records, test, round);
+    if (afterTest !== undefined)
+        return afterTest;
+    const review = evidence(records, "review", pr, Math.max(after, time(test.created_at)));
+    if (review === undefined)
+        return { action: "dispatch", role: "reviewer", round, reason: `no reviewer evidence for head ${pr.head}` };
+    const afterReview = verdict(snapshot, records, review, round);
+    if (afterReview !== undefined)
+        return afterReview;
+    return gates(snapshot, pr, [test, review]);
+}

package/dist/doctor.js

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { adapterFor } from "./agents/index.js";
+import { CONFIG_PATH, LOCAL_CONFIG_PATH, loadConfig, ROLES, TEST_AGENT } from "./config.js";
+import { hasErrors } from "./finding.js";
+const TOOLS = [
+    { name: "git", fix: "Install Git: https://git-scm.com/downloads" },
+    { name: "gh", fix: "Install GitHub CLI: https://cli.github.com" },
+];
+/** The oldest herdr this backend's workspace and pane commands were verified against (docs/agents.md). */
+export const MIN_HERDR_VERSION = "0.9.1";
+const HERDR_VERSION = /herdr (\d+)\.(\d+)\.(\d+)/;
+function versionAtLeast(found, minimum) {
+    const a = found.split(".").map(Number);
+    const b = minimum.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left !== right)
+            return left > right;
+    }
+    return true;
+}
+/** Reads the installed herdr version, or null when it is missing or unreadable. */
+function herdrVersion(env) {
+    const path = which("herdr", env);
+    if (path === null)
+        return null;
+    const result = spawnSync(path, ["--version"], { env, encoding: "utf8" });
+    const text = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    const match = HERDR_VERSION.exec(text);
+    if (result.status !== 0 || match === null)
+        return { path, error: text };
+    return { path, version: `${match[1]}.${match[2]}.${match[3]}` };
+}
+/** Preflight for `gdt start`: the recovery line when herdr is unusable, or null when it is fine. */
+export function herdrPreflight(env) {
+    const found = herdrVersion(env);
+    if (found === null)
+        return 'herdr not found on PATH; install herdr or set workflow.terminal = "headless"';
+    if ("error" in found) {
+        return `herdr did not report a version (${found.error || "no output"}); update herdr to ${MIN_HERDR_VERSION} or newer, or set workflow.terminal = "headless"`;
+    }
+    if (!versionAtLeast(found.version, MIN_HERDR_VERSION)) {
+        return `herdr ${found.version} is older than the minimum supported ${MIN_HERDR_VERSION}; update herdr or set workflow.terminal = "headless"`;
+    }
+    return null;
+}
+/** Checks that the configured herdr is present and at least `MIN_HERDR_VERSION`. */
+function herdrFinding(env) {
+    const found = herdrVersion(env);
+    const fix = 'Install or update herdr (https://herdr.dev), or set workflow.terminal = "headless"';
+    if (found === null)
+        return { check: "herdr", level: "error", message: "herdr: not found on PATH", fix };
+    if ("error" in found) {
+        return { check: "herdr", level: "error", message: `herdr: could not read its version (${found.error || "no output"})`, fix };
+    }
+    if (!versionAtLeast(found.version, MIN_HERDR_VERSION)) {
+        return {
+            check: "herdr",
+            level: "error",
+            message: `herdr: ${found.version} is older than the minimum supported ${MIN_HERDR_VERSION}`,
+            fix,
+        };
+    }
+    return { check: "herdr", level: "ok", message: `herdr: ${found.version} at ${found.path}`, fix: "" };
+}
+/** Resolves `name` against `env.PATH` like a shell would, without running anything. */
+export function which(name, env) {
+    const extensions = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const ext of extensions) {
+            const candidate = join(dir, name + ext);
+            try {
+                if (!statSync(candidate).isFile())
+                    continue;
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // Not here; keep looking.
+            }
+        }
+    }
+    return null;
+}
+/** The nearest directory at or above `cwd` that contains `.git`. */
+export function findRepository(cwd) {
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+function toolFindings(env) {
+    const findings = [];
+    const paths = new Map();
+    for (const tool of TOOLS) {
+        const path = which(tool.name, env);
+        if (path === null) {
+            findings.push({ check: tool.name, level: "error", message: `${tool.name}: not found on PATH`, fix: tool.fix });
+        }
+        else {
+            paths.set(tool.name, path);
+            findings.push({ check: tool.name, level: "ok", message: `${tool.name}: found at ${path}`, fix: "" });
+        }
+    }
+    return { findings, paths };
+}
+function ghAuthFinding(gh, cwd, env) {
+    const result = spawnSync(gh, ["auth", "status", "--hostname", "github.com"], { cwd, env, encoding: "utf8" });
+    if (result.status === 0) {
+        return { check: "gh-auth", level: "ok", message: "gh: authenticated to github.com", fix: "" };
+    }
+    return {
+        check: "gh-auth",
+        level: "error",
+        message: "gh: not authenticated to github.com",
+        fix: 'Run "gh auth login"',
+    };
+}
+function excludePath(root, git, env) {
+    if (git !== undefined) {
+        const result = spawnSync(git, ["rev-parse", "--git-path", "info/exclude"], { cwd: root, env, encoding: "utf8" });
+        if (result.status === 0 && result.stdout.trim() !== "")
+            return resolve(root, result.stdout.trim());
+    }
+    const gitDir = join(root, ".git");
+    return statSync(gitDir).isDirectory() ? join(gitDir, "info", "exclude") : null;
+}
+/** Ensures the local override file is ignored by Git without touching the committed .gitignore. */
+function excludeFinding(root, git, env) {
+    const check = "local-config-excluded";
+    const fix = `Add the line ${LOCAL_CONFIG_PATH} to .git/info/exclude`;
+    try {
+        const path = excludePath(root, git, env);
+        if (path === null) {
+            return { check, level: "warning", message: "Could not locate .git/info/exclude", fix };
+        }
+        const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+        if (!current.split(/\r?\n/).some((line) => line.trim() === LOCAL_CONFIG_PATH)) {
+            mkdirSync(dirname(path), { recursive: true });
+            const separator = current === "" || current.endsWith("\n") ? "" : "\n";
+            appendFileSync(path, `${separator}${LOCAL_CONFIG_PATH}\n`);
+        }
+        return { check, level: "ok", message: `${LOCAL_CONFIG_PATH} is listed in .git/info/exclude`, fix: "" };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { check, level: "warning", message: `Could not update .git/info/exclude: ${reason}`, fix };
+    }
+}
+/**
+ * AC-5: an error finding for every role whose agent has no adapter, i.e. no unattended invocation
+ * (docs/agents.md). Generic: any agent absent from the adapter registry is rejected here. The test
+ * agent is exempt: it runs a script instead of a CLI.
+ */
+export function unsupportedAgentFindings(roles) {
+    return ROLES.flatMap((role) => {
+        const { agent } = roles[role];
+        if (agent === TEST_AGENT || adapterFor(agent) !== undefined)
+            return [];
+        return [
+            {
+                check: `roles.${role}`,
+                level: "error",
+                message: `roles.${role}.agent: ${agent} has no unattended mode; see docs/agents.md`,
+                fix: `Set roles.${role}.agent in ${CONFIG_PATH} to an agent with an unattended mode`,
+            },
+        ];
+    });
+}
+/** Checks the agent binary of every configured role, and that the tester is independent of the developer. */
+function agentFindings(config, env) {
+    const findings = unsupportedAgentFindings(config.roles);
+    for (const role of ROLES) {
+        const { agent } = config.roles[role];
+        const adapter = adapterFor(agent);
+        if (adapter === undefined)
+            continue;
+        const check = `roles.${role}`;
+        const path = which(adapter.binary, env);
+        findings.push(path === null
+            ? { check, level: "error", message: `roles.${role}: ${adapter.binary} not found on PATH`, fix: adapter.install }
+            : { check, level: "ok", message: `roles.${role}: ${adapter.binary} found at ${path}`, fix: "" });
+    }
+    const vendor = (role) => adapterFor(config.roles[role].agent)?.vendorOf(config.roles[role].model);
+    const developer = vendor("developer");
+    if (developer !== undefined && developer === vendor("tester")) {
+        findings.push({
+            check: "roles.tester",
+            level: "warning",
+            message: `developer and tester both use ${developer}; use a different vendor for the tester for independent verification`,
+            fix: "Set roles.tester to an agent and model from another vendor",
+        });
+    }
+    return findings;
+}
+export function runDoctor(cwd, env) {
+    const findings = [];
+    const tools = toolFindings(env);
+    findings.push(...tools.findings);
+    const root = findRepository(cwd);
+    const gh = tools.paths.get("gh");
+    if (gh !== undefined)
+        findings.push(ghAuthFinding(gh, root ?? cwd, env));
+    if (root === null) {
+        findings.push({
+            check: "repository",
+            level: "error",
+            message: `${resolve(cwd)} is not inside a Git repository`,
+            fix: "Run gdt from inside a Git checkout of the target repository",
+        });
+        return { ok: false, repository: null, config: { valid: false, files: [] }, findings };
+    }
+    const { report, findings: configFindings } = loadConfig(root, env);
+    if (existsSync(join(root, CONFIG_PATH)) || existsSync(join(root, LOCAL_CONFIG_PATH))) {
+        findings.push(excludeFinding(root, tools.paths.get("git"), env));
+    }
+    findings.push(...configFindings);
+    if (report.valid) {
+        findings.push(...agentFindings(report, env));
+        if (report.workflow.terminal === "herdr")
+            findings.push(herdrFinding(env));
+    }
+    return { ok: !hasErrors(findings), repository: root, config: report, findings };
+}

package/dist/finding.js

@@ -0,0 +1,3 @@
+export function hasErrors(findings) {
+    return findings.some((f) => f.level === "error");
+}

package/dist/git.js

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+function git(args, cwd, env) {
+    return spawnSync("git", args, { cwd, env, encoding: "utf8" }).stdout ?? "";
+}
+/** Paths from `git status --porcelain -z`; renames report the new path. */
+export function changedFiles(root, env, untracked) {
+    const entries = git(["status", "--porcelain", "-z", `--untracked-files=${untracked ? "all" : "no"}`], root, env).split("\0");
+    const files = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i] ?? "";
+        if (entry.length < 4)
+            continue;
+        files.push(entry.slice(3));
+        // A rename or copy is followed by its original path.
+        if ("RC".includes(entry[0] ?? "") || "RC".includes(entry[1] ?? ""))
+            i++;
+    }
+    return files;
+}
+export function checkout(root, env) {
+    return {
+        head: git(["rev-parse", "HEAD"], root, env).trim(),
+        branch: git(["symbolic-ref", "--quiet", "--short", "HEAD"], root, env).trim(),
+    };
+}

package/dist/github.js

@@ -0,0 +1,95 @@
+import { spawnSync } from "node:child_process";
+import { which } from "./doctor.js";
+export class GhError extends Error {
+}
+function gh(args, cwd, env) {
+    const bin = which("gh", env);
+    if (bin === null)
+        throw new GhError("gh: not found on PATH. Install GitHub CLI: https://cli.github.com");
+    const result = spawnSync(bin, args, { cwd, env, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) {
+        const reason = (result.stderr ?? "").trim().split("\n")[0] || `gh exited with ${result.status ?? result.signal}`;
+        throw new GhError(reason);
+    }
+    return result.stdout;
+}
+function ghJson(args, cwd, env) {
+    const out = gh(args, cwd, env);
+    try {
+        return JSON.parse(out);
+    }
+    catch {
+        throw new GhError(`unexpected output from gh ${args.slice(0, 2).join(" ")}`);
+    }
+}
+/** Runs `gh args` with `input` on stdin; used to post a comment without putting its text in argv. */
+function ghInput(args, input, cwd, env) {
+    const bin = which("gh", env);
+    if (bin === null)
+        throw new GhError("gh: not found on PATH. Install GitHub CLI: https://cli.github.com");
+    const result = spawnSync(bin, args, { cwd, env, encoding: "utf8", input, maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) {
+        const reason = (result.stderr ?? "").trim().split("\n")[0] || `gh exited with ${result.status ?? result.signal}`;
+        throw new GhError(reason);
+    }
+    return result.stdout;
+}
+/** Posts one comment on an issue; pull requests are issues too, but prefer `postPullRequestComment`. */
+export function postIssueComment(number, body, cwd, env) {
+    ghInput(["issue", "comment", String(number), "--body-file", "-"], body, cwd, env);
+}
+/** Posts one comment on a pull request conversation. */
+export function postPullRequestComment(number, body, cwd, env) {
+    ghInput(["pr", "comment", String(number), "--body-file", "-"], body, cwd, env);
+}
+/** Fetches the current body of issue `issue` in the repository `gh` resolves from `cwd`. */
+export function issueBody(issue, cwd, env) {
+    try {
+        const { body } = ghJson(["issue", "view", String(issue), "--json", "body"], cwd, env);
+        if (typeof body === "string")
+            return { body };
+        return { error: `Could not fetch issue #${issue}: unexpected output from gh issue view. Run "gdt doctor".` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        if (reason.startsWith("gh: not found"))
+            return { error: reason };
+        return { error: `Could not fetch issue #${issue}: ${reason}. Check the issue number and run "gdt doctor".` };
+    }
+}
+/** `owner/name` of the repository `gh` resolves from `cwd`. */
+export function repository(cwd, env) {
+    return ghJson(["repo", "view", "--json", "nameWithOwner"], cwd, env).nameWithOwner;
+}
+/** The login `gh` is authenticated as. */
+export function viewer(cwd, env) {
+    return ghJson(["api", "user"], cwd, env).login;
+}
+/** The issue body and the open pull requests that close the issue ("Closes #n"). */
+export function issueSnapshot(issue, cwd, env) {
+    const data = ghJson(["issue", "view", String(issue), "--json", "body,closedByPullRequestsReferences"], cwd, env);
+    return { body: data.body, pullRequests: (data.closedByPullRequestsReferences ?? []).map((pr) => pr.number) };
+}
+/** All comments on an issue or pull request conversation, oldest first. */
+export function comments(repo, number, cwd, env) {
+    const pages = ghJson(["api", "--paginate", "--slurp", `repos/${repo}/issues/${number}/comments`], cwd, env);
+    return pages.flat().map((c) => ({ id: c.id, author: c.user?.login ?? "", created_at: c.created_at, body: c.body ?? "" }));
+}
+/** Maps GitHub check runs and commit statuses to success, pending or failure; anything unexpected fails. */
+export function checkStates(rollup) {
+    const states = {};
+    for (const item of rollup) {
+        if (item.__typename === "CheckRun") {
+            states[item.name] = item.status !== "COMPLETED" ? "pending" : item.conclusion === "SUCCESS" ? "success" : "failure";
+        }
+        else {
+            states[item.context] = item.state === "SUCCESS" ? "success" : item.state === "PENDING" || item.state === "EXPECTED" ? "pending" : "failure";
+        }
+    }
+    return states;
+}
+export function pullRequest(number, cwd, env) {
+    const data = ghJson(["pr", "view", String(number), "--json", "number,headRefOid,mergeable,statusCheckRollup"], cwd, env);
+    const mergeable = data.mergeable === "MERGEABLE" ? "mergeable" : data.mergeable === "CONFLICTING" ? "conflicting" : "unknown";
+    return { number: data.number, head: data.headRefOid, mergeable, checks: checkStates(data.statusCheckRollup ?? []) };
+}