@gevezex/gdt 0.3.0 → 0.4.1

package/README.md

@@ -122,13 +122,14 @@ evidence too.
 | `git` | the shared checkout the roles work in |
 | `gh`, logged in (`gh auth login`) | issues, pull requests, comments, checks |
 | at least one agent CLI | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` (see below) |
+| CI on pull requests | the target repository needs at least one CI check (for example a GitHub Actions job); `workflow.required_checks` lists its name as shown on the pull request and `gdt init` detects the names. Set `workflow.allow_no_required_checks = true` only as the explicit opt-out |
 | [herdr](https://herdr.dev) 0.9.1+ | the default way to watch the roles live, one tab per role; on machines without herdr set `workflow.terminal = "headless"` |
 
 ### Agent prerequisites
 
-Before the first `gdt start`, every agent CLI you name in `.gdt/config.toml` must
-already work on your machine with the exact model id you set there. For each
-role:
+Before the first `gdt start`, every agent CLI you name in the user config
+(`~/.config/gdt/config.toml`) must already work on your machine with the exact
+model id you set there. For each role:
 
 1. install the agent CLI,
 2. log in or configure its API key or subscription,
@@ -159,6 +160,12 @@ npm run build
 npm link          # puts `gdt` on your PATH
 ```
 
+A linked install runs `dist/` of that checkout, so gdt runs the code you built
+there. A workflow that runs gdt on that same checkout (for example on gdt's own
+repository) can rebuild `dist/` and change the running gdt mid-workflow. Use a
+linked install only to develop gdt; to run workflows, install the published
+package with `npm i -g @gevezex/gdt`.
+
 Then install the operator skill, so your coding agent knows how to drive gdt:
 
 ```bash
@@ -168,13 +175,34 @@ gdt install-skill
 It copies `skill/SKILL.md` into the skill directory of every agent CLI it finds
 (for example `~/.claude/skills/gdt`) and is safe to run again.
 
+## Security
+
+Before the first `gdt start`, know what a role turn can do:
+
+- Every role turn runs its agent CLI **without permission prompts** and with
+  shell access to the machine. The adapters pass, for example,
+  `--permission-mode bypassPermissions` for Claude Code and
+  `--dangerously-bypass-approvals-and-sandbox` for Codex, because nobody is
+  there to answer a prompt. Run gdt only where you accept that.
+- Issue and comment text is **task data** for the roles, never instructions to
+  the supervisor. Treat an issue body or a comment as untrusted input.
+- The tester and reviewer are **checked mechanically**: after their turn the
+  supervisor verifies that HEAD, branch and the tracked files are unchanged, and
+  blocks the workflow otherwise.
+- Roles act with **your own `gh` login**. An agent-written comment is
+  indistinguishable from one you wrote; gdt never merges, deploys or closes
+  issues.
+
+The full invocation for each agent is in [docs/agents.md](docs/agents.md); the
+trust boundaries are in
+[section 10 of docs/design.md](docs/design.md#10-security-and-trust-boundaries).
+
 ## Quick start
 
-### 1. Configure the target repository
+### 1. Set up the user config once per machine
 
-In the repository you want gdt to work on, create `.gdt/config.toml` with
-`gdt init` instead of writing TOML by hand. Ask your coding agent, or run it
-yourself:
+Roles belong to you, not to a repository, so they live in your user config. Ask
+your coding agent, or run `gdt init` yourself:
 
 ```bash
 gdt init --developer opencode/deepseek/deepseek-v4-flash \
@@ -182,24 +210,35 @@ gdt init --developer opencode/deepseek/deepseek-v4-flash \
          --reviewer codex/gpt-5.6-luna
 ```
 
-`gdt init` writes the config, runs `gdt doctor` and installs the operator skill.
-Without the three role options it only reports what it found (agents on `PATH`,
-the terminal, the detected CI checks) so your agent can discuss the roles with
-you first. It never overwrites an existing config without `--force`, and it
-requires at least one required check unless you pass `--allow-no-required-checks`.
+`gdt init` writes the roles to the user config (`~/.config/gdt/config.toml`, or
+`$XDG_CONFIG_HOME/gdt/config.toml`) and installs the operator skill. Run it from
+one of your checkouts: it also creates that repository's `.gdt/config.toml`, so
+that first repository is configured too. Without the three role options, it
+reuses the roles from your user config when they are all there; otherwise it
+only reports what it found (agents on `PATH`, the terminal, the detected CI
+checks) so your agent can discuss the roles with you first. It never overwrites
+an existing config without `--force`.
+
+### 2. Configure each target repository
 
-Then check your setup:
+For every other repository you want gdt to work on, create `.gdt/config.toml`
+with `gdt init` (no role options: it reuses the roles from your user config), or
+commit a file based on [`examples/config.toml`](examples/config.toml). `gdt init`
+requires at least one required check unless you pass
+`--allow-no-required-checks`.
+
+Then check your setup in that repository:
 
 ```bash
 gdt doctor
 ```
 
-`doctor` checks `git`, `gh` and its login, the agent CLIs, herdr (when used)
-and the config, and prints a `fix:` line for every problem. It also warns when
-developer and tester use the same model vendor, because the tester is less
-independent then.
+`doctor` checks `git`, `gh` and its login, the agent CLIs, herdr (when used) and
+the user, repository and local config, and prints a `fix:` line for every
+problem. It also warns when developer and tester use the same model vendor,
+because the tester is less independent then.
 
-### 2. Write the issue as a contract
+### 3. Write the issue as a contract
 
 The issue body is the only specification. It needs fixed sections and numbered
 acceptance criteria, each with Given, When, Then and a concrete Example:
@@ -248,7 +287,7 @@ gdt check-issue --body-file body.md    # a draft, without calling GitHub
 Your agent can help write the body with the issue-writer instructions in
 [`roles/issue-writer.md`](roles/issue-writer.md).
 
-### 3. Start it from your agent
+### 4. Start it from your agent
 
 Just ask your coding agent, in your own language:
 
@@ -266,7 +305,7 @@ gdt wait 251      # blocks until the workflow needs attention
 gdt status 251    # one line plus the next step
 ```
 
-### 4. Answer, steer, merge
+### 5. Answer, steer, merge
 
 | Situation | What you (or your agent) run |
 |---|---|
@@ -292,7 +331,7 @@ changes product behaviour makes the role ask for the issue body to be updated.
 | `awaiting_human` | a role asked a question | `gdt answer <n> <question-id> "<text>"` |
 | `blocked` | a gate failed or a role reported blocked; the reason says why | follow the hint, e.g. `gdt allow-round <n>` |
 | `contract_changed` | the issue body changed; evidence is reset | wait |
-| `failed` | an agent turn exited non-zero | `gdt retry <n>` |
+| `failed` | an agent turn exited non-zero | `gdt retry <n>`, then `gdt start <n>` |
 | `paused` / `stopped` | you paused or stopped it | `gdt resume <n>` / `gdt start <n>` |
 | `ready_to_merge` | all gates passed | review and merge the PR |
 
@@ -302,8 +341,8 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 
 | Command | Effect |
 |---|---|
-| `gdt init` | Create `.gdt/config.toml` and install the operator skill |
-| `gdt doctor` | Check tools, GitHub login, agents, herdr and `.gdt/config.toml` |
+| `gdt init` | Write the roles to the user config and `.gdt/config.toml`, install the operator skill |
+| `gdt doctor` | Check tools, GitHub login, agents, herdr and the user, repository and local config |
 | `gdt check-issue <n>` | Validate an issue body against the contract |
 | `gdt start <n>` | Preflight, start the supervisor and workers, return |
 | `gdt status <n>` | Status, role, round, open findings and next step |
@@ -319,23 +358,38 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 
 ## Configuration
 
-`.gdt/config.toml` is committed; `.gdt/config.local.toml` holds machine-local
-overrides (for example another model) and is not committed.
-
-| Key | Default | Meaning |
-|---|---|---|
-| `language` | `"en"` | Language of issue and PR text (`en`, `nl`) |
-| `roles.<role>.agent` | required | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` |
-| `roles.<role>.model` | required | Model id for that agent |
-| `workflow.required_checks` | required | CI checks that must be green before `ready_to_merge` |
-| `workflow.allow_no_required_checks` | `false` | Allow an empty `required_checks` list |
-| `workflow.max_correction_rounds` | `2` | Correction rounds after round 0 |
-| `workflow.terminal` | `"herdr"` | `"herdr"` or `"headless"` |
-| `workflow.supervisor_pane` | `false` | herdr: also show the supervisor in a pane |
-| `workflow.herdr_layout` | `tabs` | herdr: `"tabs"` (one tab per pane) or `"split"` (panes side by side in one tab) |
-| `workflow.poll_seconds` | `30` | How often the supervisor reads GitHub |
-| `contract.max_acceptance_criteria` | `8` | Maximum number of ACs per issue |
-| `contract.extra_rules` | none | File with project rules added to every role prompt |
+Roles belong to a person, not to a repository, so gdt keeps them in a per-user
+config. gdt loads three files and merges them in this order, with the later file
+winning per key:
+
+1. the **user config** — `$XDG_CONFIG_HOME/gdt/config.toml`, or
+   `~/.config/gdt/config.toml` when `XDG_CONFIG_HOME` is not set. It holds only
+   `[roles.*]`. A relative `XDG_CONFIG_HOME` is ignored.
+2. the **repository config** — `.gdt/config.toml`, committed. It holds the project
+   settings and must not contain `[roles.*]`.
+3. the **local config** — `.gdt/config.local.toml`, never committed. It overrides
+   any key, for example one role's model on this machine.
+
+`gdt init` writes the roles to the user config and the project settings to
+`.gdt/config.toml`. Ready-made files are in [`examples/`](examples/):
+[`examples/user-config.toml`](examples/user-config.toml),
+[`examples/config.toml`](examples/config.toml) and
+[`examples/config.local.toml`](examples/config.local.toml).
+
+| Key | File | Default | Meaning |
+|---|---|---|---|
+| `roles.<role>.agent` | user | required | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` |
+| `roles.<role>.model` | user | required | Model id for that agent |
+| `language` | repository | `"en"` | Language of issue and PR text (`en`, `nl`) |
+| `workflow.required_checks` | repository | required | CI checks that must be green before `ready_to_merge` |
+| `workflow.allow_no_required_checks` | repository | `false` | Allow an empty `required_checks` list |
+| `workflow.max_correction_rounds` | repository | `2` | Correction rounds after round 0 |
+| `workflow.terminal` | repository | `"herdr"` | `"herdr"` or `"headless"` |
+| `workflow.supervisor_pane` | repository | `false` | herdr: also show the supervisor in a pane |
+| `workflow.herdr_layout` | repository | `tabs` | herdr: `"tabs"` (one tab per pane) or `"split"` (panes side by side in one tab) |
+| `workflow.poll_seconds` | repository | `30` | How often the supervisor reads GitHub |
+| `contract.max_acceptance_criteria` | repository | `8` | Maximum number of ACs per issue |
+| `contract.extra_rules` | repository | none | File with project rules added to every role prompt |
 
 ### Per-role rules
 
@@ -356,6 +410,26 @@ the three files empty so you can see where your rules go; commit them like
 
 How each agent CLI is invoked is documented in [docs/agents.md](docs/agents.md).
 
+## Upgrading
+
+### From 0.3 to 0.4
+
+Since 0.4.0, `[roles.*]` in `.gdt/config.toml` is an error and `gdt start`
+refuses to run. Roles now live in the user config. To upgrade:
+
+1. Move the three `[roles.*]` tables from `.gdt/config.toml` to the user config
+   at `~/.config/gdt/config.toml`, or `$XDG_CONFIG_HOME/gdt/config.toml` when
+   `XDG_CONFIG_HOME` is set.
+2. Remove the `[roles.*]` tables from `.gdt/config.toml`, so only the repository
+   settings (`[workflow]`, `[contract]`) remain.
+3. Run `gdt doctor` to check that the configuration is valid again.
+
+Instead of steps 1 and 2 you can run `gdt init --force` with the three role
+options (see [Quick start](#quick-start)). It writes the roles to the user
+config, but it also replaces `.gdt/config.toml` in the current checkout with
+freshly detected defaults, so any custom repository settings there are lost.
+Use the manual move when you have changed `[workflow]` or `[contract]`.
+
 ## Watching it: herdr or headless
 
 ```text
@@ -373,6 +447,51 @@ Everything gdt keeps for an issue lives under `.git/gdt/issue-<n>/`: `state.json
 (the workflow state), `logs/` (one log per process) and `runs/` (the prompt and
 result of every turn). It is never committed.
 
+### Notifications
+
+When a workflow needs you, gdt notifies you through the first of
+`terminal-notifier`, `osascript` (macOS) or `notify-send` (Linux) that is on
+`PATH` and works. If none of them is available, the notification is only
+written to `.git/gdt/issue-<n>/logs/supervisor.log`, and `gdt wait` is the way
+to be told: it blocks until the workflow needs attention.
+
+## The checkout during and after a workflow
+
+The roles work in the checkout where you run `gdt start`: the developer checks
+out the feature branch there, and the tester and reviewer read that same working
+tree. `gdt start` needs a **clean working tree** and refuses to run otherwise
+("Commit or stash before starting."), so commit or stash first. Do not edit that
+checkout while a workflow runs; if you want to keep working, use a separate
+clone for gdt.
+
+After `ready_to_merge`, or after `gdt stop`, two things stay behind:
+
+- the herdr workspace `gdt-<n>`, which you can close yourself in herdr;
+- the state directory `.git/gdt/issue-<n>/`, which you may delete once the pull
+  request is merged and no gdt process for that issue is running.
+
+## Troubleshooting
+
+When a turn fails or a workflow stops unexpectedly, start with:
+
+```bash
+gdt status <n>
+gdt doctor
+```
+
+`gdt status <n>` shows the status, role, round and next step; `gdt doctor`
+reports a `fix:` line for every configuration or tool problem.
+
+Everything gdt keeps for an issue is under the state directory: one log per
+process in `.git/gdt/issue-<n>/logs/`, and the prompt and result of every turn
+in `.git/gdt/issue-<n>/runs/`.
+
+- **exit code 78** means the configuration was invalid or the turn's prompt
+  could not be built. Run `gdt doctor`, fix what it reports, then
+  `gdt retry <n>` and `gdt start <n>`.
+- **any other non-zero exit code** means the agent CLI itself failed; its log
+  under `.git/gdt/issue-<n>/logs/` shows why.
+
 ## Principles
 
 - **The issue body is the contract.** Work starts only when there are no open questions.
@@ -395,7 +514,7 @@ npm ci
 npm run build
 npm run lint
 npm test
-node dist/cli.js doctor   # run inside a repository with .gdt/config.toml
+node dist/cli.js doctor   # run in a repository configured for gdt (user + repository + local config)
 ```
 
 Rules for agents working on this repository: [AGENTS.md](AGENTS.md).

package/dist/cli.js

@@ -2,11 +2,11 @@
 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 { CONFIG_PATH, DEFAULT_LANGUAGE, DEFAULT_MAX_ACCEPTANCE_CRITERIA, loadConfig, readUserConfig, ROLES } from "./config.js";
 import { validateContract } from "./contract.js";
 import { findRepository, herdrPreflight, runDoctor } from "./doctor.js";
 import { detectedChecks, issueBody } from "./github.js";
-import { createRoleRulesFiles, parseRoleSpec, proposal, serializeConfig, writeConfig } from "./init.js";
+import { createRoleRulesFiles, parseRoleSpec, proposal, serializeConfig, writeConfig, writeUserConfig } from "./init.js";
 import { loadLocale, shippedLanguages } from "./locale.js";
 import { allowRound, answer, installSkill, pause, resume, setAgent, steer } from "./steering.js";
 import { supervise } from "./supervisor.js";
@@ -22,8 +22,8 @@ Usage:
   gdt <command> [options]
 
 Commands:
-  init          Create .gdt/config.toml and install the operator skill
-  doctor        Check tools, GitHub authentication and .gdt/config.toml
+  init          Write roles to the user config and .gdt/config.toml; install the skill
+  doctor        Check tools, GitHub authentication and the configuration
   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
@@ -45,9 +45,9 @@ Options:
 `;
 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".
+Checks that git and gh are installed, gh is authenticated, and that the user
+config (roles), .gdt/config.toml (project settings) and .gdt/config.local.toml
+are valid. Exits with 1 when any finding has level "error".
 `;
 const INIT_HELP = `Usage: gdt init [--json]
        gdt init --developer <agent>/<model> --tester <agent>/<model> --reviewer <agent>/<model>
@@ -55,9 +55,12 @@ const INIT_HELP = `Usage: gdt init [--json]
                 [--required-check <name>]... [--allow-no-required-checks] [--force]
 
 Without the three role options, reports the supported agents, whether each is on
-PATH, the usable terminal, the detected CI checks and the language, and writes
-nothing. With them, writes .gdt/config.toml, runs "gdt doctor" and installs the
-operator skill.
+PATH, the usable terminal, the detected CI checks and the language. When the
+user config (see below) defines all three roles it writes .gdt/config.toml; with
+the three role options it writes the roles to the user config and the project
+settings to .gdt/config.toml, then runs "gdt doctor" and installs the operator
+skill. The user config is $XDG_CONFIG_HOME/gdt/config.toml, or
+$HOME/.config/gdt/config.toml when XDG_CONFIG_HOME is not set.
 
 Options:
   --developer <agent>/<model>    Agent and model for the developer role
@@ -238,27 +241,41 @@ function initCommand(args, io) {
         io.stderr(`${io.cwd} is not inside a Git repository. Run gdt from a checkout of the target repository.\n`);
         return EXIT_FAILED;
     }
+    const user = readUserConfig(io.env);
+    if (user.findings.length > 0) {
+        io.stderr(`${user.findings.map((finding) => finding.message).join("\n")}\n`);
+        return EXIT_FAILED;
+    }
     const specs = { developer, tester, reviewer };
     const given = ROLES.filter((role) => specs[role] !== undefined);
-    if (given.length === 0) {
+    // AC-6: without a user config that defines all three roles, `gdt init` only reports the proposal.
+    if (given.length === 0 && !ROLES.every((role) => user.roles[role] !== undefined)) {
         const facts = proposal(root, io.env);
         io.stdout(json ? `${JSON.stringify(facts, null, 2)}\n` : formatProposal(facts));
         return EXIT_OK;
     }
-    if (given.length < ROLES.length) {
-        const missing = ROLES.filter((role) => specs[role] === undefined)
-            .map((role) => `"--${role}"`)
-            .join(", ");
-        return usageError(io, `Missing ${missing} for "gdt init".`, "gdt init --help");
-    }
-    const roles = {};
-    for (const role of ROLES) {
-        const parsed = parseRoleSpec(specs[role] ?? "");
-        if ("error" in parsed) {
-            io.stderr(`${parsed.error}\n`);
+    let roles;
+    if (given.length > 0) {
+        if (given.length < ROLES.length) {
+            const missing = ROLES.filter((role) => specs[role] === undefined)
+                .map((role) => `"--${role}"`)
+                .join(", ");
+            return usageError(io, `Missing ${missing} for "gdt init".`, "gdt init --help");
+        }
+        roles = {};
+        for (const role of ROLES) {
+            const parsed = parseRoleSpec(specs[role] ?? "");
+            if ("error" in parsed) {
+                io.stderr(`${parsed.error}\n`);
+                return EXIT_FAILED;
+            }
+            roles[role] = parsed;
+        }
+        // AC-5: refuse before writing anything when the user config already defines a role.
+        if (!force && user.defined.length > 0) {
+            io.stderr(`The user config ${user.path} already defines roles (${user.defined.join(", ")}); use --force to replace them\n`);
             return EXIT_FAILED;
         }
-        roles[role] = parsed;
     }
     const languages = shippedLanguages();
     if (language !== undefined && !languages.includes(language)) {
@@ -275,8 +292,19 @@ function initCommand(args, io) {
         io.stderr("No required checks detected; pass --required-check <name> for each check, or --allow-no-required-checks to accept none\n");
         return EXIT_FAILED;
     }
+    // AC-5: write the roles to the user config; AC-6 leaves an existing user config untouched.
+    if (roles !== undefined) {
+        const userError = writeUserConfig(io.env, roles);
+        if (userError !== null) {
+            io.stderr(`${userError}\n`);
+            return EXIT_FAILED;
+        }
+        io.stdout(`roles: written to ${user.path}\n`);
+    }
+    else {
+        io.stdout(`roles: from ${user.path}\n`);
+    }
     const text = serializeConfig({
-        roles,
         language: language ?? DEFAULT_LANGUAGE,
         terminal: resolvedTerminal,
         requiredChecks: checks,

package/dist/config.js

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
 import { parse as parseToml, TomlError } from "smol-toml";
 import { z } from "zod";
+import { hasErrors } from "./finding.js";
 export const AGENTS = ["claude", "codex", "opencode", "mcode", "pi", "omp"];
 export const ROLES = ["developer", "tester", "reviewer"];
 export const TERMINALS = ["herdr", "headless"];
@@ -9,10 +11,27 @@ export const TERMINALS = ["herdr", "headless"];
 export const HERDR_LAYOUTS = ["split", "tabs"];
 export const CONFIG_PATH = ".gdt/config.toml";
 export const LOCAL_CONFIG_PATH = ".gdt/config.local.toml";
+/** The `gdt` directory under the XDG config home that holds the per-user config. */
+export const USER_CONFIG_DIR = "gdt";
 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";
+/** The OS home directory, or `env.HOME` when it names one (AC-1 of issue #51). */
+function homeDir(env) {
+    const home = env.HOME;
+    return home === undefined || home === "" ? homedir() : home;
+}
+/**
+ * The per-user config path. `$XDG_CONFIG_HOME/gdt/config.toml` when `XDG_CONFIG_HOME` is an
+ * absolute path, otherwise `$HOME/.config/gdt/config.toml`. A relative `XDG_CONFIG_HOME` is
+ * ignored, as the XDG base directory specification requires.
+ */
+export function userConfigPath(env) {
+    const xdg = env.XDG_CONFIG_HOME;
+    const base = xdg !== undefined && isAbsolute(xdg) ? xdg : join(homeDir(env), ".config");
+    return join(base, USER_CONFIG_DIR, "config.toml");
+}
 const roleSchema = z.strictObject({
     agent: z.enum(AGENTS),
     model: z.string().min(1),
@@ -35,7 +54,10 @@ 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 }),
+        // Roles live in the user config now; a role that is absent is reported separately (AC-4).
+        roles: z
+            .strictObject({ developer: role.optional(), tester: role.optional(), reviewer: role.optional() })
+            .optional(),
         workflow: z.strictObject({
             max_correction_rounds: z.int().min(0).default(2),
             // Deliberately without a default: an empty gate must be an explicit choice.
@@ -83,7 +105,7 @@ function valueAt(data, path) {
 function formatPath(path) {
     return path.map(String).join(".");
 }
-/** The layer that supplied the value at `path`, preferring the local override. */
+/** The layer that supplied the value at `path`, preferring the later layer. */
 function sourceOf(layers, path) {
     for (let i = layers.length - 1; i >= 0; i--) {
         const layer = layers[i];
@@ -92,6 +114,18 @@ function sourceOf(layers, path) {
     }
     return layers[0]?.path ?? CONFIG_PATH;
 }
+/** The config file that last set a key of `role`; a role is only layered in the user and local config. */
+function roleSource(layers, role, fallback) {
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (layer === undefined)
+            continue;
+        const table = valueAt(layer.data, ["roles", role]);
+        if (isTable(table) && Object.keys(table).length > 0)
+            return layer.path;
+    }
+    return fallback;
+}
 function describe(value) {
     return value === undefined ? "missing" : JSON.stringify(value);
 }
@@ -119,10 +153,11 @@ function issueFindings(issue, merged, layers) {
             return [error(`${key}: ${issue.message}`, `Correct ${key} in ${file}`)];
     }
 }
-function readLayer(root, path) {
-    const text = readFileSync(join(root, path), "utf8");
+/** Reads and parses one TOML file; `display` is the path used in findings. */
+function readLayer(fullPath, display, kind) {
+    const text = readFileSync(fullPath, "utf8");
     try {
-        return { path, data: parseToml(text) };
+        return { path: display, kind, data: parseToml(text) };
     }
     catch (err) {
         const where = err instanceof TomlError ? ` at line ${err.line}, column ${err.column}` : "";
@@ -130,15 +165,72 @@ function readLayer(root, path) {
         return {
             check: "config",
             level: "error",
-            message: `${path}: invalid TOML${where}: ${reason}`,
-            fix: `Fix the TOML syntax in ${path}`,
+            message: `${display}: invalid TOML${where}: ${reason}`,
+            fix: `Fix the TOML syntax in ${display}`,
         };
     }
 }
-/** Loads, merges and validates `.gdt/config.toml` and `.gdt/config.local.toml` in `root`. */
+/**
+ * Reads the user config for `gdt init`. It parses the file and reports which role tables it
+ * contains; it does not validate the repository config, because `gdt init` may run before that
+ * file exists (AC-6).
+ */
+export function readUserConfig(env) {
+    const path = userConfigPath(env);
+    if (!existsSync(path))
+        return { path, exists: false, roles: {}, defined: [], findings: [] };
+    const layer = readLayer(path, path, "user");
+    if (!("data" in layer))
+        return { path, exists: true, roles: {}, defined: [], findings: [layer] };
+    const roles = {};
+    const defined = [];
+    const raw = layer.data.roles;
+    if (isTable(raw)) {
+        for (const role of ROLES) {
+            const table = raw[role];
+            if (!isTable(table))
+                continue;
+            defined.push(role);
+            if (typeof table.agent === "string" && typeof table.model === "string") {
+                roles[role] = {
+                    agent: table.agent,
+                    model: table.model,
+                    ...(typeof table.script === "string" ? { script: table.script } : {}),
+                };
+            }
+        }
+    }
+    return { path, exists: true, roles, defined, findings: [] };
+}
+function roleMissingFinding(role, userPath) {
+    const init = "gdt init --developer <agent>/<model> --tester <agent>/<model> --reviewer <agent>/<model>";
+    return {
+        check: "config",
+        level: "error",
+        message: `roles.${role}: missing`,
+        fix: `Add roles.${role} to ${userPath} with "${init}"`,
+    };
+}
+/**
+ * Loads the user config, the repository config and the local config, merges them in that order
+ * (later layers win per key) and validates the result. Roles are read from the user config unless
+ * the local config overrides them; a `[roles.*]` table in the repository config is an error (AC-2).
+ */
 export function loadConfig(root, env = {}) {
-    const files = [CONFIG_PATH, LOCAL_CONFIG_PATH].filter((path) => existsSync(join(root, path)));
-    if (!files.includes(CONFIG_PATH)) {
+    const userPath = userConfigPath(env);
+    const repoPath = join(root, CONFIG_PATH);
+    const localPath = join(root, LOCAL_CONFIG_PATH);
+    const userExists = existsSync(userPath);
+    const repoExists = existsSync(repoPath);
+    const localExists = existsSync(localPath);
+    const files = [];
+    if (userExists)
+        files.push(userPath);
+    if (repoExists)
+        files.push(CONFIG_PATH);
+    if (localExists)
+        files.push(LOCAL_CONFIG_PATH);
+    if (!repoExists) {
         return {
             report: { valid: false, files },
             findings: [
@@ -146,15 +238,20 @@ export function loadConfig(root, env = {}) {
                     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`,
+                    fix: `Create ${CONFIG_PATH}; example: https://github.com/gevezex/gdt/blob/main/examples/config.toml`,
                 },
             ],
         };
     }
     const layers = [];
     const findings = [];
-    for (const path of files) {
-        const layer = readLayer(root, path);
+    const inputs = [[repoPath, CONFIG_PATH, "repo"]];
+    if (userExists)
+        inputs.unshift([userPath, userPath, "user"]);
+    if (localExists)
+        inputs.push([localPath, LOCAL_CONFIG_PATH, "local"]);
+    for (const [full, display, kind] of inputs) {
+        const layer = readLayer(full, display, kind);
         if ("data" in layer)
             layers.push(layer);
         else
@@ -162,28 +259,89 @@ export function loadConfig(root, env = {}) {
     }
     if (findings.length > 0)
         return { report: { valid: false, files }, findings };
-    const merged = layers.reduce((acc, layer) => merge(acc, layer.data), {});
+    const userLayer = layers.find((layer) => layer.kind === "user");
+    const repoLayer = layers.find((layer) => layer.kind === "repo");
+    // AC-3: the user config holds only roles.
+    if (userLayer !== undefined) {
+        for (const key of Object.keys(userLayer.data)) {
+            if (key === "roles")
+                continue;
+            findings.push({
+                check: "config",
+                level: "error",
+                message: `${key}: not allowed in ${userPath}`,
+                fix: `Move ${key} to ${CONFIG_PATH}`,
+            });
+        }
+    }
+    // AC-2: the repository config must not commit roles.
+    const repoRoles = repoLayer?.data.roles;
+    if (isTable(repoRoles)) {
+        for (const role of Object.keys(repoRoles)) {
+            findings.push({
+                check: "config",
+                level: "error",
+                message: `roles.${role}: not allowed in ${CONFIG_PATH}`,
+                fix: `Move roles.${role} to ${userPath} or ${LOCAL_CONFIG_PATH}`,
+            });
+        }
+    }
+    else if (repoRoles !== undefined) {
+        findings.push({
+            check: "config",
+            level: "error",
+            message: `roles: not allowed in ${CONFIG_PATH}`,
+            fix: `Move roles to ${userPath} or ${LOCAL_CONFIG_PATH}`,
+        });
+    }
+    // Roles come from the user config and the local config only; the repository config is excluded.
+    const roleData = layers
+        .filter((layer) => layer.kind !== "repo")
+        .reduce((acc, layer) => (isTable(layer.data.roles) ? merge(acc, layer.data.roles) : acc), {});
+    const merged = layers.reduce((acc, layer) => {
+        const copy = { ...layer.data };
+        delete copy.roles;
+        return merge(acc, copy);
+    }, {});
+    if (Object.keys(roleData).length > 0)
+        merged.roles = roleData;
     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)),
-        };
+        findings.push(...parsed.error.issues.flatMap((issue) => issueFindings(issue, merged, layers)));
+    }
+    // AC-4: every role the user and local configs do not define is an error pointing at the user config.
+    for (const role of ROLES) {
+        if (!isTable(valueAt(merged, ["roles", role])))
+            findings.push(roleMissingFinding(role, userPath));
     }
+    if (hasErrors(findings) || !parsed.success)
+        return { report: { valid: false, files }, findings };
     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 }];
-    }));
+    const resolved = {
+        developer: { ...config.roles?.developer, source: roleSource(layers, "developer", userPath) },
+        tester: { ...config.roles?.tester, source: roleSource(layers, "tester", userPath) },
+        reviewer: { ...config.roles?.reviewer, source: roleSource(layers, "reviewer", userPath) },
+    };
     findings.push({
         check: "config",
         level: "ok",
-        message: files.length > 1 ? `${CONFIG_PATH} is valid, with overrides from ${LOCAL_CONFIG_PATH}` : `${CONFIG_PATH} is valid`,
+        message: localExists && userExists
+            ? `${CONFIG_PATH} is valid, with roles from ${userPath} and overrides from ${LOCAL_CONFIG_PATH}`
+            : localExists
+                ? `${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 };
+    const report = {
+        valid: true,
+        files,
+        language: config.language,
+        workflow: config.workflow,
+        contract: config.contract,
+        roles: resolved,
+    };
+    return { report, findings };
 }
 /** Checks that pass the schema but would make gdt unsafe or surprising. */
 function semanticFindings(root, config) {

package/dist/doctor.js

@@ -2,7 +2,7 @@ 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 { CONFIG_PATH, LOCAL_CONFIG_PATH, loadConfig, ROLES, TEST_AGENT, userConfigPath } from "./config.js";
 import { hasErrors } from "./finding.js";
 const TOOLS = [
     { name: "git", fix: "Install Git: https://git-scm.com/downloads" },
@@ -159,7 +159,7 @@ function excludeFinding(root, git, env) {
  * (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) {
+export function unsupportedAgentFindings(roles, userConfig) {
     return ROLES.flatMap((role) => {
         const { agent } = roles[role];
         if (agent === TEST_AGENT || adapterFor(agent) !== undefined)
@@ -169,14 +169,14 @@ export function unsupportedAgentFindings(roles) {
                 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`,
+                fix: `Set roles.${role}.agent in ${userConfig} 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);
+    const findings = unsupportedAgentFindings(config.roles, userConfigPath(env));
     for (const role of ROLES) {
         const { agent } = config.roles[role];
         const adapter = adapterFor(agent);

package/dist/init.js

@@ -1,7 +1,7 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { adapterFor, supportedAgents } from "./agents/index.js";
-import { CONFIG_PATH, DEFAULT_LANGUAGE, ROLES } from "./config.js";
+import { CONFIG_PATH, DEFAULT_LANGUAGE, ROLES, userConfigPath } from "./config.js";
 import { herdrPreflight, which } from "./doctor.js";
 import { detectedChecks } from "./github.js";
 import { ROLE_RULES_DIR, roleRulesPath } from "./prompts.js";
@@ -40,15 +40,11 @@ export function parseRoleSpec(spec) {
         return { error: `Missing model in "${spec}"; use <agent>/<model>` };
     return { agent: agent, model };
 }
-/** The `.gdt/config.toml` text; a key that keeps its schema default is not written (AC-2). */
+/** The `.gdt/config.toml` text without roles; a key that keeps its schema default is not written. */
 export function serializeConfig(config) {
     const lines = [];
     if (config.language !== DEFAULT_LANGUAGE)
         lines.push(`language = ${JSON.stringify(config.language)}`, "");
-    for (const role of ROLES) {
-        const { agent, model } = config.roles[role];
-        lines.push(`[roles.${role}]`, `agent = ${JSON.stringify(agent)}`, `model = ${JSON.stringify(model)}`, "");
-    }
     lines.push("[workflow]", `required_checks = [${config.requiredChecks.map((name) => JSON.stringify(name)).join(", ")}]`);
     if (config.allowNoRequiredChecks)
         lines.push("allow_no_required_checks = true");
@@ -57,6 +53,225 @@ export function serializeConfig(config) {
     lines.push("");
     return lines.join("\n");
 }
+function roleTable(role, spec) {
+    return `[roles.${role}]\nagent = ${JSON.stringify(spec.agent)}\nmodel = ${JSON.stringify(spec.model)}\n`;
+}
+/** The user config text for `roles`, used when the file does not exist yet. */
+export function serializeUserConfig(roles) {
+    return ROLES.map((role) => roleTable(role, roles[role])).join("\n");
+}
+/** Strips the surrounding quotes of one TOML key segment. */
+function unquoteKey(segment) {
+    if (segment.length >= 2 && segment.startsWith('"') && segment.endsWith('"')) {
+        try {
+            const value = JSON.parse(segment);
+            if (typeof value === "string")
+                return value;
+        }
+        catch {
+            // Not JSON-compatible; fall back to a plain strip.
+        }
+        return segment.slice(1, -1);
+    }
+    if (segment.length >= 2 && segment.startsWith("'") && segment.endsWith("'"))
+        return segment.slice(1, -1);
+    return segment;
+}
+/** Splits a TOML dotted key into its segments, honoring quoted segments (e.g. `roles."a.b"`). */
+function keySegments(key) {
+    const segments = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < key.length; i += 1) {
+        const ch = key[i] ?? "";
+        if (quote === '"') {
+            current += ch;
+            if (ch === "\\") {
+                current += key[i + 1] ?? "";
+                i += 1;
+            }
+            else if (ch === '"')
+                quote = null;
+            continue;
+        }
+        if (quote === "'") {
+            current += ch;
+            if (ch === "'")
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ".") {
+            segments.push(unquoteKey(current.trim()));
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    segments.push(unquoteKey(current.trim()));
+    return segments;
+}
+const HEADER_RE = /^\s*\[\[?\s*(.*?)\s*\]\]?\s*(?:#.*)?$/;
+/** The dotted path of a `[table]` / `[[array]]` header, or null when the line is not a header. */
+function headerSegments(line) {
+    const match = HEADER_RE.exec(line);
+    return match === null ? null : keySegments(match[1] ?? "");
+}
+/** Splits `key = value` at the first `=` outside quoted key segments. */
+function splitAssignment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i] ?? "";
+        if (quote === '"') {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === '"')
+                quote = null;
+            continue;
+        }
+        if (quote === "'") {
+            if (ch === "'")
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "=")
+            return { key: line.slice(0, i), value: line.slice(i + 1) };
+    }
+    return null;
+}
+/** Tracks one TOML value across lines so multi-line values stay attached to their assignment. */
+class ValueScan {
+    depth = 0;
+    mode = "normal";
+    /** Feeds one line; returns true once the value is complete at the end of that line. */
+    feed(line) {
+        for (let i = 0; i < line.length; i += 1) {
+            const ch = line[i] ?? "";
+            switch (this.mode) {
+                case "normal":
+                    if (ch === "#")
+                        i = line.length;
+                    else if (ch === '"') {
+                        if (line.startsWith('"""', i)) {
+                            this.mode = "basic-multi";
+                            i += 2;
+                        }
+                        else
+                            this.mode = "basic";
+                    }
+                    else if (ch === "'") {
+                        if (line.startsWith("'''", i)) {
+                            this.mode = "literal-multi";
+                            i += 2;
+                        }
+                        else
+                            this.mode = "literal";
+                    }
+                    else if (ch === "[" || ch === "{")
+                        this.depth += 1;
+                    else if (ch === "]" || ch === "}")
+                        this.depth -= 1;
+                    break;
+                case "basic":
+                    if (ch === "\\")
+                        i += 1;
+                    else if (ch === '"')
+                        this.mode = "normal";
+                    break;
+                case "literal":
+                    if (ch === "'")
+                        this.mode = "normal";
+                    break;
+                case "basic-multi":
+                    if (line.startsWith('"""', i)) {
+                        this.mode = "normal";
+                        i += 2;
+                    }
+                    else if (ch === "\\")
+                        i += 1;
+                    break;
+                case "literal-multi":
+                    if (line.startsWith("'''", i)) {
+                        this.mode = "normal";
+                        i += 2;
+                    }
+                    break;
+            }
+        }
+        return this.mode === "normal" && this.depth === 0;
+    }
+}
+/**
+ * AC-5: replaces the `roles` key of `existing`, keeping every other line (comments, other keys and
+ * tables) byte-for-byte. Roles are removed whatever valid TOML form they were written in — role
+ * tables, a `[roles]` table with inline entries, a top-level inline `roles = { ... }`, or dotted
+ * keys — so a rewrite never leaves a duplicate definition behind. The new tables are appended.
+ */
+export function upsertRoles(existing, roles) {
+    const kept = [];
+    let table = null;
+    let pending = null;
+    for (const line of existing.split("\n")) {
+        if (pending !== null) {
+            const complete = pending.scan.feed(line);
+            if (!pending.drop)
+                kept.push(line);
+            if (complete)
+                pending = null;
+            continue;
+        }
+        const trimmed = line.trim();
+        const inRoleRegion = table !== null && table[0] === "roles";
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            if (!inRoleRegion)
+                kept.push(line);
+            continue;
+        }
+        const header = headerSegments(line);
+        if (header !== null) {
+            table = header;
+            if (header[0] !== "roles")
+                kept.push(line);
+            continue;
+        }
+        const assignment = splitAssignment(line);
+        if (assignment === null) {
+            if (!inRoleRegion)
+                kept.push(line);
+            continue;
+        }
+        const drop = inRoleRegion || (table === null && keySegments(assignment.key)[0] === "roles");
+        if (!drop)
+            kept.push(line);
+        const scan = new ValueScan();
+        if (!scan.feed(assignment.value))
+            pending = { scan, drop };
+    }
+    while (kept.length > 0 && (kept[kept.length - 1] ?? "").trim() === "")
+        kept.pop();
+    const prefix = kept.length > 0 ? `${kept.join("\n")}\n\n` : "";
+    const blocks = ROLES.map((role) => roleTable(role, roles[role]).trimEnd()).join("\n\n");
+    return `${prefix}${blocks}\n`;
+}
+/** Writes the roles to the user config, creating its directory; returns an error message or null. */
+export function writeUserConfig(env, roles) {
+    const path = userConfigPath(env);
+    try {
+        const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, existing === null ? serializeUserConfig(roles) : upsertRoles(existing, roles));
+        return null;
+    }
+    catch (err) {
+        return `Cannot write ${path}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
 /** Writes the config, creating `.gdt/` when needed; returns an error message, or null on success. */
 export function writeConfig(root, text) {
     try {

package/dist/workflow.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { relative } from "node:path";
 import { headless } from "./backends/headless.js";
 import { backendFor } from "./backends/index.js";
-import { loadConfig, ROLES } from "./config.js";
+import { loadConfig, ROLES, userConfigPath } from "./config.js";
 import { validateContract } from "./contract.js";
 import { findRepository, herdrPreflight, unsupportedAgentFindings } from "./doctor.js";
 import { changedFiles } from "./git.js";
@@ -55,10 +55,13 @@ 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);
+    const { report, findings } = loadConfig(root, env);
+    if (!report.valid) {
+        // AC-2: `gdt start` refuses with the same config errors as `gdt doctor`.
+        const errors = findings.filter((finding) => finding.level === "error").map((finding) => finding.message);
+        return fail(`${errors.join("\n")}\nRun "gdt doctor" for details.\n`);
+    }
+    const unsupported = unsupportedAgentFindings(report.roles, userConfigPath(env));
     if (unsupported.length > 0)
         return fail(`${unsupported.map((f) => f.message).join("\n")}\n`);
     if (report.workflow.terminal === "herdr") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gevezex/gdt",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.",
   "keywords": [
     "github",

package/skill/SKILL.md

@@ -5,13 +5,17 @@ gdt for them. They should never have to memorise a gdt command.
 
 ## First-time setup
 
-- With no `.gdt/config.toml`, run `gdt init --json`. It writes nothing and reports
-  the supported agents, which are on PATH, the terminal and the detected CI checks.
+- With no `.gdt/config.toml`, run `gdt init --json`. It reports the supported
+  agents, which are on PATH, the terminal and the detected CI checks.
 - Present that proposal to the user and ask which agent and model each role
   (developer, tester, reviewer) uses. Do not pick models for them.
 - Run `gdt init` with their choices, for example
   `gdt init --developer opencode/deepseek/deepseek-v4-flash --tester claude/claude-sonnet-5 --reviewer codex/gpt-5.6-luna`.
-  It writes the config, runs `gdt doctor` and installs this skill.
+  It writes the roles to the user config (`~/.config/gdt/config.toml`, or
+  `$XDG_CONFIG_HOME/gdt/config.toml`) and the project settings to
+  `.gdt/config.toml`, then runs `gdt doctor` and installs this skill.
+- When the user config already defines all three roles, `gdt init` without role
+  options reuses them and only writes `.gdt/config.toml`.
 
 ## Start