tix/

config.rs

//! `tix.toml` config schema, defaults, loading, saving and validation.
//!
//! Mirrors `contracts/tix-toml.md` and `data-model.md` §Config. The
//! [`Config`] type is the Serde surface for `tix.toml`; [`StateConfig`]
//! carries the legacy `[state].next_number` counter, which is tolerated on
//! load and never written back out (issue #52 — the issue number is
//! resolved at creation time by scanning the live issue set). Loading emits
//! a warning whenever a cleartext token is read from the file, and
//! [`Config::save`] never serializes tokens back to disk.

use std::collections::HashSet;
use std::path::{Path, PathBuf};

use indexmap::IndexMap;
use serde::{Deserialize, Serialize};

use crate::error::{Result, TixError};
use crate::keybindings::{EffectiveBindings, KeyBindings};

/// Remote tracker credentials/targets embedded in `tix.toml`.
///
/// `token` values are read-only: they are never serialized back out and are
/// never echoed in logs or errors. `base_url` may override the default
/// endpoint for self-hosted GitLab instances.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RemoteConfig {
    /// Optional cleartext token; prefer the `GITLAB_TOKEN`/`LINEAR_TOKEN`
    /// env vars. Never serialized back to disk.
    pub token: Option<String>,
    /// Optional base URL (e.g. self-hosted GitLab).
    pub base_url: Option<String>,
    /// GitLab project path (e.g. `acme/tix`) passed to `glab`.
    pub project: Option<String>,
    /// Linear team name passed to `linear-cli`.
    pub team: Option<String>,
}

/// The `[export]` section: per-target remote configuration.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ExportConfig {
    /// GitLab remote target.
    pub gitlab: Option<RemoteConfig>,
    /// Linear remote target.
    pub linear: Option<RemoteConfig>,
}

/// A named team (`[teams.<label>]` in `tix.toml`). The label lives as the
/// map key; `members` are free-form identities feeding the assignee/reviewer
/// pickers only (never constraining stored values, DM-01M311MRK517KRHR426QPNP6P7).
///
/// An absent/empty `[teams]` section means teams are disabled (today's
/// behavior), and an empty `[teams]` table is never written back out.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Team {
    /// Non-empty per team; unique within the team.
    pub members: Vec<String>,
}

/// A named cycle (`[cycles.<name>]` in `tix.toml`). The name lives as the
/// map key; `start_date`/`due_date` are optional `YYYY-MM-DD` strings with
/// `due_date >= start_date` when both are present.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct PlanningCycle {
    /// Optional human description.
    pub description: Option<String>,
    /// Optional start date (`YYYY-MM-DD`).
    pub start_date: Option<String>,
    /// Optional due date (`YYYY-MM-DD`); must be `>= start_date`.
    pub due_date: Option<String>,
}

/// The `[planning]` section: the monotonic auto-cycle counter plus the
/// picker presets written by `tix init` (`contracts/tix-toml-planning.md`).
///
/// `cycle_number` is the next auto "Cycle N" number: it starts at 1, is bumped
/// on every unnamed cycle create, and never decrements (FR-003,
/// DM-01M311BJKMN3PPCR9GR9Y7ESD2). Contrary to the legacy `[state]` counter,
/// this section **is** serialized once mutated.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct PlanningConfig {
    /// Monotonic next auto-cycle number; `>= 1`. Default `1`.
    pub cycle_number: u32,
    /// Optional picker preset naming a cycle.
    pub default_cycle: Option<String>,
    /// Optional picker preset naming a milestone.
    pub default_milestone: Option<String>,
    /// Optional picker preset naming a team.
    pub default_team: Option<String>,
}

impl PlanningConfig {
    /// Whether this section is untouched (all values at their defaults); such
    /// a section is not written to disk so legacy `tix.toml` files keep
    /// round-tripping byte-identically (NFR-003).
    pub fn is_default(&self) -> bool {
        self == &Self::default()
    }
}

impl Default for PlanningConfig {
    fn default() -> Self {
        Self {
            cycle_number: 1,
            default_cycle: None,
            default_milestone: None,
            default_team: None,
        }
    }
}

/// The `[state]` section — deprecated runtime bookkeeping that is still
/// tolerated on load for legacy `tix.toml` files but is never serialized.
///
/// The monotonic `next_number` counter this held was removed in issue #52:
/// issue numbers are now resolved at creation time by scanning the live
/// issue set, so [`Config::save`] writes no `[state]` section at all.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StateConfig {
    /// Legacy monotonic issue-number counter (C-007). Read-only — kept so
    /// old `tix.toml` files with `[state].next_number` still load, and
    /// never persisted once saved again.
    #[serde(skip_serializing)]
    pub next_number: u32,
}

/// Card ordering for the rendered board (`[kanban.<name>].order_by`).
///
/// Applied per column in the board builders; the store's underlying order is
/// untouched so the CLI keeps its own sequencing (board-display FR-02).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum OrderBy {
    /// Most recently created issues first (the default).
    #[default]
    #[serde(rename = "created_at_desc")]
    CreatedAtDesc,
    /// Oldest issues first.
    #[serde(rename = "created_at_asc")]
    CreatedAtAsc,
    /// Preserve the underlying store (filename/created-date ascending) order.
    #[serde(rename = "none")]
    None,
}

impl OrderBy {
    /// The TOML spelling of this variant.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::CreatedAtDesc => "created_at_desc",
            Self::CreatedAtAsc => "created_at_asc",
            Self::None => "none",
        }
    }

    /// The next variant when cycling the setting in the TUI settings modal.
    pub fn next(self) -> Self {
        match self {
            Self::CreatedAtDesc => Self::CreatedAtAsc,
            Self::CreatedAtAsc => Self::None,
            Self::None => Self::CreatedAtDesc,
        }
    }
}

/// The fixed, global category vocabulary (C-002, contract §1).
///
/// One list, referenced by the config validator, the per-board mapping and the
/// service WP02 builds. A vocabulary spelled out in three places is a vocabulary
/// that disagrees with itself the first time one of them changes.
///
/// `TERMINAL` is the subset that ends the workflow. `canceled` is terminal but
/// **not** complete — `COMPLETE` is deliberately a separate one-element list rather
/// than `!TERMINAL.contains(...)`, because "terminal" and "complete" are different
/// claims and the contract makes conflating them an escalation.
pub const CATEGORY_KEYS: &[&str] = &[
    "backlog",
    "unstarted",
    "active",
    "blocked",
    "completed",
    "canceled",
];

/// Categories that end the workflow.
pub const TERMINAL_CATEGORIES: &[&str] = &["completed", "canceled"];

/// The **only** category that means done. `canceled` is terminal without being
/// complete, so this is a one-element list and not "everything terminal".
pub const COMPLETE_CATEGORY: &str = "completed";

/// The documented safe default for a column with no mapping (contract §4).
///
/// Non-terminal and non-complete, so an unmapped column is never silently counted
/// as done. A default that resolved to `completed` would change completion
/// meaning by accident, which the contract makes an escalation rather than a
/// convenience — [`validate_categories`] refuses one.
pub const SAFE_DEFAULT_CATEGORY: &str = "unstarted";

/// `[categories]`: the global vocabulary and the safe default.
///
/// Omitted from disk when untouched, so a legacy `tix.toml` round-trips
/// byte-identically and gains no new keys (NFR-003, C-007).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CategoryConfig {
    /// The vocabulary, in the project's preferred order for presentation.
    ///
    /// Defaults to [`CATEGORY_KEYS`]. A configured list is still validated
    /// against that vocabulary: a board maps columns *into* the global
    /// vocabulary, it does not define its own (C-002), so adding a key here is
    /// an `unknown_category` error rather than a new category.
    pub order: Vec<String>,
    /// The category an unmapped column resolves to. Must be in `order`, and must
    /// not be [`COMPLETE_CATEGORY`].
    pub default: String,
}

impl Default for CategoryConfig {
    fn default() -> Self {
        Self {
            order: CATEGORY_KEYS.iter().map(|k| (*k).to_string()).collect(),
            default: SAFE_DEFAULT_CATEGORY.to_string(),
        }
    }
}

impl CategoryConfig {
    /// Whether this section is untouched, and so is not written to disk.
    pub fn is_default(&self) -> bool {
        self == &Self::default()
    }

    /// Whether `key` is in the configured vocabulary.
    pub fn contains(&self, key: &str) -> bool {
        self.order.iter().any(|k| k == key)
    }
}

/// `[transitions]`: the workflow policy.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TransitionConfig {
    /// Whether an issue in a terminal category refuses an ordinary move.
    ///
    /// Default `true`. "Ordinary" is load-bearing: the escape hatch WP02 settles is
    /// a *reasoned* transition out of a terminal category, not a silent
    /// reassignment, so this switch governs the second and not the first.
    pub terminal_locked: bool,
}

impl Default for TransitionConfig {
    fn default() -> Self {
        Self {
            terminal_locked: true,
        }
    }
}

impl TransitionConfig {
    pub fn is_default(&self) -> bool {
        self == &Self::default()
    }
}

/// A named board configuration (`[kanban.<name>]` in `tix.toml`).
///
/// Carries the ordered column list plus per-configuration metadata: the done
/// column, columns hidden from the rendered board, and whether the computed
/// "Mismatched" pseudo-column is shown (C-002 / DM-01M2MH4D84NHG0JVWEPR6ZH4VR).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct BoardConfiguration {
    /// Ordered, case-sensitive, non-empty, unique column names.
    pub columns: Vec<String>,
    /// The column treated as "done" (commit prompting). Defaults to `"done"`
    /// when that name is present in `columns`, else the last configured
    /// column (contracts/tix-toml.md field rules).
    ///
    /// **Its meaning is unchanged by this mission.** It remains the commit-prompt
    /// trigger and the legacy completion signal. WP02 reads the *category* for the
    /// completion decision; this field is not reinterpreted here, and a
    /// `category_map` does not change what it does.
    pub done_column: Option<String>,
    /// Column name → category key (contract §2). Omitted when empty, so a board
    /// without a mapping gains no key on save.
    ///
    /// A board with **no** map is a legacy board: its `done_column` resolves to
    /// `completed` and every other column to the safe default. See
    /// [`BoardConfiguration::category_for`], which is the single place that
    /// fallback lives — duplicating it in the service is how a board ends up with
    /// two notions of its own default.
    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
    pub category_map: IndexMap<String, String>,
    /// Columns hidden from the rendered board. Must be a subset of `columns`;
    /// their cards stay in board state and remain reachable via filters/search.
    pub hidden_columns: Vec<String>,
    /// Whether the computed "Mismatched" pseudo-column is rendered. Default
    /// `false`. Never a configured column.
    pub show_mismatch: bool,
    /// Whether long card titles wrap onto multiple lines. Default `true`.
    pub wrap_titles: bool,
    /// The maximum number of lines a wrapped card may occupy. Default `3`;
    /// validated `>= 1` in [`validate_board`]. Ignored when `wrap_titles`
    /// is `false`.
    pub title_lines: usize,
    /// Sparse manual card order persisted by drag-and-drop reordering. When
    /// non-empty, this order takes precedence over [`order_by`] for the cards
    /// whose positions differ from the automatic ordering.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub card_order: Vec<String>,
    /// Ordering of cards within each rendered column. Default
    /// `created_at_desc` (most recently created first).
    pub order_by: OrderBy,
}

impl Default for BoardConfiguration {
    fn default() -> Self {
        Self {
            columns: ["todo", "in progress", "in review", "done"]
                .into_iter()
                .map(String::from)
                .collect(),
            done_column: Some("done".to_string()),
            category_map: IndexMap::new(),
            hidden_columns: Vec::new(),
            show_mismatch: false,
            wrap_titles: true,
            title_lines: 3,
            card_order: Vec::new(),
            order_by: OrderBy::default(),
        }
    }
}

/// The board a **new repository** starts with (`tix init`), rather than the bare
/// [`BoardConfiguration::default`] a config-less or partial file falls back to.
///
/// It carries the two columns the triage inbox needs: `triage` (where unreviewed work
/// lands — `[triage].entry_status`) and `wontfix` (where a decline goes; it has to
/// exist, because `declined_status` must resolve to the `canceled` category).
///
/// **Only those two are mapped**, and that is deliberate. The map is what makes a
/// board `explicit_policy`, and an explicit policy brings *adjacency*: a category may
/// move to itself or forward through the declared order, never backwards. Mapping the
/// working columns would have to call them `unstarted` or `active`, and then
/// `in progress -> todo` — a move people make every day when a review finds a problem
/// — would be refused outright, with no `--reason` to override it. Leaving them
/// unmapped resolves them all to the same safe default, so movement among them stays
/// free while `done`/`wontfix` are terminal, which is the discipline a new repository
/// can *opt into* later (`tix lint` names the unmapped columns and how to map them).
pub fn starter_board() -> BoardConfiguration {
    BoardConfiguration {
        columns: [
            "triage",
            "todo",
            "in progress",
            "in review",
            "done",
            "wontfix",
        ]
        .into_iter()
        .map(String::from)
        .collect(),
        category_map: IndexMap::from([
            ("done".to_string(), "completed".to_string()),
            ("wontfix".to_string(), "canceled".to_string()),
        ]),
        ..BoardConfiguration::default()
    }
}

impl BoardConfiguration {
    /// The category `column` resolves to, given the global configuration.
    ///
    /// The single place the fallback lives, and the seam WP02's service builds
    /// on. Three cases, in order:
    ///
    /// 1. An explicit `category_map` entry wins.
    /// 2. Otherwise, on a board with **no** map at all, `done_column` is
    ///    `completed` and every other column is the safe default.
    /// 3. Otherwise (a map exists but omits this column), the safe default.
    ///
    /// Case 2 is a reconciliation, and the contract's two rules collide without
    /// it: *"a board without a `category_map` inherits `[categories].default` for
    /// every column"* (§2) plus *"no column maps to `completed` is a configuration
    /// error"* (§3) would reject every legacy `tix.toml`, while §2 also requires
    /// that one to load unchanged (C-007). `done_column` is the resolution: it is
    /// always a configured column, it already means "this column completes work",
    /// and using it keeps a legacy board's completion behaviour exactly what it
    /// was. A board that *does* declare a map gets no such help — a map that
    /// forgot `completed` is a real mistake and is reported as one.
    pub fn category_for<'c>(&'c self, column: &str, categories: &'c CategoryConfig) -> &'c str {
        if let Some(mapped) = self.category_map.get(column) {
            return mapped;
        }
        if self.category_map.is_empty() && self.effective_done_column() == Some(column) {
            return COMPLETE_CATEGORY;
        }
        &categories.default
    }

    /// The resolved done column: the explicit `done_column`, else `"done"`
    /// when present in `columns`, else the last configured column.
    pub fn effective_done_column(&self) -> Option<&str> {
        if let Some(done) = self.done_column.as_deref() {
            return Some(done);
        }
        if self.columns.iter().any(|c| c == "done") {
            Some("done")
        } else {
            self.columns.last().map(String::as_str)
        }
    }
}

/// The `[kanban]` section: named configurations in declaration order.
///
/// `#[serde(transparent)]` maps the TOML table `[kanban.<name>]` straight
/// onto the [`IndexMap`]. The `toml` parser sorts table keys, so
/// [`Config::load_with_warning`] re-orders the map from the source
/// document's `[kanban.<name>]` header order via
/// [`restore_declaration_order`] (D-02: declaration order = tab order,
/// validated by the round-trip test). The map is never empty after load —
/// [`Config::load_with_warning`] synthesizes the shipped `default`
/// configuration when `tix.toml` omits the section.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, transparent)]
pub struct KanbanSection {
    /// Named configurations, keyed by name, in declaration order.
    pub configurations: IndexMap<String, BoardConfiguration>,
}

/// The project configuration file (`tix.toml`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Config {
    /// Named board configurations (`[kanban]`). Always ≥1 after load.
    pub kanban: KanbanSection,
    /// Directory holding issue files, relative to the repo root.
    pub issues_dir: PathBuf,
    /// Directory holding milestone markdown files, relative to the repo
    /// root. `None` → the default `docs/milestones`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub milestones_dir: Option<PathBuf>,
    /// Named teams (`[teams.<label>]`), in declaration order.
    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
    pub teams: IndexMap<String, Team>,
    /// Named cycles (`[cycles.<name>]`), in declaration order.
    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
    pub cycles: IndexMap<String, PlanningCycle>,
    /// Planning presets and the auto-cycle counter (`[planning]`).
    #[serde(default, skip_serializing_if = "PlanningConfig::is_default")]
    pub planning: PlanningConfig,
    /// `[categories]`: the global vocabulary and safe default. Omitted when
    /// untouched, so a legacy file gains no key on save.
    #[serde(default, skip_serializing_if = "CategoryConfig::is_default")]
    pub categories: CategoryConfig,
    /// `[transitions]`: the workflow policy. Omitted when untouched.
    #[serde(default, skip_serializing_if = "TransitionConfig::is_default")]
    pub transitions: TransitionConfig,
    /// `[triage]`: the normal columns that make up the triage inbox.
    ///
    /// Mission `triage-inbox-review-flow-01M3C600`. The inbox is opt-in: `None` means
    /// no section, so no inbox, and every `tix triage` command refuses by naming the
    /// missing section. **`tix init` writes one**, with the board columns it needs, so
    /// a new repository starts with the inbox on; a legacy `tix.toml` gains no key on
    /// save. See [`crate::triage::config`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub triage: Option<crate::triage::TriageConfig>,
    /// Optional `$EDITOR` override for full-file editing.
    pub editor: Option<String>,
    /// Configured AI agent command (opencode, claude, etc.) launched with
    /// the issue body as its specification. Mirrors the `editor` resolution
    /// chain (explicit → `$TIX_AGENT` → `$AGENT` env → PATH fallback).
    pub agent: Option<String>,
    /// Persisted runtime state (`[state]`). Tolerated on load for legacy
    /// files, never written back to disk (issue #52).
    #[serde(skip_serializing)]
    pub state: StateConfig,
    /// External tracker targets (`[export]`).
    pub export: ExportConfig,
    /// Sparse TUI keybinding overrides (`[keybindings]`).
    #[serde(default, skip_serializing_if = "KeyBindings::is_empty")]
    pub keybindings: KeyBindings,
    /// Top-level frontmatter keys this project uses on purpose (`[custom_attributes]`).
    ///
    /// #1361. `tix` preserves a frontmatter key it does not recognise and warns
    /// about it, because an unrecognised key is usually a typo (`titel:`) and a
    /// typo that round-trips silently is worse than one that is dropped. A project
    /// that *does* use a custom key declares it here once and stops being warned.
    ///
    /// **Top-level names only**, not dotted paths — the thing being declared is a
    /// top-level key, and accepting a path syntax here would imply nested
    /// declarations are checked, which they are not.
    #[serde(default, skip_serializing_if = "CustomAttributes::is_empty")]
    pub custom_attributes: CustomAttributes,
}

/// The `[custom_attributes]` section: top-level frontmatter keys this project
/// carries on purpose (#1361).
///
/// A **section** rather than a bare top-level array so there is somewhere to put
/// the next option, and so the declaration reads as a named decision rather than as
/// one more anonymous list in a file that is mostly named sections.
///
/// ```toml
/// [custom_attributes]
/// keys = ["build_id", "reviewed_by"]
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CustomAttributes {
    /// Top-level frontmatter key names. Names only — no dotted paths; the thing
    /// being declared is a top-level key, and a path syntax here would imply nested
    /// declarations are checked when they are not.
    pub keys: Vec<String>,
}

impl CustomAttributes {
    /// Whether anything is declared, for `skip_serializing_if`.
    pub fn is_empty(&self) -> bool {
        self.keys.is_empty()
    }
}

impl Default for Config {
    fn default() -> Self {
        Config {
            kanban: KanbanSection {
                configurations: IndexMap::from([(
                    "default".to_string(),
                    BoardConfiguration::default(),
                )]),
            },
            issues_dir: PathBuf::from("docs/issues"),
            milestones_dir: None,
            teams: IndexMap::new(),
            cycles: IndexMap::new(),
            planning: PlanningConfig::default(),
            categories: CategoryConfig::default(),
            transitions: TransitionConfig::default(),
            // The bare default has no inbox, and that stays true: the mechanism is
            // opt-in, so a config with no `[triage]` section has no inbox and every
            // `tix triage` command refuses, naming the section. What changed is the
            // *starting point*: `tix init` writes the section (and the board columns it
            // needs), so a new repository begins with an inbox rather than with a
            // refusal. See [`crate::commands::init`].
            triage: None,
            editor: None,
            state: StateConfig::default(),
            export: ExportConfig::default(),
            agent: None,
            keybindings: KeyBindings::default(),
            custom_attributes: CustomAttributes::default(),
        }
    }
}

impl Config {
    /// The configuration a **new repository** starts with — what `tix init` writes.
    ///
    /// Deliberately not [`Default`]: that is the fallback for a missing or partial
    /// `tix.toml` (and the base hundreds of tests build fixtures on), and it stays
    /// minimal. The *starting point* is a product decision: a new repository gets the
    /// board [`starter_board`] lays out and a working `[triage]` section, so
    /// `tix triage list` works on a fresh checkout instead of refusing and asking for
    /// configuration first.
    ///
    /// The three keys match the board: unreviewed work sits in `triage`, an accept
    /// lands in `todo`, a decline in `wontfix`. `deferred_status` is left unset
    /// because it defaults to `entry_status`, and a default that is never written is a
    /// default that cannot drift from the meaning it stands for.
    #[must_use]
    pub fn starter() -> Config {
        let mut config = Config::default();
        config
            .kanban
            .configurations
            .insert("default".to_string(), starter_board());
        config.triage = Some(crate::triage::TriageConfig {
            entry_status: Some("triage".to_string()),
            accepted_status: Some("todo".to_string()),
            declined_status: Some("wontfix".to_string()),
            deferred_status: None,
        });
        config
    }

    /// Validate the invariant rules from `contracts/tix-toml.md`, returning
    /// the `Config` error variant with a human message. Errors name the
    /// offending configuration as `kanban.<name>.<field>` (NFR-003).
    pub(crate) fn validate(&self) -> Result<()> {
        if self.issues_dir.as_os_str().is_empty() {
            return Err(TixError::Config("`issues_dir` must not be blank".into()));
        }
        if self.milestones_dir().as_os_str().is_empty() {
            return Err(TixError::Config(
                "`milestones_dir` must not be blank".into(),
            ));
        }
        validate_planning(&self.planning)?;
        validate_categories(&self.categories)?;
        self.effective_keybindings()?;
        if self.kanban.configurations.is_empty() {
            return Err(TixError::Config(
                "`[kanban]` must define at least one configuration".into(),
            ));
        }
        for (name, board) in &self.kanban.configurations {
            validate_board(name, board)?;
            validate_category_map(name, board, &self.categories)?;
        }
        for (label, team) in &self.teams {
            validate_team(label, team)?;
        }
        for (name, cycle) in &self.cycles {
            validate_cycle(name, cycle)?;
        }
        // Last, deliberately. `[triage]` names columns from the active board
        // *and* from that board's `category_map`, so it can only be judged once
        // both are; running it earlier would hand `workflow::resolution` an
        // unvalidated vocabulary, which is the `unreachable!` it documents
        // (C-002).
        crate::triage::config::validate(self)?;
        Ok(())
    }

    /// Resolve sparse user overrides over the built-in TUI registry.
    pub fn effective_keybindings(&self) -> Result<EffectiveBindings> {
        KeyBindings::resolve(&self.keybindings)
    }

    /// Restore the canonical declaration order of named configurations,
    /// which the TOML parser loses (it sorts table keys). The order comes
    /// from `[kanban.<name>]` section headers in the source document.
    fn restore_declaration_order(&mut self, contents: &str) {
        crate::config::restore_section_order(&mut self.kanban.configurations, contents, "kanban");
        crate::config::restore_section_order(&mut self.cycles, contents, "cycles");
        crate::config::restore_section_order(&mut self.teams, contents, "teams");
    }

    /// Declared custom top-level frontmatter keys, lowercased for comparison.
    ///
    /// Lowercased because YAML keys are case-sensitive but nobody has ever
    /// intended `Titel` and `titel` to be different keys, and a suppression list
    /// that silently fails to match is worse than no list at all.
    pub fn custom_attributes(&self) -> Vec<String> {
        self.custom_attributes
            .keys
            .iter()
            .map(|k| k.trim().to_ascii_lowercase())
            .collect()
    }

    /// The resolved milestones directory: the configured value, or the
    /// contract default `docs/milestones` when unset.
    pub fn milestones_dir(&self) -> &Path {
        self.milestones_dir
            .as_deref()
            .unwrap_or(Path::new("docs/milestones"))
    }

    /// The configuration used by the CLI and other single-config surfaces:
    /// the one named `default` if present, else the first declared.
    pub fn default_config(&self) -> &BoardConfiguration {
        self.kanban
            .configurations
            .get("default")
            .or_else(|| self.kanban.configurations.first().map(|(_, board)| board))
            .expect("validate() guarantees at least one configuration")
    }

    /// Named configurations in declaration order (tab order = declaration
    /// order, D-02).
    pub fn configs(&self) -> impl Iterator<Item = (&str, &BoardConfiguration)> {
        self.kanban
            .configurations
            .iter()
            .map(|(name, board)| (name.as_str(), board))
    }

    /// Load a `tix.toml` at `path`, emitting a warning through `sink` for
    /// every cleartext token read from the file.
    ///
    /// Parse and validation failures surface as [`TixError::Config`] with
    /// the file's path and (where the TOML parser reports it) line.
    pub fn load_with_warning(path: &Path, mut sink: impl FnMut(&str)) -> Result<Config> {
        let contents = std::fs::read_to_string(path)
            .map_err(|e| TixError::Config(format!("{}: {e}", path.display())))?;
        let mut config: Config = toml::from_str(&contents)
            .map_err(|e| TixError::Config(format!("{}: {e}", path.display())))?;
        config.restore_declaration_order(&contents);
        if config.kanban.configurations.is_empty() {
            config.kanban = KanbanSection {
                configurations: IndexMap::from([(
                    "default".to_string(),
                    BoardConfiguration::default(),
                )]),
            };
        }
        config.validate().map_err(|e| match e {
            TixError::Config(msg) => TixError::Config(format!("{}: {msg}", path.display())),
            other => other,
        })?;
        for remote in [config.export.gitlab.as_ref(), config.export.linear.as_ref()]
            .into_iter()
            .flatten()
        {
            if remote.token.is_some() {
                sink(
                    "Warning: token found in tix.toml — prefer GITLAB_TOKEN / LINEAR_TOKEN env vars",
                );
            }
        }
        Ok(config)
    }

    /// Load the config for a project root: `tix.toml` at the root if
    /// present, otherwise the defaults. An absent file is *not* an error —
    /// the CLI layer decides whether to nag about `tix init`.
    pub fn load(project_root: &Path) -> Result<Config> {
        let path = project_root.join("tix.toml");
        if !path.is_file() {
            return Ok(Config::default());
        }
        Self::load_with_warning(&path, |w| eprintln!("{w}"))
    }

    /// Find the project root for `cwd` by walking upward for a `tix.toml`.
    /// Returns `None` when no ancestor (including `cwd` itself) holds one.
    pub fn project_root(cwd: &Path) -> Option<PathBuf> {
        let mut dir = Some(cwd.to_path_buf());
        while let Some(current) = dir {
            if current.join("tix.toml").is_file() {
                return Some(current);
            }
            dir = current.parent().map(Path::to_path_buf);
        }
        None
    }

    /// A copy of this config with every token stripped, for writing.
    fn sanitized_for_disk(&self) -> Config {
        let mut copy = self.clone();
        if let Some(gitlab) = copy.export.gitlab.as_mut() {
            gitlab.token = None;
        }
        if let Some(linear) = copy.export.linear.as_mut() {
            linear.token = None;
        }
        copy
    }

    /// Write `tix.toml` atomically (temp file + rename in the same
    /// directory, with an `fsync` before the rename — NFR-006).
    ///
    /// Tokens are never written to disk, so a round-trip `load` → `save`
    /// drops any cleartext token (expected: prefer env vars).
    pub fn save(&self, path: &Path) -> Result<()> {
        let dir = match path.parent() {
            Some(p) if !p.as_os_str().is_empty() => p.to_path_buf(),
            _ => PathBuf::from("."),
        };
        std::fs::create_dir_all(&dir)?;

        let disk = self.sanitized_for_disk();
        let contents = toml::to_string_pretty(&disk)
            .map_err(|e| TixError::Config(format!("cannot serialize tix.toml: {e}")))?;

        let file_name = path
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("tix.toml");
        let tmp = dir.join(format!("{file_name}.tmp-{}", std::process::id()));

        let write_result = (|| -> std::io::Result<()> {
            let mut f = std::fs::File::create(&tmp)?;
            use std::io::Write;
            f.write_all(contents.as_bytes())?;
            f.sync_all()?;
            Ok(())
        })();
        if let Err(e) = write_result {
            let _ = std::fs::remove_file(&tmp);
            return Err(TixError::Io(e));
        }

        if let Err(e) = std::fs::rename(&tmp, path) {
            let _ = std::fs::remove_file(&tmp);
            return Err(TixError::Io(e));
        }
        Ok(())
    }
}

/// Reorder a named-config `IndexMap` to the declaration order of its
/// `[<section>.<name>]` section headers in the source document (D-02:
/// declaration order = tab order). The `toml` crate sorts table keys on
/// deserialize, so the parser's order is not trustworthy; this returns to the
/// document's byte order. Applies to `[kanban.*]`, `[cycles.*]` and
/// `[teams.*]`. Names are unquoted when the header used a quoted key (e.g.
/// `[cycles."Cycle 1"]`).
fn restore_section_order<V: Clone>(map: &mut IndexMap<String, V>, contents: &str, section: &str) {
    let mut order: Vec<String> = Vec::new();
    for line in contents.lines() {
        let line = line.trim();
        if let Some(rest) = line.strip_prefix('[').and_then(|s| s.strip_suffix(']'))
            && let Some((head, key)) = rest.split_once('.')
            && head.trim() == section
            && !key.trim().contains('.')
            && let Some(name) = unquote_key(key.trim())
            && !order.iter().any(|n| n == name)
        {
            order.push(name.to_string());
        }
    }
    if order.is_empty() {
        return;
    }
    let mut ordered = IndexMap::new();
    for name in &order {
        if let Some(value) = map.shift_remove(name) {
            ordered.insert(name.clone(), value);
        }
    }
    ordered.extend(map.iter().map(|(n, v)| (n.clone(), (*v).clone())));
    *map = ordered;
}

/// Strip a single pair of surrounding single or double quotes from a TOML
/// table-header key, when present.
fn unquote_key(key: &str) -> Option<&str> {
    if let Some(inner) = key.strip_prefix('"').and_then(|k| k.strip_suffix('"')) {
        Some(inner)
    } else if let Some(inner) = key.strip_prefix('\'').and_then(|k| k.strip_suffix('\'')) {
        Some(inner)
    } else {
        Some(key)
    }
}

/// Validation for the `[planning]` section (NFR-003): the counter must be
/// positive once the section is present.
fn validate_planning(planning: &PlanningConfig) -> Result<()> {
    if planning.cycle_number == 0 {
        return Err(TixError::Config(
            "`planning.cycle_number` must be at least 1".into(),
        ));
    }
    Ok(())
}

/// Per-team validation (NFR-003): non-blank label, non-empty members, unique
/// member identities.
fn validate_team(label: &str, team: &Team) -> Result<()> {
    if label.trim().is_empty() {
        return Err(TixError::Config("`teams.<label>` must not be blank".into()));
    }
    if team.members.is_empty() {
        return Err(TixError::Config(format!(
            "`teams.{label}.members` must not be empty"
        )));
    }
    let mut seen: HashSet<&str> = HashSet::new();
    for member in &team.members {
        if !seen.insert(member.as_str()) {
            return Err(TixError::Config(format!(
                "`teams.{label}.members` must be unique; found duplicate `{member}`"
            )));
        }
    }
    Ok(())
}

/// Per-cycle validation (NFR-003): non-blank name, parseable dates, and
/// `due_date >= start_date` when both are present.
fn validate_cycle(name: &str, cycle: &PlanningCycle) -> Result<()> {
    if name.trim().is_empty() {
        return Err(TixError::Config("`cycles.<name>` must not be blank".into()));
    }
    if let Some(start) = &cycle.start_date {
        if !crate::model::validate_date(start) {
            return Err(TixError::Config(format!(
                "`cycles.{name}.start_date` (`{start}`) must be a `YYYY-MM-DD` calendar date"
            )));
        }
    }
    if let Some(due) = &cycle.due_date {
        if !crate::model::validate_date(due) {
            return Err(TixError::Config(format!(
                "`cycles.{name}.due_date` (`{due}`) must be a `YYYY-MM-DD` calendar date"
            )));
        }
        if let Some(start) = &cycle.start_date
            && due.as_str() < start.as_str()
        {
            return Err(TixError::Config(format!(
                "`cycles.{name}.due_date` (`{due}`) must be `>= start_date` (`{start}`)"
            )));
        }
    }
    Ok(())
}

/// Per-configuration validation (NFR-003): non-empty unique non-blank
/// columns, `done_column` ⊆ columns, `hidden_columns` ⊆ columns.
/// The `[categories]` section's own rules (contract §2, §4).
///
/// Both are refusals of a *default*, which is the escalation the contract names:
/// a default naming a category outside the vocabulary is a typo, and a default
/// that resolves to `completed` would silently mark every unmapped column done.
fn validate_categories(categories: &CategoryConfig) -> Result<()> {
    if categories.order.is_empty() {
        return Err(TixError::Config(
            "`categories.order` must not be empty — it is the global vocabulary".into(),
        ));
    }
    for key in &categories.order {
        if !CATEGORY_KEYS.contains(&key.as_str()) {
            return Err(TixError::Config(format!(
                "unknown_category: `categories.order` names `{key}`, which is not in the \
                 global vocabulary ({}). The vocabulary is fixed and global (C-002); a \
                 board maps columns into it and does not define it.",
                CATEGORY_KEYS.join(", ")
            )));
        }
    }
    if !categories.contains(&categories.default) {
        return Err(TixError::Config(format!(
            "unknown_category: `categories.default` is `{}`, which is not in \
             `categories.order`",
            categories.default
        )));
    }
    if categories.default == COMPLETE_CATEGORY {
        return Err(TixError::Config(format!(
            "`categories.default` may not be `{COMPLETE_CATEGORY}`. Every column \
             without an explicit mapping would resolve to complete, which changes \
             completion meaning by accident. Map the completing column explicitly \
             instead."
        )));
    }
    Ok(())
}

/// Per-board mapping validation (contract §3).
///
/// A board either has a completion category or is an explicit configuration
/// error; there is no silent "nothing completes". A *missing* mapping is never an
/// error — it resolves by the safe default — because erroring would reject every
/// existing custom configuration (NFR-003, C-007).
fn validate_category_map(
    name: &str,
    board: &BoardConfiguration,
    categories: &CategoryConfig,
) -> Result<()> {
    for (column, key) in &board.category_map {
        if !board.columns.iter().any(|c| c == column) {
            return Err(TixError::Config(format!(
                "mapping_for_unknown_column: `kanban.{name}.category_map` maps \
                 `{column}`, which is not one of the board's columns ({})",
                board.columns.join(", ")
            )));
        }
        if !categories.contains(key) {
            return Err(TixError::Config(format!(
                "unknown_category: `kanban.{name}.category_map` maps `{column}` to \
                 `{key}`, which is not in the vocabulary ({})",
                categories.order.join(", ")
            )));
        }
    }
    // Only a board that *declares* a map is held to naming a completion column. A
    // board with no map gets `done_column` -> `completed` in `category_for`, so
    // counting completions here would reject every legacy config.
    if board.category_map.is_empty() {
        return Ok(());
    }
    let completers: Vec<&String> = board
        .category_map
        .iter()
        .filter(|(_, key)| key.as_str() == COMPLETE_CATEGORY)
        .map(|(column, _)| column)
        .collect();
    match completers.as_slice() {
        [] => Err(TixError::Config(format!(
            "missing_completion_category: `kanban.{name}.category_map` maps no column \
             to `{COMPLETE_CATEGORY}` ({} mapped). Without one, no card on this board \
             is ever complete — map exactly one column to it.",
            board.category_map.len()
        ))),
        [_only] => Ok(()),
        many => Err(TixError::Config(format!(
            "`kanban.{name}.category_map` maps {} columns to `{COMPLETE_CATEGORY}` \
             ({}); exactly one column may complete work",
            many.len(),
            many.iter()
                .map(|c| c.as_str())
                .collect::<Vec<_>>()
                .join(", ")
        ))),
    }
}

fn validate_board(name: &str, board: &BoardConfiguration) -> Result<()> {
    if board.columns.is_empty() {
        return Err(TixError::Config(format!(
            "`kanban.{name}.columns` must not be empty"
        )));
    }
    if board.columns.iter().any(|c| c.trim().is_empty()) {
        return Err(TixError::Config(format!(
            "`kanban.{name}.columns` must not contain blank names"
        )));
    }
    let mut seen: HashSet<&str> = HashSet::new();
    for column in &board.columns {
        if !seen.insert(column.as_str()) {
            return Err(TixError::Config(format!(
                "`kanban.{name}.columns` must be unique; found duplicate `{column}`"
            )));
        }
    }
    if let Some(done) = &board.done_column
        && !board.columns.contains(done)
    {
        return Err(TixError::Config(format!(
            "`kanban.{name}.done_column` (`{done}`) must be one of the configured columns"
        )));
    }
    for hidden in &board.hidden_columns {
        if !board.columns.contains(hidden) {
            return Err(TixError::Config(format!(
                "`kanban.{name}.hidden_columns` (`{hidden}`) must be a subset of `columns`"
            )));
        }
    }
    if board.title_lines == 0 {
        return Err(TixError::Config(format!(
            "`kanban.{name}.title_lines` must be at least 1"
        )));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::PathBuf;
    use tempfile::TempDir;

    fn write_toml(dir: &Path, contents: &str) -> PathBuf {
        let path = dir.join("tix.toml");
        std::fs::write(&path, contents).unwrap();
        path
    }

    #[test]
    fn starter_config_carries_a_working_inbox() {
        let config = Config::starter();
        config
            .validate()
            .expect("the config `tix init` writes must load");

        let board = config.default_config();
        for column in [
            "triage",
            "todo",
            "in progress",
            "in review",
            "done",
            "wontfix",
        ] {
            assert!(
                board.columns.iter().any(|c| c == column),
                "the starter board is missing `{column}`: {:?}",
                board.columns
            );
        }

        let triage = config
            .triage
            .as_ref()
            .expect("the starter config has an inbox");
        assert_eq!(triage.entry_status.as_deref(), Some("triage"));
        assert_eq!(triage.accepted_status.as_deref(), Some("todo"));
        assert_eq!(triage.declined_status.as_deref(), Some("wontfix"));
        // Left unset: the default *is* the entry column, and a default that is never
        // written cannot drift from the meaning it stands for.
        assert_eq!(triage.effective_deferred_status(), Some("triage"));

        // The one mapping triage requires, plus the completion column.
        assert_eq!(
            board.category_map.get("wontfix").map(String::as_str),
            Some("canceled")
        );
        assert_eq!(
            board.category_map.get("done").map(String::as_str),
            Some("completed")
        );
        // The working columns stay **unmapped** on purpose: declaring a map makes the
        // board an explicit policy, and adjacency then refuses a *backwards* move with
        // no override to offer — `in progress -> todo` is a move people make daily.
        // Left out, they all resolve to the same safe default, so movement among them
        // stays free while `done`/`wontfix` remain terminal facts.
        for column in ["triage", "todo", "in progress", "in review"] {
            assert!(
                !board.category_map.contains_key(column),
                "`{column}` must stay unmapped, or adjacency will refuse work moving back"
            );
        }
    }

    #[test]
    fn defaults_match_contract() {
        let c = Config::default();
        let board = c.default_config();
        assert_eq!(board.columns, ["todo", "in progress", "in review", "done"]);
        assert_eq!(board.done_column.as_deref(), Some("done"));
        assert_eq!(board.hidden_columns, Vec::<String>::new());
        assert!(!board.show_mismatch);
        assert!(board.wrap_titles);
        assert_eq!(board.title_lines, 3);
        assert!(board.card_order.is_empty());
        assert_eq!(board.order_by, OrderBy::CreatedAtDesc);
        assert_eq!(c.issues_dir, PathBuf::from("docs/issues"));
        assert_eq!(c.editor, None);
        assert_eq!(c.state.next_number, 0);
        assert_eq!(c.export.gitlab, None);
        assert_eq!(c.export.linear, None);
    }

    #[test]
    fn load_returns_defaults_when_file_absent() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config::load(tmp.path()).unwrap();
        assert_eq!(cfg.state.next_number, 0);
        assert_eq!(cfg.default_config().columns.len(), 4);
    }

    #[test]
    fn load_synthesizes_default_config_when_kanban_section_missing() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "issues_dir = \"docs/issues\"\n");
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg.kanban.configurations.len(), 1);
        assert!(cfg.kanban.configurations.contains_key("default"));
        assert_eq!(cfg.default_config().columns.len(), 4);
    }

    #[test]
    fn load_parses_state_and_keeps_editor_and_remote_targets() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "tickets"
editor = "nvim"

[kanban.default]
columns = ["todo", "done"]
done_column = "done"

[state]
next_number = 17

[export.gitlab]
project = "acme/tix"
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| panic!("no token, no warning")).unwrap();
        assert_eq!(
            cfg.kanban.configurations.get("default").unwrap().columns,
            ["todo", "done"]
        );
        assert_eq!(cfg.issues_dir, PathBuf::from("tickets"));
        assert_eq!(cfg.editor.as_deref(), Some("nvim"));
        assert_eq!(cfg.state.next_number, 17);
        assert_eq!(
            cfg.export.gitlab.unwrap().project.as_deref(),
            Some("acme/tix")
        );
        assert_eq!(cfg.export.linear, None);
    }

    #[test]
    fn empty_columns_rejected_as_config_error() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[kanban.scratch]\ncolumns = []\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("kanban.scratch.columns"));
    }

    #[test]
    fn duplicate_columns_rejected_as_config_error() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"todo\"]\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("duplicate"));
    }

    #[test]
    fn blank_column_name_rejected() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \" \"]\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
    }

    #[test]
    fn done_column_must_be_in_columns() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"in progress\"]\ndone_column = \"in review\"\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("kanban.scratch.done_column"));
    }

    #[test]
    fn hidden_columns_must_be_subset_of_columns() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"done\"]\nhidden_columns = [\"nope\"]\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("kanban.scratch.hidden_columns"));
    }

    #[test]
    fn hidden_done_column_loads_fine() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"done\"]\ndone_column = \"done\"\nhidden_columns = [\"done\"]\n",
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let board = cfg.kanban.configurations.get("scratch").unwrap();
        assert_eq!(board.done_column.as_deref(), Some("done"));
        assert_eq!(board.hidden_columns, ["done"]);
    }

    #[test]
    fn legacy_top_level_keys_rejected() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "columns = [\"todo\", \"done\"]\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("tix.toml"));
        assert!(err.to_string().contains("columns"));
    }

    #[test]
    fn token_warning_fires_once_per_remote_with_token() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"[export.gitlab]
project = "a/b"
token = "gl-secret"

[export.linear]
team = "Eng"
token = "lin-secret"
"#,
        );
        let mut warnings: Vec<String> = Vec::new();
        let cfg = Config::load_with_warning(&path, |w| warnings.push(w.to_string())).unwrap();
        assert_eq!(warnings.len(), 2);
        assert!(warnings[0].contains("GITLAB_TOKEN"));
        assert!(warnings[1].contains("LINEAR_TOKEN"));
        // token values must never leak into the warning
        for w in &warnings {
            assert!(!w.contains("secret"));
        }
        assert_eq!(
            cfg.export.gitlab.unwrap().token.as_deref(),
            Some("gl-secret")
        );
    }

    #[test]
    fn no_token_means_no_warning() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "issues_dir = \"docs/issues\"\n");
        let mut fired = false;
        Config::load_with_warning(&path, |_| fired = true).unwrap();
        assert!(!fired);
    }

    #[test]
    fn save_never_writes_the_state_section() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        // Simulate a legacy load: `[state].next_number` is kept in memory
        // but must never be written back out (issue #52).
        let mut cfg = Config::default();
        cfg.state.next_number = 42;
        cfg.save(&path).unwrap();

        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(reloaded.state.next_number, 0, "state is never persisted");
        assert_eq!(
            reloaded.default_config().columns,
            cfg.default_config().columns
        );

        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert!(
            !on_disk.contains("next_number"),
            "next_number leaked into tix.toml:\n{on_disk}"
        );
        assert!(
            !on_disk.contains("[state]"),
            "state section written:\n{on_disk}"
        );
    }

    #[test]
    fn multi_config_roundtrip_preserves_declaration_order() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.release]
columns = ["planned", "in progress", "done"]
done_column = "done"
show_mismatch = true

[kanban.personal]
columns = ["todo", "done"]
done_column = "done"
hidden_columns = ["done"]
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let names: Vec<&str> = cfg.configs().map(|(n, _)| n).collect();
        assert_eq!(names, ["release", "personal"]);

        // default_config falls back to the first declared when no "default".
        assert_eq!(
            cfg.default_config().columns,
            ["planned", "in progress", "done"]
        );

        cfg.save(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(
            cfg, reloaded,
            "order and values survive save/load round trip"
        );
        let names2: Vec<&str> = reloaded.configs().map(|(n, _)| n).collect();
        assert_eq!(names2, ["release", "personal"]);
    }

    #[test]
    fn save_never_serializes_tokens_back_out() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        let mut cfg = Config::default();
        cfg.export.gitlab = Some(RemoteConfig {
            token: Some("secret".into()),
            project: Some("a/b".into()),
            ..RemoteConfig::default()
        });
        cfg.save(&path).unwrap();

        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert!(
            !on_disk.contains("secret"),
            "token leaked to disk:\n{on_disk}"
        );
        assert!(
            on_disk.contains("a/b"),
            "non-secret fields survive:\n{on_disk}"
        );

        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(reloaded.export.gitlab.unwrap().token, None);
    }

    #[test]
    fn save_is_atomic_and_leaves_no_temp_file() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        Config::default().save(&path).unwrap();
        let entries: Vec<_> = std::fs::read_dir(tmp.path())
            .unwrap()
            .filter_map(|e| e.ok())
            .collect();
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].file_name().to_string_lossy(), "tix.toml");
    }

    #[test]
    fn default_loadwrites_are_idempotent() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        let cfg = Config::default();
        cfg.save(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg, reloaded);
    }

    #[test]
    fn effective_done_column_falls_back_to_last() {
        let board = BoardConfiguration {
            columns: vec!["todo".into(), "later".into()],
            done_column: None,
            ..Default::default()
        };
        assert_eq!(board.effective_done_column(), Some("later"));

        let with_done = BoardConfiguration {
            columns: vec!["todo".into(), "done".into(), "later".into()],
            done_column: None,
            ..Default::default()
        };
        assert_eq!(with_done.effective_done_column(), Some("done"));
    }

    #[test]
    fn project_root_walks_up_the_tree() {
        let tmp = TempDir::new().unwrap();
        let nested = tmp.path().join("a").join("b");
        std::fs::create_dir_all(&nested).unwrap();
        std::fs::write(tmp.path().join("tix.toml"), "issues_dir = \"tix\"\n").unwrap();

        assert_eq!(
            Config::project_root(&nested),
            Some(tmp.path().to_path_buf())
        );
        assert_eq!(
            Config::project_root(tmp.path()),
            Some(tmp.path().to_path_buf())
        );
    }

    #[test]
    fn project_root_is_none_when_no_toml_exists() {
        let tmp = TempDir::new().unwrap();
        assert_eq!(Config::project_root(tmp.path()), None);
    }

    #[test]
    fn order_by_parses_all_names_and_defaults_to_desc() {
        let tmp = TempDir::new().unwrap();
        for name in ["created_at_desc", "created_at_asc", "none"] {
            let path = write_toml(
                tmp.path(),
                &format!(
                    "[kanban.x]\ncolumns = [\"todo\", \"done\"]\ndone_column = \"done\"\norder_by = \"{name}\"\n"
                ),
            );
            let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
            let board = cfg.kanban.configurations.get("x").unwrap();
            assert_eq!(board.order_by.as_str(), name);
        }
        assert_eq!(OrderBy::default(), OrderBy::CreatedAtDesc);
        assert_eq!(OrderBy::CreatedAtDesc.next(), OrderBy::CreatedAtAsc);
        assert_eq!(OrderBy::CreatedAtAsc.next(), OrderBy::None);
        assert_eq!(OrderBy::None.next(), OrderBy::CreatedAtDesc);
    }

    #[test]
    fn zero_title_lines_rejected_as_config_error() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"done\"]\ndone_column = \"done\"\ntitle_lines = 0\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(
            err.to_string().contains("kanban.scratch.title_lines"),
            "error names the offending field: {err}"
        );
    }

    #[test]
    fn unknown_order_by_rejected_as_config_error() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.scratch]\ncolumns = [\"todo\", \"done\"]\ndone_column = \"done\"\norder_by = \"bogus\"\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
    }

    #[test]
    fn board_without_display_keys_loads_default_display_settings() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[kanban.default]\ncolumns = [\"todo\", \"done\"]\n",
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let board = cfg.default_config();
        assert!(board.wrap_titles);
        assert_eq!(board.title_lines, 3);
        assert_eq!(board.order_by, OrderBy::CreatedAtDesc);
    }

    #[test]
    fn display_settings_roundtrip_through_save() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        let mut cfg = Config::default();
        {
            let board = cfg.kanban.configurations.get_mut("default").unwrap();
            board.wrap_titles = false;
            board.title_lines = 5;
            board.order_by = OrderBy::None;
        }
        cfg.save(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(
            reloaded, cfg,
            "display settings survive save/load round trip"
        );
        let on_disk = std::fs::read_to_string(&path).unwrap();
        for key in ["wrap_titles", "title_lines", "order_by"] {
            assert!(on_disk.contains(key), "missing `{key}` in:\n{on_disk}");
        }
    }

    #[test]
    fn manual_card_order_roundtrips_through_save() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("tix.toml");
        let mut cfg = Config::default();
        {
            let board = cfg.kanban.configurations.get_mut("default").unwrap();
            board.card_order = vec!["a.md".into(), "b.md".into()];
        }
        cfg.save(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(
            reloaded
                .kanban
                .configurations
                .get("default")
                .unwrap()
                .card_order,
            vec!["a.md".to_string(), "b.md".to_string()]
        );
        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert!(
            on_disk.contains("card_order"),
            "missing card_order in:\n{on_disk}"
        );
    }

    #[test]
    fn planning_defaults_match_contract() {
        let c = Config::default();
        assert_eq!(c.planning.cycle_number, 1);
        assert_eq!(c.planning.default_cycle, None);
        assert_eq!(c.planning.default_milestone, None);
        assert_eq!(c.planning.default_team, None);
        assert!(c.teams.is_empty());
        assert!(c.cycles.is_empty());
        assert_eq!(c.milestones_dir, None);
        assert_eq!(c.milestones_dir(), Path::new("docs/milestones"));
    }

    #[test]
    fn planning_sections_roundtrip_and_preserve_declaration_order() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"
milestones_dir = "docs/milestones"

[planning]
cycle_number = 1
default_cycle = "Cycle 1"
default_milestone = "Backlog"
default_team = "default"

[cycles."Cycle 1"]

[cycles."Cycle 2"]
start_date = "2026-09-21"
due_date = "2026-09-30"

[teams.default]
members = ["Herb Mason <herb@example.com>", "@alice"]

[teams.platform]
members = ["bob"]
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg.planning.cycle_number, 1);
        assert_eq!(cfg.planning.default_cycle.as_deref(), Some("Cycle 1"));
        assert_eq!(cfg.planning.default_milestone.as_deref(), Some("Backlog"));
        assert_eq!(cfg.planning.default_team.as_deref(), Some("default"));
        assert_eq!(cfg.milestones_dir(), Path::new("docs/milestones"));

        // Names are map keys; declaration order is restored from headers.
        let cycles: Vec<&str> = cfg.cycles.keys().map(String::as_str).collect();
        assert_eq!(cycles, ["Cycle 1", "Cycle 2"]);
        let cycle2 = cfg.cycles.get("Cycle 2").unwrap();
        assert_eq!(cycle2.start_date.as_deref(), Some("2026-09-21"));
        assert_eq!(cycle2.due_date.as_deref(), Some("2026-09-30"));
        assert_eq!(cycle2.description, None);

        let teams: Vec<&str> = cfg.teams.keys().map(String::as_str).collect();
        assert_eq!(teams, ["default", "platform"]);
        assert_eq!(
            cfg.teams.get("default").unwrap().members,
            ["Herb Mason <herb@example.com>", "@alice"]
        );

        // Save then reload: order + values survive the round trip (NFR-002).
        cfg.save(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg, reloaded);
        assert_eq!(
            reloaded
                .cycles
                .keys()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            ["Cycle 1", "Cycle 2"]
        );
        assert_eq!(
            reloaded
                .teams
                .keys()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            ["default", "platform"]
        );
    }

    // ---------------------------------------------------------------------
    // WP01 / T001-T005 — the category vocabulary and mapping
    // ---------------------------------------------------------------------

    const FULL_CATEGORIES: &str = r#"issues_dir = "docs/issues"

[categories]
order = ["backlog", "unstarted", "active", "blocked", "completed", "canceled"]
default = "unstarted"

[transitions]
terminal_locked = true

[kanban.default]
columns = ["triage", "wip", "review", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", wip = "active", review = "active", shipped = "completed" }

[export]
"#;

    #[test]
    fn category_sections_parse_and_default_sensibly() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), FULL_CATEGORIES);
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg.categories.order, CATEGORY_KEYS);
        assert_eq!(cfg.categories.default, "unstarted");
        assert!(cfg.transitions.terminal_locked);

        let board = cfg.default_config();
        assert_eq!(
            board.category_map.get("shipped").map(String::as_str),
            Some("completed")
        );
        assert_eq!(
            board.category_map.get("triage").map(String::as_str),
            Some("backlog")
        );
    }

    #[test]
    fn category_sections_default_when_absent() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "issues_dir = \"docs/issues\"\n");
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        // A config omitting `[categories]` still works, off the built-in
        // vocabulary — T001's "sensible defaults".
        assert_eq!(cfg.categories, CategoryConfig::default());
        assert_eq!(cfg.transitions, TransitionConfig::default());
        assert!(cfg.categories.is_default(), "and is not written back");
        assert!(cfg.transitions.is_default());
    }

    #[test]
    fn deny_unknown_fields_rejects_an_unknown_key_in_each_new_section() {
        let tmp = TempDir::new().unwrap();
        let bad_categories = write_toml(
            tmp.path(),
            "issues_dir = \"docs/issues\"\n\n[categories]\nnope = 1\n",
        );
        let err = Config::load_with_warning(&bad_categories, |_| {})
            .expect_err("an unknown key in [categories] must be refused");
        assert!(err.to_string().contains("unknown field"), "got: {err}");

        let tmp2 = TempDir::new().unwrap();
        let bad_transitions = write_toml(
            tmp2.path(),
            "issues_dir = \"docs/issues\"\n\n[transitions]\nnope = 1\n",
        );
        let err = Config::load_with_warning(&bad_transitions, |_| {})
            .expect_err("an unknown key in [transitions] must be refused");
        assert!(err.to_string().contains("unknown field"), "got: {err}");
    }

    #[test]
    fn a_configured_vocabulary_naming_an_unknown_key_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "issues_dir = \"docs/issues\"\n\n[categories]\norder = [\"backlog\", \"wontfix\"]\n",
        );
        let err = Config::load_with_warning(&path, |_| {})
            .expect_err("the vocabulary is global and fixed; a new key is not a default");
        assert!(err.to_string().contains("unknown_category"), "got: {err}");
    }

    /// The escalation the contract names: a default that resolves to `completed`
    /// would mark every unmapped column done.
    #[test]
    fn a_default_of_completed_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "issues_dir = \"docs/issues\"\n\n[categories]\ndefault = \"completed\"\n",
        );
        let err = Config::load_with_warning(&path, |_| {})
            .expect_err("a completion-changing default must be an escalation");
        let msg = err.to_string();
        assert!(msg.contains("may not be `completed`"), "got: {msg}");
    }

    #[test]
    fn a_default_outside_the_vocabulary_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "issues_dir = \"docs/issues\"\n\n[categories]\ndefault = \"wontfix\"\n",
        );
        let err = Config::load_with_warning(&path, |_| {}).expect_err("got: none");
        assert!(err.to_string().contains("unknown_category"), "got: {err}");
    }

    /// The contract's central invariant: a board either has a completion category
    /// or is an explicit configuration error. There is no silent "nothing
    /// completes".
    #[test]
    fn a_mapped_board_with_no_completion_column_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "wip", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", wip = "active" }
"#,
        );
        let err = Config::load_with_warning(&path, |_| {}).expect_err("got: none");
        assert!(
            err.to_string().contains("missing_completion_category"),
            "got: {err}"
        );
    }

    #[test]
    fn a_board_with_two_completion_columns_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["shipped", "cancelled"]
done_column = "shipped"
category_map = { shipped = "completed", cancelled = "completed" }
"#,
        );
        let err = Config::load_with_warning(&path, |_| {}).expect_err("got: none");
        let msg = err.to_string();
        assert!(
            msg.contains("exactly one column may complete"),
            "got: {msg}"
        );
    }

    #[test]
    fn a_mapping_for_a_column_the_board_does_not_configure_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", shipped = "completed", nope = "active" }
"#,
        );
        let err = Config::load_with_warning(&path, |_| {}).expect_err("got: none");
        assert!(
            err.to_string().contains("mapping_for_unknown_column"),
            "got: {err}"
        );
    }

    #[test]
    fn a_mapping_to_a_category_outside_the_vocabulary_is_refused() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "shipped"]
done_column = "shipped"
category_map = { triage = "wontfix", shipped = "completed" }
"#,
        );
        let err = Config::load_with_warning(&path, |_| {}).expect_err("got: none");
        assert!(err.to_string().contains("unknown_category"), "got: {err}");
    }

    /// T003 step 5, and the boundary that keeps NFR-003 satisfiable: a configured
    /// column with **no** mapping is valid. It resolves by the safe default, and
    /// erroring here would reject every existing custom configuration.
    #[test]
    fn an_unmapped_column_is_accepted_and_resolves_by_the_safe_default() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "wip", "shipped"]
done_column = "shipped"
category_map = { shipped = "completed" }
"#,
        );
        let cfg =
            Config::load_with_warning(&path, |_| {}).expect("an unmapped column is not an error");
        let board = cfg.default_config();
        assert_eq!(board.category_for("triage", &cfg.categories), "unstarted");
        assert_eq!(board.category_for("wip", &cfg.categories), "unstarted");
        assert_eq!(board.category_for("shipped", &cfg.categories), "completed");
    }

    /// The legacy reconciliation, and the reason `missing_completion_category`
    /// cannot fire for a board with no map. Without it, a board with no
    /// `category_map` would map nothing to `completed` and be rejected — which
    /// would reject every legacy `tix.toml` the contract requires to load
    /// unchanged.
    #[test]
    fn a_legacy_board_with_no_map_takes_done_column_as_completed() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["todo", "in progress", "in review", "done"]
done_column = "done"
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {})
            .expect("a legacy board must load, and it does");
        let board = cfg.default_config();
        assert!(board.category_map.is_empty());
        assert_eq!(board.category_for("done", &cfg.categories), "completed");
        assert_eq!(board.category_for("todo", &cfg.categories), "unstarted");
        assert_eq!(
            board.category_for("in review", &cfg.categories),
            "unstarted",
            "and nothing else is silently complete"
        );
    }

    /// NFR-003 / C-007: the strongest guard. A defaulted configuration must not
    /// materialize — otherwise a default that writes new keys is exactly the
    /// "silent change" the requirement forbids.
    #[test]
    fn a_defaulted_config_gains_no_new_keys_on_save() {
        let tmp = TempDir::new().unwrap();
        let legacy = r#"issues_dir = "docs/issues"

[kanban.default]
columns = [
    "todo",
    "in progress",
    "in review",
    "done",
]
done_column = "done"
hidden_columns = []
show_mismatch = false
wrap_titles = true
title_lines = 3
order_by = "created_at_desc"

[export]
"#;
        let path = write_toml(tmp.path(), legacy);
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        cfg.save(&path).unwrap();
        let after = std::fs::read_to_string(&path).unwrap();
        assert_eq!(
            after, legacy,
            "no `[categories]`, no `[transitions]`, no `category_map` may appear"
        );
    }

    /// A board mapping with **no** `[categories]` section loads on the built-in
    /// vocabulary, and saving it back does not materialize the section.
    #[test]
    fn a_board_mapping_without_a_categories_section_uses_the_built_in_vocabulary() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", shipped = "completed" }

[export]
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg.categories, CategoryConfig::default());
        cfg.save(&path).unwrap();
        let after = std::fs::read_to_string(&path).unwrap();
        assert!(
            !after.contains("[categories]"),
            "the section must stay unmaterialized: {after}"
        );
        assert!(
            after.contains("category_map"),
            "while the board's own mapping survives: {after}"
        );
    }

    /// What round-trips is the **values** and the `order` vector, not the raw
    /// bytes: `category_map` serializes as a `[kanban.<name>.category_map]`
    /// sub-table with its keys emitted in whatever order the TOML writer chooses,
    /// so the authored inline form
    /// `category_map = { triage = "backlog", ... }` is *not* what comes back.
    ///
    /// That is a contract/code mismatch, and the WP's rule is to fix the
    /// contract in the same change rather than let the two disagree — so the
    /// contract's example is corrected alongside this.
    ///
    /// The order that *does* matter, `[categories].order`, is a `Vec` and
    /// round-trips exactly. The mapping's key order has no semantic effect: it
    /// maps a column to a category, and the columns' presentation order comes
    /// from `columns`.
    #[test]
    fn a_full_category_config_round_trips_with_its_values_and_order() {
        let tmp = TempDir::new().unwrap();
        // A **non-default** vocabulary, so `[categories]` is written at all.
        // `FULL_CATEGORIES` spells out the built-in vocabulary verbatim, which
        // makes `CategoryConfig::is_default()` true and the section is then
        // *correctly* omitted on save — which is the property the other test
        // asserts. Using it here would have tested nothing about the round trip.
        let authored = r#"issues_dir = "docs/issues"

[categories]
order = ["backlog", "active", "completed", "canceled"]
default = "backlog"

[transitions]
terminal_locked = false

[kanban.default]
columns = ["triage", "wip", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", wip = "active", shipped = "completed" }

[export]
"#;
        let path = write_toml(tmp.path(), authored);
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        cfg.save(&path).unwrap();
        let after = std::fs::read_to_string(&path).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();

        assert_eq!(
            reloaded.categories, cfg.categories,
            "the vocabulary and its default survive"
        );
        assert_eq!(
            reloaded.categories.order,
            vec!["backlog", "active", "completed", "canceled"],
            "and `order` is a Vec, so the declared order is preserved exactly"
        );

        assert_eq!(
            reloaded.default_config().category_map,
            cfg.default_config().category_map,
            "the mapping's contents survive, in whatever order they are written"
        );
        // Both new sections are written, since neither is at its default.
        // Both new sections are written — and only because neither is at its
        // default. The first version of this fixture set `terminal_locked = true`,
        // which **is** the default, so `[transitions]` was correctly omitted and
        // the round trip had nothing to prove. Omitted-when-defaulted is the
        // NFR-003 trade this WP makes deliberately, so a fixture that pins the
        // default is a fixture that tests nothing.
        assert!(after.contains("[categories]"), "after: {after}");
        assert!(after.contains("[transitions]"), "after: {after}");
        assert!(
            !reloaded.transitions.terminal_locked,
            "and the value survives"
        );

        // **Save is idempotent.** The top-level section order is the serializer's
        // (struct field) order, not the authored order — the first version of this
        // assertion expected the authored order and failed on a correctly-saved
        // file. What actually has to hold is that a second save changes nothing,
        // which is the property a diff and a merge depend on. The authored order
        // that *is* load-bearing is preserved by the two assertions above.
        let reloaded_again = Config::load_with_warning(&path, |_| {}).unwrap();
        reloaded_again.save(&path).unwrap();
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            after,
            "a second save must be a no-op"
        );
    }

    /// Two boards with different column names, one mapped and one not — the
    /// intake's first acceptance scenario.
    #[test]
    fn two_boards_with_different_columns_map_to_the_same_categories() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.alpha]
columns = ["triage", "wip", "review", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", wip = "active", review = "active", shipped = "completed" }

[kanban.beta]
columns = ["new", "doing", "merged"]
done_column = "merged"

[export]
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let alpha = &cfg.kanban.configurations["alpha"];
        let beta = &cfg.kanban.configurations["beta"];
        // Different column names, same categories: `shipped` and `merged` both
        // complete, and both boards' working columns are `active`/`unstarted`.
        assert_eq!(alpha.category_for("shipped", &cfg.categories), "completed");
        assert_eq!(beta.category_for("merged", &cfg.categories), "completed");
        assert_eq!(alpha.category_for("wip", &cfg.categories), "active");
        assert_eq!(beta.category_for("doing", &cfg.categories), "unstarted");
        assert!(beta.category_map.is_empty());
    }

    /// The vocabulary's load-bearing distinction, asserted directly: `canceled` is
    /// terminal and **not** complete. Treating it as complete would change
    /// completion meaning, which the contract makes an escalation.
    #[test]
    fn canceled_is_terminal_but_not_complete() {
        assert!(TERMINAL_CATEGORIES.contains(&"canceled"));
        assert!(TERMINAL_CATEGORIES.contains(&"completed"));
        assert_eq!(
            COMPLETE_CATEGORY, "completed",
            "completion is defined by this category alone"
        );
        assert_ne!(COMPLETE_CATEGORY, "canceled");
        // And a board may map a column to `canceled` — the category exists and is
        // mappable, it simply is not the completing one.
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["triage", "dropped", "shipped"]
done_column = "shipped"
category_map = { triage = "backlog", dropped = "canceled", shipped = "completed" }
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let board = cfg.default_config();
        assert_eq!(board.category_for("dropped", &cfg.categories), "canceled");
        assert_ne!(
            board.category_for("dropped", &cfg.categories),
            COMPLETE_CATEGORY
        );
    }

    /// `blocked` as a category is a workflow column position, not the derived
    /// blocked state owned by issue 169's mission. Asserted as distinctness, since
    /// conflating them is a named rejected alternative.
    #[test]
    fn blocked_as_a_category_is_mappable_and_is_its_own_key() {
        assert!(CATEGORY_KEYS.contains(&"blocked"));
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            r#"issues_dir = "docs/issues"

[kanban.default]
columns = ["wip", "on hold", "shipped"]
done_column = "shipped"
category_map = { wip = "active", "on hold" = "blocked", shipped = "completed" }
"#,
        );
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        let board = cfg.default_config();
        assert_eq!(board.category_for("on hold", &cfg.categories), "blocked");
        // The derived blocked state lives in the relationship graph, not here.
        assert!(
            !cfg.default_config()
                .category_map
                .values()
                .any(|v| v.contains("state")),
            "a category is a position, never a derived state"
        );
    }

    #[test]
    fn legacy_file_roundtrips_byte_identical() {
        let tmp = TempDir::new().unwrap();
        // A pre-mission tix.toml in the canonical toml pretty form. The save
        // path must not add, drop, or reorder any pre-existing key (NFR-003):
        // maximum already-pretty formatting proves a true byte-stable save.
        let legacy = r#"issues_dir = "docs/issues"

[kanban.default]
columns = [
    "todo",
    "in progress",
    "in review",
    "done",
]
done_column = "done"
hidden_columns = []
show_mismatch = false
wrap_titles = true
title_lines = 3
order_by = "created_at_desc"

[export]
"#;
        let path = write_toml(tmp.path(), legacy);
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg.planning, PlanningConfig::default());
        assert!(cfg.teams.is_empty());
        assert!(cfg.cycles.is_empty());
        assert_eq!(cfg.milestones_dir, None);

        cfg.save(&path).unwrap();
        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert_eq!(
            on_disk, legacy,
            "legacy tix.toml must save byte-identical (NFR-003)"
        );
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(cfg, reloaded);
    }

    #[test]
    fn legacy_file_in_any_layout_never_gains_planning_keys() {
        let tmp = TempDir::new().unwrap();
        // Hand-written single-line arrays (typical of real repos) parse fine;
        // the pretty re-serializer may reformat them, but must never add a
        // planning/teams/cycles/milestones key.
        let legacy = r#"issues_dir = "docs/issues"
[kanban.default]
columns = ["todo", "in progress", "in review", "done"]
done_column = "done"
"#;
        let path = write_toml(tmp.path(), legacy);
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        cfg.save(&path).unwrap();
        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert!(!on_disk.contains("milestones_dir"));
        assert!(!on_disk.contains("[planning]"));
        assert!(!on_disk.contains("[teams]"));
        assert!(!on_disk.contains("[cycles"));
    }

    #[test]
    fn planning_default_section_with_partial_keys_loads() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[planning]\ndefault_cycle = \"Cycle 1\"\n");
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert_eq!(
            cfg.planning.cycle_number, 1,
            "counter defaults when omitted"
        );
        assert_eq!(cfg.planning.default_cycle.as_deref(), Some("Cycle 1"));
        assert_eq!(cfg.planning.default_milestone, None);
        assert_eq!(cfg.planning.default_team, None);
    }

    #[test]
    fn planning_rejects_unknown_keys() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[planning]\ncounter = 5\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("counter"));
    }

    #[test]
    fn planning_rejects_zero_cycle_number() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[planning]\ncycle_number = 0\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("cycle_number"));
    }

    #[test]
    fn cycle_dates_are_validated_and_compared() {
        let tmp = TempDir::new().unwrap();
        // parsing failure
        let bad = write_toml(tmp.path(), "[cycles.x]\nstart_date = \"2026-13-01\"\n");
        let err = Config::load_with_warning(&bad, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("start_date"));

        // ordering failure
        let ordered = write_toml(
            tmp.path(),
            "[cycles.x]\nstart_date = \"2026-09-30\"\ndue_date = \"2026-09-01\"\n",
        );
        let err = Config::load_with_warning(&ordered, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("due_date"));
        assert!(err.to_string().contains("start_date"));
    }

    #[test]
    fn cycles_reject_unknown_keys() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[cycles.X]\nbogus = 1\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("bogus"));
    }

    #[test]
    fn cycle_without_dates_loads_fine() {
        let tmp = TempDir::new().unwrap();
        let ok = write_toml(tmp.path(), "[cycles.Alpha]\ndescription = \"a\"\n");
        let cfg = Config::load_with_warning(&ok, |_| {}).unwrap();
        assert_eq!(
            cfg.cycles.get("Alpha").unwrap().description.as_deref(),
            Some("a")
        );
    }

    #[test]
    fn teams_validate_members_nonempty_and_unique() {
        let tmp = TempDir::new().unwrap();
        let empty = write_toml(tmp.path(), "[teams.dev]\nmembers = []\n");
        let err = Config::load_with_warning(&empty, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("members"));

        let dup = write_toml(
            tmp.path(),
            "[teams.dev]\nmembers = [\"alice\", \"alice\"]\n",
        );
        let err = Config::load_with_warning(&dup, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("unique"));
    }

    #[test]
    fn empty_teams_table_is_disabled_not_error() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "[teams]\n");
        let cfg = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(cfg.teams.is_empty());
        // An empty [teams] is never written back out.
        cfg.save(&path).unwrap();
        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert!(!on_disk.contains("[teams]"));
    }

    #[test]
    fn blank_milestones_dir_rejected() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "milestones_dir = \"\"\n");
        let err = Config::load_with_warning(&path, |_| {}).unwrap_err();
        assert!(matches!(err, TixError::Config(_)), "got {err:?}");
        assert!(err.to_string().contains("milestones_dir"));
    }

    #[test]
    fn sparse_keybindings_roundtrip_without_defaults() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(
            tmp.path(),
            "[keybindings.board]\nnew_issue = [\"ctrl+n\", \"f4\"]\n",
        );
        let config = Config::load_with_warning(&path, |_| {}).unwrap();
        config.save(&path).unwrap();
        let contents = std::fs::read_to_string(&path).unwrap();
        assert!(contents.contains("[keybindings.board]"));
        assert!(!contents.contains("move_left"));
        assert_eq!(Config::load_with_warning(&path, |_| {}).unwrap(), config);
    }

    #[test]
    fn omitted_keybindings_retain_effective_defaults() {
        let tmp = TempDir::new().unwrap();
        let path = write_toml(tmp.path(), "issues_dir = \"docs/issues\"\n");
        let config = Config::load_with_warning(&path, |_| {}).unwrap();
        let bindings = config.effective_keybindings().unwrap();
        assert_eq!(
            bindings.label(
                crate::keybindings::InputContext::Board,
                crate::keybindings::TuiAction::NewIssue
            ),
            "n"
        );
    }

    #[test]
    fn keybindings_reject_unknown_fields_and_empty_actions() {
        let tmp = TempDir::new().unwrap();
        let unknown = write_toml(tmp.path(), "[keybindings.board]\nbogus = [\"x\"]\n");
        assert!(
            Config::load_with_warning(&unknown, |_| {})
                .unwrap_err()
                .to_string()
                .contains("bogus")
        );
        let empty = write_toml(tmp.path(), "[keybindings.board]\nnew_issue = []\n");
        assert!(
            Config::load_with_warning(&empty, |_| {})
                .unwrap_err()
                .to_string()
                .contains("new_issue")
        );
    }
}