@gevezex/gdt 0.2.0

package/dist/cli.js

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_PATH, DEFAULT_LANGUAGE, DEFAULT_MAX_ACCEPTANCE_CRITERIA, loadConfig, ROLES } from "./config.js";
+import { validateContract } from "./contract.js";
+import { findRepository, runDoctor } from "./doctor.js";
+import { issueBody } from "./github.js";
+import { loadLocale } from "./locale.js";
+import { allowRound, answer, installSkill, pause, resume, setAgent, steer } from "./steering.js";
+import { supervise } from "./supervisor.js";
+import { work } from "./worker.js";
+import { retry, start, status, stop, wait } from "./workflow.js";
+/** Exit codes: 0 success, 1 a check failed, 2 usage error. */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+const HELP = `gdt - GitHub issues to merge-ready pull requests
+
+Usage:
+  gdt <command> [options]
+
+Commands:
+  doctor        Check tools, GitHub authentication and .gdt/config.toml
+  check-issue   Validate an issue body against the issue contract
+  start         Start the workflow for an issue in the background
+  status        Show the workflow status and the next step
+  wait          Wait until the workflow needs attention
+  stop          Stop the workflow for an issue; start resumes it
+  retry         Prepare a controlled retry of the failed turn
+  answer        Answer an open question
+  steer         Send a directive to one role
+  pause         Stop dispatching new turns
+  resume        Continue dispatching after pause
+  allow-round   Grant one extra correction round
+  set-agent     Override the agent and model of one role
+  install-skill Install the operator skill into detected agent harnesses
+
+Options:
+  --json        Machine-readable output
+  --help, -h    Show help
+  --version     Print the gdt version
+`;
+const DOCTOR_HELP = `Usage: gdt doctor [--json]
+
+Checks that git and gh are installed, gh is authenticated, and that
+.gdt/config.toml (merged with .gdt/config.local.toml) is valid.
+Exits with 1 when any finding has level "error".
+`;
+const CHECK_ISSUE_HELP = `Usage: gdt check-issue <issue> [--json]
+       gdt check-issue --body-file <file> [--json]
+
+Validates an issue body against the issue contract for the configured language
+(language in .gdt/config.toml, default en). With <issue>, the body is fetched
+with "gh issue view"; with --body-file, a local file is read and GitHub is not
+called. Exits with 1 when the contract is invalid.
+`;
+const WORKFLOW_HELP = {
+    start: `Usage: gdt start <issue>
+
+Checks the working tree and the issue contract, starts the supervisor and the
+role workers as detached processes and returns. Logs: .git/gdt/issue-<n>/logs.
+`,
+    status: `Usage: gdt status <issue> [--json]
+
+Shows the workflow status and the next step.
+`,
+    wait: `Usage: gdt wait <issue> [--timeout <seconds>] [--json]
+
+Blocks on the local workflow state and returns with the "gdt status" output as
+soon as the workflow needs attention (an action status) or the supervisor is
+gone. It returns at once when the workflow is already in an action status.
+--timeout gives up after the given number of seconds and exits 1. Reads only
+local state under .git/gdt/.
+`,
+    stop: `Usage: gdt stop <issue>
+
+Stops the supervisor, the role workers and any running agent turn.
+"gdt start <issue>" resumes the same workflow.
+`,
+    retry: `Usage: gdt retry <issue>
+
+Stops the failed or interrupted workflow and clears that turn so
+"gdt start <issue>" runs it again.
+`,
+    pause: `Usage: gdt pause <issue>
+
+Stops dispatching new turns; "gdt resume <issue>" continues.
+`,
+    resume: `Usage: gdt resume <issue>
+
+Continues dispatching after "gdt pause <issue>".
+`,
+    "allow-round": `Usage: gdt allow-round <issue>
+
+Grants one extra correction round when the round budget is exhausted.
+`,
+};
+const STEERING_HELP = {
+    answer: `Usage: gdt answer <issue> <question-id> <text>
+
+Posts a [gdt-answer:v1] comment for an open question. Exits 1 when the
+question is unknown or already answered.
+`,
+    steer: `Usage: gdt steer <issue> --role <role> <text>
+
+Posts a [gdt-directive:v1] comment for one role on the workflow pull request,
+or on the issue before a pull request exists. An unknown role exits 1.
+`,
+    "set-agent": `Usage: gdt set-agent <issue> <role> <agent>/<model>
+
+Overrides the configured agent and model for one role from its next turn;
+"gdt status --json" shows the override. An unsupported agent exits 1.
+`,
+    "install-skill": `Usage: gdt install-skill
+
+Copies skill/SKILL.md into the skill directory of every detected agent
+harness and lists the paths. Running it again reports "up to date".
+`,
+};
+export function version() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}
+function usageError(io, message, help) {
+    io.stderr(`${message} Run "${help}".\n`);
+    return EXIT_USAGE;
+}
+const MARKS = { ok: "ok     ", warning: "warning", error: "error  " };
+function formatFindings(findings) {
+    const lines = findings.map((f) => `${MARKS[f.level]}  ${f.message}${f.fix === "" ? "" : `\n         fix: ${f.fix}`}`);
+    const errors = findings.filter((f) => f.level === "error").length;
+    const warnings = findings.filter((f) => f.level === "warning").length;
+    lines.push("", `${errors} error(s), ${warnings} warning(s)`);
+    return `${lines.join("\n")}\n`;
+}
+function doctor(args, io) {
+    let json = false;
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--help" || arg === "-h") {
+            io.stdout(DOCTOR_HELP);
+            return EXIT_OK;
+        }
+        else
+            return usageError(io, `Unknown option "${arg}" for "gdt doctor".`, "gdt doctor --help");
+    }
+    const report = runDoctor(io.cwd, io.env);
+    io.stdout(json ? `${JSON.stringify(report, null, 2)}\n` : formatFindings(report.findings));
+    return report.ok ? EXIT_OK : EXIT_FAILED;
+}
+function checkIssue(args, io) {
+    let json = false;
+    let issue;
+    let bodyFile;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--help" || arg === "-h") {
+            io.stdout(CHECK_ISSUE_HELP);
+            return EXIT_OK;
+        }
+        else if (arg === "--body-file") {
+            bodyFile = args[++i];
+            if (bodyFile === undefined)
+                return usageError(io, 'Missing file for "--body-file".', "gdt check-issue --help");
+        }
+        else if (arg.startsWith("-")) {
+            return usageError(io, `Unknown option "${arg}" for "gdt check-issue".`, "gdt check-issue --help");
+        }
+        else if (issue === undefined && /^[1-9]\d*$/.test(arg))
+            issue = Number(arg);
+        else
+            return usageError(io, `Unexpected argument "${arg}" for "gdt check-issue".`, "gdt check-issue --help");
+    }
+    if (issue !== undefined && bodyFile !== undefined) {
+        return usageError(io, 'Give either an issue number or --body-file to "gdt check-issue", not both.', "gdt check-issue --help");
+    }
+    if (issue === undefined && bodyFile === undefined) {
+        return usageError(io, 'Missing issue number for "gdt check-issue".', "gdt check-issue --help");
+    }
+    const root = findRepository(io.cwd) ?? io.cwd;
+    let language = DEFAULT_LANGUAGE;
+    let maxAcceptanceCriteria = DEFAULT_MAX_ACCEPTANCE_CRITERIA;
+    if (existsSync(join(root, CONFIG_PATH))) {
+        const { report } = loadConfig(root, io.env);
+        if (!report.valid) {
+            io.stderr(`${CONFIG_PATH} is invalid. Run "gdt doctor" for details.\n`);
+            return EXIT_FAILED;
+        }
+        language = report.language;
+        maxAcceptanceCriteria = report.contract.max_acceptance_criteria;
+    }
+    let locale;
+    try {
+        locale = loadLocale(language);
+    }
+    catch (err) {
+        io.stderr(`${err instanceof Error ? err.message : String(err)}\n`);
+        return EXIT_FAILED;
+    }
+    let body;
+    if (bodyFile !== undefined) {
+        try {
+            body = readFileSync(resolve(io.cwd, bodyFile), "utf8");
+        }
+        catch (err) {
+            io.stderr(`Cannot read ${bodyFile}: ${err instanceof Error ? err.message : String(err)}\n`);
+            return EXIT_FAILED;
+        }
+    }
+    else {
+        const fetched = issueBody(issue ?? 0, root, io.env);
+        if ("error" in fetched) {
+            io.stderr(`${fetched.error}\n`);
+            return EXIT_FAILED;
+        }
+        body = fetched.body;
+    }
+    const label = bodyFile ?? `Issue #${issue}`;
+    const result = validateContract(body, locale, { maxAcceptanceCriteria });
+    if (json)
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    else if (result.valid) {
+        io.stdout(`${label}: contract valid (${result.acceptance_criteria.length} acceptance criteria)\n`);
+    }
+    else {
+        const lines = result.errors.map((error) => `  - ${error}`);
+        io.stdout(`${label}: contract invalid (${result.errors.length} error(s))\n${lines.join("\n")}\n`);
+    }
+    return result.valid ? EXIT_OK : EXIT_FAILED;
+}
+/** Parses `<issue> [--json]` for the workflow commands; returns an exit code on usage errors or help. */
+function issueArgs(command, args, io, allowJson) {
+    let json = false;
+    let issue;
+    for (const arg of args) {
+        if (arg === "--json" && allowJson)
+            json = true;
+        else if (arg === "--help" || arg === "-h") {
+            io.stdout(WORKFLOW_HELP[command] ?? HELP);
+            return EXIT_OK;
+        }
+        else if (arg.startsWith("-")) {
+            return usageError(io, `Unknown option "${arg}" for "gdt ${command}".`, `gdt ${command} --help`);
+        }
+        else if (issue === undefined && /^[1-9]\d*$/.test(arg))
+            issue = Number(arg);
+        else
+            return usageError(io, `Unexpected argument "${arg}" for "gdt ${command}".`, `gdt ${command} --help`);
+    }
+    if (issue === undefined)
+        return usageError(io, `Missing issue number for "gdt ${command}".`, `gdt ${command} --help`);
+    return { issue, json };
+}
+/** Writes a command result to the matching streams and returns its exit code. */
+function emit(result, io) {
+    if (result.stdout !== "")
+        io.stdout(result.stdout);
+    if (result.stderr !== "")
+        io.stderr(result.stderr);
+    return result.code;
+}
+function workflowCommand(command, args, io) {
+    const parsed = issueArgs(command, args, io, command === "status");
+    if (typeof parsed === "number")
+        return parsed;
+    const { issue, json } = parsed;
+    const result = command === "start"
+        ? start(issue, io.cwd, io.env)
+        : command === "stop"
+            ? stop(issue, io.cwd, io.env)
+            : command === "retry"
+                ? retry(issue, io.cwd, io.env)
+                : command === "pause"
+                    ? pause(issue, io.cwd, io.env)
+                    : command === "resume"
+                        ? resume(issue, io.cwd, io.env)
+                        : command === "allow-round"
+                            ? allowRound(issue, io.cwd, io.env)
+                            : status(issue, io.cwd, io.env, json);
+    return emit(result, io);
+}
+/** `gdt wait <issue> [--timeout <seconds>] [--json]`: blocks until the workflow needs attention. */
+function waitCommand(args, io) {
+    let json = false;
+    let timeoutSeconds = null;
+    let issue;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--help" || arg === "-h") {
+            io.stdout(WORKFLOW_HELP.wait ?? HELP);
+            return EXIT_OK;
+        }
+        else if (arg === "--timeout") {
+            const value = args[++i];
+            const seconds = value === undefined ? Number.NaN : Number(value);
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                return usageError(io, `Expected a positive number of seconds after "--timeout", got "${value ?? ""}".`, "gdt wait --help");
+            }
+            timeoutSeconds = seconds;
+        }
+        else if (arg.startsWith("-")) {
+            return usageError(io, `Unknown option "${arg}" for "gdt wait".`, "gdt wait --help");
+        }
+        else if (issue === undefined && /^[1-9]\d*$/.test(arg))
+            issue = Number(arg);
+        else
+            return usageError(io, `Unexpected argument "${arg}" for "gdt wait".`, "gdt wait --help");
+    }
+    if (issue === undefined)
+        return usageError(io, 'Missing issue number for "gdt wait".', "gdt wait --help");
+    return emit(wait(issue, io.cwd, io.env, { json, timeoutSeconds }), io);
+}
+/** `gdt answer <issue> <question-id> <text>`; everything after the id is the answer text. */
+function answerCommand(args, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        io.stdout(STEERING_HELP.answer ?? HELP);
+        return EXIT_OK;
+    }
+    const [issueArg, questionId, ...rest] = args;
+    if (issueArg === undefined || questionId === undefined || rest.length === 0) {
+        return usageError(io, 'Usage: gdt answer <issue> <question-id> <text>.', "gdt answer --help");
+    }
+    if (!/^[1-9]\d*$/.test(issueArg))
+        return usageError(io, `Expected an issue number, got "${issueArg}".`, "gdt answer --help");
+    return emit(answer(Number(issueArg), questionId, rest.join(" "), io.cwd, io.env), io);
+}
+/** `gdt steer <issue> --role <role> <text>`. */
+function steerCommand(args, io) {
+    let issue;
+    let role;
+    const text = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--help" || arg === "-h") {
+            io.stdout(STEERING_HELP.steer ?? HELP);
+            return EXIT_OK;
+        }
+        else if (arg === "--role") {
+            role = args[++i];
+            if (role === undefined)
+                return usageError(io, 'Missing value for "--role".', "gdt steer --help");
+        }
+        else if (arg.startsWith("-") && !/^-\d/.test(arg)) {
+            return usageError(io, `Unknown option "${arg}" for "gdt steer".`, "gdt steer --help");
+        }
+        else if (issue === undefined && /^[1-9]\d*$/.test(arg)) {
+            issue = Number(arg);
+        }
+        else {
+            text.push(arg);
+        }
+    }
+    if (issue === undefined)
+        return usageError(io, 'Missing issue number for "gdt steer".', "gdt steer --help");
+    if (role === undefined)
+        return usageError(io, 'Missing "--role <role>" for "gdt steer".', "gdt steer --help");
+    return emit(steer(issue, role, text.join(" "), io.cwd, io.env), io);
+}
+/** `gdt set-agent <issue> <role> <agent>/<model>`. */
+function setAgentCommand(args, io) {
+    if (args.includes("--help") || args.includes("-h")) {
+        io.stdout(STEERING_HELP["set-agent"] ?? HELP);
+        return EXIT_OK;
+    }
+    const [issueArg, role, spec, ...extra] = args;
+    if (issueArg === undefined || role === undefined || spec === undefined || extra.length > 0) {
+        return usageError(io, "Usage: gdt set-agent <issue> <role> <agent>/<model>.", "gdt set-agent --help");
+    }
+    if (!/^[1-9]\d*$/.test(issueArg))
+        return usageError(io, `Expected an issue number, got "${issueArg}".`, "gdt set-agent --help");
+    return emit(setAgent(Number(issueArg), role, spec, io.cwd, io.env), io);
+}
+/** `gdt install-skill`. */
+function installSkillCommand(args, io) {
+    for (const arg of args) {
+        if (arg === "--help" || arg === "-h") {
+            io.stdout(STEERING_HELP["install-skill"] ?? HELP);
+            return EXIT_OK;
+        }
+        return usageError(io, `Unexpected argument "${arg}" for "gdt install-skill".`, "gdt install-skill --help");
+    }
+    return emit(installSkill(io.env), io);
+}
+/** Internal entry points started by the terminal backend; not part of the public CLI. */
+async function internal(command, args, io) {
+    const issue = Number(args[0]);
+    const root = findRepository(io.cwd) ?? io.cwd;
+    if (command === "_supervise")
+        return supervise(root, issue, io.env);
+    const role = args[1];
+    if (!ROLES.includes(role))
+        return EXIT_USAGE;
+    return work(root, issue, role, io.env);
+}
+export function run(argv, io) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case undefined:
+        case "--help":
+        case "-h":
+        case "help":
+            io.stdout(HELP);
+            return EXIT_OK;
+        case "--version":
+            io.stdout(`${version()}\n`);
+            return EXIT_OK;
+        case "doctor":
+            return doctor(rest, io);
+        case "check-issue":
+            return checkIssue(rest, io);
+        case "start":
+        case "status":
+        case "stop":
+        case "retry":
+        case "pause":
+        case "resume":
+        case "allow-round":
+            return workflowCommand(command, rest, io);
+        case "wait":
+            return waitCommand(rest, io);
+        case "answer":
+            return answerCommand(rest, io);
+        case "steer":
+            return steerCommand(rest, io);
+        case "set-agent":
+            return setAgentCommand(rest, io);
+        case "install-skill":
+            return installSkillCommand(rest, io);
+        default:
+            if (command.startsWith("-"))
+                return usageError(io, `Unknown option "${command}".`, "gdt --help");
+            return usageError(io, `Unknown command "${command}".`, "gdt --help");
+    }
+}
+function isEntryPoint() {
+    const script = process.argv[1];
+    if (script === undefined)
+        return false;
+    try {
+        return realpathSync(script) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    const io = {
+        cwd: process.cwd(),
+        env: process.env,
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text),
+    };
+    const [command, ...rest] = process.argv.slice(2);
+    if (command === "_supervise" || command === "_worker") {
+        process.exitCode = await internal(command, rest, io);
+    }
+    else {
+        process.exitCode = run(process.argv.slice(2), io);
+    }
+}

package/dist/config.js

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseToml, TomlError } from "smol-toml";
+import { z } from "zod";
+export const AGENTS = ["claude", "codex", "opencode", "mcode", "pi", "omp"];
+export const ROLES = ["developer", "tester", "reviewer"];
+export const TERMINALS = ["herdr", "headless"];
+export const CONFIG_PATH = ".gdt/config.toml";
+export const LOCAL_CONFIG_PATH = ".gdt/config.local.toml";
+export const DEFAULT_LANGUAGE = "en";
+export const DEFAULT_MAX_ACCEPTANCE_CRITERIA = 8;
+/** The test agent: runs `script` instead of a coding agent. Only accepted when GDT_TEST_AGENTS=1. */
+export const TEST_AGENT = "fake";
+const roleSchema = z.strictObject({
+    agent: z.enum(AGENTS),
+    model: z.string().min(1),
+});
+const testRoleSchema = z
+    .strictObject({
+    agent: z.enum([...AGENTS, TEST_AGENT]),
+    model: z.string().min(1),
+    script: z.string().min(1).optional(),
+})
+    .superRefine((role, ctx) => {
+    if (role.agent === TEST_AGENT && role.script === undefined) {
+        ctx.addIssue({ code: "custom", path: ["script"], message: `required for agent "${TEST_AGENT}"` });
+    }
+    if (role.agent !== TEST_AGENT && role.script !== undefined) {
+        ctx.addIssue({ code: "custom", path: ["script"], message: `only allowed for agent "${TEST_AGENT}"` });
+    }
+});
+function configSchemaFor(testAgents) {
+    const role = testAgents ? testRoleSchema : roleSchema;
+    return z.strictObject({
+        language: z.string().min(1).default(DEFAULT_LANGUAGE),
+        roles: z.strictObject({ developer: role, tester: role, reviewer: role }),
+        workflow: z.strictObject({
+            max_correction_rounds: z.int().min(0).default(2),
+            // Deliberately without a default: an empty gate must be an explicit choice.
+            required_checks: z.array(z.string().min(1)),
+            allow_no_required_checks: z.boolean().default(false),
+            terminal: z.enum(TERMINALS).default("herdr"),
+            supervisor_pane: z.boolean().default(false),
+            poll_seconds: z.number().positive().default(30),
+            handoff_checks: z.int().min(1).default(5),
+        }),
+        contract: z
+            .strictObject({
+            max_acceptance_criteria: z.int().min(1).default(DEFAULT_MAX_ACCEPTANCE_CRITERIA),
+            extra_rules: z.string().min(1).optional(),
+        })
+            .prefault({}),
+    });
+}
+export const configSchema = configSchemaFor(false);
+export function testAgentsEnabled(env) {
+    return env.GDT_TEST_AGENTS === "1";
+}
+function isTable(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function merge(base, over) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(over)) {
+        const current = out[key];
+        out[key] = isTable(current) && isTable(value) ? merge(current, value) : value;
+    }
+    return out;
+}
+function valueAt(data, path) {
+    let current = data;
+    for (const key of path) {
+        if (!isTable(current) && !Array.isArray(current))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function formatPath(path) {
+    return path.map(String).join(".");
+}
+/** The layer that supplied the value at `path`, preferring the local override. */
+function sourceOf(layers, path) {
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (layer && valueAt(layer.data, path) !== undefined)
+            return layer.path;
+    }
+    return layers[0]?.path ?? CONFIG_PATH;
+}
+function describe(value) {
+    return value === undefined ? "missing" : JSON.stringify(value);
+}
+function issueFindings(issue, merged, layers) {
+    const key = formatPath(issue.path);
+    const input = valueAt(merged, issue.path);
+    const file = sourceOf(layers, issue.path);
+    const error = (message, fix) => ({ check: "config", level: "error", message, fix });
+    switch (issue.code) {
+        case "invalid_value": {
+            const allowed = issue.values.map(String).join(", ");
+            return [error(`${key}: ${describe(input)} is not one of ${allowed}`, `Set ${key} in ${file} to one of ${allowed}`)];
+        }
+        case "invalid_type":
+            if (input === undefined) {
+                return [error(`${key}: missing; expected ${issue.expected}`, `Add ${key} to ${file}`)];
+            }
+            return [error(`${key}: expected ${issue.expected}, got ${describe(input)}`, `Correct ${key} in ${file}`)];
+        case "unrecognized_keys":
+            return issue.keys.map((unknownKey) => {
+                const fullKey = formatPath([...issue.path, unknownKey]);
+                return error(`${fullKey}: unknown key`, `Remove or rename ${fullKey} in ${sourceOf(layers, [...issue.path, unknownKey])}`);
+            });
+        default:
+            return [error(`${key}: ${issue.message}`, `Correct ${key} in ${file}`)];
+    }
+}
+function readLayer(root, path) {
+    const text = readFileSync(join(root, path), "utf8");
+    try {
+        return { path, data: parseToml(text) };
+    }
+    catch (err) {
+        const where = err instanceof TomlError ? ` at line ${err.line}, column ${err.column}` : "";
+        const reason = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        return {
+            check: "config",
+            level: "error",
+            message: `${path}: invalid TOML${where}: ${reason}`,
+            fix: `Fix the TOML syntax in ${path}`,
+        };
+    }
+}
+/** Loads, merges and validates `.gdt/config.toml` and `.gdt/config.local.toml` in `root`. */
+export function loadConfig(root, env = {}) {
+    const files = [CONFIG_PATH, LOCAL_CONFIG_PATH].filter((path) => existsSync(join(root, path)));
+    if (!files.includes(CONFIG_PATH)) {
+        return {
+            report: { valid: false, files },
+            findings: [
+                {
+                    check: "config",
+                    level: "error",
+                    message: `${CONFIG_PATH}: not found`,
+                    fix: `Create ${CONFIG_PATH}; example: https://github.com/gevezex/gdt/blob/main/docs/design.md#4-configuration-per-target-repository`,
+                },
+            ],
+        };
+    }
+    const layers = [];
+    const findings = [];
+    for (const path of files) {
+        const layer = readLayer(root, path);
+        if ("data" in layer)
+            layers.push(layer);
+        else
+            findings.push(layer);
+    }
+    if (findings.length > 0)
+        return { report: { valid: false, files }, findings };
+    const merged = layers.reduce((acc, layer) => merge(acc, layer.data), {});
+    const parsed = configSchemaFor(testAgentsEnabled(env)).safeParse(merged);
+    if (!parsed.success) {
+        return {
+            report: { valid: false, files },
+            findings: parsed.error.issues.flatMap((issue) => issueFindings(issue, merged, layers)),
+        };
+    }
+    const config = parsed.data;
+    const roles = Object.fromEntries(ROLES.map((role) => {
+        const localRole = layers.length > 1 ? valueAt(layers[layers.length - 1]?.data, ["roles", role]) : undefined;
+        const source = isTable(localRole) && Object.keys(localRole).length > 0 ? LOCAL_CONFIG_PATH : CONFIG_PATH;
+        return [role, { ...config.roles[role], source }];
+    }));
+    findings.push({
+        check: "config",
+        level: "ok",
+        message: files.length > 1 ? `${CONFIG_PATH} is valid, with overrides from ${LOCAL_CONFIG_PATH}` : `${CONFIG_PATH} is valid`,
+        fix: "",
+    });
+    findings.push(...semanticFindings(root, config));
+    return { report: { valid: true, files, ...config, roles }, findings };
+}
+/** Checks that pass the schema but would make gdt unsafe or surprising. */
+function semanticFindings(root, config) {
+    const findings = [];
+    if (config.workflow.required_checks.length === 0) {
+        findings.push({
+            check: "workflow.required_checks",
+            level: config.workflow.allow_no_required_checks ? "warning" : "error",
+            message: "workflow.required_checks is empty; set workflow.allow_no_required_checks = true to accept this",
+            fix: config.workflow.allow_no_required_checks
+                ? "Add the names of the CI checks that must pass to workflow.required_checks"
+                : "Add the names of the CI checks that must pass to workflow.required_checks, or set workflow.allow_no_required_checks = true",
+        });
+    }
+    const rules = config.contract.extra_rules;
+    if (rules !== undefined) {
+        // A configured file that does not exist is almost always a typo.
+        findings.push(existsSync(join(root, rules))
+            ? { check: "contract.extra_rules", level: "ok", message: `contract.extra_rules: ${rules} found`, fix: "" }
+            : {
+                check: "contract.extra_rules",
+                level: "error",
+                message: `contract.extra_rules: ${rules} not found`,
+                fix: `Create ${rules} or correct or remove contract.extra_rules`,
+            });
+    }
+    return findings;
+}