@gevezex/gdt 0.2.0

package/dist/workflow.js

@@ -0,0 +1,333 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+import { headless } from "./backends/headless.js";
+import { backendFor } from "./backends/index.js";
+import { loadConfig, ROLES } from "./config.js";
+import { validateContract } from "./contract.js";
+import { findRepository, herdrPreflight, unsupportedAgentFindings } from "./doctor.js";
+import { changedFiles } from "./git.js";
+import { issueBody, repository } from "./github.js";
+import { loadLocale } from "./locale.js";
+import { alive, lockHolder, paths, readOverrides, readState, writeState } from "./state.js";
+import { cliPath } from "./supervisor.js";
+export const ok = (stdout) => ({ code: 0, stdout, stderr: "" });
+export const fail = (stderr) => ({ code: 1, stdout: "", stderr });
+/** Statuses that need a person or end the workflow: `gdt wait` returns when it reaches one. */
+const ACTION_STATUSES = [
+    "awaiting_human",
+    "blocked",
+    "failed",
+    "ready_to_merge",
+    "contract_changed",
+    "stopped",
+];
+/** How often `gdt wait` re-reads the local state; well under the 2 seconds the contract allows. */
+const WAIT_POLL_MS = 200;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function newState(issue, repo) {
+    return {
+        version: 1,
+        issue,
+        workflow_id: randomBytes(3).toString("hex"),
+        status: "starting",
+        reason: "",
+        role: null,
+        round: null,
+        exit_code: null,
+        repository: repo,
+        pr_number: null,
+        head: null,
+        head_transition_at: null,
+        contract: null,
+        dispatched: [],
+        inflight: null,
+        notified_status: null,
+        open_findings: [],
+        pids: { supervisor: null, workers: {} },
+        updated_at: "",
+    };
+}
+/** `gdt start <n>`: preflight, then starts a detached supervisor and returns. */
+export function start(issue, cwd, env) {
+    const root = findRepository(cwd);
+    if (root === null)
+        return fail(`${cwd} is not inside a Git repository. Run gdt from a checkout of the target repository.\n`);
+    const { report } = loadConfig(root, env);
+    if (!report.valid)
+        return fail('.gdt/config.toml is invalid. Run "gdt doctor" for details.\n');
+    const unsupported = unsupportedAgentFindings(report.roles);
+    if (unsupported.length > 0)
+        return fail(`${unsupported.map((f) => f.message).join("\n")}\n`);
+    if (report.workflow.terminal === "herdr") {
+        const problem = herdrPreflight(env);
+        if (problem !== null)
+            return fail(`${problem}\n`);
+    }
+    const p = paths(root, issue, env);
+    const holder = lockHolder(p);
+    if (holder !== null)
+        return fail(`Supervisor for #${issue} is already running (pid ${holder})\n`);
+    const existing = readState(p);
+    if (existing?.status === "failed")
+        return fail(`Workflow for #${issue} failed: ${existing.reason}. Next: gdt retry ${issue}\n`);
+    if (existing === null || existing.dispatched.length === 0) {
+        const changed = changedFiles(root, env, true);
+        if (changed.length > 0)
+            return fail(`Working tree not clean: ${changed.join(", ")}. Commit or stash before starting.\n`);
+    }
+    const fetched = issueBody(issue, root, env);
+    if ("error" in fetched)
+        return fail(`${fetched.error}\n`);
+    let locale;
+    try {
+        locale = loadLocale(report.language);
+    }
+    catch (err) {
+        return fail(`${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    const contract = validateContract(fetched.body, locale, { maxAcceptanceCriteria: report.contract.max_acceptance_criteria });
+    if (!contract.valid) {
+        const lines = contract.errors.map((error) => `  - ${error}`).join("\n");
+        return fail(`Issue #${issue}: contract invalid (${contract.errors.length} error(s))\n${lines}\nFix the issue body, then run "gdt start ${issue}" again.\n`);
+    }
+    let state;
+    try {
+        state = existing ?? newState(issue, repository(root, env));
+    }
+    catch (err) {
+        return fail(`Could not read the repository with gh: ${err instanceof Error ? err.message : String(err)}. Run "gdt doctor".\n`);
+    }
+    Object.assign(state, { status: "starting", reason: existing === null ? "" : "resuming", pids: { supervisor: null, workers: {} } });
+    writeState(p, state);
+    let backend;
+    let pid;
+    try {
+        backend = backendFor(report, root, issue, env, p);
+        backend.ensureWorkspace();
+        pid = backend.spawnPane("supervisor", [process.execPath, cliPath(), "_supervise", String(issue)]);
+    }
+    catch (err) {
+        return fail(`Could not start the supervisor for #${issue}: ${err instanceof Error ? err.message : String(err)}. Run "gdt doctor".\n`);
+    }
+    const running = () => lockHolder(p) === pid && readState(p)?.pids.supervisor === pid;
+    for (let waited = 0; waited < 4000 && !running() && alive(pid); waited += 50)
+        sleepSync(50);
+    const logs = relative(root, p.logs) || p.logs;
+    if (!running())
+        return fail(`Supervisor for #${issue} exited during startup; see ${logs}/supervisor.log\n`);
+    const attach = backend.attach();
+    const attachLine = attach === null ? "" : `Attach: ${attach}\n`;
+    return ok(`Supervisor started for #${issue}; logs: ${logs}\n${attachLine}workflow ${state.workflow_id}. Next: gdt status ${issue}\n`);
+}
+/** The workflow's terminal backend; falls back to the headless one when the config is unreadable. */
+function loadBackend(p, issue, env) {
+    const { report } = loadConfig(p.root, env);
+    return report.valid ? backendFor(report, p.root, issue, env, p) : headless(p.logs, p.root, env);
+}
+/**
+ * Stops the supervisor, its workers and any running agent. It does not release the lock: the caller
+ * releases it after writing the final state, so `gdt wait` never sees the lock vanish while the state
+ * is still a waiting status (AC-4 would otherwise fire for a deliberate stop).
+ */
+export function stopProcesses(p, state, env) {
+    // The stop window starts here; `gdt wait` keeps waiting while this process lives (see stopInProgress).
+    mkdirSync(p.dir, { recursive: true });
+    writeFileSync(p.stopping, `${process.pid}\n`);
+    const backend = loadBackend(p, state.issue, env);
+    const pids = [lockHolder(p), state.pids.supervisor, ...ROLES.map((role) => state.pids.workers[role])];
+    for (const pid of new Set(pids))
+        if (pid !== null && pid !== undefined && alive(pid))
+            backend.close(pid);
+}
+/** Ends the stop window: releases the lock after the final state is written, then the stop marker. */
+function releaseAfterStop(p) {
+    rmSync(p.lock, { force: true });
+    rmSync(p.stopping, { force: true });
+}
+/** True while a live `gdt stop` or `gdt retry` is between ending the supervisor and writing the final state. */
+function stopInProgress(p) {
+    if (!existsSync(p.stopping))
+        return false;
+    const pid = Number(readFileSync(p.stopping, "utf8").trim());
+    return Number.isInteger(pid) && alive(pid);
+}
+/** AC-6: after stopping, every herdr pane shows STOPPED; the gdt processes printed the last line. */
+function markStopped(p, issue, env) {
+    const { report } = loadConfig(p.root, env);
+    if (!report.valid || report.workflow.terminal !== "herdr")
+        return;
+    try {
+        const backend = backendFor(report, p.root, issue, env, p);
+        backend.setTitle("supervisor", "supervisor · stopped");
+        for (const role of ROLES)
+            backend.setTitle(role, `${role} · ${report.roles[role].agent} · STOPPED`);
+        // AC-5: `stopped` reports `idle` for the supervisor pane.
+        backend.reportState("supervisor", "idle");
+    }
+    catch {
+        // The processes are already stopped; a missing herdr must not fail `gdt stop`.
+    }
+}
+/** `gdt stop <n>`: stops the supervisor, workers and running agents; `gdt start` resumes. */
+export function stop(issue, cwd, env) {
+    const root = findRepository(cwd) ?? cwd;
+    const p = paths(root, issue, env);
+    const before = readState(p);
+    if (before === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    stopProcesses(p, before, env);
+    // Re-read: the supervisor may have written state until it was stopped.
+    const state = readState(p) ?? before;
+    // A failed turn keeps its status and reason; only the recovery step (gdt retry) clears it.
+    if (state.status === "failed")
+        Object.assign(state, { pids: { supervisor: null, workers: {} } });
+    else
+        Object.assign(state, { status: "stopped", reason: "", pids: { supervisor: null, workers: {} } });
+    writeState(p, state);
+    // Release the lock only now: `gdt wait` must return on the final status, never on the vanished lock.
+    releaseAfterStop(p);
+    markStopped(p, issue, env);
+    // The printed next step is exactly what `gdt status` reports after this command.
+    return ok(`Stopped #${issue}. Next: ${describe(state, false).next}\n`);
+}
+/** States from which `gdt retry` may clear the interrupted turn: a failed turn, or a blocked one that never produced a usable record. */
+function retryable(state) {
+    if (state.status === "failed")
+        return true;
+    return state.status === "blocked" && (state.reason.includes("without a visible handoff") || state.reason.includes("already ran"));
+}
+/** `gdt retry <n>`: stops the workflow and clears the interrupted turn so `gdt start` runs it again. */
+export function retry(issue, cwd, env) {
+    const root = findRepository(cwd) ?? cwd;
+    const p = paths(root, issue, env);
+    const state = readState(p);
+    if (state === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    if (!retryable(state)) {
+        return fail(`Workflow for #${issue} is not in a retryable state (status ${state.status}). Next: ${describe(state, lockHolder(p) !== null).next}\n`);
+    }
+    stopProcesses(p, state, env);
+    const key = state.inflight?.key ?? state.blocked_key ?? undefined;
+    if (key !== undefined) {
+        rmSync(p.started(key), { force: true });
+        rmSync(p.result(key), { force: true });
+        state.dispatched = state.dispatched.filter((known) => known !== key);
+    }
+    Object.assign(state, {
+        status: "stopped",
+        reason: "",
+        exit_code: null,
+        inflight: null,
+        blocked_key: null,
+        pids: { supervisor: null, workers: {} },
+    });
+    writeState(p, state);
+    // Release the lock only now: `gdt wait` must return on the final status, never on the vanished lock.
+    releaseAfterStop(p);
+    return ok(`Retry prepared for #${issue}. Next: ${describe(state, false).next}\n`);
+}
+function blockedHint(issue, reason) {
+    if (reason.startsWith("round budget exhausted"))
+        return `gdt allow-round ${issue}`;
+    if (reason.includes("without a visible handoff") || reason.includes("already ran"))
+        return `gdt retry ${issue}`;
+    if (reason.includes("without a Changelog update"))
+        return `add a Changelog entry to issue #${issue}, or revert the body change`;
+    return "resolve the cause; the supervisor checks again on every poll";
+}
+/** The one-line status and the next step. */
+export function describe(state, supervisorAlive) {
+    const n = state.issue;
+    if (state.status === "paused")
+        return { line: "paused", next: `gdt resume ${n}` };
+    // In herdr mode the supervisor exits after `ready_to_merge`; merging needs no live supervisor.
+    const active = !["stopped", "failed", "ready_to_merge"].includes(state.status);
+    if (active && !supervisorAlive)
+        return { line: `supervisor not running (last status: ${state.status})`, next: `gdt start ${n}` };
+    const withReason = state.reason === "" ? state.status : `${state.status}: ${state.reason}`;
+    switch (state.status) {
+        case "failed":
+            return { line: state.reason, next: `gdt retry ${n}` };
+        case "stopped":
+            return { line: "stopped", next: `gdt start ${n}` };
+        case "running":
+            return { line: `running: ${state.role ?? "?"} turn, round ${state.round ?? 0}`, next: "wait" };
+        case "blocked":
+            return { line: withReason, next: blockedHint(n, state.reason) };
+        case "awaiting_human":
+            return { line: withReason, next: `gdt answer ${n} <question-id> "<answer>"` };
+        case "ready_to_merge":
+            return { line: withReason, next: `review and merge pull request #${state.pr_number ?? "?"}` };
+        default:
+            return { line: withReason, next: "wait" };
+    }
+}
+/** The state as status and wait see it: the pause file reports `paused` until the workflow ends. */
+function effectiveState(p, state) {
+    const paused = existsSync(p.pause) && state.status !== "stopped" && state.status !== "failed";
+    return paused ? { ...state, status: "paused", reason: "" } : state;
+}
+/** `gdt status <n>`. The pause file reports `paused` even before the supervisor notices it. */
+export function status(issue, cwd, env, json) {
+    const root = findRepository(cwd) ?? cwd;
+    const p = paths(root, issue, env);
+    const state = readState(p);
+    if (state === null) {
+        return json
+            ? { code: 1, stdout: `${JSON.stringify({ issue, status: null, next_step: `gdt start ${issue}` }, null, 2)}\n`, stderr: "" }
+            : fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    }
+    const effective = effectiveState(p, state);
+    const { line, next } = describe(effective, lockHolder(p) !== null);
+    if (!json)
+        return ok(`${line}. Next: ${next}\n`);
+    let maxRounds = null;
+    const { report } = loadConfig(root, env);
+    if (report.valid)
+        maxRounds = report.workflow.max_correction_rounds;
+    const out = {
+        issue,
+        workflow_id: state.workflow_id,
+        status: effective.status,
+        reason: effective.reason,
+        role: state.role,
+        round: state.round,
+        max_rounds: maxRounds,
+        exit_code: state.exit_code,
+        pr_number: state.pr_number,
+        open_findings: state.open_findings ?? [],
+        overrides: readOverrides(p),
+        next_step: next,
+    };
+    return ok(`${JSON.stringify(out, null, 2)}\n`);
+}
+/**
+ * `gdt wait <n>`: blocks on the local workflow state only (no gh, no model tokens) and returns with
+ * the `gdt status` output as soon as the workflow reaches an action status. It also returns when the
+ * supervisor dies in a waiting status, because that is an event the operator must relay (AC-4).
+ */
+export function wait(issue, cwd, env, options) {
+    const root = findRepository(cwd) ?? cwd;
+    const p = paths(root, issue, env);
+    const deadline = options.timeoutSeconds === null ? null : Date.now() + options.timeoutSeconds * 1000;
+    for (;;) {
+        const state = readState(p);
+        // No workflow is status's error path (AC-6); an action status returns at once (AC-1, AC-2).
+        if (state === null)
+            return status(issue, cwd, env, options.json);
+        const effective = effectiveState(p, state);
+        if (ACTION_STATUSES.includes(effective.status))
+            return status(issue, cwd, env, options.json);
+        // A dead supervisor ends the wait, except while the operator paused it deliberately (AC-4).
+        // A deliberate stop is not a dead supervisor: its final state follows once the stop window ends.
+        if (effective.status !== "paused" && lockHolder(p) === null && !stopInProgress(p))
+            return status(issue, cwd, env, options.json);
+        if (deadline !== null && Date.now() >= deadline) {
+            return fail(`still ${effective.status} after ${options.timeoutSeconds} s. Next: gdt wait ${issue}\n`);
+        }
+        sleepSync(WAIT_POLL_MS);
+    }
+}

package/locales/en.toml

@@ -0,0 +1,28 @@
+# Everything the issue-contract validator must recognise in English issue bodies.
+
+# Top-level keys: they must come before the first [table].
+name = "English"
+vague_phrases = ["etc.", "and so on", "where needed", "as needed", "properly", "as usual",
+  "in the right way", "robust", "user-friendly", "and the like"]
+
+[sections]
+plain_language = "Plain language"
+goal = "Goal"
+context = "Context"
+definitions = "Definitions"
+acceptance_criteria = "Acceptance criteria"
+non_functional = "Non-functional"
+out_of_scope = "Out of scope"
+assumptions = "Assumptions"
+open_questions = "Open questions"
+changelog = "Changelog"
+readiness = "Readiness"
+
+[ac_fields]
+given = "Given"
+when = "When"
+then = "Then"
+example = "Example"
+
+[markers]
+none = "None."

package/locales/nl.toml

@@ -0,0 +1,28 @@
+# Everything the issue-contract validator must recognise in Dutch issue bodies.
+
+# Top-level keys: they must come before the first [table].
+name = "Dutch"
+vague_phrases = ["etc.", "enzovoort", "waar nodig", "netjes", "zoals gebruikelijk",
+  "op de juiste manier", "robuust", "gebruiksvriendelijk", "en dergelijke"]
+
+[sections]
+plain_language = "In gewone taal"
+goal = "Doel"
+context = "Context"
+definitions = "Definities"
+acceptance_criteria = "Acceptatiecriteria"
+non_functional = "Niet-functioneel"
+out_of_scope = "Buiten scope"
+assumptions = "Aannames"
+open_questions = "Open vragen"
+changelog = "Changelog"
+readiness = "Readiness"
+
+[ac_fields]
+given = "Gegeven"
+when = "Wanneer"
+then = "Dan"
+example = "Voorbeeld"
+
+[markers]
+none = "Geen."

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@gevezex/gdt",
+  "version": "0.2.0",
+  "description": "GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.",
+  "keywords": [
+    "github",
+    "pull-request",
+    "ai-agents",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Ayhan Cicek",
+  "homepage": "https://github.com/gevezex/gdt#readme",
+  "bugs": {
+    "url": "https://github.com/gevezex/gdt/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gevezex/gdt.git"
+  },
+  "type": "module",
+  "bin": {
+    "gdt": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "locales",
+    "roles",
+    "schemas",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/export-schemas.js",
+    "lint": "eslint . && tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "dependencies": {
+    "smol-toml": "^1.9.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.0",
+    "eslint": "^10.11.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/roles/developer.md

@@ -0,0 +1,66 @@
+# Role: developer
+
+You are the developer in a gdt workflow. You turn one GitHub issue into one draft pull request that
+meets every acceptance criterion (AC). A tester and a reviewer, each a separate agent, check your work
+after you hand off. A deterministic supervisor decides whose turn it is, from the records you post.
+
+## Your job this turn
+
+1. Read the issue body with `gh issue view <issue>`. The current body is the only specification.
+   Comments are discussion and evidence; they never change the contract.
+2. Round 0: create a feature branch from the up-to-date default branch and implement the ACs.
+   Round 1 or later: read the latest `[gdt-test:v1]` and `[gdt-review:v1]` records on the pull request
+   and fix every finding in one set of commits. That set is one correction round.
+3. Implement only what the ACs require. Anything under "Out of scope", or not covered by an AC, stays
+   out. Record choices the issue leaves open under `assumptions`, and any departure from an AC under
+   `deviations`.
+4. Add or update tests so that each AC is covered, and run the project's build, lint and tests.
+5. Commit, push, and open the pull request as a draft if it does not exist yet. Its body must contain
+   `Closes #<issue>`: that is how the supervisor finds the workflow pull request. There is exactly one
+   workflow pull request; never open a second one.
+6. Post your handoff record as a comment on the pull request (see below), then stop.
+
+## Boundaries
+
+- Never merge, deploy, close the issue or mark the pull request ready for review. Those are human
+  actions.
+- Never write `[gdt-test:v1]`, `[gdt-review:v1]`, `[gdt-answer:v1]`, `[gdt-directive:v1]` or
+  `[gdt-round:v1]` records.
+- Human directives (listed in this prompt when there are any) are guidance, not contract. If a
+  directive would change product behaviour that the ACs do not settle, do not follow it: ask a
+  question instead, and ask for the issue body to be updated.
+
+## The handoff record
+
+Post one comment on the pull request containing the marker, one JSON object and the closing marker:
+
+```
+[gdt-handoff:v1]
+{ ...JSON matching the schema in this prompt... }
+[/gdt-handoff:v1]
+```
+
+Use `gh pr comment <pr> --body-file <file>`; if no pull request exists (a `blocked` or
+`awaiting_human` handoff before the first push), post it on the issue with `gh issue comment` instead.
+Copy `repository`, `issue`, `round`,
+`issue_body_sha256` and `acceptance_criteria` exactly from the dispatch facts. Set `pr_number` to the
+pull request number. For each AC, `ac_traceability` lists the files and tests that implement it.
+Prose for humans may follow the closing marker, in the language this prompt names. Marker, keys and
+status values always stay in English.
+
+Allowed `status` values:
+
+- `ready`: the work is pushed and ready for the tester.
+- `awaiting_human`: you cannot continue without a human decision. Post a `[gdt-question:v1]` record
+  too (below).
+- `blocked`: you cannot continue for a reason a human must fix, such as missing access or a broken
+  environment. Explain it in prose below the record.
+
+## Questions
+
+When a product decision is missing, do not guess. Post a `[gdt-question:v1]` record: on the pull
+request if it exists, otherwise on the issue with `gh issue comment`. Use `role` `developer`,
+`resume_role` `developer`, a new `question_id` (`Q1`, `Q2`, ...), and the question text.
+Copy `repository`, `issue`, `round`, `pr_number`, `issue_body_sha256` and `acceptance_criteria`
+from the dispatch facts, as for your record. Then stop. The supervisor resumes you after a human
+answers.

package/roles/issue-writer.md

@@ -0,0 +1,40 @@
+# Role: issue writer
+
+You help a user turn an idea into a GitHub issue that gdt can work on. The issue body is the contract:
+the developer, tester and reviewer agents work only from it, so it must be complete and unambiguous.
+
+## How to write the body
+
+1. Talk with the user until the goal, the behaviour and the boundaries are clear. Ask; do not invent
+   product decisions. Every open point must be settled before the body is final.
+2. Write the body to a local file, for example `body.md`, in the user's configured language. Use
+   exactly the section headings and acceptance-criterion labels of that language's locale file
+   (`locales/<language>.toml` in gdt); never translate headings yourself.
+3. Give every acceptance criterion a number (`AC-1`, `AC-2`, ...) and the four fields Given, When, Then
+   and Example, each with concrete values. An error path with different behaviour gets its own
+   criterion. Stay within the configured maximum number of criteria.
+4. List desired behaviour that is not covered under the out-of-scope section. The open-questions
+   section must contain exactly the locale's none marker. Avoid the vague phrases the locale lists.
+5. Check the file:
+
+   ```sh
+   gdt check-issue --body-file body.md
+   ```
+
+   Fix every reported error and run the check again until it reports the contract as valid.
+
+## Creating the issue
+
+Create the issue only when the user asked you to create it, and only after the check passes:
+
+```sh
+gh issue create --title "<title>" --body-file body.md
+```
+
+Otherwise, give the user the body file and the check result, and stop.
+
+## Boundaries
+
+- You write issue bodies only. You do not start workflows, write code or post workflow records.
+- Keep a changelog entry in the body; when you later change a created issue's body, add a new
+  changelog entry describing the change.

package/roles/reviewer.md

@@ -0,0 +1,65 @@
+# Role: reviewer
+
+You are the reviewer in a gdt workflow. After the tester approved, you review the pull request at its
+current head: does the change meet every acceptance criterion (AC), stay within scope, and have the
+quality to be merged?
+
+## Your job this turn
+
+1. Read the issue body with `gh issue view <issue>`. The current body is the only specification.
+2. Read the pull request and its diff with `gh pr view <pr>` and `gh pr diff <pr>`. All roles share one
+   checkout, and it is already at the pull request head: confirm that `git rev-parse HEAD` equals the
+   head in this prompt (otherwise post `blocked`), read the code in context, and run the build and
+   tests if that helps. Never check out another commit.
+3. Check, in this order:
+   - every AC is implemented and covered by a test;
+   - nothing outside the ACs was added (compare with "Out of scope");
+   - choices the issue leaves open are named in the pull request body;
+   - code quality: correctness, edge cases, error handling, security, readability, and consistency
+     with the surrounding code.
+4. Post your review record as a comment on the pull request (see below), then stop.
+
+## Boundaries
+
+- You are read-only. Never commit, push, switch branches, reset, or edit tracked files. The supervisor
+  checks the working tree after your turn and blocks the workflow if a tracked file, the branch or
+  HEAD changed. Scratch files that git does not track are fine; remove them when you are done.
+- Never fix the code yourself; report findings instead.
+- Never merge, deploy, close the issue or mark the pull request ready for review.
+- Never write `[gdt-handoff:v1]`, `[gdt-test:v1]`, `[gdt-answer:v1]`, `[gdt-directive:v1]` or
+  `[gdt-round:v1]` records.
+- Human directives (listed in this prompt when there are any) guide your review. They never count as
+  evidence and never replace an AC.
+
+## The review record
+
+Post one comment on the pull request containing the marker, one JSON object and the closing marker:
+
+```
+[gdt-review:v1]
+{ ...JSON matching the schema in this prompt... }
+[/gdt-review:v1]
+```
+
+Use `gh pr comment <pr> --body-file <file>`. Copy `repository`, `issue`, `round`, `pr_number`,
+`issue_body_sha256` and `acceptance_criteria` exactly from the dispatch facts. Set `head` to the full
+40-character SHA you reviewed. Give every AC one `ac_results` entry with `passed`, `failed` or
+`not_verified`, and concrete `evidence` (file and line, or test name). Each problem is a finding with
+id `R-1`, `R-2`, ...; set `blocking` to true for an unmet AC, scope creep or a real defect, and false
+for suggestions. Prose for humans may follow the closing marker, in the language this prompt names.
+Marker, keys and status values stay in English.
+
+Allowed `status` values:
+
+- `approved`: every AC is `passed` and there is no blocking finding.
+- `changes_requested`: at least one AC is not `passed`, or a blocking finding is open.
+- `awaiting_human`: you need a human decision. Post a `[gdt-question:v1]` record too.
+- `blocked`: you cannot review for a reason a human must fix.
+
+## Questions
+
+When the issue does not settle something the review depends on, post a `[gdt-question:v1]` record on
+the pull request with `role` `reviewer`, `resume_role` `reviewer`, a new `question_id` and the
+question, then stop.
+Copy `repository`, `issue`, `round`, `pr_number`, `issue_body_sha256` and `acceptance_criteria`
+from the dispatch facts, as for your record.