tix/

storage.rs

use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};

use crate::config::Config;
use crate::error::{Result, TixError, render_diagnostics};
use crate::hierarchy::{self, HierarchyIndex};
use crate::model::{HistoryEventKind, Issue, Status, TransitionDecision};
use crate::relationships::{
    CanonicalEdge, Diagnostic, IssueView, RelationKind, Relationship, RelationshipGraph,
};
use crate::slug::slugify;

pub struct Store {
    pub issues_dir: PathBuf,
    pub config: Config,
}

/// The outcome of one relationship mutation.
///
/// A typed relationship is a **single directed edge**, so a mutation normally
/// writes exactly one issue file — the one whose frontmatter owns the canonical
/// edge. `written` is `None` when the mutation was a no-op (an
/// already-present edge, or an absent edge on remove), which is what makes
/// "an idempotent re-apply appends no second History event" checkable.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RelationshipOutcome {
    /// The issue whose file was written, if any.
    pub written: Option<Issue>,
    /// The relationship the mutation concerned, in canonical form.
    pub relationship: Relationship,
    /// Whether a file was actually written.
    pub changed: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IssueSelector {
    Number(u32),
    Filename(String),
    Slug(String),
}

/// Result of `Store::add_asset`: the relative markdown link inserted into the
/// body and the actual written file name (collision-resolved).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AssetAdded {
    pub link: String,
    pub written_name: String,
}

// Disclosures raised by writes, drained by whichever surface is presenting.
//
// A disclosure is something the user must be told that is not an error: today
// that is only the removal of the retired `links:` key. It is queued rather than
// printed so every surface can render it in its own channel — stderr for the
// CLI, the MCP result payload for a tool call, the status line for the TUI.
//
// Thread-local rather than process-global: a CLI and an MCP request each drain
// their own, and a process-global queue made concurrent callers — and the test
// suite, which runs in parallel — see each other's disclosures.
thread_local! {
    static RETIRED_KEY_DISCLOSURES: std::cell::RefCell<Vec<String>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

/// Record that a write removed the retired `links:` key from `filename`.
/// `pub(crate)` so the surface drains in `app` and `mcp` can be tested against
/// a raised disclosure. Production code reaches it only through `Store::update`.
pub(crate) fn retired_key_disclosure(filename: &str) {
    RETIRED_KEY_DISCLOSURES.with(|queue| {
        queue.borrow_mut().push(format!(
            "remove `links:` by hand to silence \u{2014} {filename} (retired by \
             C-001; never read as typed data, no migration)"
        ));
    });
}

/// Take everything queued since the last drain.
pub fn take_disclosures() -> Vec<String> {
    RETIRED_KEY_DISCLOSURES.with(|queue| std::mem::take(&mut *queue.borrow_mut()))
}

/// The identity recorded as the `actor` of a History event.
///
/// Falls back to `unknown` rather than failing a mutation, so a repository with
/// no configured git identity can still record an audit trail.
///
/// Public because the blocked-move guard (WP04) records its own History event
/// outside the storage layer — the acknowledgement is a *policy* decision, not a
/// storage step. Duplicating the git-identity resolution in the command layer
/// would give the audit trail two definitions of "who acted", which is the kind
/// of drift an audit trail exists to prevent.
pub fn actor_identity() -> String {
    crate::assignee::git_identity()
        .map(|id| id.to_string())
        .unwrap_or_else(|| "unknown".to_string())
}

/// A request to move an issue to a column, through the seam.
///
/// WP03 T013. A struct rather than a positional list because the three arguments
/// are all `Option`-shaped and adjacent: `(Some(commit), None, None)` is a mistake
/// waiting to happen at a call site, and the field names are what stop it.
///
/// ## Deliberately absent
///
/// **No `actor`.** The seam records the identity itself through
/// [`actor_identity`], so a caller cannot attribute a decision to somebody else
/// and the audit trail keeps one definition of "who acted". Passing an actor in
/// would make the attribution a choice of the caller, which is exactly the thing
/// an audit trail must not be.
///
/// **No `updated`.** The seam bumps it, on exactly the transitions that change
/// something. A caller supplying it would be able to write a file whose date says
/// a no-op was an edit.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StatusChange<'a> {
    /// The column to move to. A column the board does not configure is refused
    /// with `unknown_column`; a same-column request is accepted and inert.
    pub column: &'a str,
    /// The commit to record when this move reaches the board's completion column.
    ///
    /// Ignored on a move that does not reach completion, and a previously recorded
    /// commit is cleared on a move that *leaves* it. `None` therefore means "record
    /// nothing", which is distinct from "leave the old value alone" — leaving an
    /// issue in its completion column with an unrelated commit is what the clear
    /// exists to prevent.
    pub commit: Option<&'a str>,
    /// Why a policy rule was being overridden, when one was.
    ///
    /// Without a reason the service refuses a transition out of a terminal
    /// category outright, so this is the only way out of `done`. The CLI flag that
    /// supplies it lands in WP04; the seam takes the parameter now so a
    /// half-built seam — one that can refuse but never accept-with-reason — is
    /// never what ships.
    pub override_reason: Option<&'a str>,
}

impl<'a> StatusChange<'a> {
    /// A plain move: no commit, no override.
    ///
    /// The common case, named so the call site reads as "move it" rather than as
    /// three `None`s.
    pub fn to(column: &'a str) -> Self {
        Self {
            column,
            commit: None,
            override_reason: None,
        }
    }

    /// This request with a commit, for a move that reaches completion.
    pub fn with_commit(mut self, commit: Option<&'a str>) -> Self {
        self.commit = commit;
        self
    }

    /// This request with an override reason, for a move out of a terminal
    /// category.
    pub fn with_override(mut self, reason: Option<&'a str>) -> Self {
        self.override_reason = reason;
        self
    }
}

/// What the seam did (`WP03` T013).
///
/// `written` and `decision` are deliberately redundant. Either alone would do:
/// `written == false` implies `decision.is_none()`, and a decision always implies
/// a write. They are both here because the two questions a caller asks are
/// different — "did anything happen?" and "what gets appended?" — and reading the
/// answer to one off the other is the kind of inference that breaks silently when a
/// fourth outcome is added later.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StatusOutcome {
    /// The issue as it now stands in the store: the accepted column, the bumped
    /// `updated`, and the appended decision. On an inert no-op this is the issue
    /// exactly as it was.
    pub issue: Issue,
    /// The decision appended to the issue's History, or `None` when nothing was
    /// written.
    pub decision: Option<TransitionDecision>,
    /// Whether the file was written at all.
    ///
    /// `false` for a same-column re-apply and for any path that carries no change.
    /// A refusal is not represented here — it is an `Err`, so "refused" and
    /// "accepted but did nothing" are different types rather than one `Outcome`
    /// with a flag.
    pub written: bool,
}

/// The accepted half of [`crate::workflow::TransitionOutcome`], unpacked.
///
/// WP03. A private struct so the seam's body reads as ordinary code, and so the
/// only way to reach the write is to have destructured the service's `Accepted`
/// variant. The alternative — matching on the enum at each use — is how a future
/// edit ends up handling a new outcome variant once in this function and not at
/// all in the next one.
struct TransitionAccepted {
    changed: bool,
    from: String,
    to: String,
    from_category: crate::workflow::WorkflowCategory,
    to_category: crate::workflow::WorkflowCategory,
    override_reason: Option<String>,
}

impl TransitionAccepted {
    /// The accepted transition, or the diagnostic that refused it.
    fn try_from(
        outcome: crate::workflow::TransitionOutcome,
    ) -> std::result::Result<Self, crate::workflow::WorkflowDiagnostic> {
        match outcome {
            crate::workflow::TransitionOutcome::Accepted {
                changed,
                from,
                to,
                from_category,
                to_category,
                override_reason,
            } => Ok(Self {
                changed,
                from,
                to,
                from_category,
                to_category,
                override_reason,
            }),
            crate::workflow::TransitionOutcome::Rejected(diagnostic) => Err(diagnostic),
        }
    }
}

/// A [`Relationship`] standing for a canonical edge that has no stored row.
///
/// Deliberately local to the storage layer rather than a method on
/// `CanonicalEdge`: the service's surface is owned by WP01 and is not widened
/// from here. The id and display are empty because no row exists to carry them
/// — this value only reports *which* edge a no-op concerned.
fn canonical_placeholder(canonical: &CanonicalEdge) -> Relationship {
    Relationship {
        id: String::new(),
        from: canonical.from,
        to: canonical.to,
        kind: canonical.kind,
        display: String::new(),
    }
}

/// Turn a blocking validation result into the crate error surface.
///
/// The first diagnostic's message is preserved verbatim so the user sees the
/// field-aware text the service produced, prefixed with its diagnostic name
/// (C-004). A blocking result means **no** file was written (SC-005), so this
/// is raised before any mutation.
fn relationship_error(errors: &[Diagnostic]) -> TixError {
    if errors.is_empty() {
        return TixError::InvalidInput("relationship rejected".into());
    }
    TixError::InvalidInput(render_diagnostics(
        errors.iter().map(|d| (d.kind.as_str(), d.message.as_str())),
    ))
}

/// A durable, exclusive claim on one issue number.
///
/// ## Why this exists (#1352, part 2)
///
/// [`Store::resolve_next_number`] reads the directory, takes `max(number)`, and adds
/// one. That is a **hint**, not an allocation: nothing serialises read-then-write
/// across processes, so two `tix create` runs that reach it together both get the
/// same answer and both write an issue with that number.
///
/// Measured with 24 concurrent `tix create` subprocesses with distinct titles:
///
/// ```text
/// files: 24   distinct numbers: 8
///   5 × number: 7    4 × number: 4    4 × number: 6    3 × number: 3
///   3 × number: 5    2 × number: 0    2 × number: 1    1 × number: 2
/// ```
///
/// 16 of 24 issues shared a number with another file. After that every
/// number-addressed operation — `tix view 0`, `tix move 0`, `tix edit 0`,
/// `tix link 0 X`, `tix delete 0` — silently addresses an arbitrary one of several
/// issues, which is arguably worse than the clobber it accompanies.
///
/// It needs **two** processes (an agent's `tix mcp` plus a human's `tix`), which is
/// why it is rarer and why spacing the calls out appears to fix it. There is no
/// intra-process race: `src/mcp/mod.rs` handles one message to completion before
/// reading the next, the TUI is a single event loop, and `Store` is `&self`.
///
/// ## Why a claim ledger and not a lockfile
///
/// The obvious fix is a lock file held across resolve-and-write, and it was rejected
/// because **a lock can be lost**: a process that crashes while holding it leaves the
/// next create to break the lock on a timeout, and breaking a lock on a timeout also
/// breaks it for a process that is merely slow. Every lock-staleness heuristic trades
/// mutual exclusion for liveness, and this is the one property that must not be
/// traded.
///
/// A claim ledger cannot lose mutual exclusion. The claim is a zero-byte file created
/// with `O_EXCL`, and a process that dies holding one leaves an **orphan claim** —
/// an allocated-but-unused number, never a lost lock. A burned number is a gap, and
/// this system already produces gaps deliberately: reusing a number requires deleting
/// every higher-numbered issue first, and deleting an issue leaves its number free.
/// So the failure mode of the fix matches the existing, documented behaviour of the
/// allocator rather than introducing a new one.
///
/// The cost is one hidden marker file per created issue. That is real, and it is the
/// price of not needing a lease timeout. The markers live **beside** the issues
/// directory rather than inside it, so nothing that reads `docs/issues/` — a glob, a
/// script, a test counting segments — ever sees them; see [`claims_dir`].
struct NumberClaim {
    path: PathBuf,
    /// Whether this claim must be released on drop. `false` once the issue file
    /// exists, at which point the file — not the marker — is the authority for the
    /// number.
    armed: bool,
}

impl NumberClaim {
    /// The directory holding one marker per claimed number.
    const DIR: &'static str = ".tix-numbers";

    /// Claim `start`, or the next free number at or above it.
    ///
    /// `start` comes from [`Store::resolve_next_number`] and is already past every
    /// number any issue file claims, so the first candidate is normally free and the
    /// loop runs once. The loop exists for the concurrent case, and the climb is
    /// bounded so a corrupt ledger produces an error rather than an unbounded scan.
    fn acquire(issues_dir: &Path, start: u32) -> Result<Self> {
        const MAX_ATTEMPTS: u32 = 10_000;
        let dir = claims_dir(issues_dir);
        std::fs::create_dir_all(&dir)?;
        let mut number = start;
        for _ in 0..MAX_ATTEMPTS {
            let path = dir.join(format!("{number}.claim"));
            match std::fs::OpenOptions::new()
                .write(true)
                .create_new(true)
                .open(&path)
            {
                Ok(_) => {
                    return Ok(Self { path, armed: true });
                }
                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                    number += 1;
                }
                Err(e) => return Err(TixError::Io(e)),
            }
        }
        Err(TixError::Io(std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            format!(
                "no free issue number at or above {start} after {MAX_ATTEMPTS} attempts; \
                 {} is probably corrupt",
                dir.display()
            ),
        )))
    }

    /// The number this claim holds.
    fn number(&self) -> Option<u32> {
        self.path.file_stem()?.to_str()?.parse::<u32>().ok()
    }

    /// Free a number that is no longer in use.
    ///
    /// Called by [`Store::delete`], so the ledger does not permanently reserve the
    /// number of a deleted issue. Best-effort: if the ledger directory is missing or
    /// the removal fails, the create path simply climbs past the stale claim — which
    /// costs a number but never hands the same number to two issues.
    fn release_number(issues_dir: &Path, number: u32) {
        let _ = std::fs::remove_file(claims_dir(issues_dir).join(format!("{number}.claim")));
    }

    /// Give the number back, so a create that failed after claiming it does not burn
    /// one. Idempotent, and a no-op for an already-committed claim.
    fn release(&mut self) {
        if self.armed {
            let _ = std::fs::remove_file(&self.path);
            self.armed = false;
        }
    }

    /// Keep the claim permanently, because the issue file for it now exists.
    ///
    /// Without this, `Drop` would release the marker and the whole mechanism would
    /// be a no-op — which is exactly what happened the first time this was written.
    /// The `Drop` backstop below is for frames that *never reach* a commit, so it
    /// must be disarmed deliberately on the success path rather than left to run
    /// unconditionally.
    fn commit(&mut self) {
        self.armed = false;
    }
}

impl Drop for NumberClaim {
    /// A claim still armed when the `Store::create` frame unwinds — a `write`
    /// error, or a panic — is released, so a failed create does not leak a number.
    /// The `is_err` branch in `create` releases on the ordinary path; this is the
    /// backstop for the paths that never reach it.
    fn drop(&mut self) {
        self.release();
    }
}

impl std::fmt::Debug for NumberClaim {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("NumberClaim")
            .field("path", &self.path)
            .field("armed", &self.armed)
            .finish()
    }
}

impl PartialEq for NumberClaim {
    fn eq(&self, other: &Self) -> bool {
        self.path == other.path
    }
}
impl Eq for NumberClaim {}

/// The outcome of a hierarchy write, mirroring [`RelationshipOutcome`] so a
/// surface handles both with the same shape.
#[derive(Debug, Clone)]
pub struct ParentOutcome {
    /// The child as written, or `None` when the mutation was a no-op.
    ///
    /// `None` for a no-op, matching [`RelationshipOutcome`]: a retried command must
    /// not pad the audit trail, and a `changed: true` that wrote nothing is a lie.
    /// A caller that needs the current state reads [`Self::parent`], which is
    /// reported either way — the same split `RelationshipOutcome` uses for
    /// `relationship`.
    pub written: Option<Issue>,
    /// The child's parent after the call.
    pub parent: Option<u32>,
    /// The event appended to `## History`, or `None` for a no-op.
    ///
    /// `None` for a no-op is the point: a retried command must not pad the
    /// audit trail, and a `changed: true` that wrote nothing is a lie.
    pub event: Option<crate::hierarchy::ParentEvent>,
    /// Whether anything was written.
    pub changed: bool,
}

impl Store {
    pub fn open(config: &Config) -> Result<Store> {
        let issues_dir = &config.issues_dir;
        if !issues_dir.exists() {
            std::fs::create_dir_all(issues_dir)?;
        }
        Ok(Store {
            issues_dir: issues_dir.clone(),
            config: config.clone(),
        })
    }

    /// The **active** issue set: every issue file that is not archived.
    ///
    /// Archived issues are marked by a dot-prefixed markdown filename
    /// (`docs/issues/<assignee>/.<file>.md`, issue #1492). They are skipped
    /// **from the directory entry**, before the file is opened, so the default
    /// path never parses an archived issue — the performance requirement that
    /// keeps a repository with thousands of archived issues fast.
    ///
    /// Use [`Store::list_all`] when an archived issue must still be reachable.
    pub fn list(&self) -> Result<Vec<Issue>> {
        self.scan(false)
    }

    /// The **exhaustive** issue set: active issues plus archived ones.
    ///
    /// Archived issues carry `archived == true`, derived from the leading dot
    /// of their filename. This is the enumeration for selector resolution and
    /// number allocation, both of which must see an archived issue; it is
    /// deliberately *not* the default view.
    pub fn list_all(&self) -> Result<Vec<Issue>> {
        self.scan(true)
    }

    /// Walk the issues tree.
    ///
    /// `include_archived == false` is the default path: a dot-prefixed `.md`
    /// entry is dropped from the directory entry so the file is never read.
    /// `true` reads them too and marks them with `archived = true`.
    ///
    /// The read+parse of every file is the expense of a cold start, so it is
    /// fanned across threads above [`Store::PARALLEL_SCAN_THRESHOLD`] (see
    /// [`Store::parse_issue_files`]); the directory walk itself stays serial.
    fn scan(&self, include_archived: bool) -> Result<Vec<Issue>> {
        if !self.issues_dir.exists() {
            return Ok(Vec::new());
        }
        let mut files: Vec<(PathBuf, String, bool)> = Vec::new();
        Self::collect_issue_files(&self.issues_dir, "", include_archived, &mut files)?;
        // Deterministic order for both the result and any parse error: the walk
        // itself is `read_dir`-ordered, which differs between filesystems.
        files.sort_by(|a, b| a.1.cmp(&b.1));
        let mut issues = Self::parse_issue_files(&files)?;
        issues.sort_by(|a, b| a.filename.cmp(&b.filename));
        Ok(issues)
    }

    /// File counts at or above this fan the scan's read+parse across threads.
    /// Below it a serial loop is faster than the thread setup, so a small
    /// repository keeps the boring path.
    const PARALLEL_SCAN_THRESHOLD: usize = 256;
    /// Upper bound on scan threads. The work is read- and YAML-parse-bound;
    /// unbounded fan-out adds scheduling cost without throughput.
    const PARALLEL_SCAN_THREADS: usize = 8;

    /// Recursive walk used by [`Store::scan`]: any depth, skipping `.tix-tmp-*`
    /// temp directories, `<slug>-assets/` directories, and hidden directories.
    ///
    /// Collects `(full path, relative path, archived)` **without reading a
    /// file** — the read and parse belong to [`Store::parse_issue_files`], so this
    /// cheap walk stays single-threaded while the expensive work fans out.
    fn collect_issue_files(
        dir: &Path,
        prefix: &str,
        include_archived: bool,
        out: &mut Vec<(PathBuf, String, bool)>,
    ) -> Result<()> {
        for entry in std::fs::read_dir(dir)? {
            let entry = entry?;
            let path = entry.path();
            let name = entry.file_name().to_string_lossy().to_string();
            if path.is_dir() {
                if name.starts_with('.')
                    || name.starts_with(".tix-tmp-")
                    || name.ends_with("-assets")
                {
                    continue;
                }
                let child = if prefix.is_empty() {
                    name
                } else {
                    format!("{prefix}/{name}")
                };
                Self::collect_issue_files(&path, &child, include_archived, out)?;
            } else if path.is_file() && name.ends_with(".md") {
                let archived = name.starts_with('.');
                if archived && !include_archived {
                    continue;
                }
                let rel = if prefix.is_empty() {
                    name
                } else {
                    format!("{prefix}/{name}")
                };
                out.push((path, rel, archived));
            }
        }
        Ok(())
    }

    /// Read and parse every entry from [`Store::collect_issue_files`], keeping
    /// the input order.
    ///
    /// Below [`Store::PARALLEL_SCAN_THRESHOLD`] files this is a plain serial
    /// loop. At or above it the work is split across up to
    /// [`Store::PARALLEL_SCAN_THREADS`] scoped threads; each chunk keeps its
    /// place, so the result is in the same order as `files` and the first error —
    /// a parse failure names its file — is deterministic.
    fn parse_issue_files(files: &[(PathBuf, String, bool)]) -> Result<Vec<Issue>> {
        if files.len() < Self::PARALLEL_SCAN_THRESHOLD {
            return files
                .iter()
                .map(|(path, rel, archived)| Self::read_issue_file(path, rel, *archived))
                .collect();
        }
        let threads = std::thread::available_parallelism()
            .map(|n| n.get())
            .unwrap_or(1)
            .clamp(1, Self::PARALLEL_SCAN_THREADS);
        if threads < 2 {
            return files
                .iter()
                .map(|(path, rel, archived)| Self::read_issue_file(path, rel, *archived))
                .collect();
        }
        let chunk = files.len().div_ceil(threads);
        let parts: Vec<Vec<Result<Issue>>> = std::thread::scope(|scope| {
            let handles: Vec<_> = files
                .chunks(chunk)
                .map(|slice| {
                    scope.spawn(move || {
                        slice
                            .iter()
                            .map(|(path, rel, archived)| {
                                Self::read_issue_file(path, rel, *archived)
                            })
                            .collect::<Vec<_>>()
                    })
                })
                .collect();
            handles
                .into_iter()
                .map(|handle| handle.join().expect("issue-scan worker panicked"))
                .collect()
        });
        let mut issues = Vec::with_capacity(files.len());
        for part in parts {
            for issue in part {
                issues.push(issue?);
            }
        }
        Ok(issues)
    }

    /// Read one issue file from its full `path` and stamp it with `rel` (the
    /// store-relative filename) and `archived` (the dot-prefix marker). Shared by
    /// the serial and parallel scan paths so they cannot diverge.
    fn read_issue_file(path: &Path, rel: &str, archived: bool) -> Result<Issue> {
        let contents = std::fs::read_to_string(path)?;
        let mut issue = Issue::parse(&contents).map_err(|e| match e {
            TixError::Parse(msg) => TixError::Parse(format!("{rel}: {msg}")),
            other => other,
        })?;
        issue.filename = rel.to_string();
        issue.archived = archived;
        Ok(issue)
    }

    /// The assignee storage folders under the issues directory, sorted.
    ///
    /// These are the `docs/issues/<username>/` segments [`Self::scan`] walks —
    /// the ground truth for who has issues. The reserved segments are excluded:
    /// `unassigned` is the fallback for "no assignee" and is not a person, and a
    /// `<slug>-assets/` or `.tix-tmp-*` directory is not a person either. Used by
    /// the Triage mode's assignee picker (design D6); never creates a directory.
    pub fn assignee_segments(&self) -> Result<Vec<String>> {
        let mut segments = Vec::new();
        if !self.issues_dir.exists() {
            return Ok(segments);
        }
        for entry in std::fs::read_dir(&self.issues_dir)? {
            let entry = entry?;
            if !entry.path().is_dir() {
                continue;
            }
            let name = entry.file_name().to_string_lossy().to_string();
            if name == "unassigned" || name.starts_with(".tix-tmp-") || name.ends_with("-assets") {
                continue;
            }
            segments.push(name);
        }
        segments.sort();
        segments.dedup();
        Ok(segments)
    }

    pub fn get(&self, selector: IssueSelector) -> Result<Issue> {
        match selector {
            IssueSelector::Number(num) => {
                let issues = self.list_all()?;
                issues
                    .into_iter()
                    .find(|i| i.number == num)
                    .ok_or_else(|| TixError::NotFound(format!("issue #{num}")))
            }
            IssueSelector::Filename(name) => {
                validate_filename(&name)?;
                let path = self.issues_dir.join(&name);
                if !path.is_file() {
                    return Err(TixError::NotFound(format!("file {name}")));
                }
                let contents = std::fs::read_to_string(&path)?;
                let mut issue = Issue::parse(&contents)?;
                issue.filename = name;
                Ok(issue)
            }
            IssueSelector::Slug(slug) => {
                let issues = self.list_all()?;
                issues
                    .into_iter()
                    .find(|i| slugify(&i.title) == slug)
                    .ok_or_else(|| TixError::NotFound(format!("slug {slug}")))
            }
        }
    }

    /// Read one issue by its **store-relative** filename (issue #10
    /// follow-up).
    ///
    /// The single-file counterpart of [`Store::scan`], for the incremental
    /// corpus path: it sets `filename` and `archived` exactly as `scan` does
    /// (the archived marker is the leading dot of the file name) and applies
    /// the same parse-error context, so an incrementally updated corpus holds
    /// byte-identical issues to a full rebuild. It deliberately does **not**
    /// linear-scan [`IssueSelector`] — the caller already has the relative
    /// path from the watcher.
    ///
    /// A path that is not a file is `NotFound`; the caller decides whether
    /// that means "removed".
    pub fn read_issue_at(&self, rel: &Path) -> Result<Issue> {
        let filename = rel.to_string_lossy().to_string();
        let path = self.issues_dir.join(rel);
        if !path.is_file() {
            return Err(TixError::NotFound(format!("file {filename}")));
        }
        let contents = std::fs::read_to_string(&path)?;
        let mut issue = Issue::parse(&contents).map_err(|e| match e {
            TixError::Parse(msg) => TixError::Parse(format!("{filename}: {msg}")),
            other => other,
        })?;
        issue.filename = filename;
        issue.archived = rel
            .file_name()
            .and_then(|name| name.to_str())
            .is_some_and(|name| name.starts_with('.'));
        Ok(issue)
    }

    /// Archive an issue: rename its file to a dot-prefixed name **in place**.
    ///
    /// The marker is the filename (issue #1492), so this is a rename within the
    /// same assignee segment (`x.md` ↔ `.x.md`) plus exactly one `## History`
    /// event. `number`, `status`, `created` and every other frontmatter field
    /// are left untouched, no data is dropped, and the file is never deleted or
    /// moved between directories.
    ///
    /// An already-archived issue is refused with the `already_archived`
    /// diagnostic rather than re-archived: the operation is not idempotent by
    /// design, because a second call would append a second audit entry for a
    /// mutation that did not happen.
    pub fn archive(&self, sel: &str) -> Result<Issue> {
        self.set_archived(sel, true)
    }

    /// Restore an archived issue: the inverse of [`Store::archive`].
    ///
    /// An active issue is refused with the `not_archived` diagnostic.
    pub fn restore(&self, sel: &str) -> Result<Issue> {
        self.set_archived(sel, false)
    }

    fn set_archived(&self, sel: &str, archive: bool) -> Result<Issue> {
        // `resolve_issue` → `parse_selector` → `list_all`, so an archived issue
        // resolves here even though the default view hides it.
        let mut issue = self.resolve_issue(sel)?;
        if issue.archived == archive {
            return Err(TixError::InvalidInput(format!(
                "{}: issue #{} ({}) is already {}",
                if archive {
                    "already_archived"
                } else {
                    "not_archived"
                },
                issue.number,
                issue.filename,
                if archive { "archived" } else { "active" },
            )));
        }
        let old_rel = issue.filename.clone();
        let new_rel = flip_archived(&old_rel, archive).ok_or_else(|| {
            TixError::InvalidInput(format!(
                "cannot {} {old_rel}: its filename does not carry the archived marker in the \
                 expected position",
                if archive { "archive" } else { "restore" }
            ))
        })?;
        let old_path = self.issues_dir.join(&old_rel);
        let new_path = self.issues_dir.join(&new_rel);
        if !old_path.is_file() {
            return Err(TixError::NotFound(format!("file {old_rel}")));
        }
        if new_path.exists() {
            return Err(TixError::InvalidInput(format!(
                "cannot {} {old_rel}: {new_rel} already exists",
                if archive { "archive" } else { "restore" }
            )));
        }
        // Rename first: it is atomic, stays in the same directory, and cannot
        // lose content. Only then is the audit event written, at the new name.
        // A failure between the two leaves the file renamed but without the
        // event — never a duplicate, never lost data.
        std::fs::rename(&old_path, &new_path)?;
        issue.filename = new_rel.clone();
        issue.archived = archive;
        issue.history.append_now(
            &actor_identity(),
            if archive {
                HistoryEventKind::Archived
            } else {
                HistoryEventKind::Restored
            },
            &format!("{old_rel} -> {new_rel}"),
        );
        // No `bump_updated`: `updated` is a frontmatter field and archiving must
        // leave every frontmatter field byte-identical.
        issue.filename = self.update(&new_rel, &issue)?;
        Ok(issue)
    }

    /// Create an issue file atomically and assign its number by scanning the
    /// live issue set (issue #52): the highest existing `number` plus one,
    /// with a floor of `0` for an empty store.
    ///
    /// The number is resolved at creation time rather than read from a
    /// persisted `[state].next_number` counter, so `tix.toml` is never
    /// rewritten by `create`. A deleted high-numbered issue's number can be
    /// reused by a later create; the frontmatter `number` stays stable for
    /// every surviving issue (C-007).
    ///
    /// The file is written into the assignee segment derived from
    /// `issue.assignee` (`unassigned/` fallback, FR-029/FR-030), creating the
    /// segment directory as needed, and `issue.filename` is set to the
    /// relative path so `create` output and later edits agree. Atomic-write
    /// discipline (temp + rename, NFR-006) is preserved.
    pub fn create(
        &self,
        issue: &mut Issue,
        body: &str,
        filename_stem: Option<&str>,
    ) -> Result<PathBuf> {
        issue.body = body.to_string();
        issue.bump_updated();

        std::fs::create_dir_all(&self.issues_dir)?;
        issue.number = self.resolve_next_number()?;

        // Claim the number **before** anything is serialised, and hold it across the
        // whole write. `resolve_next_number` above reads the directory, takes `max`,
        // and adds 1, which is only a *hint*: two processes reaching this line
        // together both get the same answer and both proceed. See [`NumberClaim`]
        // for what that cost and why an `O_EXCL` marker is the fix.
        //
        // **Before** the serialisation, specifically. `to_file_contents` embeds
        // `number:` in the frontmatter, so serialising first and claiming after —
        // which is the order this was first written in — writes a *stale* number into
        // the file while the ledger records the correct one. The 24-create test still
        // saw 8 distinct numbers with 24 valid claims in place, because every claim
        // was correct and every file was wrong. A claim that does not reach the bytes
        // on disk is not a claim.
        let mut claim = NumberClaim::acquire(&self.issues_dir, issue.number)?;
        // Belt and braces (#1352): the number actually claimed must be the number
        // about to be written. `acquire` only climbs when the requested number is
        // already taken, so this is normally an identity — but it means a future
        // change to either side that drifts from the other fails loudly here
        // instead of writing an issue whose `number:` disagrees with the ledger.
        issue.number = claim.number().ok_or_else(|| {
            TixError::Io(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                format!("claimed number is unreadable from {}", claim.path.display()),
            ))
        })?;

        // WP02 layout, now configurable ([layout] in tix.toml): the directory is
        // rendered from the configured template and may be nested; `filename_stem`
        // still overrides the filename for callers that pin a stem.
        let rel = crate::layout::render(&self.config.layout, issue);
        let (dir, file) = rel.rsplit_once('/').unwrap_or(("", rel.as_str()));
        std::fs::create_dir_all(self.issues_dir.join(dir))?;

        let stem = match filename_stem {
            Some(s) => s.to_string(),
            None => file.strip_suffix(".md").unwrap_or(file).to_string(),
        };
        // Serialised **after** the number is fixed, so the `number:` in the file is
        // the claimed one.
        let contents = issue.to_file_contents();

        let written = self.write_new_issue_file(dir, &stem, contents.as_bytes());
        // The claim is now permanent: the issue file exists, so that file — not the
        // marker — is the authority for the number, and dropping the marker would
        // reopen the window this exists to close. A create that *failed* releases
        // its claim instead, so a failure does not leak a number for nothing.
        match written {
            Ok((filename, path)) => {
                claim.commit();
                issue.filename = filename;
                Ok(path)
            }
            Err(e) => {
                claim.release();
                Err(e)
            }
        }
    }

    /// Write a **new** issue file, never overwriting an existing one.
    ///
    /// The stem is `{created}-{slugified title}`, so it is a function of the issue's
    /// creation date, its title, and its assignee segment — three things routinely
    /// identical across two issues. Two `tix create --title "Same title"` runs on
    /// the same day therefore resolved to the **same path**, and `atomic_write`
    /// renames over the target, so the second create silently destroyed the first.
    /// No concurrency was required, and both commands reported success:
    ///
    /// ```text
    /// $ tix create --title "Same title" --priority high
    /// Created herbert-maschke/2026-09-28-same-title.md
    /// $ tix create --title "Same title" --priority low
    /// Created herbert-maschke/2026-09-28-same-title.md
    /// $ ls docs/issues/*/
    /// 2026-09-28-same-title.md            # one file
    /// $ tix list
    /// NUM  TITLE       STATUS  PRIORITY
    /// 2    Same title  todo    low       # issue #1 is gone
    /// ```
    ///
    /// Two layers, because the first alone is still a race:
    ///
    /// 1. **Probe** for a free name, appending `-2`, `-3`, … to the stem. This
    ///    handles the deterministic case, which is the common one.
    /// 2. **Create the file with `O_EXCL`** via [`write_file_new`]. Probing cannot
    ///    see a file another process creates between the probe and the write, and
    ///    `rename` overwrites unconditionally, so the final step is the one that
    ///    actually guarantees no clobber. Losing the race retries from step 1.
    ///
    /// Probing alone is the version that looks correct and is not: a second process
    /// that writes the same stem in the same millisecond would still be destroyed,
    /// and the retry-on-`AlreadyExists` below exists precisely because a reviewer
    /// should not have to take that on trust.
    fn write_new_issue_file(
        &self,
        segment: &str,
        stem: &str,
        contents: &[u8],
    ) -> Result<(String, PathBuf)> {
        const MAX_ATTEMPTS: usize = 1_000;
        let mut suffix = 1usize;
        for _ in 0..MAX_ATTEMPTS {
            let filename = if suffix == 1 {
                format!("{segment}/{stem}.md")
            } else {
                format!("{segment}/{stem}-{suffix}.md")
            };
            let path = self.issues_dir.join(&filename);
            match write_file_new(&self.issues_dir, &path, contents) {
                Ok(()) => return Ok((filename, path)),
                // Someone took this name between the probe and the write. The
                // collision is benign — it is only a *name* — so take the next one.
                Err(TixError::Io(e)) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                    suffix += 1;
                }
                Err(e) => return Err(e),
            }
        }
        Err(TixError::Io(std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            format!(
                "could not find a free filename for {segment}/{stem}.md in {MAX_ATTEMPTS} attempts"
            ),
        )))
    }

    /// The number for the next created issue: `max(number)` over the live
    /// issue set plus one, or `1` when no issues exist (issue #52 — no
    /// persisted counter to advance). Scanning the same list that every
    /// other command uses keeps number resolution conservative: reusing a
    /// number requires first deleting every higher-numbered issue.
    ///
    /// **The empty case is `1`, not `0`.** It used to be `0`, because `max()` over
    /// an empty set has no natural answer and `0` was the fallback — which made the
    /// first issue in every fresh repository `#0`, and that number is then
    /// indistinguishable from a sentinel, an uninitialised value, or a field that
    /// failed to read. Found by running the binary rather than reading the code
    /// (tix #1376); two places in the codebase had already written the opposite
    /// assumption into a comment, and a third had used `0` as a
    /// `HierarchyNode::NO_ISSUE_YET` marker.
    ///
    /// Only the empty case changes. With any issue present the answer is `max + 1`,
    /// which is unaffected — so no existing repository renumbers, and no migration
    /// is implied. (One real issue in this repository is numbered `0`, written
    /// before this fix; it keeps its number, because renumbering is a migration and
    /// the mission's doctrine makes those an escalation trigger.)
    fn resolve_next_number(&self) -> Result<u32> {
        // `list_all`, not `list`: an archived issue keeps its number forever.
        // Reading only the active set would let a `create` reuse the number of
        // the highest-numbered archived issue (issue #1492).
        let issues = self.list_all()?;
        match issues.iter().map(|i| i.number).max() {
            None => Ok(1),
            Some(max) => max
                .checked_add(1)
                .ok_or_else(|| TixError::InvalidInput("issue-number overflow".to_string())),
        }
    }

    pub fn config_path(&self) -> Result<std::path::PathBuf> {
        if let Some(root) = Config::project_root(&self.issues_dir) {
            Ok(root.join("tix.toml"))
        } else {
            Err(TixError::Config(
                "tix.toml not found in any parent directory of issues_dir".into(),
            ))
        }
    }

    /// Write `issue` over the file at `filename`, then reconcile the file's
    /// **location** with the configured `[layout]` (`move_on_change`).
    ///
    /// Returns the store-relative path the issue lives at afterwards — the same
    /// one in the common case, a new one when a templated field (status, type,
    /// assignee, cycle, …) now renders a different directory. **Every write path
    /// goes through here**, so no surface (CLI, MCP, TUI, triage, sync) can
    /// leave an issue at a path that disagrees with the layout.
    pub fn update(&self, filename: &str, issue: &Issue) -> Result<String> {
        validate_filename(filename)?;
        let path = self.issues_dir.join(filename);
        if !path.is_file() {
            return Err(TixError::NotFound(format!("file {filename}")));
        }
        // The retired `links:` key is not in the model, so re-serializing drops
        // it — and with it the `retired_links_key` finding, silently. The
        // consequence is that `tix lint` reports a problem, the user runs an
        // unrelated `tix edit`, and both the finding and the data vanish with no
        // notice. That is the defect; C-001's no-migration intent is not.
        //
        // The write still proceeds, because refusing would make tix unusable
        // across the repository: 1216 of 1290 issue files here carry `links:`.
        // What changes is that the removal is *disclosed*, naming the field and
        // the file, so nothing is lost quietly. Removing the key by hand first
        // silences this.
        if issue.has_retired_links_key {
            // Recorded on the store, not printed here. `eprintln!` inside a
            // library function is invisible to the MCP server and the TUI, so
            // the same operation produced different observable output per
            // surface, which `contracts/surface-parity.md` forbids.
            //
            // Drained at the three surface boundaries, not at each write path:
            // `main` for every CLI command, the MCP `serve` loop per request,
            // and the TUI event loop. Draining per command was tried and reached
            // only `link` and `edit`, so every other write path — `mv`,
            // `rollover`, planning, sync, the TUI, MCP — warned about nothing.
            // That was worse than the `eprintln!` it replaced, which fired from
            // inside `update` and so covered all of them. A count of write
            // paths is deliberately not stated here: it drifts, and a figure a
            // later reader trusts is worse than no figure. `tests/mcp.rs` pins
            // the behaviour instead, for `main` and the MCP server.
            retired_key_disclosure(filename);
        }
        let contents = issue.to_file_contents();
        atomic_write(&self.issues_dir, &path, contents.as_bytes())?;
        // Unconditional auto-migration: after any write, the file is moved to the
        // directory `[layout]` renders (subject only to `move_on_change`). A
        // legacy or mismatched path is migrated, not left behind.
        self.reconcile_location(filename, issue)
    }

    /// Move the file at `filename` so its directory matches what `[layout]`
    /// renders for `issue`, when `move_on_change` is set and the directory
    /// differs. The basename (including the archived-marker dot) is preserved.
    /// Returns the relative path afterwards (unchanged when no move happens).
    fn reconcile_location(&self, filename: &str, issue: &Issue) -> Result<String> {
        if !self.config.layout.move_on_change {
            return Ok(filename.to_string());
        }
        let target_dir = crate::layout::render_directory(&self.config.layout, issue);
        let Some((old_dir, base)) = split_relative(filename) else {
            return Ok(filename.to_string());
        };
        if old_dir == target_dir {
            return Ok(filename.to_string());
        }
        let stem = base.strip_suffix(".md").unwrap_or(&base);
        let moved = self.move_issue_file(filename, &target_dir, stem)?;
        Ok(moved.to_string_lossy().to_string())
    }

    /// Copy an asset into the issue's `<slug>-assets/` directory (FR-006) and
    /// insert a relative markdown link at the end of the body, persisted via
    /// [`Store::update`] (NFR-004).
    ///
    /// The asset dir is derived from the issue filename per
    /// `contracts/comments-format.md`: `<slug>-assets/` where `<slug>` is the
    /// basename stem minus the leading `YYYY-MM-DD-` date prefix. The copy is
    /// atomic (temp + rename, NFR-004); on a name collision the file is stored
    /// as `<stem>-<n>.<ext>` (first free `n`) and the inserted link points at
    /// the actual written name. Image extensions (`.png` `.jpg` `.jpeg`
    /// `.gif` `.svg` `.webp` `.bmp`) get the `![…](…)` form, everything else
    /// the `[…](…)` form. The link path is relative to the issue file, so the
    /// segment prefix is never part of it.
    pub fn add_asset(&self, filename: &str, source_path: &Path) -> Result<AssetAdded> {
        validate_filename(filename)?;
        let mut issue = self.get(IssueSelector::Filename(filename.to_string()))?;

        let (segment, basename) = split_relative(filename).ok_or_else(|| {
            TixError::InvalidInput(format!("invalid relative issue filename: {filename}"))
        })?;
        let stem = basename
            .strip_suffix(".md")
            .ok_or_else(|| {
                TixError::InvalidInput(format!(
                    "asset target must be a `.md` issue file: {filename}"
                ))
            })?
            .to_string();
        let slug = slug_from_stem(&stem);
        let dir_name = format!("{slug}-assets");
        let asset_dir = self.issues_dir.join(&segment).join(&dir_name);
        std::fs::create_dir_all(&asset_dir)?;

        let source_name = source_path
            .file_name()
            .and_then(|n| n.to_str())
            .ok_or_else(|| {
                TixError::InvalidInput("asset source must have a file name".to_string())
            })?
            .to_string();
        let written_name = resolve_asset_name(&asset_dir, &source_name);
        atomic_copy(&asset_dir, &asset_dir.join(&written_name), source_path)?;

        let label = written_name
            .rsplit_once('.')
            .map(|(stem, _)| stem)
            .unwrap_or(&written_name);
        let link = if is_image_name(&written_name) {
            format!("![{label}]({dir_name}/{written_name})")
        } else {
            format!("[{label}]({dir_name}/{written_name})")
        };

        // Append the link as a new line at the end of the body, reusing the
        // comment-appender newline discipline so the description is never
        // rewritten (FR-007).
        if !issue.body.is_empty() {
            if !issue.body.ends_with('\n') {
                issue.body.push('\n');
            }
            if !issue.body.ends_with("\n\n") {
                issue.body.push('\n');
            }
        }
        issue.body.push_str(&link);
        issue.body.push('\n');
        issue.bump_updated();
        self.update(filename, &issue)?;

        Ok(AssetAdded { link, written_name })
    }

    pub fn delete(&self, filename: &str) -> Result<()> {
        validate_filename(filename)?;
        let path = self.issues_dir.join(filename);
        if !path.is_file() {
            return Err(TixError::NotFound(format!("file {filename}")));
        }
        // Read the number **before** the file goes, so the claim ledger can be told
        // the number is free again (#1352).
        //
        // Releasing the claim is what preserves issue #52's documented behaviour:
        // the next number is re-derived from the live set, so deleting the
        // highest-numbered issue lets its number be reused. Without this the ledger
        // holds that number forever, the next create climbs past it, and the feature
        // stops working — which is a regression the existing test caught.
        //
        // The residual window, stated rather than hidden: if a `create` is in flight
        // holding this claim while the `delete` runs, the claim is released and a
        // later create could take the number too. That needs a delete and a create to
        // interleave, and it was *unconditionally* broken before this ledger existed;
        // the ledger removes the plain concurrent-create case, which is the one that
        // actually happens. Repairing the delete/create interleave would need a lock,
        // and this is the reason the ledger was chosen over one.
        let freed = std::fs::read_to_string(&path)
            .ok()
            .and_then(|text| frontmatter_number(&text));
        std::fs::remove_file(&path)?;
        if let Some(number) = freed {
            NumberClaim::release_number(&self.issues_dir, number);
        }
        // Best-effort cleanup of the `<slug>-assets/` dir (FR-008): the `.md`
        // removal is the contract, so an asset-dir removal failure is only
        // reported as a warning, never propagated.
        if let Some((segment, basename)) = split_relative(filename) {
            let stem = basename.strip_suffix(".md").unwrap_or(&basename);
            let slug = slug_from_stem(stem);
            let asset_dir = self
                .issues_dir
                .join(&segment)
                .join(format!("{slug}-assets"));
            if asset_dir.exists()
                && let Err(e) = std::fs::remove_dir_all(&asset_dir)
            {
                eprintln!(
                    "warning: failed to remove asset dir {}: {e}",
                    asset_dir.display()
                );
            }
        }
        Ok(())
    }

    /// **The** status write path (WP03, C-003, FR-002, NFR-002).
    ///
    /// Every surface that changes an issue's column comes through here, so the
    /// transition service is on the path *structurally* rather than by convention:
    /// CLI (`tix mv`, `tix edit --status`), the TUI's move and edit actions, MCP's
    /// `move_issue` and `update_issue`, and sync's import. A caller that judges a
    /// transition itself is a parity defect, and the two that used to are the
    /// reason this function had no production caller at all.
    ///
    /// ## The three outcomes
    ///
    /// | Result | Meaning | Written |
    /// |---|---|---|
    /// | `Ok(outcome)`, `outcome.written` | accepted, changed column | file + one decision |
    /// | `Ok(outcome)`, `!outcome.written` | accepted, same column | **nothing** (idempotent) |
    /// | `Err(TixError::Workflow(_))` | refused | **nothing at all** |
    ///
    /// The separation is in the type, not in a runtime check: a refusal is an
    /// `Err` carrying the **named** diagnostic, so a caller cannot read it as a
    /// write, and cannot mistake `unknown_column` (a typo) for `invalid_transition`
    /// (policy) — one message shape for both would lose the distinction the
    /// contract's shared vocabulary exists to keep (contract §6).
    ///
    /// ## Rejection is inert
    ///
    /// Nothing is touched before the service has accepted: no issue file, no
    /// `tix.toml`, no History entry. The service is pure (`src/workflow.rs` is
    /// filesystem-free by design), and the only write in this function is the
    /// single `update` at the end — so there is no window in which a refusal
    /// leaves a partial change behind.
    ///
    /// ## No repair path
    ///
    /// A file hand-edited into an inconsistent status is read, judged, and
    /// reported. This function never corrects one (C-005, decision
    /// `01M3C3XBMTR5WFV7059NXM04AJ`); WP06 owns the diagnosis. An auto-repair
    /// sneaking in here would be an escalation trigger.
    ///
    /// Routes through [`Store::update`] rather than serialising directly, so the
    /// retired `links:` disclosure happens on this path too. Cycle-5 Minor 9: this
    /// used to write the file itself, which drops the retired `links:` key
    /// because the key is not in the model — with **no disclosure**, since the
    /// disclosure lives in `update`. It was dead code reachable only from tests,
    /// so nothing caught it, and wiring it up would have silently destroyed the
    /// key on every surface at once.
    pub fn set_status(&self, filename: &str, request: StatusChange<'_>) -> Result<StatusOutcome> {
        let mut issue = self.get(IssueSelector::Filename(filename.to_string()))?;

        // Once per config load, not per issue: the contract's O(V) sweep rests on
        // this being a single hash lookup per column rather than a rebuild.
        let (_, resolution) = crate::workflow::active_resolution(&self.config);

        // The one transition evaluation (C-003). Everything below is the write this
        // WP is responsible for; no rule of its own lives here.
        let outcome = crate::workflow::validate_transition(
            &issue,
            request.column,
            &resolution,
            &self.config,
            request.override_reason,
        );
        // The inert case. Return before any mutation, so there is nothing to undo
        // and no History entry to retract.
        let accepted = match TransitionAccepted::try_from(outcome) {
            Ok(accepted) => accepted,
            Err(diagnostic) => return Err(TixError::Workflow(diagnostic)),
        };

        // Idempotency: a same-column re-apply is accepted but writes nothing.
        // `updated` is deliberately *not* bumped either — a no-op that touches the
        // file is not a no-op, and bumping the date would make `tix edit --status`
        // with the column it already has look like an edit.
        if !accepted.changed {
            return Ok(StatusOutcome {
                issue,
                decision: None,
                written: false,
            });
        }

        // The completion coupling, which used to live in `mv.rs`. It belongs here
        // because it is a rule about the *status* column: reaching completion
        // records a commit, and leaving it clears the one it recorded. Keeping it
        // in the command layer is what let `tix edit --status` move an issue to
        // done without recording a commit, i.e. a second definition of "done".
        //
        // WP04: both halves of this now ask the **service** whether a column is
        // complete, rather than comparing against `effective_done_column()`.
        //
        // This was a live defect, not a tidy-up. WP03 wrote the coupling against the
        // column name; WP04 moved the CLI's *prompt trigger* to the service's
        // decision. The two then disagreed on any board whose `category_map` puts
        // `completed` somewhere other than its `done_column`: the CLI correctly
        // decided the move reached completion and asked for a commit hash, and the
        // seam then compared the column to `done_column`, concluded it had not, and
        // **silently dropped the hash the user had just typed**. The commit-prompt
        // parity test is what found it.
        //
        // `was_complete` is computed before `issue.status` is reassigned below, so
        // it describes where the issue *was*.
        let was_complete = crate::workflow::is_completed(&issue, &resolution);
        let reaches_complete = resolution
            .resolve(&accepted.to)
            .is_some_and(crate::workflow::WorkflowCategory::is_complete);
        if reaches_complete {
            issue.commit = request.commit.map(str::to_string);
        } else if was_complete {
            issue.commit = None;
        }

        issue.status = Status::new(accepted.to.clone());
        issue.bump_updated();

        // Exactly one decision per accepted transition (C-006), appended to the
        // issue's existing History — never a second log.
        let decision = TransitionDecision::new(
            crate::model::utc_now_rfc3339(),
            // The existing identity path, not a new one. `actor_identity` is the
            // same function the relationship and hierarchy events use, so a
            // decision's actor is spelled the way every other History entry's is
            // and cannot drift from it (T012 step 4).
            actor_identity(),
            accepted.from.clone(),
            accepted.to.clone(),
            accepted.from_category.key(),
            accepted.to_category.key(),
            accepted.override_reason,
        );
        issue.history.append(decision.to_event());

        issue.filename = self.update(filename, &issue)?;
        Ok(StatusOutcome {
            issue,
            decision: Some(decision),
            written: true,
        })
    }

    /// Build a [`RelationshipGraph`] over every issue in the store.
    ///
    /// The service is the only place relationship semantics live, so the write
    /// path validates through it rather than re-deriving direction handling,
    /// cycle detection, or blocked state locally (C-003).
    /// The board's configured completion column.
    ///
    /// Read from the first configured board. Completion is always resolved
    /// from configuration, never by matching the literal string `done`; when no
    /// board configures one, the service's `done` fallback applies.
    ///
    /// Resolved from the **active** board — the one named `default`, falling back
    /// to the first declared, which is exactly what
    /// [`Config::default_config`](crate::config::Config::default_config) returns
    /// and what every other single-surface consumer already uses.
    ///
    /// It used to take the **first declared** board instead
    /// (`configurations.values().next()`). That is a different board whenever a
    /// configuration is declared before `default` with a different
    /// `done_column`, and it put two different boards inside a single decision:
    /// `blocked_move_guard` asked "is the target the completion column?" via
    /// `completion_column(config)` — the active board — and then "is this issue
    /// blocked?" via this function's graph — the *first declared* board. The
    /// guard was reasoning about two different workflows in one call.
    ///
    /// `data-model.md` §4 says completion "is always resolved through the board's
    /// configured `done_column`" and that the predicate is "the only definition
    /// used by FR-003, FR-004, the move guard, and every surface". That requires
    /// one board, not "whichever is declared first".
    pub fn relationship_done_column(&self) -> String {
        // WP09: the service's completion column. The name says `done_column` because
        // that is what the `RelationshipGraph` and `hierarchy` services take as a
        // parameter — re-deriving the *meaning* inside them is what this mission
        // ended; supplying that meaning from one place is the whole of the fix, and
        // it does not change either service's signature.
        //
        // Before: `effective_done_column().unwrap_or("done")`, so on a board whose
        // `category_map` puts `completed` on a column other than `done_column` the
        // blocked marker and the hierarchy rollup were computed against the wrong
        // column. `unwrap_or("done")` also invented a completion column on a board
        // that declared none.
        crate::workflow::completion_column_or_default(self.config.default_config(), &self.config)
    }

    /// Create the typed relationship `a --kind--> b`.
    ///
    /// Selectors resolve with the same grammar as the selector-taking
    /// commands. The edge is stored **once**, in the frontmatter of whichever
    /// issue owns the canonical edge — the `from` side for a directional kind,
    /// and the lower-numbered side for `related`, which is order-normalized so
    /// both spellings of an association are one edge. No back-reference is
    /// written on the other issue: that symmetry was the retired model.
    ///
    /// Validation runs through the service first, so a self-link, a missing
    /// target, a conflicting kind, or a cycle is refused **before any file is
    /// touched** (SC-005). Re-asserting an edge that already exists is an
    /// idempotent no-op: no file is written and no History event is appended.
    pub fn link(&self, a: &str, b: &str, kind: RelationKind) -> Result<RelationshipOutcome> {
        let issue_a = self.resolve_issue(a)?;
        let issue_b = self.resolve_issue(b)?;
        // The graph borrows the loaded issues, so both are built here and stay
        // alive until this function returns. The service is the only place
        // relationship semantics live (C-003).
        let issues = self.list_all()?;
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        let done_column = self.relationship_done_column();
        let graph = RelationshipGraph::new(&views, &done_column);

        let verdict = graph.validate_create(issue_a.number, issue_b.number, kind);
        if verdict.blocking() {
            return Err(relationship_error(&verdict.errors));
        }

        // Idempotency goes through the service's own lookup, so an inverse
        // spelling or a non-canonical stored order still matches.
        if let Some(existing) = graph.find_canonical(issue_a.number, issue_b.number, kind) {
            // Nothing is written and no History event is appended. The **real
            // row** is reported rather than a synthetic one: the contract defines
            // the output as the accepted relationship, and an empty id is not
            // addressable by `edit_relation`/`remove_relation`, so returning one
            // hands the caller a dangling reference (F15).
            return Ok(RelationshipOutcome {
                written: None,
                relationship: existing.clone(),
                changed: false,
            });
        }

        let canonical = CanonicalEdge::new(issue_a.number, issue_b.number, kind);
        let mut owner = self.get(IssueSelector::Number(canonical.from))?;
        let target_title = self
            .get(IssueSelector::Number(canonical.to))
            .map(|i| i.title)
            .unwrap_or_default();
        let relationship =
            Relationship::new(canonical.from, canonical.to, canonical.kind, &target_title);
        let detail = format!("created {}: {}", relationship.id, relationship.display);
        owner.relationships.push(relationship.clone());
        owner.history.append_now(
            &actor_identity(),
            HistoryEventKind::RelationshipAdded,
            &detail,
        );
        owner.bump_updated();
        owner.filename = self.update(&owner.filename, &owner)?;

        Ok(RelationshipOutcome {
            written: Some(owner),
            relationship,
            changed: true,
        })
    }

    // -- T008 — hierarchy writes ------------------------------------------
    //
    // Validate-then-write, exactly as `link` does it. The service owns the rule
    // and produces the History event; this layer performs the write. A blocking
    // result writes nothing and appends nothing (contract §4, SC-004).

    /// The in-memory snapshot the hierarchy service reads.
    ///
    /// `pub` because the `--parent` edit flag (WP03) must validate through the
    /// service before any write, exactly as this module does. It is a read, so
    /// exposing it costs no more than a duplicate `list()` would.
    ///
    /// One `IssueView` per issue, shared with the relationship service rather than
    /// a second projection — two views of one issue type is how two services end up
    /// disagreeing about the same snapshot.
    ///
    /// The `Vec` is returned rather than discarded because the write path needs the
    /// child **from this same snapshot**. Re-reading it through a second `list()`
    /// would give the write and the validation two different notions of "current":
    /// two files carrying the same `number:` (reachable by hand-edit, since
    /// `HierarchyIndex::build` keys by number and last-write-wins while
    /// `Store::get` is first-match), or a concurrent writer, would make the
    /// service decide on one parent and the writer emit another. The invariant is
    /// then not merely unasserted, it is false.
    pub fn hierarchy_index(&self) -> Result<(HierarchyIndex, Vec<Issue>)> {
        let issues = self.list_all()?;
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        Ok((HierarchyIndex::build(&views), issues))
    }

    /// The child, taken from the snapshot the service just validated against.
    ///
    /// Returns an error rather than a default so a snapshot that somehow lacks the
    /// child is a loud failure, not a silent write of an unrelated file.
    fn child_in(snapshot: &[Issue], number: u32) -> Result<Issue> {
        snapshot
            .iter()
            .find(|i| i.number == number)
            .cloned()
            .ok_or_else(|| {
                TixError::NotFound(format!(
                    "issue #{number} vanished between validating and writing it"
                ))
            })
    }

    /// Point `child` at `parent`, or repoint it if it already has one.
    ///
    /// Both selectors go through [`Store::resolve_issue`], so `#4`, `4` and a title
    /// fragment all work and an unresolvable one produces the CLI's own message. The
    /// **number** is what lands in the file, because a title is not stable.
    pub fn set_parent(&self, child: &str, parent: &str) -> Result<ParentOutcome> {
        let child_issue = self.resolve_issue(child)?;
        let parent_issue = self.resolve_issue(parent)?;
        let (index, issues) = self.hierarchy_index()?;
        let change = hierarchy::set_parent(&index, child_issue.number, parent_issue.number)?;
        self.commit_parent_change(Store::child_in(&issues, child_issue.number)?, change)
    }

    /// Repoint `child` at a new parent. A no-op when the parent is unchanged.
    pub fn change_parent(&self, child: &str, parent: &str) -> Result<ParentOutcome> {
        let child_issue = self.resolve_issue(child)?;
        let parent_issue = self.resolve_issue(parent)?;
        let (index, issues) = self.hierarchy_index()?;
        let change = hierarchy::change_parent(&index, child_issue.number, parent_issue.number)?;
        self.commit_parent_change(Store::child_in(&issues, child_issue.number)?, change)
    }

    /// Remove `child`'s parent, yielding the absent state.
    pub fn clear_parent(&self, child: &str) -> Result<ParentOutcome> {
        let child_issue = self.resolve_issue(child)?;
        let (index, issues) = self.hierarchy_index()?;
        let change = hierarchy::clear_parent(&index, child_issue.number)?;
        self.commit_parent_change(Store::child_in(&issues, child_issue.number)?, change)
    }

    /// Apply an accepted change: write the field and append exactly one event.
    ///
    /// The single write path for all three operations, so they cannot drift in
    /// whether they record what they did.
    /// The `issue` must come from the same snapshot the service validated against;
    /// see [`Store::hierarchy_index`]. That is what makes the assert below sound.
    fn commit_parent_change(
        &self,
        mut issue: Issue,
        change: hierarchy::ParentChange,
    ) -> Result<ParentOutcome> {
        let Some(event) = change.event else {
            // A no-op: nothing is written, nothing is read for write-back, and no
            // event is appended. `change.parent` is still the real current state,
            // because the service derived it from the snapshot, so the caller does
            // not have to re-read to learn it.
            return Ok(ParentOutcome {
                written: None,
                parent: change.parent,
                event: None,
                changed: false,
            });
        };
        // Read the previous value **before** overwriting it. Building the detail
        // after the assignment compares the new value with itself, and every
        // repoint was recorded as `parent #7 -> #7` — an audit trail that names
        // neither the old parent nor the fact that anything moved.
        let previous = issue.parent;
        let kind = HistoryEventKind::from_parent(event.kind);
        // The detail names both sides so a reader can follow the change without
        // reconstructing state from the surrounding entries. Rendered by the
        // service, because the `--parent` edit flag needs the identical string and
        // two copies of a spelling rule drift.
        let detail = hierarchy::change_detail(previous, change.parent);
        // Sound now, and it is the service's rule rather than storage's: `issue`
        // comes from the validated snapshot, so `previous` is by construction what
        // the service compared against. It was a `debug_assert_ne!` on a value
        // re-read through a *second* snapshot, where two files sharing a `number:`
        // made it fire on a correct write — panicking every dev build — and where
        // release builds compiled it out and wrote the contentless
        // `parent #N -> #N` event it was there to catch. The comment on
        // [`Store::hierarchy_index`] is the reason it cannot drift again.
        debug_assert_ne!(
            previous, change.parent,
            "an accepted change must alter the parent, or the event records nothing"
        );
        // The field only. **Nothing is written to the parent's file**: child
        // membership is derived by inverting this pointer, never stored (C-003).
        issue.parent = change.parent;
        issue.history.append_now(&actor_identity(), kind, &detail);
        issue.bump_updated();
        self.update(&issue.filename, &issue)?;
        Ok(ParentOutcome {
            written: Some(issue),
            parent: change.parent,
            event: Some(event),
            changed: true,
        })
    }

    /// Every relationship touching `number`, as the service resolves it.
    ///
    /// **This is what a read surface must render**, not `issue.relationships`.
    /// A relationship is stored once, in its canonical source's frontmatter, so
    /// the stored field is a *partial* view of one endpoint: for `2 related 1`
    /// the edge lives in #1's file, so #2's own `relationships` is empty even
    /// though #2 plainly has a relationship. Reading the raw field made `tix
    /// view 2` and the TUI detail pane show nothing where the service reports
    /// one, which is a user-visible regression against the retired symmetric
    /// model — the old field was mirrored on both sides by construction.
    ///
    /// Routing every surface through one accessor is also what keeps C-003
    /// honest: derived relationship state is computed in exactly one place.
    pub fn relationships_for(&self, number: u32) -> Result<Vec<Relationship>> {
        let issues = self.list_all()?;
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        let done_column = self.relationship_done_column();
        let graph = RelationshipGraph::new(&views, &done_column);
        Ok(graph
            .relationships_for(number)
            .into_iter()
            .cloned()
            .collect())
    }

    /// Remove the typed relationship `a --kind--> b`.
    ///
    /// Removing an edge that is not there is an idempotent no-op: no file is
    /// written and no History event is appended.
    pub fn unlink(&self, a: &str, b: &str, kind: RelationKind) -> Result<RelationshipOutcome> {
        let canonical = self.canonical_request(a, b, kind)?;
        let stored = self.find_stored_rows(&canonical)?;

        if stored.is_empty() {
            // Idempotent no-op: nothing is written and no History event is
            // appended. The reported relationship is the canonical form the
            // caller asked about.
            return Ok(RelationshipOutcome {
                written: None,
                relationship: canonical_placeholder(&canonical),
                changed: false,
            });
        }

        // Remove every row matching the canonical edge, wherever it is stored,
        // and record **one** History event for the accepted mutation. Redundant
        // rows are one invalid condition to clean up, not N mutations
        // (contract §6: one event per accepted mutation).
        let mut by_file: HashMap<String, Vec<Relationship>> = HashMap::new();
        for (filename, rel) in stored {
            by_file.entry(filename).or_default().push(rel);
        }

        let actor = actor_identity();
        // Ascending filename, for the same reproducibility reason as above.
        let mut file_order: Vec<String> = by_file.keys().cloned().collect();
        file_order.sort_unstable();

        // The first row this call removes, captured before anything is written.
        // M11: a re-scan *after* removal can never match — every matching row is
        // gone — so a successful unlink always fell through to the empty
        // placeholder and reported an unaddressable relationship, while `link`'s
        // no-op path reported a real one. F15 was applied to one path, not both.
        let mut removed_row: Option<Relationship> = None;

        // M10: the summary is computed **once**, from every row this call
        // removes, and the same event is recorded on each file that changes.
        // Appending per file produced two events for one `unlink` when the same
        // edge was hand-authored into both endpoints, while the comment above
        // claimed one event per accepted mutation. One unlink is one mutation.
        let all_removed: Vec<Relationship> = by_file.values().flatten().cloned().collect();
        let summary = if all_removed.len() == 1 {
            let one = &all_removed[0];
            format!("removed {}: {}", one.id, one.display)
        } else {
            let kinds: Vec<String> = all_removed.iter().map(|r| r.kind.to_string()).collect();
            format!(
                "removed {} relationships ({})",
                all_removed.len(),
                kinds.join(", ")
            )
        };

        let mut written: Option<Issue> = None;
        for filename in &file_order {
            let doomed = &by_file[filename];
            let mut owner = self.get(IssueSelector::Filename(filename.clone()))?;
            if removed_row.is_none() {
                removed_row = doomed.first().cloned();
            }
            owner.relationships.retain(|r| r.canonical() != canonical);
            owner
                .history
                .append_now(&actor, HistoryEventKind::RelationshipRemoved, &summary);
            owner.bump_updated();
            owner.filename = self.update(&owner.filename, &owner)?;
            written = Some(owner);
        }

        // The row that *was* removed, captured above — an empty id is not
        // addressable by `edit_relation`/`remove_relation`.
        let relationship = removed_row.unwrap_or_else(|| canonical_placeholder(&canonical));

        Ok(RelationshipOutcome {
            written,
            relationship,
            changed: true,
        })
    }

    /// Retarget and/or re-kind the relationship with this stable id.
    ///
    /// The id is generated once and **survives** the edit, so a relationship a
    /// user has already referenced elsewhere does not change identity when its
    /// target moves (contract §1). `new_to` and `new_kind` are both optional and
    /// naming neither is the identity edit: nothing is written and no History
    /// event is appended.
    ///
    /// Validation goes through [`RelationshipGraph::validate_edit`], so an edit
    /// that would self-link, point at a missing issue, duplicate an existing
    /// edge, or close a cycle is refused **before any file is touched**
    /// (SC-005). An edit may change the *kind* but never the source: the source
    /// is the edge's owner, and moving it would mean deleting a relationship and
    /// creating another, which is what `remove` plus `link` is for.
    pub fn edit_relation(
        &self,
        id: &str,
        new_to: Option<u32>,
        new_kind: Option<RelationKind>,
    ) -> Result<RelationshipOutcome> {
        let issues = self.list_all()?;
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        let done_column = self.relationship_done_column();
        let graph = RelationshipGraph::new(&views, &done_column);

        let Some(existing) = graph.find_relationship(id) else {
            // An id that does not resolve is a named diagnostic, not a bare
            // `NotFound`: the user passed a well-formed argument, and what is
            // missing is a relationship, not an issue.
            let mut verdict = crate::relationships::RelationshipValidationResult::clean();
            verdict.errors.push(Diagnostic::unknown_relation(id));
            return Err(relationship_error(&verdict.errors));
        };

        let verdict = graph.validate_edit(id, new_to, new_kind);
        if verdict.blocking() {
            return Err(relationship_error(&verdict.errors));
        }

        let to = new_to.unwrap_or(existing.to);
        let kind = new_kind.unwrap_or(existing.kind);
        let old_canonical = existing.canonical();

        // The new form has to be **canonicalized before anything else is derived
        // from it**, not merely validated. `--type blocked_by` and re-kinding
        // `related` change which issue owns the edge *and* which issue it points
        // at: `A --blocked_by--> B` is stored as `B blocks A`, so the canonical
        // target is the authored `from`, not the authored `to`.
        //
        // Deriving the display name from the *authored* target is what produced
        // `blocks #2 Issue A` for a `2 duplicates 0` edge re-kinded to
        // `blocked_by`: right endpoints, wrong title, and a stored row that lies
        // about the issue it names. Canonicalize first, then read the title off
        // the canonical target.
        let requested = CanonicalEdge::new(existing.from, to, kind);
        let mut updated = existing.clone();
        updated.from = requested.from;
        updated.to = requested.to;
        updated.kind = requested.kind;

        // The target's *current* title, from the canonical target. A target that
        // does not resolve would otherwise store an edge with an empty display
        // name, so this stays lenient and the row carries what it can.
        let target_title = self
            .get(IssueSelector::Number(updated.to))
            .map(|i| i.title)
            .unwrap_or_default();
        updated.refresh_display(&target_title);
        let new_canonical = updated.canonical();

        // No-op detection is on the *resolved* edge, not on the arguments: an
        // edit naming its own current target and kind is the identity, and so is
        // an edit that only re-renders the same display.
        if old_canonical == new_canonical && updated.display == existing.display {
            return Ok(RelationshipOutcome {
                written: None,
                relationship: existing.clone(),
                changed: false,
            });
        }

        let actor = actor_identity();
        let detail = format!("{} → {}: {}", existing.display, updated.display, updated.id);

        // Remove the old row from every file that holds it, without recording
        // a `relationship_removed` event: this is one edit, not a delete plus a
        // create. Only the canonical source is written when ownership does not
        // move, so the common case stays a single-file write.
        // Removal and insertion are **separate passes**, because the canonical
        // source of the new form is not necessarily a file that held the old
        // one. Re-kinding can move ownership — `related` is order-normalised and
        // `blocked_by` swaps the endpoints — and when it does, a loop that both
        // removes and re-adds deletes the row from its old owner and never
        // writes it to the new one. The relationship is then destroyed while the
        // call reports success, and a `blocked_by` re-kind reports a `blocks`
        // edge that does not exist, so every derived read is wrong the same way.
        //
        // Two passes make that shape unrepresentable: the first only ever
        // removes, the second only ever adds.
        let mut removed_anywhere = false;
        for issue in self.list_all()? {
            if !issue
                .relationships
                .iter()
                .any(|r| r.id == id && r.canonical() == old_canonical)
            {
                continue;
            }
            let mut owner = self.get(IssueSelector::Filename(issue.filename.clone()))?;
            owner
                .relationships
                .retain(|r| !(r.id == id && r.canonical() == old_canonical));
            removed_anywhere = true;
            owner.bump_updated();
            owner.filename = self.update(&owner.filename, &owner)?;
        }
        debug_assert!(removed_anywhere, "graph found the row, the scan did not");

        // The new canonical source carries the row and the History event. It may
        // be the file just written, a different file, or one the old form never
        // touched, so all three cases are written here rather than inside the
        // removal loop.
        let mut new_owner = self.get(IssueSelector::Number(new_canonical.from))?;
        new_owner.relationships.push(updated.clone());
        new_owner
            .history
            .append_now(&actor, HistoryEventKind::RelationshipRetargeted, &detail);
        new_owner.bump_updated();
        new_owner.filename = self.update(&new_owner.filename, &new_owner)?;

        Ok(RelationshipOutcome {
            written: Some(self.get(IssueSelector::Number(new_canonical.from))?),
            relationship: updated,
            changed: true,
        })
    }

    /// Remove the relationship with this stable id.
    ///
    /// An id that is not stored is an **idempotent no-op**: no file is written
    /// and no History event is appended, exactly as [`Store::unlink`] treats an
    /// absent edge. `tix link remove` is therefore safe to retry.
    pub fn remove_relation(&self, id: &str) -> Result<RelationshipOutcome> {
        let stored = self.find_stored_rows_by_id(id)?;
        if stored.is_empty() {
            // Reported as a no-op rather than an error, and the reported
            // relationship carries the id the caller asked about so the outcome
            // is addressable in the message.
            return Ok(RelationshipOutcome {
                written: None,
                relationship: Relationship {
                    id: id.to_string(),
                    ..canonical_placeholder(&CanonicalEdge::new(0, 0, RelationKind::Related))
                },
                changed: false,
            });
        }

        let canonical = stored[0].1.canonical();
        // Reuse the edge-keyed removal so both spellings of a remove stay one
        // implementation, including redundant-row cleanup and the single
        // History event per accepted mutation.
        let from = canonical.from.to_string();
        let to = canonical.to.to_string();
        self.unlink(&from, &to, canonical.kind)
    }

    /// Every stored row with this id, paired with the store-relative filename
    /// it lives in.
    ///
    /// Ids are unique per relationship, but a hand-edited file can hold the same
    /// id twice, so this returns all of them and the caller removes all of them.
    fn find_stored_rows_by_id(&self, id: &str) -> Result<Vec<(String, Relationship)>> {
        let mut found = Vec::new();
        for issue in self.list_all()? {
            for rel in &issue.relationships {
                if rel.id == id {
                    found.push((issue.filename.clone(), rel.clone()));
                }
            }
        }
        Ok(found)
    }

    /// The issue set plus the board's configured completion column, for
    /// building a [`RelationshipGraph`] over the whole store.
    ///
    /// The issue set is returned **alongside** the column rather than as a
    /// finished graph because the graph borrows the issues: a caller that wants
    /// three derived reads (`relationships_for`, `blocked_state`,
    /// `dependency_chain`) over one snapshot would otherwise pay three
    /// separate `O(V + E)` builds and risk the three disagreeing.
    ///
    /// This is the single place a read surface obtains its graph, so no surface
    /// can reach past the service to re-derive direction handling, cycle
    /// detection, or blocked state (C-003).
    ///
    /// Reads the **active** set ([`Store::list`]): it is the graph a default
    /// view renders — `tix list --show relationships`, `tix relationship list`
    /// — so archived issues are deliberately absent from it (issue #1492).
    /// Per-issue lookups that must still resolve an archived issue go through
    /// [`Store::relationships_for`], which reads [`Store::list_all`].
    pub fn graph_source(&self) -> Result<(Vec<Issue>, String)> {
        Ok((self.list()?, self.relationship_done_column()))
    }

    /// Resolve a requested pair into the canonical edge it refers to, without
    /// requiring the *target* to exist.
    ///
    /// A dangling edge is a diagnosed, expected condition (`data-model.md` §4,
    /// contract §7), so the removal path must still be able to reach it. Both
    /// selectors are therefore resolved leniently: a selector that fails to
    /// resolve is accepted if it is a bare issue number, because that is enough
    /// to canonicalize the request. Anything else is still `NotFound`.
    fn canonical_request(&self, a: &str, b: &str, kind: RelationKind) -> Result<CanonicalEdge> {
        let lenient = |sel: &str| -> Result<u32> {
            match self.resolve_issue(sel) {
                Ok(issue) => Ok(issue.number),
                Err(e) => sel.trim().parse::<u32>().map_err(|_| e),
            }
        };
        let from = lenient(a)?;
        let to = lenient(b)?;
        Ok(CanonicalEdge::new(from, to, kind))
    }

    /// Every stored row matching `canonical`, paired with the store-relative
    /// filename it actually lives in.
    ///
    /// This is the single answer to "where is this edge stored", and it is the
    /// reason the three entry points no longer disagree. It matches on
    /// [`Relationship::canonical`] — the service's own normalization — rather
    /// than comparing authored fields, so a row is found no matter which file
    /// holds it or which endpoint order it was written in. Two defects came
    /// from re-deriving that comparison locally: a hand-authored
    /// non-canonically-ordered `related` row was un-removable, and a row
    /// persisted with the input-only `blocked_by` spelling was un-removable too.
    ///
    /// Cost is one `O(V + E)` pass, the same order as the validation the write
    /// path already performs. Correctness of "which file holds this edge" is
    /// worth it; a wrong answer here silently deletes nothing.
    fn find_stored_rows(&self, canonical: &CanonicalEdge) -> Result<Vec<(String, Relationship)>> {
        let mut found = Vec::new();
        for issue in self.list_all()? {
            for rel in &issue.relationships {
                if rel.canonical() == *canonical {
                    found.push((issue.filename.clone(), rel.clone()));
                }
            }
        }
        Ok(found)
    }

    /// Make the issue's relationship set exactly `targets`, with `kind`.
    ///
    /// A typed relationship is stored **once, in its canonical source's file**.
    /// For a directional kind that is the declaring issue; for `related`, which
    /// is order-normalized, it is the lower-numbered of the pair. So this method
    /// may have to write more than one file: an edge requested from an issue
    /// that is not its canonical source belongs to the other issue's frontmatter.
    /// That is the same ownership rule [`Store::link`] already follows, and it
    /// is what "stored once, no mirrored edge" requires.
    ///
    /// Every target number must already resolve (`NotFound` otherwise) and a
    /// self-link is refused — both before anything is written (SC-005).
    /// Relationships that survive keep their stable id and their History
    /// entries; removals are recorded.
    pub fn set_relationships(
        &self,
        filename: &str,
        targets: &[(u32, RelationKind)],
    ) -> Result<Issue> {
        let issue = self.get(IssueSelector::Filename(filename.to_string()))?;
        let own = issue.number;
        let actor = actor_identity();

        // Validate every target up front, before any mutation (SC-005).
        let mut wanted: Vec<CanonicalEdge> = Vec::with_capacity(targets.len());
        for (target, kind) in targets {
            if *target == own {
                return Err(TixError::InvalidInput(format!(
                    "issue #{own} cannot relate to itself"
                )));
            }
            self.get(IssueSelector::Number(*target))?;
            let canonical = CanonicalEdge::new(own, *target, *kind);
            // Identical canonical triples collapse, so asking for the same edge
            // twice is not two writes and not a self-conflict.
            if !wanted.contains(&canonical) {
                wanted.push(canonical);
            }
        }

        // Every wanted edge is validated **through the service** before the
        // first write, exactly as `link` does. This used to re-implement
        // existence and the self-link rule locally and skip the rest, so with
        // `1 blocks 2` already on disk it would happily store `2 blocks 1` — a
        // reciprocal pair that `link` rejects one line earlier and that
        // contract §3 rules 3 and 4 require be refused. Re-deriving part of the
        // rule set is also the boundary breach C-003 exists to prevent, and it
        // becomes user-reachable the moment WP03 wires `--type`.
        {
            let issues = self.list_all()?;
            let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
            let done_column = self.relationship_done_column();
            let graph = RelationshipGraph::new(&views, &done_column);
            for canonical in &wanted {
                let verdict = graph.validate_create(canonical.from, canonical.to, canonical.kind);
                if verdict.blocking() {
                    return Err(relationship_error(&verdict.errors));
                }
            }
        }

        // Remove: every existing relationship this issue owns that is not
        // wanted, grouped by the file that actually stores it.
        //
        // "Owns" has two cases, and getting this wrong is a silent data bug:
        //
        //  - The canonical `from` is this issue. True for every directional
        //    kind, and for `related` whenever this issue has the lower number.
        //  - The canonical `to` is this issue **and** the kind is
        //    non-directional. A `related` association belongs to both
        //    endpoints even though it is stored once, in the lower-numbered
        //    issue's file. `tix edit 5 --links ""` has to remove a
        //    `5 related 3` edge even though it lives in #3's frontmatter and
        //    #5's own file is empty.
        //
        // An *inbound directional* edge is deliberately excluded: if #3 blocks
        // #5, that edge is #3's declaration, and #5 clearing its own
        // relationship set must not silently rewrite #3's dependency graph.
        let issues = self.list_all()?;
        let mut removals: HashMap<u32, Vec<Relationship>> = HashMap::new();
        for candidate in &issues {
            for rel in &candidate.relationships {
                let canonical = rel.canonical();
                let owned_by_us = canonical.from == own
                    || (canonical.to == own && !canonical.kind.is_directional());
                if owned_by_us && !wanted.contains(&canonical) {
                    removals
                        .entry(canonical.from)
                        .or_default()
                        .push(rel.clone());
                }
            }
        }

        // Add: each wanted edge goes into its canonical source's file. One
        // already present is left alone, so the stable id survives.
        let mut additions: HashMap<u32, Vec<(CanonicalEdge, String)>> = HashMap::new();
        for canonical in &wanted {
            let owner = match self.get(IssueSelector::Number(canonical.from)) {
                Ok(owner) => owner,
                Err(TixError::NotFound(_)) => continue,
                Err(e) => return Err(e),
            };
            if owner
                .relationships
                .iter()
                .any(|r| r.canonical() == *canonical)
            {
                continue;
            }
            let target_title = self
                .get(IssueSelector::Number(canonical.to))
                .map(|i| i.title)
                .unwrap_or_default();
            additions
                .entry(canonical.from)
                .or_default()
                .push((*canonical, target_title));
        }

        if removals.is_empty() && additions.is_empty() {
            return Ok(issue);
        }

        // Apply removals, then additions. This can write **N** files — the
        // removals map is keyed by whichever file actually holds each row, and
        // an order-normalized `related` edge is held by the lower-numbered
        // issue, not the one named by `filename`. A failure partway through
        // would therefore leave the store half-mutated, so every file's
        // pre-write contents are captured on the way through and restored if a
        // later write fails (SC-005: no file is left partially rewritten).
        //
        // The restore is best-effort per file and the original error is
        // returned either way: a rollback that itself fails must not mask the
        // cause.
        // Every file's pre-write contents are captured on the way through and
        // restored if a later write in the same call fails, so a refused
        // mutation leaves nothing behind (SC-005). The restore is best-effort
        // per file and the original error is returned either way: a rollback
        // that itself fails must not mask the cause.
        // Owners are written in ascending number order. `removals` and
        // `additions` are `HashMap`s, so iterating them directly makes the write
        // order — and therefore which files are committed before a failure —
        // differ between runs of the same input.
        let mut removal_order: Vec<u32> = removals.keys().copied().collect();
        removal_order.sort_unstable();
        let mut addition_order: Vec<u32> = additions.keys().copied().collect();
        addition_order.sort_unstable();

        // Write one owner, remembering how to undo it. A nested `fn` rather than
        // a closure so `undo` and `touched_named` can be passed explicitly
        // instead of captured, which would make them unborrowable at the
        // call sites.
        fn apply(
            store: &Store,
            mut owner: Issue,
            undo: &mut Vec<(PathBuf, String)>,
            touched_named: &mut bool,
            named_path: &Path,
        ) -> Result<()> {
            let path = store.issues_dir.join(&owner.filename);
            if path == named_path {
                *touched_named = true;
            }
            if let Ok(previous) = std::fs::read_to_string(&path) {
                undo.push((path, previous));
            }
            owner.bump_updated();
            store.update(&owner.filename, &owner).map(|_| ())
        }

        let named_path = self.issues_dir.join(&issue.filename);
        let mut undo: Vec<(PathBuf, String)> = Vec::new();
        let mut touched_named = false;

        let applied = (|| -> Result<()> {
            for owner_number in &removal_order {
                let doomed = &removals[owner_number];
                let mut owner = self.get(IssueSelector::Number(*owner_number))?;
                let mut changed = false;
                for rel in doomed {
                    let canonical = rel.canonical();
                    let before = owner.relationships.len();
                    owner.relationships.retain(|r| r.canonical() != canonical);
                    if owner.relationships.len() != before {
                        let detail = format!("removed {}: {}", rel.id, rel.display);
                        owner.history.append_now(
                            &actor,
                            HistoryEventKind::RelationshipRemoved,
                            &detail,
                        );
                        changed = true;
                    }
                }
                if changed {
                    apply(self, owner, &mut undo, &mut touched_named, &named_path)?;
                }
            }

            for owner_number in &addition_order {
                let wanted_here = &additions[owner_number];
                let mut owner = self.get(IssueSelector::Number(*owner_number))?;
                for (canonical, target_title) in wanted_here {
                    let rel = Relationship::new(
                        canonical.from,
                        canonical.to,
                        canonical.kind,
                        target_title,
                    );
                    let detail = format!("created {}: {}", rel.id, rel.display);
                    owner
                        .history
                        .append_now(&actor, HistoryEventKind::RelationshipAdded, &detail);
                    owner.relationships.push(rel);
                }
                apply(self, owner, &mut undo, &mut touched_named, &named_path)?;
            }

            // F16. The named issue's own frontmatter can be untouched while its
            // relationship set changed, because an order-normalized `related`
            // edge is stored in the *other* endpoint's file. `tix edit 2 --links
            // 1` then left #2 byte-identical with a stale `updated`, so the
            // command appeared to do nothing to the issue it named and the audit
            // trail lived only on the other endpoint. `updated` tracks the
            // issue's last mutation and its relationship set did change.
            //
            // Inside the rolled-back sequence and through the same `apply`, so
            // its file is captured for restore like every other. Placed after the
            // rollback check it was a fresh partial-write hole: a failure here
            // returned an error with the relationship writes already committed
            // and nothing left to restore.
            if !touched_named {
                let named = self.get(IssueSelector::Filename(filename.to_string()))?;
                apply(self, named, &mut undo, &mut touched_named, &named_path)?;
            }
            Ok(())
        })();

        if let Err(e) = applied {
            for (path, previous) in undo.iter().rev() {
                let _ = atomic_write(&self.issues_dir, path, previous.as_bytes());
            }
            return Err(e);
        }

        self.get(IssueSelector::Filename(filename.to_string()))
    }

    /// Resolve a selector string exactly like the selector-taking commands
    /// (`parse_selector`) and fetch the issue (D2: "Resolver SHALL match
    /// `tix edit`/`tix move`").
    ///
    /// `pub` because the `--parent` flags (WP03) resolve a parent selector to its
    /// **number** through this same path, so `#4`, `4` and a title fragment all work
    /// on a parent exactly as they do on any other selector — and a second
    /// resolver in the command layer is how two surfaces end up disagreeing about
    /// which issue a selector names.
    pub fn resolve_issue(&self, raw: &str) -> Result<Issue> {
        let selector = crate::commands::parse_selector(self, raw)?;
        self.get(selector)
    }

    /// Physically move an issue file into the assignee segment of a new
    /// assignee (FR-031, `contracts/file-format.md` rule 9).
    ///
    /// `filename` is a path relative to the issues dir: either a legacy flat
    /// basename (`2026-05-10-fix-login.md`, C-010) or a grouped path
    /// (`alice/2026-05-10-fix-login.md`). It is validated via the relaxed
    /// [`validate_filename`] before anything touches the filesystem, so
    /// traversal attempts are refused here as everywhere else.
    ///
    /// The old assignee segment is read from the current relative path, the
    /// new one derived with [`derive_segment`]; equal segments are a no-op.
    /// The target filename keeps the original `created-slug` stem; when the
    /// target already holds `<stem>.md`, a deterministic `-1`, `-2`, …
    /// suffix is appended by testing existence — an existing file is never
    /// overwritten or deleted. `number`/`created` live in the frontmatter and
    /// are untouched, so issue-number stability is guaranteed by construction
    /// (C-007).
    ///
    /// The move is a single `std::fs::rename` (atomic-ish, same filesystem).
    /// Returns the **new relative path** (matching how `issue.filename` is
    /// stored) on success, including the unchanged relative path for the
    /// equal-segment no-op.
    pub fn reassign(&self, filename: &str, new_assignee: Option<&str>) -> Result<PathBuf> {
        // `get` validates `filename` and errors NotFound when it is missing.
        let issue = self.get(IssueSelector::Filename(filename.to_string()))?;
        let mut updated = issue.clone();
        updated.assignee = new_assignee.map(str::to_string);
        let target_dir = crate::layout::render_directory(&self.config.layout, &updated);
        let (old_dir, base) = split_relative(filename).ok_or_else(|| {
            TixError::InvalidInput(format!("invalid relative issue filename: {filename}"))
        })?;
        if old_dir == target_dir {
            return Ok(PathBuf::from(filename));
        }
        let stem = base.strip_suffix(".md").unwrap_or(&base);
        self.move_issue_file(filename, &target_dir, stem)
    }

    /// Relocate an issue file to an exact store-relative `target` (used by
    /// `tix layout migrate`). Frontmatter and number are preserved because
    /// nothing is rewritten — it is a rename; an occupied target is refused; the
    /// `<slug>-assets/` dir moves alongside.
    pub fn migrate_issue(&self, filename: &str, target: &str) -> Result<()> {
        if target == filename {
            return Ok(());
        }
        validate_filename(target)?;
        let from = self.issues_dir.join(filename);
        if !from.is_file() {
            return Err(TixError::NotFound(format!("file {filename}")));
        }
        let to = self.issues_dir.join(target);
        if to.exists() {
            return Err(TixError::InvalidInput(format!(
                "cannot migrate {filename}: {target} already exists"
            )));
        }
        if let Some(parent) = to.parent() {
            std::fs::create_dir_all(parent)?;
        }
        std::fs::rename(&from, &to)?;
        let (old_dir, base) = split_relative(filename).unwrap_or_default();
        let stem = base.strip_suffix(".md").unwrap_or(&base);
        let asset_name = format!("{}-assets", slug_from_stem(stem));
        let old_asset_dir = self.issues_dir.join(&old_dir).join(&asset_name);
        if old_asset_dir.exists()
            && let Some(new_dir) = to.parent()
        {
            let moved = resolve_asset_dir_name(new_dir, &asset_name);
            std::fs::rename(&old_asset_dir, new_dir.join(&moved))?;
        }
        Ok(())
    }

    /// Move an issue file (and its `<slug>-assets/` dir) from `filename` to
    /// `<target_dir>/<stem>[-N].md`, creating the directory as needed. A target
    /// collision takes the first free `-N` suffix; nothing is overwritten.
    fn move_issue_file(&self, filename: &str, target_dir: &str, stem: &str) -> Result<PathBuf> {
        let target_dir_path = self.issues_dir.join(target_dir);
        std::fs::create_dir_all(&target_dir_path)?;
        let new_name = resolve_target_name(&target_dir_path, stem);
        let old_dir = split_relative(filename).map_or_else(String::new, |(d, _)| d);
        std::fs::rename(
            self.issues_dir.join(filename),
            target_dir_path.join(&new_name),
        )?;
        // Move the `<slug>-assets/` dir alongside the file (FR-007). On a
        // same-named dir in the target, disambiguate rather than overwrite.
        let slug = slug_from_stem(stem);
        let asset_name = format!("{slug}-assets");
        let old_asset_dir = self.issues_dir.join(&old_dir).join(&asset_name);
        if old_asset_dir.exists() {
            let moved = resolve_asset_dir_name(&target_dir_path, &asset_name);
            std::fs::rename(&old_asset_dir, target_dir_path.join(&moved))?;
        }
        Ok(PathBuf::from(format!("{target_dir}/{new_name}")))
    }

    /// Whether `filename` already sits at the directory its templated fields
    /// render to. Used to decide whether a mutation may relocate the file: only a
    /// file already *on* the layout is moved, so a legacy or mismatched path is
    /// left to `tix layout migrate`.
    #[must_use]
    pub fn path_is_laid_out(&self, filename: &str, issue: &Issue) -> bool {
        split_relative(filename).is_some_and(|(dir, _)| {
            dir == crate::layout::render_directory(&self.config.layout, issue)
        })
    }

    /// Move an issue to the directory its templated fields now render to, when
    /// `move_on_change` is set. The basename is preserved. Returns whether it
    /// moved; a no-op when already in place or when `move_on_change` is off.
    pub fn move_to_layout(&self, issue: &mut Issue) -> Result<bool> {
        let before = issue.filename.clone();
        let after = self.reconcile_location(&before, issue)?;
        issue.filename = after.clone();
        Ok(after != before)
    }
}

/// Whether a **relative** path is one [`Store::scan`] would index as an issue
/// file, at any depth (issue #10 follow-up; configurable layout).
///
/// A path is an issue file when every component is a normal name, no component
/// is a `.tix-tmp-*` temp dir or a `<slug>-assets/` dir, and the final component
/// ends in `.md`. Depth is unbounded so the incremental corpus matches a full
/// rebuild under any `[layout]` template.
pub(crate) fn is_issue_rel_path(rel: &Path) -> bool {
    let mut file_name: Option<&std::ffi::OsStr> = None;
    for component in rel.components() {
        match component {
            std::path::Component::Normal(segment) => {
                let Some(s) = segment.to_str() else {
                    return false;
                };
                if s.starts_with(".tix-tmp-") || s.ends_with("-assets") {
                    return false;
                }
                file_name = Some(segment);
            }
            std::path::Component::CurDir => {}
            // RootDir, ParentDir, Prefix: not a store-relative issue path.
            _ => return false,
        }
    }
    file_name.is_some_and(|name| name.to_string_lossy().ends_with(".md"))
}

/// Validate an issue filename. A filename is either a legacy flat basename
/// (`2026-05-10-fix-login.md`) or a grouped path with exactly one assignee
/// segment prefix (`alice/2026-05-10-fix-login.md`, C-008/C-010).
///
/// Refused in all cases: NUL bytes, backslashes, the `..` component, empty
/// components (leading/trailing/double slashes), absolute / leading-slash
/// paths, and nesting deeper than one segment. Every refusal is a hard
/// [`TixError::InvalidInput`] raised before any filesystem touch.
fn validate_filename(filename: &str) -> Result<()> {
    if filename.is_empty() {
        return Err(TixError::InvalidInput(format!(
            "filename must not be empty: {filename:?}"
        )));
    }
    if filename.starts_with('/') {
        return Err(TixError::InvalidInput(format!(
            "filename must be relative (no leading `/`): {filename}"
        )));
    }
    if filename.contains('\\') {
        return Err(TixError::InvalidInput(format!(
            "filename must not contain backslashes: {filename}"
        )));
    }
    if filename.contains("..") {
        return Err(TixError::InvalidInput(format!(
            "filename must not contain `..`: {filename}"
        )));
    }
    if filename.contains('\0') {
        return Err(TixError::InvalidInput(format!(
            "filename must not contain NUL: {filename}"
        )));
    }
    if filename.split('/').any(|component| component.is_empty()) {
        return Err(TixError::InvalidInput(format!(
            "filename path components must not be empty: {filename}"
        )));
    }
    Ok(())
}

/// Split a validated relative filename into `(segment, basename)`. Legacy
/// flat filenames have an empty segment (`("", "2026-05-10-x.md")`), grouped
/// ones carry exactly one segment (`("alice", "2026-05-10-x.md")`). [`None`]
/// for anything that survived a bad path shape.
/// The `number:` field of an issue file's frontmatter, without a full parse.
///
/// `Store::delete` needs the number of the issue it is removing so it can free that
/// number's claim, and it needs it *before* the file is gone. A full `Issue` parse
/// would be the obvious way, but this sits on the delete path and only needs one
/// scalar, so a scoped scan is enough — and it cannot fail on an issue that would
/// fail to load, which keeps `delete`'s existing "removes the file" contract
/// (#1352) independent of frontmatter validity.
///
/// The scan stops at the closing `---` so a `number:` in the **body** cannot be
/// mistaken for the field.
fn frontmatter_number(text: &str) -> Option<u32> {
    let mut lines = text.lines();
    // The opening delimiter. A file that does not start with one has no frontmatter.
    if lines.next()?.trim() != "---" {
        return None;
    }
    for line in lines {
        let line = line.trim_end();
        // The closing delimiter ends the frontmatter, so a `number:` after it is
        // body text and must not be mistaken for the field.
        if line == "---" {
            return None;
        }
        if let Some(rest) = line.strip_prefix("number:") {
            return rest.trim().parse().ok();
        }
    }
    None
}

/// The directory holding one marker per claimed number.
///
/// **A sibling of the issues directory, not a child of it.** `docs/issues/` is the
/// tool's source of truth: people hand-edit it, script against it, and glob it, and
/// its contents are committed. Adding an internal directory inside it changes what
/// every one of those consumers sees — a test helper that counts segments, a `for`
/// loop over `docs/issues/*`, a CI check — for machinery no reader should have to
/// know about. Beside it, `docs/issues/` contains exactly what it did before.
///
/// Derived from the configured `issues_dir` rather than hardcoded, so a repo that
/// points `issues_dir` somewhere else still gets a ledger beside that.
fn claims_dir(issues_dir: &Path) -> PathBuf {
    issues_dir
        .parent()
        .unwrap_or(issues_dir)
        .join(NumberClaim::DIR)
}

fn split_relative(filename: &str) -> Option<(String, String)> {
    let mut parts = filename.rsplitn(2, '/');
    let basename = parts.next()?;
    let segment = parts.next().unwrap_or("");
    Some((segment.to_string(), basename.to_string()))
}

/// Flip the archived marker on a store-relative issue filename.
///
/// `alice/2026-01-01-x.md` → `alice/.2026-01-01-x.md` when `archive` is true,
/// and the inverse when false. Only the basename's leading dot changes; the
/// segment stays put, so the file never moves between directories. `None` when
/// the name is already in the requested state.
fn flip_archived(filename: &str, archive: bool) -> Option<String> {
    let (segment, basename) = split_relative(filename)?;
    let flipped = if archive {
        if basename.starts_with('.') {
            return None;
        }
        format!(".{basename}")
    } else {
        basename.strip_prefix('.')?.to_string()
    };
    Some(if segment.is_empty() {
        flipped
    } else {
        format!("{segment}/{flipped}")
    })
}

/// The first free `<stem>.md` / `<stem>-1.md` / `<stem>-2.md` … name in
/// `dir` (deterministic existence probe). Never returns an existing name.
fn resolve_target_name(dir: &Path, stem: &str) -> String {
    let mut candidate = format!("{stem}.md");
    let mut i = 1u32;
    while dir.join(&candidate).exists() {
        candidate = format!("{stem}-{i}.md");
        i += 1;
    }
    candidate
}

/// The slug used for the asset dir: the issue filename stem minus the leading
/// `YYYY-MM-DD-` date prefix (`2026-09-13-fix-login-bug` → `fix-login-bug`).
/// When the stem has no date prefix it is used as-is (legacy fallback).
fn slug_from_stem(stem: &str) -> String {
    let bytes = stem.as_bytes();
    if stem.len() > 10 && bytes[4] == b'-' && bytes[7] == b'-' && bytes[10] == b'-' {
        stem[11..].to_string()
    } else {
        stem.to_string()
    }
}

/// The first free `<name>` / `<name>-<n>.<ext>` name for an asset in `dir`.
/// When `<name>` is taken the extension is kept and a deterministic
/// numeric suffix is appended (FR-006).
fn resolve_asset_name(dir: &Path, name: &str) -> String {
    if !dir.join(name).exists() {
        return name.to_string();
    }
    let (stem, ext) = match name.rsplit_once('.') {
        Some((s, e)) => (s, format!(".{e}")),
        None => (name, String::new()),
    };
    let mut i = 1u32;
    loop {
        let candidate = format!("{stem}-{i}{ext}");
        if !dir.join(&candidate).exists() {
            return candidate;
        }
        i += 1;
    }
}

/// The first free `<name>` / `<name>-1` / `<name>-2` … directory name in
/// `dir` (mirrors `resolve_target_name` for the `<slug>-assets/` move).
fn resolve_asset_dir_name(dir: &Path, name: &str) -> String {
    let mut candidate = name.to_string();
    let mut i = 1u32;
    while dir.join(&candidate).exists() {
        candidate = format!("{name}-{i}");
        i += 1;
    }
    candidate
}

/// Copy a file atomically into `dir` under `target` (temp + rename, NFR-004).
/// The temp file is cleaned up on failure and never left behind.
fn atomic_copy(dir: &Path, target: &Path, source: &Path) -> Result<()> {
    let pid = std::process::id();
    let nonce = nanos();
    let tmp = dir.join(format!(".tix-tmp-{pid}-{nonce}"));
    let copy_result = (|| -> std::io::Result<()> {
        std::fs::copy(source, &tmp)?;
        let f = std::fs::File::open(&tmp)?;
        f.sync_all()?;
        Ok(())
    })();
    if let Err(e) = copy_result {
        let _ = std::fs::remove_file(&tmp);
        return Err(TixError::Io(e));
    }
    if let Err(e) = std::fs::rename(&tmp, target) {
        let _ = std::fs::remove_file(&tmp);
        return Err(TixError::Io(e));
    }
    Ok(())
}

/// Whether an asset file name is an image by extension (the `![…]` link form).
fn is_image_name(name: &str) -> bool {
    matches!(
        name.rsplit('.')
            .next()
            .unwrap_or("")
            .to_ascii_lowercase()
            .as_str(),
        "png" | "jpg" | "jpeg" | "gif" | "svg" | "webp" | "bmp"
    )
}

fn atomic_write(dir: &Path, target: &Path, data: &[u8]) -> Result<()> {
    write_file(dir, target, data, Link::Overwrite)
}

/// Write `data` to `target`, refusing to replace an existing file.
///
/// [`atomic_write`] uses `rename`, which replaces the target unconditionally and is
/// therefore the wrong tool for *creating* an issue: a name collision would destroy
/// the file already there. This writes the payload to a temp file, `fsync`s it, and
/// then creates `target` with `hard_link`, which is atomic and fails with
/// `AlreadyExists` if the name is taken. The temp file is removed either way.
///
/// A hard link is the portable way to get `O_EXCL`-style semantics on the final
/// path (it works on unix and Windows and needs no new dependency). The temp file
/// lives in the same directory, so it is always on the same filesystem and the link
/// cannot fail for that reason. If the link is refused for any other reason — a
/// filesystem without hard links, say — it falls back to `rename`, which keeps
/// atomicity but is no longer no-clobber, and the caller's own probe is the
/// remaining protection.
///
/// The directory `fsync` that follows the link is what makes the *name* durable, so
/// it is not skippable on the fallback path either.
fn write_file_new(dir: &Path, target: &Path, data: &[u8]) -> Result<()> {
    write_file(dir, target, data, Link::Exclusive)
}

#[derive(Clone, Copy)]
enum Link {
    Overwrite,
    Exclusive,
}

fn write_file(dir: &Path, target: &Path, data: &[u8], link: Link) -> Result<()> {
    let pid = std::process::id();
    let nonce = nanos();
    let tmp = dir.join(format!(".tix-tmp-{pid}-{nonce}"));
    let write_result = (|| -> std::io::Result<()> {
        let mut f = std::fs::File::create(&tmp)?;
        use std::io::Write;
        f.write_all(data)?;
        f.sync_all()?;
        Ok(())
    })();
    if let Err(e) = write_result {
        let _ = std::fs::remove_file(&tmp);
        return Err(TixError::Io(e));
    }
    let link_result = match link {
        Link::Overwrite => std::fs::rename(&tmp, target),
        Link::Exclusive => match std::fs::hard_link(&tmp, target) {
            // The name was taken: the payload is already durable, so only the link
            // failed. `AlreadyExists` is the signal `write_new_issue_file` retries on,
            // so it is propagated rather than flattened into a generic I/O error.
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Err(e),
            // No hard links on this filesystem. Atomicity survives; the no-clobber
            // guarantee does not, and the caller's probe is what is left.
            Err(_) => std::fs::rename(&tmp, target),
            Ok(()) => {
                let _ = std::fs::remove_file(&tmp);
                Ok(())
            }
        },
    };
    if let Err(e) = link_result {
        let _ = std::fs::remove_file(&tmp);
        return Err(TixError::Io(e));
    }
    let _ = std::fs::File::open(dir).and_then(|f| f.sync_all());
    Ok(())
}

fn nanos() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos() as u64)
        .unwrap_or(0)
}

#[cfg(test)]
mod tests {
    use super::*;
    // Only the tests need this; the library path went through `render_diagnostics`.
    use crate::model::{Priority, today};
    use crate::relationships::DiagnosticKind;
    use std::fs;
    use tempfile::TempDir;

    /// The no-clobber layer, tested directly.
    ///
    /// `write_new_issue_file`'s **probe** is the common path and is covered end to
    /// end by `two_creates_with_the_same_title_both_survive` in `tests/cli.rs`.
    /// The probe cannot see a name another process takes between the probe and the
    /// write, which is why the final create is exclusive. This is the guarantee that
    /// closes that window, so it is asserted on the primitive rather than through a
    /// race that would be flaky to provoke.
    ///
    /// If the exclusive path were replaced by a `rename` — the obvious "simplify
    /// this" edit — the planted file below would be silently destroyed, which is
    /// precisely the data loss `write_new_issue_file` exists to prevent.
    #[test]
    fn write_file_new_refuses_an_existing_target() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("issue.md");
        write_file_new(dir.path(), &target, b"first").unwrap();
        assert_eq!(fs::read_to_string(&target).unwrap(), "first");

        let err = write_file_new(dir.path(), &target, b"second").unwrap_err();
        let TixError::Io(io_err) = err else {
            panic!("expected an I/O error, so the caller can retry on a name collision")
        };
        assert_eq!(
            io_err.kind(),
            std::io::ErrorKind::AlreadyExists,
            "the error must be AlreadyExists, so the caller can retry on a name \\
             collision rather than treating it as a hard failure"
        );
        assert_eq!(
            fs::read_to_string(&target).unwrap(),
            "first",
            "the existing file must be byte-identical — not truncated, not replaced"
        );
    }

    /// The retry loop turns an `AlreadyExists` into the next free name.
    #[test]
    fn a_clobbered_name_is_retried_rather_than_failing_or_overwriting() {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path();
        let store = Store::open(&crate::config::Config {
            issues_dir: dir.to_path_buf(),
            ..Default::default()
        })
        .unwrap();

        // The probe looks at `<issues_dir>/<segment>/<stem>.md`, so the plants have
        // to sit in the segment directory — that is where the collision is.
        let segment_dir = dir.join("seg");
        fs::create_dir_all(&segment_dir).unwrap();

        // Two plants on the exact names the probe would try first, so the retry has
        // to walk past both to reach the third.
        for name in ["2026-01-01-race.md", "2026-01-01-race-2.md"] {
            fs::write(segment_dir.join(name), "planted").unwrap();
        }

        let (filename, path) = store
            .write_new_issue_file("seg", "2026-01-01-race", b"mine")
            .unwrap();
        assert_eq!(filename, "seg/2026-01-01-race-3.md");
        assert_eq!(fs::read_to_string(&path).unwrap(), "mine");
        assert_eq!(
            fs::read_to_string(segment_dir.join("2026-01-01-race.md")).unwrap(),
            "planted"
        );
        assert_eq!(
            fs::read_to_string(segment_dir.join("2026-01-01-race-2.md")).unwrap(),
            "planted"
        );
    }

    /// No temp files are left behind on either the success or the collision path.
    ///
    /// A leftover `.tix-tmp-*` in `docs/issues/<segment>/` would be picked up by the
    /// next `tix list` as a malformed issue, and the exclusive path has an extra
    /// step (`hard_link` then `remove_file`) where a leak is easy to introduce.
    #[test]
    fn no_temp_files_are_left_behind_on_success_or_collision() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("issue.md");
        write_file_new(dir.path(), &target, b"first").unwrap();
        let _ = write_file_new(dir.path(), &target, b"second");
        let leftovers: Vec<String> = fs::read_dir(dir.path())
            .unwrap()
            .filter_map(|e| e.ok())
            .map(|e| e.file_name().to_string_lossy().to_string())
            .filter(|n| n.starts_with(".tix-tmp-"))
            .collect();
        assert!(
            leftovers.is_empty(),
            "temp files must not survive, found {leftovers:?}"
        );
    }

    fn make_store() -> (tempfile::TempDir, Store) {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let mut config = Config {
            issues_dir: dir.clone(),
            ..Config::default()
        };
        // Storage unit tests predate configurable layout and assert the legacy
        // one-segment paths; pin it and disable move-on-change so they stay about
        // grouping, not layout. Both the default template and auto-migration are
        // covered by dedicated tests.
        config.layout.directory = "{assignee}".to_string();
        config.layout.move_on_change = false;
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let store = Store {
            issues_dir: dir,
            config,
        };
        (tmp, store)
    }

    fn write_issue(store: &Store, name: &str, contents: &str) {
        fs::write(store.issues_dir.join(name), contents).unwrap();
    }

    fn sample_frontmatter(number: u32, title: &str, status: &str) -> String {
        format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"{status}\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text."
        )
    }

    // ------------------------------------------------------------------
    // Issue #1492 — archived issues (dot-prefixed filename, in place)
    // ------------------------------------------------------------------

    /// The default walk must skip a dot-prefixed file **without opening it**, so
    /// an archived file with unparseable frontmatter cannot break `list()`. That
    /// an unparseable one is *only* reachable through `list_all()` is the cheapest
    /// honest proof the skip happens before the read.
    #[test]
    fn list_never_opens_an_archived_file_but_list_all_does() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-active.md",
            &sample_frontmatter(1, "Active", "todo"),
        );
        fs::write(
            store.issues_dir.join("alice/.2026-01-02-broken.md"),
            "this file has no frontmatter at all\n",
        )
        .unwrap();

        let active = store
            .list()
            .expect("the default walk must not read the archived file");
        assert_eq!(active.len(), 1);
        assert_eq!(active[0].number, 1);
        assert!(!active[0].archived);

        let all = store.list_all();
        assert!(
            matches!(all, Err(TixError::Parse(_))),
            "list_all() reads it, so the broken file is only invisible to list(): {all:?}"
        );
    }

    #[test]
    fn archive_renames_in_place_and_restore_is_the_inverse() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );

        let archived = store.archive("5").unwrap();
        assert_eq!(archived.filename, "alice/.2026-01-01-x.md");
        assert!(archived.archived);
        assert!(store.issues_dir.join("alice/.2026-01-01-x.md").is_file());
        assert!(!store.issues_dir.join("alice/2026-01-01-x.md").exists());
        assert!(
            store.list().unwrap().is_empty(),
            "hidden from the default view"
        );

        let all = store.list_all().unwrap();
        assert_eq!(all.len(), 1);
        assert!(all[0].archived);
        assert_eq!(all[0].number, 5, "the number is untouched");

        // Both selectors still resolve the archived issue.
        assert_eq!(
            store.get(IssueSelector::Number(5)).unwrap().filename,
            "alice/.2026-01-01-x.md"
        );
        assert!(store.get(IssueSelector::Slug(slugify("X"))).is_ok());

        let restored = store.restore("5").unwrap();
        assert_eq!(restored.filename, "alice/2026-01-01-x.md");
        assert!(!restored.archived);
        assert_eq!(store.list().unwrap().len(), 1, "visible again");
    }

    #[test]
    fn archive_appends_one_event_and_leaves_the_frontmatter_untouched() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );
        let before = store
            .get(IssueSelector::Filename("alice/2026-01-01-x.md".into()))
            .unwrap();

        let archived = store.archive("5").unwrap();
        assert_eq!(archived.history.len(), 1, "exactly one History event");
        assert_eq!(
            archived.history.events()[0].kind,
            HistoryEventKind::Archived
        );

        let after = store.get(IssueSelector::Number(5)).unwrap();
        // Every field a reader cares about survives unchanged. `update` re-renders
        // the frontmatter (quoting and key order normalize, as on every tix write),
        // so the invariant is the *values*, not the bytes.
        assert_eq!(after.number, before.number);
        assert_eq!(after.title, before.title);
        assert_eq!(after.status, before.status);
        assert_eq!(after.labels, before.labels);
        assert_eq!(after.priority, before.priority);
        assert_eq!(after.assignee, before.assignee);
        assert_eq!(after.created, before.created);
        assert_eq!(
            after.updated, before.updated,
            "archiving must not bump `updated`: it is a frontmatter field"
        );
        // The marker is the filename; nothing was written into the frontmatter.
        let raw = read_issue_file(&store, "alice/.2026-01-01-x.md");
        let fm = raw.split("\n---").next().unwrap();
        assert!(
            !fm.contains("archived"),
            "the archived flag must never reach the frontmatter: {fm}"
        );
    }

    #[test]
    fn restore_appends_one_restored_event() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );
        store.archive("5").unwrap();
        let restored = store.restore("5").unwrap();
        assert_eq!(restored.history.len(), 2, "archive + restore");
        assert_eq!(
            restored.history.events()[1].kind,
            HistoryEventKind::Restored
        );
    }

    #[test]
    fn archiving_the_highest_number_does_not_free_it_for_reuse() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(
            &store,
            "alice/2026-01-01-b.md",
            &sample_frontmatter(7, "B", "todo"),
        );

        store.archive("7").unwrap();

        let mut fresh = Issue::parse(&sample_frontmatter(0, "New", "todo")).unwrap();
        store.create(&mut fresh, "body", None).unwrap();
        assert_eq!(
            fresh.number, 8,
            "an archived issue keeps its number: `create` must not reuse #7"
        );
    }

    #[test]
    fn redundant_archive_and_restore_are_refused_by_name() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );

        let err = store.restore("5").unwrap_err();
        assert!(
            err.to_string().contains("not_archived"),
            "an active issue cannot be restored: {err}"
        );
        assert!(
            store.issues_dir.join("alice/2026-01-01-x.md").is_file(),
            "the refused restore writes nothing"
        );

        store.archive("5").unwrap();
        let err = store.archive("5").unwrap_err();
        assert!(
            err.to_string().contains("already_archived"),
            "an archived issue cannot be re-archived: {err}"
        );
        assert!(
            store.issues_dir.join("alice/.2026-01-01-x.md").is_file(),
            "the refused archive writes nothing"
        );
    }

    #[test]
    fn archive_never_clobbers_an_occupied_target_name() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );
        // A pre-existing dot-prefixed file would be the target of the rename.
        write_issue(
            &store,
            "alice/.2026-01-01-x.md",
            &sample_frontmatter(6, "Other", "todo"),
        );
        let err = store.archive("5").unwrap_err();
        assert!(err.to_string().contains("already exists"), "got: {err}");
        assert!(store.issues_dir.join("alice/2026-01-01-x.md").is_file());
        assert!(store.issues_dir.join("alice/.2026-01-01-x.md").is_file());
    }

    #[test]
    fn archive_and_restore_a_legacy_flat_file_in_place() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &sample_frontmatter(3, "Legacy", "todo"),
        );

        let archived = store.archive("3").unwrap();
        assert_eq!(archived.filename, ".2026-01-01-legacy.md");
        assert!(store.issues_dir.join(".2026-01-01-legacy.md").is_file());
        assert!(store.list().unwrap().is_empty());
        assert_eq!(store.list_all().unwrap().len(), 1);

        let restored = store.restore("3").unwrap();
        assert_eq!(restored.filename, "2026-01-01-legacy.md");
        assert!(store.issues_dir.join("2026-01-01-legacy.md").is_file());
    }

    #[test]
    fn list_returns_sorted_by_filename() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-03-01-c.md",
            &sample_frontmatter(3, "C", "todo"),
        );
        write_issue(
            &store,
            "2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(
            &store,
            "2026-02-01-b.md",
            &sample_frontmatter(2, "B", "todo"),
        );
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 3);
        assert_eq!(issues[0].number, 1);
        assert_eq!(issues[1].number, 2);
        assert_eq!(issues[2].number, 3);
        assert_eq!(issues[0].title, "A");
    }

    // Issue #10 follow-up — the single-file reader behind `Corpus::apply`.

    #[test]
    fn is_issue_rel_path_matches_what_scan_walks() {
        // `scan` indexes these.
        for path in [
            "a.md",
            "alice/b.md",
            ".hidden.md",
            "alice/.hidden.md",
            "deep/a/b.md",
        ] {
            assert!(
                is_issue_rel_path(Path::new(path)),
                "{path} is an issue file `scan` reads"
            );
        }
        // ...and skips these.
        for path in [
            "notes.txt",
            "alice/notes.txt",
            "alice",
            ".tix-tmp-x/a.md",
            "foo-assets/a.md",
            "alice/foo-assets/a.md",
        ] {
            assert!(
                !is_issue_rel_path(Path::new(path)),
                "{path} is not a path `scan` indexes"
            );
        }
    }

    #[test]
    fn scan_above_the_parallel_threshold_is_sorted_and_complete() {
        // The parallel branch runs only above `PARALLEL_SCAN_THRESHOLD`, so a
        // small fixture never reaches it. This pins that the fan-out keeps every
        // file, in filename order, with the same numbering a serial walk gives.
        let (tmp, store) = make_store();
        let _ = tmp;
        let n = Store::PARALLEL_SCAN_THRESHOLD + 44;
        for i in (1..=n).rev() {
            write_issue(
                &store,
                &format!("2026-01-01-{i:04}.md"),
                &sample_frontmatter(i as u32, &format!("T{i}"), "todo"),
            );
        }
        let issues = store.list().unwrap();
        assert_eq!(
            issues.len(),
            n,
            "every file is read, none dropped or doubled"
        );
        let names: Vec<&str> = issues.iter().map(|i| i.filename.as_str()).collect();
        let mut sorted = names.clone();
        sorted.sort_unstable();
        assert_eq!(names, sorted, "sorted by filename as `scan` promises");
        assert_eq!(issues[0].number, 1, "content came from the first file");
        assert_eq!(issues[n - 1].number, n as u32, "and from the last");
    }

    #[test]
    fn read_issue_at_sets_filename_and_archived_like_scan() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(
            &store,
            "alice/.2026-01-02-b.md",
            &sample_frontmatter(2, "B", "todo"),
        );

        let active = store
            .read_issue_at(Path::new("alice/2026-01-01-a.md"))
            .unwrap();
        assert_eq!(active.number, 1);
        assert_eq!(active.filename, "alice/2026-01-01-a.md");
        assert!(!active.archived);

        let archived = store
            .read_issue_at(Path::new("alice/.2026-01-02-b.md"))
            .unwrap();
        assert_eq!(archived.filename, "alice/.2026-01-02-b.md");
        assert!(
            archived.archived,
            "the leading dot marks it archived, as `scan` does"
        );

        // A flat file keeps its bare basename, and a missing one is `NotFound`.
        write_issue(&store, "flat.md", &sample_frontmatter(3, "F", "todo"));
        assert_eq!(
            store.read_issue_at(Path::new("flat.md")).unwrap().filename,
            "flat.md"
        );
        assert!(matches!(
            store.read_issue_at(Path::new("alice/gone.md")),
            Err(TixError::NotFound(_))
        ));
    }

    #[test]
    fn list_ignores_non_md_files() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(&store, "readme.txt", "not an issue");
        write_issue(&store, "2026-01-01-sub", "no extension");
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
    }

    #[test]
    fn list_errors_on_malformed_frontmatter() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(&store, "2026-01-01-bad.md", "no frontmatter here\n");
        let err = store.list().unwrap_err();
        assert!(matches!(err, TixError::Parse(_)), "got {err:?}");
    }

    #[test]
    fn get_by_number() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-x.md",
            &sample_frontmatter(5, "X", "todo"),
        );
        let issue = store.get(IssueSelector::Number(5)).unwrap();
        assert_eq!(issue.title, "X");
    }

    #[test]
    fn get_by_filename() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-y.md",
            &sample_frontmatter(2, "Y", "done"),
        );
        let issue = store
            .get(IssueSelector::Filename("2026-01-01-y.md".into()))
            .unwrap();
        assert_eq!(issue.status.display(), "done");
    }

    #[test]
    fn get_by_slug() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-z.md",
            &sample_frontmatter(3, "Z", "todo"),
        );
        let issue = store.get(IssueSelector::Slug("z".into())).unwrap();
        assert_eq!(issue.number, 3);
    }

    #[test]
    fn get_not_found() {
        let (tmp, store) = make_store();
        let _ = tmp;
        assert!(store.get(IssueSelector::Number(99)).is_err());
    }

    #[test]
    fn create_assigns_number_from_live_issues_and_leaves_config_untouched() {
        let (tmp, store) = make_store();
        let _ = tmp;
        assert_eq!(store.config.state.next_number, 0);
        let mut issue = Issue {
            number: 0,
            title: "First".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let path = store.create(&mut issue, "Hello world", None).unwrap();
        assert!(path.exists());
        assert_eq!(
            issue.number, 1,
            "an empty store starts at 1, not 0 — #0 is indistinguishable from a \
             sentinel or a failed read (tix #1376)"
        );
        // Issue #52: create never rewrites tix.toml with a counter.
        let config_path = tmp.path().join("tix.toml");
        let on_disk = std::fs::read_to_string(&config_path).unwrap();
        assert!(
            !on_disk.contains("next_number"),
            "create must not persist an issue-number counter:\n{on_disk}"
        );
        let reloaded = Config::load_with_warning(&config_path, |_| {}).unwrap();
        assert_eq!(reloaded.state.next_number, 0, "state is never written");
    }

    #[test]
    fn create_resolves_max_live_number_plus_one() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-a.md",
            &sample_frontmatter(0, "A", "todo"),
        );
        write_issue(
            &store,
            "2026-01-01-b.md",
            &sample_frontmatter(1, "B", "todo"),
        );
        write_issue(
            &store,
            "2026-01-01-c.md",
            &sample_frontmatter(2, "C", "todo"),
        );
        let mut issue = Issue {
            number: 0,
            title: "D".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue, "", None).unwrap();
        assert_eq!(issue.number, 3);
    }

    #[test]
    fn create_reuses_number_of_deleted_highest_issue() {
        // Issue #52 tradeoff: without a persisted counter the next number is
        // re-derived from the live set, so deleting the highest-numbered
        // issue lets its number be reused by the next create.
        let (_tmp, store) = make_store();
        let mut issue_a = Issue {
            number: 0,
            title: "A".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue_a, "", None).unwrap();
        let filename = issue_a.filename.clone();
        assert_eq!(issue_a.number, 1, "the first issue in a fresh store is #1");
        store.delete(&filename).unwrap();
        let mut issue_b = Issue {
            number: 0,
            title: "B".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-02".into(),
            type_: None,
            updated: "2026-01-02".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue_b, "", None).unwrap();
        assert_eq!(
            issue_b.number, 1,
            "an emptied store resumes at the same floor as a fresh one: 1"
        );
    }

    #[test]
    fn create_with_custom_filename_stem() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let path = store
            .create(&mut issue, "body", Some("custom-stem"))
            .unwrap();
        assert!(path.to_string_lossy().contains("custom-stem.md"));
    }

    #[test]
    fn create_ensures_issues_dir_exists() {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("nested").join("issues");
        let config_path = tmp.path().join("tix.toml");
        let config = Config {
            issues_dir: dir.clone(),
            ..Config::default()
        };
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let store = Store {
            issues_dir: dir,
            config,
        };
        let mut issue = Issue {
            number: 0,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue, "", None).unwrap();
        assert_eq!(issue.number, 1, "the first issue in a fresh store is #1");
    }

    #[test]
    fn update_replaces_content_atomically() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-u.md",
            &sample_frontmatter(1, "U", "todo"),
        );
        let mut issue = store
            .get(IssueSelector::Filename("2026-01-01-u.md".into()))
            .unwrap();
        issue.title = "Updated".into();
        issue.bump_updated();
        store.update("2026-01-01-u.md", &issue).unwrap();
        let reloaded = store
            .get(IssueSelector::Filename("2026-01-01-u.md".into()))
            .unwrap();
        assert_eq!(reloaded.title, "Updated");
    }

    #[test]
    fn update_not_found() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let issue = Issue {
            number: 1,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        assert!(store.update("nope.md", &issue).is_err());
    }

    #[test]
    fn delete_removes_file() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-d.md",
            &sample_frontmatter(1, "D", "todo"),
        );
        assert!(store.issues_dir.join("2026-01-01-d.md").exists());
        store.delete("2026-01-01-d.md").unwrap();
        assert!(!store.issues_dir.join("2026-01-01-d.md").exists());
    }

    #[test]
    fn delete_not_found() {
        let (tmp, store) = make_store();
        let _ = tmp;
        assert!(store.delete("nope.md").is_err());
    }

    #[test]
    fn stray_tmp_file_not_treated_as_issue() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        fs::write(store.issues_dir.join(".tix-tmp-9999-0"), "orphaned data").unwrap();
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
    }

    // ------------------------------------------------------------------
    // WP03 T015 — the storage seam's contract, as executable evidence
    // ------------------------------------------------------------------
    //
    // Every case asserts the **file bytes**, not just the returned `Result`. A
    // refusal that returns an error after having already re-serialised the issue
    // would pass an `is_err()` assertion and still have destroyed the audit trail,
    // so "did it refuse?" and "did it touch anything?" are separate questions here
    // and both are asked.

    /// A store whose board **declares a `category_map`**, so category policy —
    /// the terminal lock and adjacency — applies.
    ///
    /// The mapping is `todo=unstarted, doing=active, done=completed`, which is
    /// forward-moving in the declared vocabulary order. `triage` is added as a
    /// `backlog` column so there is a genuine backwards move to be refused.
    fn seam_store() -> (tempfile::TempDir, Store) {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let mut config = Config {
            issues_dir: dir.clone(),
            kanban: crate::config::KanbanSection {
                configurations: indexmap::IndexMap::from([(
                    "default".to_string(),
                    crate::config::BoardConfiguration {
                        columns: vec![
                            "triage".into(),
                            "todo".into(),
                            "doing".into(),
                            "done".into(),
                        ],
                        done_column: Some("done".to_string()),
                        category_map: indexmap::IndexMap::from([
                            ("triage".to_string(), "backlog".to_string()),
                            ("todo".to_string(), "unstarted".to_string()),
                            ("doing".to_string(), "active".to_string()),
                            ("done".to_string(), "completed".to_string()),
                        ]),
                        ..Default::default()
                    },
                )]),
            },
            ..Config::default()
        };
        config.layout.move_on_change = false;
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        (
            tmp,
            Store {
                issues_dir: dir,
                config,
            },
        )
    }

    /// A seam store holding one issue at `status`, and that file's bytes.
    ///
    /// The fixture carries every key the model always writes, `files` included.
    /// That is not tidiness: `t015_no_new_frontmatter_key_was_introduced` compares
    /// the key set before and after, and a fixture that omits `files` makes the
    /// comparison report the model's own always-written key as a change — so the
    /// test would have been measuring the fixture instead of the seam.
    fn seam_issue(status: &str) -> (tempfile::TempDir, Store, String) {
        let (tmp, store) = seam_store();
        write_issue(
            &store,
            "2026-01-01-seam.md",
            &format!(
                "---\nnumber: 1\ntitle: \"Seam\"\nstatus: {status}\nlabels: []\n\
                 priority: \"medium\"\nfiles: []\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody."
            ),
        );
        let before = read_issue_file(&store, "2026-01-01-seam.md");
        (tmp, store, before)
    }

    /// Assert a refusal left the file byte-identical.
    fn assert_untouched(store: &Store, before: &str, what: &str) {
        let after = read_issue_file(store, "2026-01-01-seam.md");
        assert_eq!(after, before, "{what}: the file must be byte-identical");
    }

    #[test]
    fn t015_accepted_transition_writes_status_bumps_updated_and_appends_one_decision() {
        let (_tmp, store, _before) = seam_issue("todo");
        let outcome = store
            .set_status("2026-01-01-seam.md", StatusChange::to("doing"))
            .unwrap();
        assert!(outcome.written, "an accepted, changing move writes");
        let decision = outcome
            .decision
            .clone()
            .expect("an accepted transition appends exactly one decision");
        assert_eq!(decision.from, "todo");
        assert_eq!(decision.to, "doing");
        assert_eq!(decision.from_category, "unstarted");
        assert_eq!(decision.to_category, "active");
        assert!(
            decision.override_reason.is_none(),
            "no override was supplied"
        );
        assert_eq!(
            outcome.issue.status.display(),
            "doing",
            "Issue.status holds the COLUMN name, never a category (C-001)"
        );
        assert_eq!(outcome.issue.updated, today(), "`updated` is bumped");

        // Re-read from disk: the in-memory record is not evidence of what landed.
        let reloaded = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(reloaded.status.display(), "doing");
        let events = reloaded.history.events();
        assert_eq!(
            events.len(),
            1,
            "exactly one History entry, and it is the decision: {events:?}"
        );
        assert_eq!(events[0].kind, HistoryEventKind::TransitionAccepted);
        assert_eq!(
            crate::model::TransitionDecision::from_event(events[0])
                .unwrap()
                .to,
            "doing",
            "and the decision round-trips out of the file with its fields intact"
        );
    }

    #[test]
    fn t015_unknown_column_is_refused_by_name_and_writes_nothing() {
        let (_tmp, store, before) = seam_issue("todo");
        let err = store
            .set_status("2026-01-01-seam.md", StatusChange::to("nope"))
            .unwrap_err();
        assert!(
            matches!(&err, TixError::Workflow(d) if d.kind.as_str() == "unknown_column"),
            "the shared named diagnostic, contract §6: {err:?}"
        );
        assert!(
            err.to_string()
                .contains("valid columns: triage, todo, doing, done"),
            "in BOARD order, not hash order: {err}"
        );
        assert_untouched(&store, &before, "unknown column");
    }

    #[test]
    fn t015_terminal_exit_is_refused_and_writes_nothing() {
        let (_tmp, store, before) = seam_issue("done");
        let err = store
            .set_status("2026-01-01-seam.md", StatusChange::to("todo"))
            .unwrap_err();
        assert!(
            matches!(&err, TixError::Workflow(d) if d.kind.as_str() == "invalid_transition"),
            "{err:?}"
        );
        assert_untouched(&store, &before, "terminal exit without a reason");
    }

    #[test]
    fn t015_adjacency_restricted_backwards_move_is_refused_and_writes_nothing() {
        // `doing` is `active`; `triage` is `backlog`. Forward in the declared
        // vocabulary order, so no terminal lock applies — this is adjacency alone,
        // and it must name the same `invalid_transition` kind.
        let (_tmp, store, before) = seam_issue("doing");
        let err = store
            .set_status("2026-01-01-seam.md", StatusChange::to("triage"))
            .unwrap_err();
        assert!(
            matches!(&err, TixError::Workflow(d) if d.kind.as_str() == "invalid_transition"),
            "{err:?}"
        );
        assert!(
            err.to_string().contains("category policy"),
            "the message names the rule that refused it: {err}"
        );
        assert_untouched(&store, &before, "adjacency refusal");
    }

    #[test]
    fn t015_terminal_exit_with_a_reason_is_accepted_and_the_reason_is_recorded() {
        let (_tmp, store, before) = seam_issue("done");
        let outcome = store
            .set_status(
                "2026-01-01-seam.md",
                StatusChange::to("todo").with_override(Some("reopening: wrong epic")),
            )
            .unwrap();
        assert!(outcome.written);
        let decision = outcome.decision.expect("one decision");
        assert_eq!(
            decision.override_reason.as_deref(),
            Some("reopening: wrong epic"),
            "an override with no recorded reason is not an audit record"
        );
        assert_ne!(
            read_issue_file(&store, "2026-01-01-seam.md"),
            before,
            "sanity: an accepted move must have changed the file at all"
        );
    }

    #[test]
    fn t015_a_blank_reason_is_not_an_override() {
        // The service trims and drops a blank reason, so a whitespace-only string
        // must not unlock a terminal exit. Asserted here as well as in the service
        // because "the seam passes the caller's string through untouched" would
        // satisfy a service-level test and still be wrong at the boundary.
        let (_tmp, store, before) = seam_issue("done");
        let err = store
            .set_status(
                "2026-01-01-seam.md",
                StatusChange::to("todo").with_override(Some("   ")),
            )
            .unwrap_err();
        assert!(
            matches!(&err, TixError::Workflow(_)),
            "a blank reason is not a reason: {err:?}"
        );
        assert_untouched(&store, &before, "blank override reason");
    }

    #[test]
    fn t015_same_column_is_accepted_and_writes_nothing() {
        let (_tmp, store, before) = seam_issue("doing");
        let outcome = store
            .set_status("2026-01-01-seam.md", StatusChange::to("doing"))
            .unwrap();
        assert!(!outcome.written, "a same-column re-apply is a no-op");
        assert!(
            outcome.decision.is_none(),
            "and appends no decision, contract §3.2"
        );
        assert_untouched(&store, &before, "same column");
        // `updated` is not bumped either: a no-op that touched the date would make
        // `tix edit --status <current column>` look like an edit.
        let reloaded = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(
            reloaded.updated, "2026-01-01",
            "the fixture's original date"
        );
    }

    #[test]
    fn t015_no_new_frontmatter_key_was_introduced() {
        // C-001. The mission must be byte-compatible on the file surface, so this
        // compares the key set of a file the seam wrote against the key set of the
        // fixture it read. A category key on the issue would break here.
        let (_tmp, store, before) = seam_issue("todo");
        store
            .set_status("2026-01-01-seam.md", StatusChange::to("doing"))
            .unwrap();
        let after = read_issue_file(&store, "2026-01-01-seam.md");
        let keys = |text: &str| -> Vec<String> {
            text.split("---\n")
                .nth(1)
                .unwrap()
                .lines()
                .filter_map(|l| l.split_once(':').map(|(k, _)| k.trim().to_string()))
                .filter(|k| !k.is_empty())
                .collect()
        };
        assert_eq!(
            keys(&after),
            keys(&before),
            "the seam must not add or remove a top-level frontmatter key"
        );
    }

    #[test]
    fn t015_a_hand_edited_inconsistent_file_is_read_and_not_repaired() {
        // C-005. A file whose `status` was hand-edited to a column the policy would
        // never have allowed is *readable* and this path must leave it alone. The
        // diagnosis is WP06's job; storage correcting it would be the escalation
        // the decision `01M3C3XBMTR5WFV7059NXM04AJ` names.
        let (_tmp, store, before) = seam_issue("doing");
        // Simulate the hand edit: `doing` (active) becomes `triage` (backlog),
        // a move adjacency refuses.
        let edited = before.replace("status: doing", "status: triage");
        write_issue(&store, "2026-01-01-seam.md", &edited);
        let after_edit = read_issue_file(&store, "2026-01-01-seam.md");

        let issue = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(
            issue.status.display(),
            "triage",
            "a hand-edited status is read, not rejected at load"
        );
        assert_eq!(
            read_issue_file(&store, "2026-01-01-seam.md"),
            after_edit,
            "reading must not repair it"
        );
        // And a legal move away from the hand-edited column proceeds, without the
        // seam trying to reconcile the history of how the file got there.
        store
            .set_status("2026-01-01-seam.md", StatusChange::to("doing"))
            .unwrap();
        let moved = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(moved.status.display(), "doing");
        assert_eq!(
            moved.history.events().len(),
            1,
            "only the new decision; nothing was written to explain the old one"
        );
    }

    #[test]
    fn t015_every_rejection_kind_is_one_of_the_contract_vocabulary() {
        // The contract fixes seven names (contract §6). A refusal that invents an
        // eighth is a surface that reports a condition under a name no other
        // surface knows, which is the exact failure the vocabulary exists to stop.
        let allowed = [
            "missing_completion_category",
            "unknown_category",
            "mapping_for_unknown_column",
            "unmapped_column_default",
            "invalid_transition",
            "unknown_column",
            "direct_edit_policy_violation",
        ];
        let cases: Vec<(&str, &str)> = vec![
            ("todo", "nope"),    // unknown_column
            ("done", "todo"),    // invalid_transition (terminal lock)
            ("doing", "triage"), // invalid_transition (adjacency)
        ];
        for (from, to) in cases {
            let (_tmp, store, _before) = seam_issue(from);
            let err = store
                .set_status("2026-01-01-seam.md", StatusChange::to(to))
                .unwrap_err();
            let TixError::Workflow(d) = &err else {
                panic!("{from} -> {to} must refuse through the workflow variant: {err:?}");
            };
            assert!(
                allowed.contains(&d.kind.as_str()),
                "`{}` is not in the contract's vocabulary",
                d.kind.as_str()
            );
        }
    }

    #[test]
    fn t015_a_legacy_board_gains_no_policy_but_keeps_completion() {
        // The opt-in this WP decided: a board with no `category_map` gets the
        // completion definition and the commit-clearing rule, and no transition
        // restriction. Both halves are asserted, because a change that dropped the
        // completion rule along with the policy would otherwise look correct.
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &sample_frontmatter(1, "Legacy", "done"),
        );
        let moved = store
            .set_status("2026-01-01-legacy.md", StatusChange::to("todo"))
            .unwrap();
        assert!(moved.written, "a legacy board imposes no policy");
        assert_eq!(moved.issue.status.display(), "todo");

        // And completion still resolves through the reconciliation, not the string
        // "done": this issue is no longer complete, and an untouched `done` one is.
        let resolution =
            crate::workflow::resolution(&store.config, store.config.default_config(), "default");
        assert!(
            !resolution.explicit_policy,
            "precondition: this board declared no category_map"
        );
        assert!(
            resolution.has_completion(),
            "but it still has a done column"
        );
        assert!(
            !crate::workflow::is_completed(&moved.issue, &resolution),
            "and `todo` is not complete"
        );
    }

    #[test]
    fn t015_a_mapped_board_keeps_the_commit_coupling() {
        // The commit rule moved from `mv.rs` into the seam, so it is pinned here
        // rather than only in the command layer: reaching completion records the
        // commit, leaving it clears the one that was recorded.
        let (_tmp, store, _before) = seam_issue("doing");
        store
            .set_status(
                "2026-01-01-seam.md",
                StatusChange::to("done").with_commit(Some("abc123")),
            )
            .unwrap();
        let at_done = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(at_done.commit.as_deref(), Some("abc123"));

        store
            .set_status(
                "2026-01-01-seam.md",
                StatusChange::to("todo").with_override(Some("not actually finished")),
            )
            .unwrap();
        let off_done = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        assert_eq!(
            off_done.commit, None,
            "leaving completion clears the recorded commit"
        );
    }

    #[test]
    fn t015_a_decision_round_trips_through_a_file_unchanged() {
        // T012's round trip, end to end rather than in memory: the rendered line
        // must parse back to the same fields, or WP06 cannot read a file's last
        // accepted column out of it.
        let (_tmp, store, _before) = seam_issue("todo");
        store
            .set_status("2026-01-01-seam.md", StatusChange::to("doing"))
            .unwrap();
        let first = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        let text = read_issue_file(&store, "2026-01-01-seam.md");
        // Parse the file back from its own bytes — not from the in-memory issue.
        let parsed = Issue::parse(&text).unwrap();
        let events = parsed.history.events();
        let decision = crate::model::TransitionDecision::from_event(events[0]).unwrap();
        assert_eq!(decision.to, "doing");
        assert_eq!(decision.from_category, "unstarted");
        assert_eq!(decision.to_category, "active");
        // And re-serialising the parsed file reproduces it byte for byte, so the
        // grammar is not lossy in a way only a rewrite would reveal.
        assert_eq!(
            parsed.to_file_contents(),
            text,
            "a parsed decision must re-render to the same bytes"
        );
        assert_eq!(parsed.history.events().len(), first.history.events().len());
    }

    #[test]
    fn t015_two_transitions_append_two_decisions_in_order() {
        let (_tmp, store, _before) = seam_issue("triage");
        for to in ["todo", "doing"] {
            store
                .set_status("2026-01-01-seam.md", StatusChange::to(to))
                .unwrap();
        }
        let after = store
            .get(IssueSelector::Filename("2026-01-01-seam.md".into()))
            .unwrap();
        let events = after.history.events();
        assert_eq!(events.len(), 2, "one per accepted transition");
        let tos: Vec<String> = events
            .iter()
            .map(|e| crate::model::TransitionDecision::from_event(e).unwrap().to)
            .collect();
        assert_eq!(tos, vec!["todo", "doing"], "append order, not sorted");
    }

    #[test]
    fn set_status_changes_status_and_bumps_updated() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-s.md",
            &sample_frontmatter(1, "S", "todo"),
        );
        let outcome = store
            .set_status("2026-01-01-s.md", StatusChange::to("in progress"))
            .unwrap();
        let issue = &outcome.issue;
        assert_eq!(issue.status.display(), "in progress");
        assert_eq!(issue.updated, today());
        assert_eq!(issue.title, "S");
        assert_eq!(issue.body, "Body text.");
    }

    #[test]
    fn set_status_preserves_file_path() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-f.md",
            &sample_frontmatter(1, "F", "todo"),
        );
        let _ = store
            .set_status("2026-01-01-f.md", StatusChange::to("done"))
            .unwrap();
        assert!(store.issues_dir.join("2026-01-01-f.md").exists());
    }

    // ------------------------------------------------------------------
    // WP02 T009 — typed relationship writes delegate to the service
    // ------------------------------------------------------------------

    /// Read an issue file's raw bytes, for the byte-identical assertions.
    fn read_issue_file(store: &Store, filename: &str) -> String {
        std::fs::read_to_string(store.issues_dir.join(filename)).unwrap()
    }

    /// A frontmatter fixture with no relationship data, i.e. what every
    /// pre-existing issue file in the repository looks like.
    fn bare_frontmatter(number: u32, title: &str) -> String {
        format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text."
        )
    }

    /// A frontmatter fixture carrying the **retired** `links:` key.
    fn legacy_links_frontmatter(number: u32, title: &str, links: &str) -> String {
        format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"todo\"\nlabels: []\nlinks: {links}\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text."
        )
    }

    /// Two seeded issues, plus the store, for the relationship tests.
    fn related_pair() -> (TempDir, Store, Issue, Issue) {
        let (tmp, store) = make_store();
        write_issue(&store, "2026-01-01-a.md", &bare_frontmatter(1, "A"));
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
        let a = store.get(IssueSelector::Number(1)).unwrap();
        let b = store.get(IssueSelector::Number(2)).unwrap();
        (tmp, store, a, b)
    }

    #[test]
    fn t009_link_records_a_single_directed_edge() {
        let (_tmp, store, a, b) = related_pair();
        let outcome = store
            .link(
                &a.number.to_string(),
                &b.number.to_string(),
                RelationKind::Blocks,
            )
            .unwrap();
        assert!(outcome.changed);

        // One edge, stored once, on the blocking side. The old symmetric
        // back-reference on the other issue is gone (C-001).
        let a_after = store.get(IssueSelector::Number(1)).unwrap();
        let b_after = store.get(IssueSelector::Number(2)).unwrap();
        assert_eq!(a_after.relationships.len(), 1);
        assert!(
            b_after.relationships.is_empty(),
            "no back-reference is written for a directed edge"
        );
        assert_eq!(a_after.relationships[0].kind, RelationKind::Blocks);
        assert_eq!(
            (a_after.relationships[0].from, a_after.relationships[0].to),
            (1, 2)
        );
    }

    #[test]
    fn t009_link_appends_exactly_one_history_event() {
        let (_tmp, store, a, b) = related_pair();
        store
            .link(
                &a.number.to_string(),
                &b.number.to_string(),
                RelationKind::Blocks,
            )
            .unwrap();
        let a_after = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(a_after.history.len(), 1);
        assert_eq!(
            a_after.history.events()[0].kind,
            HistoryEventKind::RelationshipAdded
        );
        // Every event records an actor, or the audit trail is not an audit trail.
        assert!(!a_after.history.events()[0].actor.is_empty());
    }

    #[test]
    fn t009_idempotent_reapply_writes_nothing_and_appends_no_second_event() {
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        let first = store.get(IssueSelector::Number(1)).unwrap();
        let bytes_after_first = read_issue_file(&store, &first.filename);

        let second = store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        assert!(!second.changed, "re-applying an existing edge is a no-op");
        assert!(second.written.is_none(), "no file is written for a no-op");

        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(after.relationships.len(), 1, "no duplicate edge");
        assert_eq!(after.history.len(), 1, "no second History event");
        assert_eq!(
            read_issue_file(&store, &after.filename),
            bytes_after_first,
            "the file is byte-identical after the no-op"
        );
    }

    #[test]
    fn t009_inverse_spelling_resolves_to_the_same_stored_edge() {
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        // "2 is blocked by 1" is the same edge as "1 blocks 2".
        let again = store
            .link(&args.1, &args.0, RelationKind::BlockedBy)
            .unwrap();
        assert!(!again.changed, "the inverse spelling must not add an edge");
        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(after.relationships.len(), 1);
        assert_eq!(
            after.relationships[0].kind,
            RelationKind::Blocks,
            "the stored kind is always the canonical one"
        );
    }

    #[test]
    fn t009_self_link_is_refused_and_writes_nothing() {
        let (_tmp, store, a, _b) = related_pair();
        let before = read_issue_file(&store, &a.filename);
        let err = store
            .link(
                &a.number.to_string(),
                &a.number.to_string(),
                RelationKind::Blocks,
            )
            .unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
        assert!(
            err.to_string().contains("self_link"),
            "the diagnostic names the rule: {err}"
        );
        assert_eq!(
            read_issue_file(&store, &a.filename),
            before,
            "SC-005: a rejected mutation leaves the file byte-identical"
        );
    }

    #[test]
    fn t009_cycle_closing_edge_is_refused_and_writes_nothing() {
        let (tmp, store) = make_store();
        write_issue(&store, "2026-01-01-a.md", &bare_frontmatter(1, "A"));
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
        write_issue(&store, "2026-01-01-c.md", &bare_frontmatter(3, "C"));
        let _ = tmp;
        store.link("1", "2", RelationKind::Blocks).unwrap();
        store.link("2", "3", RelationKind::Blocks).unwrap();
        let c_before = read_issue_file(&store, "2026-01-01-c.md");

        let err = store.link("3", "1", RelationKind::Blocks).unwrap_err();
        assert!(err.to_string().contains("cycle"), "{err}");
        assert_eq!(
            read_issue_file(&store, "2026-01-01-c.md"),
            c_before,
            "SC-005: both files of a rejected two-issue mutation are unchanged"
        );
    }

    #[test]
    fn t009_unlink_removes_the_edge_and_is_idempotent() {
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();

        let removed = store
            .unlink(&args.0, &args.1, RelationKind::Blocks)
            .unwrap();
        assert!(removed.changed);
        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert!(after.relationships.is_empty());
        assert_eq!(after.history.len(), 2, "added then removed");

        // Removing again is a no-op, not a second History entry.
        let again = store
            .unlink(&args.0, &args.1, RelationKind::Blocks)
            .unwrap();
        assert!(!again.changed);
        let after2 = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(after2.history.len(), 2, "no third History event");
    }

    #[test]
    fn t009_unlink_of_a_never_linked_pair_is_a_noop() {
        let (_tmp, store, a, b) = related_pair();
        let outcome = store
            .unlink(
                &a.number.to_string(),
                &b.number.to_string(),
                RelationKind::Blocks,
            )
            .unwrap();
        assert!(!outcome.changed);
        assert!(outcome.written.is_none());
        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert!(after.relationships.is_empty());
        assert!(after.history.is_empty(), "a no-op appends nothing");
    }

    #[test]
    fn t009_set_relationships_replaces_the_set_and_keeps_surviving_ids() {
        let (_tmp, store, _a, _b) = related_pair();
        store.link("1", "2", RelationKind::Blocks).unwrap();
        let before = store.get(IssueSelector::Number(1)).unwrap();
        let survivor_id = before.relationships[0].id.clone();

        // Replace the set with a different target; the old edge goes, recorded.
        let updated = store
            .set_relationships(&before.filename, &[(2, RelationKind::Blocks)])
            .unwrap();
        assert_eq!(updated.relationships.len(), 1);
        assert_eq!(
            updated.relationships[0].id, survivor_id,
            "a surviving relationship keeps its stable id"
        );
    }

    #[test]
    fn t009_set_relationships_rejects_unknown_target_and_self() {
        let (_tmp, store, a, _b) = related_pair();
        assert!(
            store
                .set_relationships(&a.filename, &[(404, RelationKind::Blocks)])
                .is_err(),
            "an unknown target is refused"
        );
        assert!(
            store
                .set_relationships(&a.filename, &[(1, RelationKind::Blocks)])
                .is_err(),
            "a self-link is refused"
        );
    }

    // ------------------------------------------------------------------
    // WP02 review round 1 — F1, F4, F5, F13: canonical storage lookups
    // ------------------------------------------------------------------

    /// Seed an issue, optionally with raw extra frontmatter.
    fn seeded(store: &Store, number: u32, title: &str, extra: &str) {
        let slug = title.to_lowercase();
        write_issue(
            store,
            &format!("2026-01-01-{slug}.md"),
            &format!(
                "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\n{extra}files: []\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody.\n"
            ),
        );
    }

    #[test]
    fn f1_set_relationships_refuses_a_reciprocal_pair_the_service_rejects() {
        // F1. `set_relationships` used to re-implement existence and the
        // self-link rule locally and skip the rest, so with `1 blocks 2` on disk
        // it stored `2 blocks 1` — a reciprocal pair that `link` rejects one
        // line earlier and that contract §3 rules 3 and 4 require be refused.
        // Latent only because `--links` hard-codes `related`; user-reachable the
        // moment WP03 wires `--type`.
        let (_tmp, store) = make_store();
        seeded(&store, 1, "A", "");
        seeded(&store, 2, "B", "");
        store.link("1", "2", RelationKind::Blocks).unwrap();

        let err = store
            .set_relationships("2026-01-01-b.md", &[(1, RelationKind::Blocks)])
            .unwrap_err();
        assert!(
            err.to_string().contains("cycle"),
            "the service's verdict is what refuses it: {err}"
        );
        let two = store.get(IssueSelector::Number(2)).unwrap();
        assert!(
            two.relationships.is_empty(),
            "SC-005: a refused mutation writes nothing"
        );
    }

    #[test]
    fn f4_a_hand_ordered_related_row_is_removable() {
        // F4. A hand-authored `related` row in the non-canonical endpoint order.
        // Removals used to be keyed by where the row *should* live while rows
        // were found where they *were* stored, so this row matched no file and
        // no code path could delete it.
        let (_tmp, store) = make_store();
        seeded(&store, 2, "B", "");
        seeded(
            &store,
            5,
            "E",
            "relationships:\n- id: rel_handauthored\n  from: 5\n  to: 2\n  kind: related\n  display: \"related #2 B\"\n",
        );
        let out = store.unlink("5", "2", RelationKind::Related).unwrap();
        assert!(out.changed, "the row is found and removed");
        assert!(
            store
                .get(IssueSelector::Number(5))
                .unwrap()
                .relationships
                .is_empty()
        );
    }

    #[test]
    fn f5_a_persisted_blocked_by_row_is_removable() {
        // F5. `blocked_by` is the input-only spelling and must never be
        // persisted, but the format is human-editable so a hand edit can put it
        // there. `unlink` compared authored fields while `link` canonicalized,
        // so the two disagreed and the row was un-removable — leaving a
        // permanently invalid row plus a `tix lint` cycle finding with no way to
        // clear it.
        let (_tmp, store) = make_store();
        seeded(&store, 1, "A", "");
        seeded(
            &store,
            2,
            "B",
            "relationships:\n- id: rel_bb\n  from: 2\n  to: 1\n  kind: blocked_by\n  display: \"blocks #1 A\"\n",
        );
        let out = store.unlink("2", "1", RelationKind::BlockedBy).unwrap();
        assert!(out.changed, "the row is found and removed");
        assert!(
            store
                .get(IssueSelector::Number(2))
                .unwrap()
                .relationships
                .is_empty()
        );
    }

    #[test]
    fn f13_a_dangling_edge_is_removable() {
        // F13. A dangling edge is a diagnosed, expected condition, so the one
        // operation that can clean it up must still work. `unlink` resolved
        // both endpoints first, so deleting the target made the edge
        // permanently unfixable through the tool.
        let (_tmp, store) = make_store();
        seeded(&store, 1, "A", "");
        seeded(&store, 2, "B", "");
        store.link("1", "2", RelationKind::Blocks).unwrap();
        std::fs::remove_file(store.issues_dir.join("2026-01-01-b.md")).unwrap();

        let out = store.unlink("1", "2", RelationKind::Blocks).unwrap();
        assert!(out.changed, "a dangling edge is still removable");
        let one = store.get(IssueSelector::Number(1)).unwrap();
        assert!(one.relationships.is_empty());
        assert_eq!(one.history.len(), 2, "and the removal is recorded");
    }

    #[test]
    fn m10_one_unlink_of_a_duplicated_edge_appends_one_event() {
        // M10. The same canonical `related` edge hand-authored into **both**
        // endpoints — the redundancy the data model says is kept so no stored id
        // silently stops resolving. One `unlink` is one accepted mutation, so it
        // appends one History event, not one per file written. The previous
        // implementation computed the summary per file, and the comment directly
        // above it claimed the opposite.
        let (_tmp, store) = make_store();
        // A redundant pair is one row in **each** endpoint's file — the two
        // spellings of a single association. My first version of this fixture
        // put both rows in one file, which tested a different thing and then
        // asserted an event count for a file that was never written.
        seeded(
            &store,
            1,
            "A",
            "relationships:\n- id: rel_dup_12\n  from: 1\n  to: 2\n  kind: related\n  display: \"related #2 B\"\n",
        );
        seeded(
            &store,
            2,
            "B",
            "relationships:\n- id: rel_dup_21\n  from: 2\n  to: 1\n  kind: related\n  display: \"related #1 A\"\n",
        );

        let outcome = store.unlink("1", "2", RelationKind::Related).unwrap();
        assert!(outcome.changed, "both redundant rows are removed");
        let mut summaries = Vec::new();
        for number in [1u32, 2] {
            let issue = store.get(IssueSelector::Number(number)).unwrap();
            assert!(
                issue.relationships.is_empty(),
                "issue #{number} keeps no edge"
            );
            assert_eq!(
                issue.history.len(),
                1,
                "issue #{number} records exactly one event, got {:?}",
                issue.history.events()
            );
            let event = &issue.history.events()[0];
            assert!(
                event.detail.contains("removed 2 relationships"),
                "and the event says both spellings went: {}",
                event.detail
            );
            summaries.push(event.detail.clone());
        }
        // The point of the fix: one mutation, one wording. The previous version
        // computed the summary per file, so each file described only its own row
        // and the two events disagreed about what had happened.
        assert_eq!(
            summaries[0], summaries[1],
            "both files record the same single event, not two differing ones"
        );
    }

    #[test]
    fn m11_unlink_reports_the_row_it_removed_not_an_empty_placeholder() {
        // M11. The post-removal re-scan could never match — every matching row is
        // gone by then — so a successful unlink always reported a relationship
        // with an empty id, which is not addressable by
        // `edit_relation`/`remove_relation`. `link`'s no-op path returned a real
        // row; this brings the two into line.
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        let before = store.get(IssueSelector::Number(1)).unwrap();
        let real_id = before.relationships[0].id.clone();

        let outcome = store
            .unlink(&args.0, &args.1, RelationKind::Blocks)
            .unwrap();
        assert!(outcome.changed);
        assert_eq!(
            outcome.relationship.id, real_id,
            "the reported row is the one that was actually removed"
        );
        assert!(!outcome.relationship.id.is_empty(), "so it is addressable");
        assert_eq!(
            outcome.relationship.display,
            before.relationships[0].display
        );
    }

    #[test]
    fn m15_the_history_detail_names_the_relationship_id() {
        // M15. `display` already begins with the kind, so naming the kind again
        // produced `created blocks: blocks #2 B`. The id is the stable handle and
        // is what data-model §8's example shows.
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        let one = store.get(IssueSelector::Number(1)).unwrap();
        let id = one.relationships[0].id.clone();

        let detail = &one.history.events()[0].detail;
        assert!(
            detail.starts_with(&format!("created {id}:")),
            "the detail names the stable id: {detail}"
        );
        assert!(
            !detail.contains(&format!("created {}:", RelationKind::Blocks)),
            "and does not stutter the kind, which `display` already carries: {detail}"
        );
    }

    #[test]
    fn f17_all_diagnostics_are_reported_not_just_the_first() {
        // F17 / M4. The previous version of this test built exactly **one**
        // diagnostic and asserted only that the kind prefix was not doubled —
        // so it never exercised the multi-diagnostic path the fix exists for.
        // Replacing the join with `errors.iter().take(1)` left it green.
        //
        // `1 blocks 2` plus `2 duplicates 1` makes the same pair carry two
        // distinct rule violations at once.
        // The corrupt state is hand-authored, because the write path refuses to
        // create it — which is the point. A file written before these rules
        // existed, or edited by hand, can hold several violations at once, and
        // `validate_snapshot` is the surface that must report all of them.
        let (_tmp, store) = make_store();
        seeded(
            &store,
            1,
            "A",
            "relationships:\n- id: rel_b12\n  from: 1\n  to: 2\n  kind: blocks\n  display: blocks\n- id: rel_d12\n  from: 1\n  to: 2\n  kind: duplicates\n  display: dup\n",
        );
        seeded(
            &store,
            2,
            "B",
            "relationships:\n- id: rel_b21\n  from: 2\n  to: 1\n  kind: blocks\n  display: blocks\n",
        );

        let issues = store.list().unwrap();
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        let verdict = RelationshipGraph::new(&views, "done").validate_snapshot();
        assert!(
            verdict.errors.len() >= 2,
            "the fixture must really produce several diagnostics, got {:?}",
            verdict.errors
        );

        let rendered = relationship_error(&verdict.errors).to_string();
        for kind in ["conflicting_edge", "cycle"] {
            assert!(
                rendered.contains(kind),
                "every diagnostic must be reported; {kind} missing from: {rendered}"
            );
        }
        assert!(
            !rendered.contains("conflicting_edge: conflicting_edge")
                && !rendered.contains("cycle: cycle:"),
            "no doubled kind prefix: {rendered}"
        );
        // M5, tested at the seam. Whether the *service* emits a duplicate
        // self-link diagnostic depends on which rules fire, and that has not
        // been reproducible from either the library or the binary — so this
        // asserts the property where it is decided: `relationship_error` must
        // never render the same (kind, message) twice, whatever it is handed.
        let dup = vec![
            Diagnostic::new(
                DiagnosticKind::SelfLink,
                "to",
                "#1 cannot block itself: a self-link is not a valid relationship",
            ),
            Diagnostic::new(
                DiagnosticKind::SelfLink,
                "to",
                "#1 cannot block itself: a self-link is not a valid relationship",
            ),
            Diagnostic::new(DiagnosticKind::Cycle, "to", "cycle: 1 -> 1 -> #1"),
        ];
        let rendered = relationship_error(&dup).to_string();
        assert_eq!(
            rendered.matches("cannot block itself").count(),
            1,
            "an identical diagnostic renders once, not twice: {rendered}"
        );
        assert!(
            rendered.contains("cycle"),
            "a distinct diagnostic is still reported: {rendered}"
        );
        assert!(
            !rendered.contains("self_link: self_link") && !rendered.contains("cycle: cycle:"),
            "and no kind is prefixed twice: {rendered}"
        );
    }

    #[test]
    fn t009_clearing_a_set_removes_a_related_edge_owned_by_another_file() {
        // Regression, found in final review. A `related` edge is stored once, in
        // the lower-numbered issue's frontmatter, so #5's own file is empty even
        // though #5 *is* related to #3. Clearing #5's set must still remove the
        // association, or `tix edit 5 --links ""` silently does nothing.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-a.md", &bare_frontmatter(3, "A"));
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(5, "B"));

        store.link("5", "3", RelationKind::Related).unwrap();
        let three = store.get(IssueSelector::Number(3)).unwrap();
        let five = store.get(IssueSelector::Number(5)).unwrap();
        assert_eq!(
            three.relationships.len(),
            1,
            "the edge is stored in the lower-numbered issue's file"
        );
        assert!(
            five.relationships.is_empty(),
            "and #5's own file holds none"
        );

        store.set_relationships(&five.filename, &[]).unwrap();

        let three_after = store.get(IssueSelector::Number(3)).unwrap();
        let five_after = store.get(IssueSelector::Number(5)).unwrap();
        assert!(
            three_after.relationships.is_empty(),
            "the association is gone from the file that actually stored it"
        );
        assert!(five_after.relationships.is_empty());
    }

    #[test]
    fn t009_clearing_a_set_does_not_remove_an_inbound_directional_edge() {
        // The other half of the ownership rule. If #3 blocks #5, that edge is
        // #3's declaration; #5 clearing its own relationship set must not
        // rewrite #3's dependency graph. Only the non-directional case is
        // shared, because only there does the association belong to both ends.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-a.md", &bare_frontmatter(3, "A"));
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(5, "B"));

        store.link("3", "5", RelationKind::Blocks).unwrap();
        let five = store.get(IssueSelector::Number(5)).unwrap();

        store.set_relationships(&five.filename, &[]).unwrap();

        let three_after = store.get(IssueSelector::Number(3)).unwrap();
        assert!(
            three_after
                .relationships
                .iter()
                .any(|r| r.to == 5 && r.kind == RelationKind::Blocks),
            "#3's declaration that it blocks #5 survives: a blocked issue \
             cannot unilaterally clear the blocker's graph"
        );
    }

    /// The path of a committed relationship fixture.
    fn relationship_fixture(name: &str) -> String {
        format!(
            "{}/tests/fixtures/relationships/{name}",
            env!("CARGO_MANIFEST_DIR")
        )
    }

    #[test]
    fn t010_typed_fixture_round_trips_byte_stable_including_history() {
        // NFR-003, model-level half: a typed fixture survives read -> write ->
        // read unchanged, `## History` region included.
        let original =
            std::fs::read_to_string(relationship_fixture("typed-relationships.md")).unwrap();
        let issue = Issue::parse(&original).unwrap();
        assert_eq!(issue.relationships.len(), 2);
        assert_eq!(issue.history.len(), 2);
        let rendered = issue.to_file_contents();
        assert_eq!(
            rendered, original,
            "a typed fixture must not churn on a read/write round trip"
        );
        assert_eq!(
            Issue::parse(&rendered).unwrap().to_file_contents(),
            rendered
        );
        // The stable ids and the section position both survive.
        assert_eq!(issue.relationships[0].id, "rel_01JQ8Z4W2M6N7P9R3S5T7V9X1");
        assert!(
            rendered.find("## History").unwrap() < rendered.find("Prose that follows").unwrap(),
            "History sits between the frontmatter and the body"
        );
    }

    #[test]
    fn t010_issue_with_no_relationship_data_is_untouched() {
        let original =
            std::fs::read_to_string(relationship_fixture("no-relationship-data.md")).unwrap();
        let issue = Issue::parse(&original).unwrap();
        assert!(issue.relationships.is_empty());
        assert!(issue.history.is_empty());
        assert!(!issue.has_retired_links_key);
        let rendered = issue.to_file_contents();
        assert_eq!(
            rendered, original,
            "an issue with no relationship data must not churn"
        );
        assert!(!rendered.contains("relationships:"));
        assert!(!rendered.contains("## History"));
    }

    #[test]
    fn t010_an_empty_history_section_is_dropped_not_preserved() {
        // A hand-left `## History` heading with no entries parses to an empty
        // log. The section is derived from the log, so an empty one has no
        // representation on disk and is omitted on write — diagnosed, never
        // silently filled in, and never kept as a bare heading.
        let original = std::fs::read_to_string(relationship_fixture("history-empty.md")).unwrap();
        assert!(
            original.contains("## History"),
            "the fixture must actually carry the empty heading"
        );
        let issue = Issue::parse(&original).unwrap();
        assert!(
            issue.history.is_empty(),
            "a heading with no entries parses to an empty log"
        );
        assert!(
            issue
                .body
                .contains("An issue whose History section is present but empty."),
            "the prose after the heading is body, not a dropped event: {:?}",
            issue.body
        );
        let rendered = issue.to_file_contents();
        assert!(
            !rendered.contains("## History"),
            "the empty section is omitted rather than kept as a bare heading"
        );
        assert!(rendered.contains("An issue whose History section is present but empty."));
    }

    #[test]
    fn t010_issue_with_no_history_section_is_untouched() {
        let original = std::fs::read_to_string(relationship_fixture("history-absent.md")).unwrap();
        let issue = Issue::parse(&original).unwrap();
        assert!(issue.history.is_empty());
        let rendered = issue.to_file_contents();
        assert_eq!(
            rendered, original,
            "a file written before History existed must not gain an empty section"
        );
    }

    #[test]
    fn f2_one_bad_history_line_does_not_make_the_store_unreadable() {
        // Store-level consequence of the model-level guarantee. Before the parse
        // became non-fatal, `Store::list` propagated the error, so a single
        // mistyped line in one issue broke `list`, `get`, `view`, `board`,
        // `status`, `lint`, `export`, `link`, `unlink` and `set_relationships`
        // for *every* issue — including `get` on a completely unrelated,
        // perfectly valid one. There is also no recovery through the tool,
        // because every command that could rewrite the file was among the
        // failures.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-a.md", &bare_frontmatter(1, "A"));
        write_issue(
            &store,
            "2026-01-01-c.md",
            "---\nnumber: 3\ntitle: \"C\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\n## History\n\n- 2026-01-01T00:00:00Z - alice - relationship_added - ascii hyphens\n",
        );

        let all = store.list().expect("the store must remain listable");
        assert_eq!(all.len(), 2, "both issues load");
        assert_eq!(
            store
                .get(IssueSelector::Number(1))
                .expect("an unrelated, valid issue must stay readable")
                .title,
            "A"
        );
        // And the damaged line is still reachable for diagnosis, which is the
        // whole point of the non-fatal parse. An ASCII-hyphen line is not
        // *recognised*, so no event is fabricated from it, but it is retained in
        // the section verbatim and reported rather than demoted into the body
        // (see the F1 trade in `parse_front`).
        let three = store.get(IssueSelector::Number(3)).unwrap();
        assert!(three.history.events().is_empty(), "no event is fabricated");
        assert_eq!(
            three.history.unparsed().len(),
            1,
            "the line is preserved for diagnosis: {:?}",
            three.history.unparsed()
        );
        assert!(
            !three.body.contains("ascii hyphens"),
            "and is not demoted into the body: {:?}",
            three.body
        );
    }

    /// Seed an issue into its own assignee segment, so a write can be failed
    /// for one owner and not another.
    #[cfg(unix)]
    fn seeded_in_segment(store: &Store, number: u32, title: &str, segment: &str) {
        let dir = store.issues_dir.join(segment);
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join(format!("2026-01-01-{}.md", title.to_lowercase())),
            format!(
                "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\nfiles: []\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody.\n"
            ),
        )
        .unwrap();
    }

    #[cfg(unix)]
    #[test]
    fn f6_a_mid_sequence_write_failure_rolls_every_file_back() {
        use std::os::unix::fs::PermissionsExt;
        // F6 / anti-pattern 7. This can write N files, because an edge is stored
        // in its canonical source's file, so a failure partway through used to
        // leave the store half-mutated while the command reported failure.
        //
        // `atomic_write` renames a temp file, which needs write permission on
        // the *directory*, so the injection makes one owner's segment
        // read-only. The owners are 1, 2 and 3 and are written in ascending
        // order, so #1 and #2 are committed before #3 fails.
        let (tmp, store) = make_store();
        let _ = tmp;
        seeded_in_segment(&store, 1, "A", "alice");
        seeded_in_segment(&store, 2, "B", "bob");
        seeded_in_segment(&store, 3, "C", "carol");
        seeded_in_segment(&store, 5, "E", "erin");

        let paths: Vec<std::path::PathBuf> = [
            "alice/2026-01-01-a.md",
            "bob/2026-01-01-b.md",
            "carol/2026-01-01-c.md",
        ]
        .iter()
        .map(|p| store.issues_dir.join(p))
        .collect();
        let before: Vec<String> = paths
            .iter()
            .map(|p| std::fs::read_to_string(p).unwrap())
            .collect();

        // Order-normalization puts target 5's edge on the lower number, so the
        // owners really are 1, 2 and 3 and #3 is written last.
        let carol = store.issues_dir.join("carol");
        let mut perms = std::fs::metadata(&carol).unwrap().permissions();
        perms.set_mode(0o555);
        std::fs::set_permissions(&carol, perms).unwrap();

        let result = store.set_relationships(
            "carol/2026-01-01-c.md",
            &[
                (1, RelationKind::Related),
                (2, RelationKind::Related),
                (5, RelationKind::Related),
            ],
        );

        let mut perms = std::fs::metadata(&carol).unwrap().permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&carol, perms).unwrap();

        assert!(result.is_err(), "the blocked write must fail");
        for (path, previous) in paths.iter().zip(before.iter()) {
            assert_eq!(
                std::fs::read_to_string(path).unwrap(),
                *previous,
                "{} was left mutated by a failed mutation",
                path.display()
            );
        }
    }

    #[cfg(unix)]
    #[test]
    fn f6b_the_updated_bump_is_itself_rollback_covered() {
        // The `updated` bump on the named issue (F16) is a real write, and it
        // used to sit *after* the rollback check — so a failure there returned an
        // error with the relationship writes already committed and nothing left
        // to restore. That is the same class of defect F6 was about, reintroduced
        // by the F16 fix.
        //
        // Order matters here: the relationship write lands in the *other*
        // endpoint's segment, and the bump targets the named issue's own
        // segment, so blocking the named segment fails the second write.
        use std::os::unix::fs::PermissionsExt;

        let (tmp, store) = make_store();
        let _ = tmp;
        seeded_in_segment(&store, 1, "A", "alice");
        seeded_in_segment(&store, 3, "C", "carol");

        let alice = store.issues_dir.join("alice/2026-01-01-a.md");
        let before = std::fs::read_to_string(&alice).unwrap();

        let carol = store.issues_dir.join("carol");
        let mut perms = std::fs::metadata(&carol).unwrap().permissions();
        perms.set_mode(0o555);
        std::fs::set_permissions(&carol, perms).unwrap();

        let result =
            store.set_relationships("carol/2026-01-01-c.md", &[(1, RelationKind::Related)]);

        let mut perms = std::fs::metadata(&carol).unwrap().permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&carol, perms).unwrap();

        assert!(result.is_err(), "the blocked bump must fail the call");
        assert_eq!(
            std::fs::read_to_string(&alice).unwrap(),
            before,
            "the relationship write that succeeded earlier must be rolled back \
             when the subsequent `updated` bump fails"
        );
    }

    #[test]
    fn f9_relationships_for_reports_both_endpoints_of_a_one_sided_edge() {
        // F9. An edge is stored once, in its canonical source's file, so the
        // issue's own `relationships` field is a *partial* view. Reading it made
        // a related issue look unrelated — a user-visible regression against the
        // retired symmetric model, which mirrored the link on both sides by
        // construction.
        let (_tmp, store) = make_store();
        seeded(&store, 1, "A", "");
        seeded(&store, 2, "B", "");
        store.link("2", "1", RelationKind::Related).unwrap();

        // The edge is stored once, in the lower-numbered issue's file.
        let one = store.get(IssueSelector::Number(1)).unwrap();
        let two = store.get(IssueSelector::Number(2)).unwrap();
        assert_eq!(one.relationships.len(), 1, "precondition: #1 stores it");
        assert!(
            two.relationships.is_empty(),
            "precondition: #2's own field is the partial view that caused F9"
        );

        // The service-backed accessor is what a read surface must use, and it
        // answers for both endpoints.
        for number in [1u32, 2] {
            let resolved = store.relationships_for(number).unwrap();
            assert_eq!(
                resolved.len(),
                1,
                "issue #{number} must see the relationship that touches it"
            );
            assert_eq!(resolved[0].kind, RelationKind::Related);
        }
    }

    #[test]
    fn f7_writing_an_issue_with_the_retired_key_discloses_that_it_is_removed() {
        // F7 / M6. The previous version of this test asserted only the
        // *consequence* — the key is gone from the file — which was already true
        // before the fix, so removing the disclosure entirely left it green.
        // It never checked the thing its name promised.
        let (tmp, store) = make_store();
        let _ = tmp;
        let _ = take_disclosures();
        // **Populated**, not `[]`. The disclosure fires because the key's value is
        // no longer readable, and an empty value has nothing to lose — reporting
        // the key's mere presence made `tix lint` reject every issue file this
        // repository has ever written, since they all carry a `links: []`.
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &legacy_links_frontmatter(1, "Legacy", "['7']"),
        );
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            issue.has_retired_links_key,
            "precondition: the key is present"
        );

        store.update(&issue.filename, &issue).unwrap();

        // The disclosure, which is the whole point of the fix.
        let disclosures = take_disclosures();
        assert_eq!(
            disclosures.len(),
            1,
            "the write must disclose that it dropped the key: {disclosures:?}"
        );
        let line = &disclosures[0];
        assert!(
            line.contains("`links:`"),
            "it names what was removed: {line}"
        );
        // The action leads, so it is the part that survives truncation in the
        // TUI's one-row status area. Cycle 6 measured the previous wording being
        // cut off at 80, 100 and 120 columns.
        assert!(
            line.starts_with("remove `links:` by hand"),
            "and leads with what to do about it: {line}"
        );
        assert!(
            line.contains(&issue.filename),
            "and which file it was removed from: {line}"
        );
        assert!(
            line.contains("C-001"),
            "and that no migration was applied, so the user is not left \
             wondering where their data went: {line}"
        );

        // The consequence the disclosure is about.
        let after = read_issue_file(&store, &issue.filename);
        assert!(
            !after.contains("links:"),
            "the key is not re-emitted (C-001: no migration)"
        );
        // And a re-read no longer reports it, which is precisely why the
        // disclosure matters: the diagnostic is self-erasing without it.
        let reread = store.get(IssueSelector::Number(1)).unwrap();
        assert!(!reread.has_retired_links_key);
        assert!(
            take_disclosures().is_empty(),
            "and it is disclosed once, not on every read"
        );
    }

    #[test]
    fn f7b_writing_an_issue_without_the_retired_key_is_silent() {
        // The disclosure is scoped to the condition that triggers it, so the
        // ordinary path stays quiet and this queue cannot become noise.
        let (tmp, store) = make_store();
        let _ = tmp;
        let _ = take_disclosures();
        write_issue(&store, "2026-01-01-plain.md", &bare_frontmatter(1, "Plain"));
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert!(!issue.has_retired_links_key);
        store.update(&issue.filename, &issue).unwrap();
        assert!(
            take_disclosures().is_empty(),
            "an ordinary write discloses nothing"
        );
    }

    #[test]
    fn t010_legacy_fixture_reports_the_retired_key_and_yields_no_edges() {
        // C-001, the compatibility/error matrix in one place: tolerant read,
        // explicit diagnostic, and zero reinterpretation.
        let original =
            std::fs::read_to_string(relationship_fixture("legacy-links-key.md")).unwrap();
        let issue = Issue::parse(&original).unwrap();
        assert!(issue.has_retired_links_key, "the retired key is reported");
        assert!(
            issue.relationships.is_empty(),
            "C-001: legacy values are never reinterpreted as typed edges"
        );
        assert!(
            issue.history.is_empty(),
            "a legacy file gains no History section from parsing"
        );
        // The diagnostic names the field and is located in the file, per the
        // validation contract. Exercised through the real `tix lint` path so
        // the test covers the code that actually ships.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-legacy.md", &original);
        let findings = crate::commands::lint::collect(&store.config, &store).unwrap();
        let retired: Vec<_> = findings
            .iter()
            .filter(|f| f.kind == "retired_links_key")
            .collect();
        assert_eq!(
            retired.len(),
            1,
            "one finding for the retired key: {findings:?}"
        );
        assert_eq!(retired[0].value, "links", "the finding names the field");
        assert!(
            retired[0].message.contains("retired"),
            "the message says why: {}",
            retired[0].message
        );
        assert!(
            retired[0].line > 0,
            "the finding points into the frontmatter"
        );
        // No code path converts the legacy value into a typed edge.
        let rewritten = issue.to_file_contents();
        assert!(!rewritten.contains("kind: related"));
        assert!(!rewritten.contains("kind: blocks"));
        assert!(!rewritten.contains("links:"));
    }

    #[test]
    fn c001_a_legacy_links_key_is_reported_and_yields_no_typed_edges() {
        let (tmp, store) = make_store();
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &legacy_links_frontmatter(1, "Legacy", "[\"12\", \"47\"]"),
        );
        let _ = tmp;
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            issue.has_retired_links_key,
            "the retired key is recorded as a validation result"
        );
        assert!(
            issue.relationships.is_empty(),
            "C-001: legacy values are never read as typed edges"
        );
    }

    #[test]
    fn c001_there_is_no_migration_path_from_the_retired_key() {
        // This test used to say "writing the issue back is the only way a
        // migration could occur" and then never write it back, so its
        // load-bearing assertion was on an in-memory flag after a pure string
        // render — which cannot change it. The actual write-back is where the
        // key disappears, so the test as written masked the very thing it
        // appeared to guard.
        //
        // It now performs the write and asserts on the resulting bytes.
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &legacy_links_frontmatter(1, "Legacy", "[\"12\", \"47\"]"),
        );
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            issue.has_retired_links_key,
            "precondition: the key is present"
        );
        assert!(
            issue.relationships.is_empty(),
            "C-001: legacy values are never read as typed edges"
        );

        store.update(&issue.filename, &issue).unwrap();
        let written = read_issue_file(&store, &issue.filename);

        // No migration: not one legacy value became a typed edge, under any kind.
        //
        // The re-read matters, and this test has already fallen into the trap
        // once: asserting on `issue.to_file_contents()` instead of the written
        // file cannot fail, because `Issue::parse` never populates
        // `relationships`, so the in-memory render is clean whatever the *writer*
        // does. Reading the file back off disk is the only form of this check
        // that the write-back actually has to satisfy.
        let reparsed = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            reparsed.relationships.is_empty(),
            "the file on disk parses to zero typed edges, not just the in-memory copy"
        );
        for kind in ["blocks", "blocked_by", "duplicates", "related"] {
            assert!(
                !written.contains(&format!("kind: {kind}")),
                "a legacy link became a `{kind}` edge:\n{written}"
            );
        }
        assert!(
            !written.contains("kind:"),
            "no typed edge was written at all"
        );
        // The retired key is not re-emitted, and the write did not manufacture
        // a History entry for something the user did not do.
        assert!(!written.contains("links:"), "the key is not re-emitted");
        let reread = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            reread.history.is_empty(),
            "a format change is not a relationship mutation, so it records no event"
        );
    }

    #[test]
    fn f15_the_idempotent_no_op_reports_the_real_addressable_row() {
        // F15. The no-op path returned a synthetic `Relationship` with an empty
        // id and display. The contract defines the output as the accepted
        // relationship, and an empty id is not addressable by
        // `edit_relation`/`remove_relation`, so a caller that persisted it would
        // store a dangling reference.
        let (_tmp, store, a, b) = related_pair();
        let args = (a.number.to_string(), b.number.to_string());
        let first = store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();
        let second = store.link(&args.0, &args.1, RelationKind::Blocks).unwrap();

        assert!(first.changed);
        assert!(!second.changed, "the second apply is a no-op");
        assert_eq!(
            second.relationship.id, first.relationship.id,
            "the no-op reports the real, addressable row"
        );
        assert!(
            !second.relationship.id.is_empty(),
            "an empty id is not addressable"
        );
        assert_eq!(second.relationship.display, first.relationship.display);
    }

    #[test]
    fn f16_clearing_a_set_bumps_updated_on_the_named_issue() {
        // F16. The named issue's own frontmatter can be untouched while its
        // relationship set changed, because an order-normalized `related` edge
        // lives in the other endpoint's file. That left `tix edit <n> --links ""`
        // looking like it had done nothing to the issue it named.
        let (_tmp, store, _a, _b) = related_pair();
        store.link("2", "1", RelationKind::Related).unwrap();
        let before = store.get(IssueSelector::Number(2)).unwrap();
        let updated_before = before.updated.clone();

        store.set_relationships(&before.filename, &[]).unwrap();

        let after = store.get(IssueSelector::Number(2)).unwrap();
        assert_ne!(
            after.updated, updated_before,
            "the named issue's relationship set changed, so `updated` must move"
        );
    }

    #[test]
    fn c002_an_issue_with_no_relationship_data_round_trips_unchanged() {
        let (tmp, store) = make_store();
        let _ = tmp;
        // A pre-existing issue file: no relationship data, no History. This is
        // the shape every file in the repository has today, and reading then
        // writing it must not churn it (the WP's "existing files must not be
        // rewritten" guard).
        write_issue(&store, "2026-01-01-plain.md", &bare_frontmatter(1, "Plain"));
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        let first = issue.to_file_contents();
        assert!(
            !first.contains("relationships:"),
            "the empty typed field is omitted, not written as `[]`"
        );
        assert!(
            !first.contains("## History"),
            "an empty History section is omitted entirely"
        );
        // Byte-stable through read -> write -> read, and no unrelated
        // frontmatter key is added, removed, or reordered.
        let reparsed = Issue::parse(&first).unwrap();
        let second = reparsed.to_file_contents();
        assert_eq!(second, first);
    }

    #[test]
    fn c002_history_section_round_trips_byte_stable() {
        let (tmp, store) = make_store();
        write_issue(&store, "2026-01-01-h.md", &bare_frontmatter(1, "H"));
        let _ = tmp;
        let mut issue = store.get(IssueSelector::Number(1)).unwrap();
        issue.history.append_now(
            "alice",
            HistoryEventKind::RelationshipAdded,
            "created blocks: blocks #2 B",
        );
        issue.history.append_now(
            "bob",
            HistoryEventKind::BlockedMoveAcknowledged,
            "acknowledged 1 open blocker",
        );
        let first = issue.to_file_contents();
        assert!(first.contains("## History"), "{first}");

        // Read -> write -> read must be byte-stable.
        let reparsed = Issue::parse(&first).unwrap();
        assert_eq!(reparsed.to_file_contents(), first);
        assert_eq!(reparsed.history.len(), 2);
        assert_eq!(reparsed.history.events()[0].actor, "alice");
        assert_eq!(
            reparsed.history.events()[1].kind,
            HistoryEventKind::BlockedMoveAcknowledged
        );
        assert!(
            !reparsed.body.contains("History"),
            "the section is stripped from the body: {:?}",
            reparsed.body
        );
    }

    #[test]
    fn f1_a_hand_edit_last_in_the_section_stays_in_it() {
        // Cycle-4 F1. The disambiguation rule carried a `!following.is_empty()`
        // guard, added to stop an earlier vacuous-truth defect. It over-corrected:
        // a hand-edited line that is the **last** line of the section has nothing
        // after it, so the guard forced the section to terminate there. Through
        // the real binary that meant `tix move 1 "in progress"` silently
        //
        //   - deleted the `## History` heading,
        //   - demoted the author's line into the issue body, and
        //   - rendered the *next* appended event above it, so file order stopped
        //     being append order,
        //
        // and `tix lint` reported nothing, because a demoted line is body prose
        // and the unparsed loop no longer sees it. Three explicit data-model §8
        // invariants at once.
        //
        // The distinguishing question is not "is there anything after this?" but
        // "is this shaped like a list item?". Nothing-following cannot disqualify
        // a line; a bare paragraph at EOF is still plainly prose.
        let (tmp, store) = make_store();
        let _ = tmp;
        let original = "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n  - my hand edit\n";
        write_issue(&store, "2026-01-01-a.md", original);

        // Read precondition: the hand edit is inside the section, and the section
        // holds the prior event.
        let before = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            before.history.events().len(),
            1,
            "precondition: the real event parsed"
        );
        assert_eq!(
            before.history.unparsed(),
            vec!["  - my hand edit"],
            "precondition: the hand edit is inside the section"
        );
        assert_eq!(before.body, "", "precondition: body is empty");

        // An ordinary command that has nothing to do with relationships.
        let mut moved = before.clone();
        moved.status = crate::model::Status::new("in progress");
        store.update(&moved.filename, &moved).unwrap();

        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            after.history.unparsed(),
            vec!["  - my hand edit"],
            "the hand edit is still in the audit log, not demoted to the body"
        );
        assert_eq!(
            after.history.events().len(),
            1,
            "and the real event survived"
        );
        assert_eq!(after.body, "", "nothing leaked into the body");

        // The heading is still there, and the next append goes *after* what was
        // already in the file.
        store
            .link("1", "2", RelationKind::Related)
            .ok()
            .or_else(|| {
                write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
                store.link("1", "2", RelationKind::Related).ok()
            });
        let linked = store.get(IssueSelector::Number(1)).unwrap();
        let rendered = linked.to_file_contents();
        assert!(
            rendered.contains("## History"),
            "the heading survived an unrelated write: {rendered}"
        );
        let hand = rendered
            .find("my hand edit")
            .expect("the hand edit is present");
        let newest = rendered
            .find("relationship_added")
            .expect("the new event is present");
        assert!(
            newest < hand,
            "the new event is appended AFTER the pre-existing content, so file \
             order is still append order: {rendered}"
        );
    }

    #[test]
    fn f1_but_a_bare_paragraph_at_end_of_section_is_still_prose() {
        // The other half of F1's rule, and the reason the fix is not simply
        // "vacuous truth is fine". A non-list line at EOF is body prose: keeping
        // it would put ordinary prose into the append-only audit log, which is
        // the defect cycle 3 found (N1) travelling in the opposite direction.
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-a.md",
            "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n\njust a closing paragraph\n",
        );
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(issue.history.events().len(), 1, "the real event parsed");
        assert!(
            issue.history.unparsed().is_empty(),
            "the paragraph is not in the audit log: {:?}",
            issue.history.unparsed()
        );
        assert!(
            issue.body.contains("just a closing paragraph"),
            "it is body prose: {:?}",
            issue.body
        );
    }

    #[test]
    fn f1_a_hand_edit_survives_body_prose_and_a_later_body_replacement() {
        // Cycle-5 Blocker 1. Cycle 4's F1 fix consulted `is_list_item` *only*
        // when nothing followed the ambiguous line, so the whole defect survived
        // for any hand-edited entry with body prose after it. The existing F1
        // tests could not see it because every one of their fixtures asserts
        // `before.body == ""` — the empty body was precisely what hid it.
        //
        // The consequence was data loss, not just reordering. A demoted line is
        // body text, and `tix edit --body` replaces the body wholesale, so:
        //
        //   ## History / - <event> / - 2026-02-02T00:00:00Z - bob \
        //     - relationship_removed - I removed this by hand / (blank) / Notes.
        //
        // then `tix edit 1 --body='Completely new body text.'` destroyed the
        // hand-edited append-only audit entry, and lint was silent.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
        let hand = "- 2026-02-02T00:00:00Z - bob - relationship_removed - by hand";
        write_issue(
            &store,
            "2026-01-01-a.md",
            &format!(
                "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n{hand}\n\nSome body prose.\n"
            ),
        );

        let before = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(before.history.events().len(), 1, "the real event parsed");
        assert_eq!(
            before.history.unparsed(),
            vec![hand],
            "the hand-edited entry is retained even though body prose follows"
        );
        assert!(
            before.body.contains("Some body prose."),
            "and the prose is still body text: {:?}",
            before.body
        );

        // An ordinary unrelated write must not relocate it.
        let mut moved = before.clone();
        moved.status = crate::model::Status::new("in progress");
        store.update(&moved.filename, &moved).unwrap();
        assert_eq!(
            store
                .get(IssueSelector::Number(1))
                .unwrap()
                .history
                .unparsed(),
            vec![hand],
            "a `tix move` keeps it in the audit log"
        );

        // And replacing the body — the operation that used to destroy it — must
        // not either.
        let mut replaced = store.get(IssueSelector::Number(1)).unwrap();
        replaced.body = "Completely new body text.".to_string();
        store.update(&replaced.filename, &replaced).unwrap();
        let after = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            after.history.unparsed(),
            vec![hand],
            "the hand-edited entry survives a wholesale body replacement"
        );
        assert_eq!(after.body, "Completely new body text.");

        // And the next append still goes after what the file already held.
        store.link("1", "2", RelationKind::Related).unwrap();
        let rendered = store
            .get(IssueSelector::Number(1))
            .unwrap()
            .to_file_contents();
        assert!(
            rendered.contains("## History"),
            "the heading survived: {rendered}"
        );
        let hand_at = rendered.find("by hand").expect("the hand edit is present");
        let new_at = rendered
            .find("created rel_")
            .expect("the new event is present");
        assert!(
            new_at > hand_at,
            "the new event is appended AFTER the pre-existing content, so file \
             order is still append order: {rendered}"
        );
    }

    #[test]
    fn f1_a_well_formed_star_marked_entry_is_retained_with_body_prose_after_it() {
        // Cycle-6 F1. A *correctly formatted* entry written with a `*` marker was
        // demoted to the body and then destroyed by `tix edit --body`, with lint
        // silent. The cause was a collapsed predicate: `looks_like_history_entry`
        // and `HistoryEvent::parse` both require the `- ` prefix, so a `*`-marked
        // em-dash line was not *recognised*; and the retention test asked
        // "does it look like a *misspelled* entry?", which explicitly excludes
        // anything containing U+2014. So a well-formed line matched neither.
        // Retention now asks its own question — is this an entry attempt under any
        // marker?
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
        let hand =
            "* 2026-02-02T00:00:00Z \u{2014} bob \u{2014} relationship_removed \u{2014} by hand";
        write_issue(
            &store,
            "2026-01-01-a.md",
            &format!(
                "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n{hand}\n\nSome body prose.\n"
            ),
        );

        let before = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(before.history.events().len(), 1, "the real event parsed");
        assert_eq!(
            before.history.unparsed(),
            vec![hand],
            "a well-formed `*` entry is retained even with body prose after it"
        );
        assert!(
            before.body.contains("Some body prose."),
            "and the prose is still body text: {:?}",
            before.body
        );

        // The destructive sequence, which is the whole point.
        let mut replaced = before.clone();
        replaced.body = "Completely new body text.".to_string();
        store.update(&replaced.filename, &replaced).unwrap();
        assert_eq!(
            store
                .get(IssueSelector::Number(1))
                .unwrap()
                .history
                .unparsed(),
            vec![hand],
            "it survives a wholesale body replacement"
        );

        store.link("1", "2", RelationKind::Related).unwrap();
        let rendered = store
            .get(IssueSelector::Number(1))
            .unwrap()
            .to_file_contents();
        assert_eq!(
            rendered.matches("## History").count(),
            1,
            "still exactly one section: {rendered}"
        );
        let hand_at = rendered.find("by hand").expect("the hand edit is present");
        let new_at = rendered
            .find("created rel_")
            .expect("the new event is present");
        assert!(
            new_at > hand_at,
            "appended after, so order is append order: {rendered}"
        );
    }

    #[test]
    fn f1_a_three_field_ascii_hyphen_entry_is_retained_with_body_prose_after_it() {
        // Cycle-6 F2. `HistoryEvent::parse` accepts three total fields with
        // `detail` optional, so `- <ts> - <actor> - <kind>` is a valid entry whose
        // only defect is the separator. The retention test required four, so that
        // line was demoted and then destroyed while the malformed four-field one
        // survived — the recoverable direction was the one that lost.
        let (_tmp, store) = make_store();
        let hand = "- 2026-02-02T00:00:00Z - bob - relationship_removed";
        write_issue(
            &store,
            "2026-01-01-a.md",
            &format!(
                "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n{hand}\n\nSome body prose.\n"
            ),
        );

        // Precondition: the em-dash twin really is a valid event, so the
        // three-field form is in fact part of the format.
        let twin = Issue::parse(
            "---\nnumber: 2\ntitle: \"T\"\nstatus: todo\n---\n\n## History\n\n- 2026-02-02T00:00:00Z \u{2014} bob \u{2014} relationship_removed\n",
        )
        .unwrap();
        assert_eq!(
            twin.history.events().len(),
            1,
            "three fields with em-dashes is a valid event, detail optional"
        );

        let before = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            before.history.unparsed(),
            vec![hand],
            "so its ASCII-hyphen twin is retained, not demoted"
        );
        let mut replaced = before.clone();
        replaced.body = "Completely new body text.".to_string();
        store.update(&replaced.filename, &replaced).unwrap();
        assert_eq!(
            store
                .get(IssueSelector::Number(1))
                .unwrap()
                .history
                .unparsed(),
            vec![hand],
            "and survives a body replacement"
        );
    }

    #[test]
    fn f1_a_heading_with_trailing_spaces_is_still_the_heading() {
        // Cycle-6 F3(c). `## History   ` was not recognised, and since the
        // heading is then neither the section nor body, the first relationship
        // write rendered a **second** `## History` above the original. That was
        // filed on #1299 as a CRLF-only consequence, which understated it: a
        // trailing space is a far likelier trigger than CRLF.
        let (_tmp, store) = make_store();
        write_issue(&store, "2026-01-01-b.md", &bare_frontmatter(2, "B"));
        for (label, heading) in [
            ("plain", "## History"),
            ("trailing spaces", "## History   "),
        ] {
            write_issue(
                &store,
                "2026-01-01-a.md",
                &format!(
                    "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n{heading}\n\n- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n"
                ),
            );
            let before = store.get(IssueSelector::Number(1)).unwrap();
            assert_eq!(
                before.history.events().len(),
                1,
                "{label}: the section is recognised"
            );
            store.link("1", "2", RelationKind::Related).unwrap();
            let rendered = store
                .get(IssueSelector::Number(1))
                .unwrap()
                .to_file_contents();
            assert_eq!(
                rendered.matches("## History").count(),
                1,
                "{label}: exactly one section after a write, got {rendered}"
            );
            assert!(
                !rendered.lines().any(|l| l != l.trim_end()),
                "{label}: no line keeps trailing whitespace, so the heading is \
                 normalised: {rendered}"
            );
        }
    }

    #[test]
    fn set_status_discloses_the_retired_key_rather_than_dropping_it_silently() {
        // Cycle-6 F4. Routing `set_status` through `update` is what makes it
        // disclose, and the behavioural difference is real — reverted to a direct
        // `atomic_write`, the key is still removed but nothing is disclosed, which
        // is silent data loss. Reverting also left the **entire suite green**,
        // because no test exercised it. That is the sixth time this package has
        // produced a correct fix with no regression protection, so this pins it.
        let (_tmp, store) = make_store();
        write_issue(
            &store,
            "2026-01-01-a.md",
            "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nlinks:\n- \"2\"\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody.\n",
        );
        let before = store.get(IssueSelector::Number(1)).unwrap();
        assert!(
            before.has_retired_links_key,
            "precondition: the file carries the retired key"
        );
        let _ = crate::storage::take_disclosures();

        store
            .set_status("2026-01-01-a.md", StatusChange::to("in progress"))
            .unwrap();

        let disclosures = crate::storage::take_disclosures();
        assert_eq!(
            disclosures.len(),
            1,
            "set_status must disclose the removal, got {disclosures:?}"
        );
        assert!(
            disclosures[0].contains("links:") && disclosures[0].contains("a.md"),
            "naming the field and the file: {disclosures:?}"
        );
        assert!(
            !store
                .get(IssueSelector::Number(1))
                .unwrap()
                .has_retired_links_key,
            "and the key is gone, as C-001 intends"
        );
    }

    #[test]
    fn f1_but_ordinary_prose_bullets_still_end_the_section() {
        // The other direction, and the reason the retention rule is not simply
        // "keep every list item". N1's original trigger: several body bullets in
        // a row. Neither is entry-shaped, so neither is plausibly a hand-edited
        // entry, and the section ends where it should.
        let (_tmp, store) = make_store();
        write_issue(
            &store,
            "2026-01-01-a.md",
            concat!(
                "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\n",
                "created: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n",
                "- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} relationship_added \u{2014} prior\n\n",
                "- step one\n- step two\n",
            ),
        );
        let issue = store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            issue.history.events().len(),
            1,
            "the real event is an event"
        );
        assert!(
            issue.history.unparsed().is_empty(),
            "ordinary bullets are not retained: {:?}",
            issue.history.unparsed()
        );
        assert!(
            issue.body.contains("step one") && issue.body.contains("step two"),
            "they stay body text: {:?}",
            issue.body
        );
    }

    #[test]
    fn a_year_is_not_an_ordered_list_marker() {
        // Cycle-5 Minor 7. `is_list_item` accepted any run of digits before `.`,
        // so `2026. Q1 goals` counted as a list item and a paragraph of ordinary
        // body prose was retained in the append-only audit log.
        for prose in [
            "2026. Q1 goals",
            "2026. roadmap review",
            "007. padded",
            "99999999999999999999. big",
        ] {
            assert!(
                !crate::model::looks_like_an_unrecognised_entry(prose)
                    && Issue::parse(&format!(
                        "---\nnumber: 1\ntitle: T\nstatus: todo\n---\n\n## History\n\n{prose}\n"
                    ))
                    .unwrap()
                    .history
                    .is_empty(),
                "{prose:?} must be body prose, not a retained entry"
            );
        }
    }

    #[test]
    fn f2_a_recognised_entry_with_a_bad_kind_keeps_its_trailing_whitespace() {
        // Cycle-4 F2. The `Err` arm — a *recognised* entry whose kind is unknown —
        // used `trim_end()`, which also eats trailing spaces and tabs. That is
        // the auto-repair data-model §8 forbids, and it contradicts §8's
        // "preserved byte-for-byte, including its own indentation and trailing
        // whitespace". The sibling ambiguous arm was already correct, so the two
        // disagreed about what "verbatim" means.
        let line = "  - 2026-01-01T00:00:00Z \u{2014} alice \u{2014} bogus_kind \u{2014} d   ";
        let raw = format!(
            "---\nnumber: 1\ntitle: \"A\"\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\n## History\n\n{line}\n"
        );
        let issue = Issue::parse(&raw).unwrap();
        assert!(issue.history.events().is_empty(), "no event was fabricated");
        assert_eq!(
            issue.history.unparsed(),
            vec![line],
            "kept byte-for-byte, trailing spaces included"
        );

        // And a real write must not repair it either.
        let rendered = issue.to_file_contents();
        assert!(
            rendered.contains(&format!("{line}\n")),
            "re-emitted exactly, so an unrelated `tix edit` does not rewrite the \
             author's audit log: {rendered}"
        );
        assert_eq!(
            Issue::parse(&rendered).unwrap().to_file_contents(),
            rendered,
            "and the file is byte-stable from here"
        );
    }

    #[test]
    fn c002_history_is_append_only() {
        let (tmp, store) = make_store();
        write_issue(&store, "2026-01-01-h.md", &bare_frontmatter(1, "H"));
        let _ = tmp;
        let mut issue = store.get(IssueSelector::Number(1)).unwrap();
        issue
            .history
            .append_now("alice", HistoryEventKind::RelationshipAdded, "first");
        let after_first = issue.history.clone();
        issue
            .history
            .append_now("alice", HistoryEventKind::RelationshipRemoved, "second");

        assert_eq!(issue.history.len(), 2, "appending never replaces");
        assert_eq!(
            &issue.history.events()[..1],
            after_first.events(),
            "the earlier entry is untouched and still first"
        );
    }

    #[test]
    fn c002_an_unknown_history_kind_is_kept_verbatim_not_coerced() {
        // The old version of this test asserted `contains("bogus_kind")` against
        // an error message that *echoes the offending line*, so it passed for any
        // input mentioning the word. It also fed ASCII hyphens, so
        // `splitn(4, U+2014)` never split and the real failure was a missing
        // field — the kind was never checked at all. Neither defect is a
        // hypothetical: the assertion was satisfied by the echo.
        //
        // Fixed on both counts. The line uses real em dashes, so the parser
        // genuinely reaches the kind field, and the assertion is on the parsed
        // outcome rather than on a substring of an error string.
        let line = "- 2026-01-01T00:00:00Z \u{2014} alice \u{2014} bogus_kind \u{2014} something";
        let raw = format!(
            "---\nnumber: 1\ntitle: \"H\"\nstatus: \"todo\"\n---\n\n## History\n\n{line}\n"
        );
        let issue = Issue::parse(&raw).expect("an unknown kind must not fail the parse");

        assert!(
            issue.history.events().is_empty(),
            "no event was fabricated for an unknown kind"
        );
        assert_eq!(
            issue.history.unparsed(),
            vec![line],
            "the line is kept verbatim: not dropped, not repaired"
        );
        // Idempotence, not equality with the hand-written input: that input
        // omits keys serde always emits, so only the rendered form is a
        // meaningful byte-stability assertion.
        let rendered = issue.to_file_contents();
        assert!(rendered.contains(line), "the line survives the write");
        assert_eq!(
            Issue::parse(&rendered).unwrap().to_file_contents(),
            rendered,
            "and the file round-trips byte-identically"
        );
    }

    #[test]
    fn list_mixes_grouped_and_flat_issues_sorted_by_relative_filename() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        fs::create_dir_all(store.issues_dir.join("bob")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(
            &store,
            "bob/2026-05-10-b.md",
            &sample_frontmatter(2, "B", "todo"),
        );
        write_issue(
            &store,
            "2026-02-01-c.md",
            &sample_frontmatter(3, "C", "todo"),
        );
        let issues = store.list().unwrap();
        let filenames: Vec<&str> = issues.iter().map(|i| i.filename.as_str()).collect();
        assert_eq!(issues.len(), 3);
        assert_eq!(
            filenames,
            vec![
                "2026-02-01-c.md",
                "alice/2026-01-01-a.md",
                "bob/2026-05-10-b.md"
            ],
            "deterministic sort by relative filename"
        );
    }

    #[test]
    fn list_sorts_chronologically_within_a_group() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-03-01-c.md",
            &sample_frontmatter(3, "C", "todo"),
        );
        write_issue(
            &store,
            "alice/2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        write_issue(
            &store,
            "alice/2026-02-01-b.md",
            &sample_frontmatter(2, "B", "todo"),
        );
        let issues = store.list().unwrap();
        let numbers: Vec<u32> = issues.iter().map(|i| i.number).collect();
        assert_eq!(numbers, vec![1, 2, 3]);
    }

    #[test]
    fn list_ignores_non_md_files_in_segments() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        fs::write(store.issues_dir.join("alice/notes.txt"), "not an issue").unwrap();
        fs::write(store.issues_dir.join("alice/.tix-tmp-123-456"), "orphan").unwrap();
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].filename, "alice/2026-01-01-a.md");
    }

    #[test]
    fn list_skips_temp_marker_directories() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join(".tix-tmp-999-0")).unwrap();
        write_issue(
            &store,
            ".tix-tmp-999-0/2026-01-01-junk.md",
            &sample_frontmatter(9, "J", "todo"),
        );
        write_issue(
            &store,
            "2026-01-01-a.md",
            &sample_frontmatter(1, "A", "todo"),
        );
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].filename, "2026-01-01-a.md");
    }

    #[test]
    fn list_parse_error_carries_grouped_relative_path() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        fs::write(
            store.issues_dir.join("alice/2026-01-01-bad.md"),
            "no frontmatter here\n",
        )
        .unwrap();
        let err = store.list().unwrap_err();
        assert!(
            matches!(&err, TixError::Parse(m) if m.starts_with("alice/2026-01-01-bad.md:")),
            "parse error must carry the relative path, got {err:?}"
        );
    }

    // ------------------------------------------------------------------
    // T007 — grouped create writes into the assignee segment (FR-029/30)
    // ------------------------------------------------------------------

    #[test]
    fn create_uses_the_default_layout_template() {
        // The documented default: `{assignee}/{type}/{status}` for the directory,
        // `{date}-{slug}.md` for the filename. With no `type:` attribute the type
        // component falls back to `default`.
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let store = Store {
            issues_dir: dir,
            config: Config::default(),
        };
        let mut issue = Issue {
            number: 0,
            title: "Round trip".into(),
            status: Status::new("todo"),
            labels: vec![],
            priority: Priority::default(),
            assignee: Some("@alice".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            parent: None,
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            entered_at: None,
            source: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
        };
        store.create(&mut issue, "", None).unwrap();
        assert_eq!(
            issue.filename,
            "alice/default/todo/2026-01-01-round-trip.md"
        );
        assert!(
            store
                .issues_dir
                .join("alice/default/todo/2026-01-01-round-trip.md")
                .is_file()
        );
    }

    #[test]
    fn update_always_reconciles_the_file_location() {
        // Unconditional auto-migration: a write moves the file to the directory
        // `[layout]` renders, even from a legacy/mismatched path.
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let store = Store {
            issues_dir: dir,
            config: Config::default(),
        };
        let mut issue = Issue {
            number: 0,
            type_: None,
            title: "Round trip".into(),
            status: Status::new("todo"),
            labels: vec![],
            priority: Priority::default(),
            assignee: Some("@alice".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            parent: None,
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            entered_at: None,
            source: None,
            created: "2026-01-01".into(),
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
        };
        store.create(&mut issue, "", None).unwrap();
        let old = issue.filename.clone();

        // A status change relocates the laid-out file into the new status dir.
        issue.status = Status::new("done");
        issue.filename = store.update(&old, &issue).unwrap();
        assert_eq!(
            issue.filename,
            "alice/default/done/2026-01-01-round-trip.md"
        );
        assert!(!store.issues_dir.join(&old).exists());

        // A mismatched (legacy flat) file is left for `tix layout migrate`.
        let flat = "2026-01-01-legacy.md";
        fs::write(
            store.issues_dir.join(flat),
            "---\nnumber: 9\ntitle: L\nstatus: todo\nlabels: []\npriority: medium\n\
             files: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nbody\n",
        )
        .unwrap();
        let mut legacy = store
            .get(IssueSelector::Filename(flat.to_string()))
            .unwrap();
        legacy.status = Status::new("done");
        let after = store.update(flat, &legacy).unwrap();
        assert_eq!(after, "unassigned/default/done/2026-01-01-legacy.md");
        assert!(!store.issues_dir.join(flat).exists(), "migrated, not left");
        assert!(store.issues_dir.join(&after).is_file());
    }

    #[test]
    fn create_writes_into_assignee_segment_and_records_relative_filename() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: Some("Herbert Maschke <thyseus@pm.me>".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let path = store
            .create(&mut issue, "body", Some("custom-stem"))
            .unwrap();
        let rel = "herbert-maschke/custom-stem.md";
        assert_eq!(issue.filename, rel);
        assert_eq!(path, store.issues_dir.join(rel));
        assert!(store.issues_dir.join("herbert-maschke").is_dir());
        assert!(store.issues_dir.join(rel).is_file());
    }

    #[test]
    fn create_without_assignee_writes_unassigned_segment() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let path = store.create(&mut issue, "", Some("stem")).unwrap();
        assert_eq!(issue.filename, "unassigned/stem.md");
        assert!(store.issues_dir.join("unassigned").is_dir());
        assert!(store.issues_dir.join("unassigned/stem.md").is_file());
        assert_eq!(path, store.issues_dir.join("unassigned/stem.md"));
    }

    #[test]
    fn create_with_at_handle_derives_bare_segment() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "T".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: Some("@alice".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue, "", Some("stem")).unwrap();
        assert_eq!(issue.filename, "alice/stem.md");
        assert!(store.issues_dir.join("alice/stem.md").is_file());
    }

    // ------------------------------------------------------------------
    // T008 — reassign(): move-on-reassign (FR-031), never overwrites
    // ------------------------------------------------------------------

    #[test]
    fn reassign_moves_file_between_segments() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(1, "X", "todo"),
        );
        let new_path = store
            .reassign("alice/2026-01-01-x.md", Some("@bob"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("bob/2026-01-01-x.md"));
        assert!(store.issues_dir.join("bob/2026-01-01-x.md").is_file());
        assert!(!store.issues_dir.join("alice/2026-01-01-x.md").exists());
    }

    #[test]
    fn reassign_into_occupied_segment_picks_deterministic_suffix() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        fs::create_dir_all(store.issues_dir.join("bob")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(1, "X", "todo"),
        );
        write_issue(
            &store,
            "bob/2026-01-01-x.md",
            &sample_frontmatter(2, "X", "todo"),
        );
        let new_path = store
            .reassign("alice/2026-01-01-x.md", Some("@bob"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("bob/2026-01-01-x-1.md"));
        assert!(store.issues_dir.join("bob/2026-01-01-x.md").is_file());
        assert!(store.issues_dir.join("bob/2026-01-01-x-1.md").is_file());
        assert!(!store.issues_dir.join("alice/2026-01-01-x.md").exists());
    }

    #[test]
    fn reassign_legacy_flat_file_into_segment() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-y.md",
            &sample_frontmatter(1, "Y", "todo"),
        );
        let new_path = store.reassign("2026-01-01-y.md", Some("alice")).unwrap();
        assert_eq!(new_path, PathBuf::from("alice/2026-01-01-y.md"));
        assert!(store.issues_dir.join("alice/2026-01-01-y.md").is_file());
        assert!(!store.issues_dir.join("2026-01-01-y.md").exists());
    }

    #[test]
    fn reassign_to_none_uses_unassigned_fallback() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-z.md",
            &sample_frontmatter(1, "Z", "todo"),
        );
        let new_path = store.reassign("alice/2026-01-01-z.md", None).unwrap();
        assert_eq!(new_path, PathBuf::from("unassigned/2026-01-01-z.md"));
        assert!(
            store
                .issues_dir
                .join("unassigned/2026-01-01-z.md")
                .is_file()
        );
        assert!(!store.issues_dir.join("alice/2026-01-01-z.md").exists());
    }

    #[test]
    fn reassign_keeps_number_and_created_stable() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "Stable".into(),
            status: Status::default(),
            labels: vec![],
            priority: Priority::default(),
            assignee: Some("alice".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue, "body", None).unwrap();
        let number = issue.number;
        let created = issue.created.clone();
        let before = issue.filename.clone();
        let new_path = store.reassign(&before, Some("@bob")).unwrap();
        let rescan = store.list().unwrap();
        let moved = rescan
            .iter()
            .find(|i| i.filename == new_path)
            .expect("moved file must be listed at its new relative path");
        assert_eq!(moved.number, number);
        assert_eq!(moved.created, created);
        assert_eq!(moved.title, "Stable");
    }

    #[test]
    fn reassign_equal_segment_is_noop() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-x.md",
            &sample_frontmatter(1, "X", "todo"),
        );
        let new_path = store
            .reassign("alice/2026-01-01-x.md", Some("alice"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("alice/2026-01-01-x.md"));
        assert!(store.issues_dir.join("alice/2026-01-01-x.md").is_file());
    }

    #[test]
    fn reassign_missing_file_is_not_found() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let err = store.reassign("nope.md", Some("alice")).unwrap_err();
        assert!(matches!(err, TixError::NotFound(_)));
    }

    // ------------------------------------------------------------------
    // T009 — validate_filename relaxation + relative-path ops (C-008/C-010)
    // ------------------------------------------------------------------

    #[test]
    fn validate_filename_allows_flat_and_single_segment_prefix() {
        validate_filename("2026-01-01-x.md").unwrap();
        validate_filename("alice/2026-01-01-x.md").unwrap();
    }

    #[test]
    fn validate_filename_allows_deeper_segments() {
        // Configurable layout: depth is unbounded, so a nested path is valid.
        validate_filename("alice/bug/in-progress/2026-01-01-x.md").unwrap();
    }

    #[test]
    fn validate_filename_refuses_leading_and_trailing_slash_and_absolute() {
        let err = validate_filename("/alice/2026-01-01-x.md").unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
        let err = validate_filename("/etc/passwd").unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
        let err = validate_filename("alice/").unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
    }

    #[test]
    fn path_traversal_with_segment_dotdot_refused() {
        let err = validate_filename("alice/../../x.md").unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
        let err = validate_filename("alice/../x.md").unwrap_err();
        assert!(matches!(err, TixError::InvalidInput(_)));
    }

    #[test]
    fn get_update_delete_set_status_work_on_grouped_relative_paths() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-g.md",
            &sample_frontmatter(7, "G", "todo"),
        );
        let got = store
            .get(IssueSelector::Filename("alice/2026-01-01-g.md".into()))
            .unwrap();
        assert_eq!(got.number, 7);
        let done = store
            .set_status("alice/2026-01-01-g.md", StatusChange::to("done"))
            .unwrap();
        assert_eq!(done.issue.status.display(), "done");
        assert!(store.issues_dir.join("alice/2026-01-01-g.md").is_file());
        let mut edited = store
            .get(IssueSelector::Filename("alice/2026-01-01-g.md".into()))
            .unwrap();
        edited.title = "Updated".into();
        store.update("alice/2026-01-01-g.md", &edited).unwrap();
        let reloaded = store
            .get(IssueSelector::Filename("alice/2026-01-01-g.md".into()))
            .unwrap();
        assert_eq!(reloaded.title, "Updated");
        store.delete("alice/2026-01-01-g.md").unwrap();
        assert!(!store.issues_dir.join("alice/2026-01-01-g.md").exists());
    }

    // ------------------------------------------------------------------
    // T010 — grouped round-trip sweep
    // ------------------------------------------------------------------

    #[test]
    fn grouped_round_trip_create_list_get_update_delete() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let mut issue = Issue {
            number: 0,
            title: "Round trip".into(),
            status: Status::default(),
            labels: vec!["bug".into()],
            priority: Priority::default(),
            assignee: Some("Herbert Maschke <thyseus@pm.me>".into()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: String::new(),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        store.create(&mut issue, "initial body", None).unwrap();
        let rel = issue.filename.clone();
        assert_eq!(rel, "herbert-maschke/2026-01-01-round-trip.md");

        let listed = store.list().unwrap();
        assert_eq!(listed.len(), 1);
        assert_eq!(listed[0].filename, rel);
        assert_eq!(listed[0].number, issue.number);

        let got = store.get(IssueSelector::Filename(rel.clone())).unwrap();
        let mut edited = got.clone();
        edited.title = "Renamed".into();
        store.update(&rel, &edited).unwrap();
        let reloaded = store.get(IssueSelector::Filename(rel.clone())).unwrap();
        assert_eq!(reloaded.title, "Renamed");

        store.delete(&rel).unwrap();
        assert!(!store.issues_dir.join(&rel).exists());
        assert!(store.list().unwrap().is_empty());
    }

    #[test]
    fn legacy_flat_file_edit_and_status_still_work_after_layout_flip() {
        let (tmp, store) = make_store();
        let _ = tmp;
        write_issue(
            &store,
            "2026-01-01-legacy.md",
            &sample_frontmatter(5, "Legacy", "todo"),
        );
        let listed = store.list().unwrap();
        assert_eq!(listed.len(), 1);
        assert_eq!(listed[0].filename, "2026-01-01-legacy.md");
        let mutated = store
            .set_status("2026-01-01-legacy.md", StatusChange::to("in progress"))
            .unwrap();
        assert_eq!(mutated.issue.status.display(), "in progress");
        assert!(store.issues_dir.join("2026-01-01-legacy.md").is_file());
    }

    // ------------------------------------------------------------------
    // T004 — add_asset(): copy + link insert (FR-006, NFR-004)
    // ------------------------------------------------------------------

    fn write_asset_source(tmp: &tempfile::TempDir, name: &str, contents: &[u8]) -> PathBuf {
        let path = tmp.path().join(name);
        fs::write(&path, contents).unwrap();
        path
    }

    fn write_issue_with_basic_body(store: &Store, name: &str, number: u32) {
        write_issue(
            store,
            name,
            &sample_frontmatter(number, "Asset host", "todo"),
        );
    }

    #[test]
    fn add_asset_image_inserts_image_link_and_writes_file() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "diagram.png", b"PNGDATA");
        let added = store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        assert_eq!(added.written_name, "diagram.png");
        assert_eq!(added.link, "![diagram](fix-login-bug-assets/diagram.png)");
        assert!(
            store
                .issues_dir
                .join("alice/fix-login-bug-assets/diagram.png")
                .is_file()
        );
    }

    #[test]
    fn add_asset_non_image_inserts_generic_markdown_link() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "report.pdf", b"%PDF");
        let added = store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        assert_eq!(added.link, "[report](fix-login-bug-assets/report.pdf)");
        assert!(
            store
                .issues_dir
                .join("alice/fix-login-bug-assets/report.pdf")
                .is_file()
        );
    }

    #[test]
    fn add_asset_collision_resolves_with_numeric_suffix_and_link_points_at_it() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "x.png", b"first");
        let first = store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        assert_eq!(first.written_name, "x.png");
        let again = store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        assert_eq!(again.written_name, "x-1.png");
        assert_eq!(again.link, "![x-1](fix-login-bug-assets/x-1.png)");
        assert!(
            store
                .issues_dir
                .join("alice/fix-login-bug-assets/x.png")
                .is_file()
        );
        assert!(
            store
                .issues_dir
                .join("alice/fix-login-bug-assets/x-1.png")
                .is_file()
        );
    }

    #[test]
    fn add_asset_appends_single_link_and_preserves_description() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue(
            &store,
            "alice/2026-01-01-fix-login-bug.md",
            "---\nnumber: 1\ntitle: \"H\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nTitle line.\n\n## Comments\n\n### alice (2026-01-01)\n\nExisting comment.\n",
        );
        let src = write_asset_source(&tmp, "diagram.svg", b"<svg/>");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        let reloaded = store
            .get(crate::storage::IssueSelector::Filename(
                "alice/2026-01-01-fix-login-bug.md".into(),
            ))
            .unwrap();
        // Description (above the `## Comments` boundary) untouched.
        assert_eq!(reloaded.description(), "Title line.");
        // Exactly one link line, appended after the comments section.
        let link_count = reloaded.body.matches("![diagram]").count();
        assert_eq!(link_count, 1);
        assert!(
            reloaded
                .body
                .ends_with("fix-login-bug-assets/diagram.svg)\n")
        );
    }

    #[test]
    fn add_asset_missing_issue_is_not_found() {
        let (tmp, store) = make_store();
        let _ = tmp;
        let src = write_asset_source(&tmp, "x.png", b"x");
        let err = store.add_asset("missing.md", &src).unwrap_err();
        assert!(matches!(err, TixError::NotFound(_)));
    }

    #[test]
    fn add_asset_legacy_flat_file_uses_stem_assets_under_issues_dir() {
        let (tmp, store) = make_store();
        write_issue_with_basic_body(&store, "2026-01-01-legacy.md", 1);
        let src = write_asset_source(&tmp, "x.png", b"x");
        let added = store.add_asset("2026-01-01-legacy.md", &src).unwrap();
        assert_eq!(added.link, "![x](legacy-assets/x.png)");
        assert!(store.issues_dir.join("legacy-assets/x.png").is_file());
    }

    // ------------------------------------------------------------------
    // T005 — reassign() moves the assets dir (FR-007)
    // ------------------------------------------------------------------

    #[test]
    fn reassign_moves_asset_dir_with_the_file() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "diagram.png", b"PNGDATA");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        let new_path = store
            .reassign("alice/2026-01-01-fix-login-bug.md", Some("@bob"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("bob/2026-01-01-fix-login-bug.md"));
        assert!(
            store
                .issues_dir
                .join("bob/fix-login-bug-assets/diagram.png")
                .is_file()
        );
        assert!(!store.issues_dir.join("alice/fix-login-bug-assets").exists());
    }

    #[test]
    fn reassign_without_asset_dir_behaves_as_before() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-plain.md", 1);
        let new_path = store
            .reassign("alice/2026-01-01-plain.md", Some("@bob"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("bob/2026-01-01-plain.md"));
        assert!(store.issues_dir.join("bob/2026-01-01-plain.md").is_file());
        assert!(!store.issues_dir.join("bob/plain-assets").exists());
    }

    #[test]
    fn reassign_into_segment_with_same_named_asset_dir_uses_suffix_no_loss() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        fs::create_dir_all(store.issues_dir.join("bob")).unwrap();
        // Both segments already hold a same-named asset dir.
        let existing = store.issues_dir.join("bob/fix-login-bug-assets");
        fs::create_dir_all(&existing).unwrap();
        fs::write(existing.join("keep.txt"), "precious").unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "diagram.png", b"PNGDATA");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        let new_path = store
            .reassign("alice/2026-01-01-fix-login-bug.md", Some("@bob"))
            .unwrap();
        assert_eq!(new_path, PathBuf::from("bob/2026-01-01-fix-login-bug.md"));
        // Pre-existing target assets untouched, moved dir suffixed.
        assert!(existing.join("keep.txt").is_file());
        assert!(
            store
                .issues_dir
                .join("bob/fix-login-bug-assets-1/diagram.png")
                .is_file()
        );
        assert!(!store.issues_dir.join("alice/fix-login-bug-assets").exists());
    }

    #[test]
    fn reassign_preserves_markdown_link_resolution_in_new_segment() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "diagram.png", b"PNGDATA");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        store
            .reassign("alice/2026-01-01-fix-login-bug.md", Some("@bob"))
            .unwrap();
        // The asset dir kept its base name, so the relative link
        // `fix-login-bug-assets/diagram.png` resolves in the new segment.
        assert!(
            store
                .issues_dir
                .join("bob/fix-login-bug-assets/diagram.png")
                .is_file()
        );
    }

    // ------------------------------------------------------------------
    // T006 — delete() removes the assets dir (FR-008) + sweep
    // ------------------------------------------------------------------

    #[test]
    fn delete_removes_asset_dir_no_orphans() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "x.png", b"x");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        store.delete("alice/2026-01-01-fix-login-bug.md").unwrap();
        assert!(
            !store
                .issues_dir
                .join("alice/2026-01-01-fix-login-bug.md")
                .exists()
        );
        assert!(!store.issues_dir.join("alice/fix-login-bug-assets").exists());
    }

    #[test]
    fn delete_without_asset_dir_still_deletes_file() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-plain.md", 1);
        store.delete("alice/2026-01-01-plain.md").unwrap();
        assert!(!store.issues_dir.join("alice/2026-01-01-plain.md").exists());
    }

    #[test]
    fn list_ignores_asset_directories() {
        let (tmp, store) = make_store();
        write_issue_with_basic_body(&store, "2026-01-01-legacy.md", 1);
        let src = write_asset_source(&tmp, "x.png", b"x");
        store.add_asset("2026-01-01-legacy.md", &src).unwrap();
        // Legacy flat file → `legacy-assets/` sits directly under issues_dir,
        // where the `-assets` guard in `list()` must skip it.
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].filename, "2026-01-01-legacy.md");
    }

    #[test]
    fn list_ignores_nested_asset_directories_under_segment() {
        let (tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        let src = write_asset_source(&tmp, "x.png", b"x");
        store
            .add_asset("alice/2026-01-01-fix-login-bug.md", &src)
            .unwrap();
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].filename, "alice/2026-01-01-fix-login-bug.md");
    }

    #[test]
    fn asset_dir_with_formless_md_child_is_not_scanned_as_segment() {
        let (tmp, store) = make_store();
        let _ = tmp;
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        write_issue_with_basic_body(&store, "alice/2026-01-01-fix-login-bug.md", 1);
        // A `.md` straggler inside an `-assets` dir must never surface as an
        // issue segment (guard in `list()` for `<slug>-assets/`).
        let assets_dir = store.issues_dir.join("alice/fix-login-bug-assets");
        fs::create_dir_all(&assets_dir).unwrap();
        fs::write(assets_dir.join("notes.md"), "no frontmatter").unwrap();
        let issues = store.list().unwrap();
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].filename, "alice/2026-01-01-fix-login-bug.md");
    }

    // -----------------------------------------------------------------------
    // WP02 / T008 — hierarchy writes
    // -----------------------------------------------------------------------
    //
    // Requirement ids in the test names: C-001 (at most one parent), C-003 (no
    // child data on the parent), C-004 (every change audited), SC-004 (a rejected
    // change writes nothing).
    //
    // These tests assert the *write* behaviour only. Every rule lives in
    // `crate::hierarchy`; the last test below is the guard against one of them
    // being copied in here.

    /// Three seeded issues, for the hierarchy write tests.
    fn hierarchy_trio() -> (TempDir, Store) {
        let (tmp, store) = make_store();
        for (n, title) in [(1, "A"), (2, "B"), (3, "C")] {
            write_issue(
                &store,
                &format!("2026-01-01-{}.md", title.to_lowercase()),
                &bare_frontmatter(n, title),
            );
        }
        (tmp, store)
    }

    /// A store over one checked-in hierarchy fixture, by file name.
    ///
    /// `tests/fixtures/hierarchy/` rather than a string built inline, because the
    /// interesting cases are exactly the states the command layer refuses to
    /// create: a self-parent, a dangling reference. Those can only be reached by
    /// writing the file, which is the point of the fixtures.
    fn store_from_hierarchy_fixture(name: &str) -> (TempDir, Store) {
        let (tmp, store) = make_store();
        write_issue(
            &store,
            name,
            &std::fs::read_to_string(format!(
                "{}/tests/fixtures/hierarchy/{name}",
                env!("CARGO_MANIFEST_DIR")
            ))
            .unwrap(),
        );
        (tmp, store)
    }

    fn bytes_of(store: &Store, number: u32) -> String {
        let issue = store.get(IssueSelector::Number(number)).unwrap();
        read_issue_file(store, &issue.filename)
    }

    #[test]
    fn t008_set_writes_the_field_and_exactly_one_history_event() {
        let (_tmp, store) = hierarchy_trio();
        let outcome = store.set_parent("2", "1").unwrap();
        assert!(outcome.changed);
        assert_eq!(outcome.parent, Some(1));

        let child = store.get(IssueSelector::Number(2)).unwrap();
        assert_eq!(child.parent, Some(1), "C-001: the number is stored");
        assert_eq!(child.history.len(), 1, "C-004: exactly one event");
        let event = &child.history.events()[0];
        assert_eq!(event.kind, HistoryEventKind::ParentSet);
        assert!(
            !event.actor.is_empty(),
            "an event without an actor is not an audit record"
        );
        // The detail names both sides, read from the *previous* value.
        assert_eq!(event.detail, "parent none -> #1", "got: {}", event.detail);
    }

    #[test]
    fn t008_change_repoints_and_records_parent_changed() {
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("3", "1").unwrap();
        let outcome = store.change_parent("3", "2").unwrap();
        assert!(outcome.changed);
        assert_eq!(outcome.parent, Some(2));

        let child = store.get(IssueSelector::Number(3)).unwrap();
        assert_eq!(child.parent, Some(2));
        assert_eq!(child.history.len(), 2, "one event per accepted change");
        let events = child.history.events();
        let last = events.last().unwrap();
        assert_eq!(last.kind, HistoryEventKind::ParentChanged);
        // Regression: the detail used to be built after the assignment, so a
        // repoint recorded `parent #1 -> #1` and named neither side.
        assert_eq!(last.detail, "parent #1 -> #2", "got: {}", last.detail);
    }

    #[test]
    fn t008_clear_removes_the_field_and_records_parent_cleared() {
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("2", "1").unwrap();
        let outcome = store.clear_parent("2").unwrap();
        assert!(outcome.changed);
        assert_eq!(outcome.parent, None);

        let child = store.get(IssueSelector::Number(2)).unwrap();
        assert_eq!(child.parent, None);
        assert_eq!(child.history.len(), 2);
        let events = child.history.events();
        let last = events.last().unwrap();
        assert_eq!(last.kind, HistoryEventKind::ParentCleared);
        assert_eq!(last.detail, "parent #1 -> none", "got: {}", last.detail);
    }

    #[test]
    fn t008_reapplying_the_same_parent_is_a_no_op_with_no_second_event() {
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("2", "1").unwrap();
        let after_first = bytes_of(&store, 2);

        let second = store.set_parent("2", "1").unwrap();
        assert!(!second.changed, "an unchanged parent is not a change");
        assert!(second.event.is_none(), "a no-op records nothing (C-004)");
        assert_eq!(
            bytes_of(&store, 2),
            after_first,
            "a no-op must not rewrite the file at all"
        );
    }

    #[test]
    fn t008_clearing_a_child_with_no_parent_is_a_no_op() {
        let (_tmp, store) = hierarchy_trio();
        let before = bytes_of(&store, 2);
        let outcome = store.clear_parent("2").unwrap();
        assert!(!outcome.changed);
        assert!(outcome.event.is_none());
        assert_eq!(bytes_of(&store, 2), before);
    }

    #[test]
    fn t008_sc004_a_rejected_cycle_leaves_every_file_byte_identical() {
        // 1 -> 2 -> 3, then ask 1 to become a child of 3: that closes the loop.
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("2", "1").unwrap();
        store.set_parent("3", "2").unwrap();
        let before: Vec<String> = (1..=3).map(|n| bytes_of(&store, n)).collect();

        let err = store
            .set_parent("1", "3")
            .expect_err("1 -> 2 -> 3 -> 1 is a cycle and must be refused");
        let msg = err.to_string();
        assert!(
            msg.contains("cycle"),
            "the diagnostic must name the rule: {msg}"
        );

        // SC-004: nothing written, nothing appended, on *any* file.
        for n in 1..=3 {
            assert_eq!(
                bytes_of(&store, n),
                before[(n - 1) as usize],
                "issue {n} must be byte-identical after a rejected cycle"
            );
        }
    }

    #[test]
    fn t008_a_self_parent_is_rejected_and_writes_nothing() {
        let (_tmp, store) = hierarchy_trio();
        let before = bytes_of(&store, 2);
        let err = store
            .set_parent("2", "2")
            .expect_err("an issue cannot be its own parent");
        assert!(err.to_string().contains("self_parent"), "got: {err}");
        assert_eq!(bytes_of(&store, 2), before);
    }

    #[test]
    fn t008_a_self_parent_already_on_disk_is_still_refused() {
        // The laundering case, through the file path rather than the service.
        //
        // A child that *already* records itself as its own parent looks like a
        // redundant request, and a no-op check placed before validation accepted it
        // as one — while the identical request against any other child was refused.
        // Only a fixture in that state can catch it: the test above seeds a
        // parentless child, so the guard never fired.
        let (_tmp, store) = store_from_hierarchy_fixture("self-parent.md");
        let before = bytes_of(&store, 7);
        let err = store
            .set_parent("7", "7")
            .expect_err("a stored self-parent must still be refused on a re-set");
        assert!(
            err.to_string().contains("self_parent"),
            "refused for the wrong reason: {err}"
        );
        assert_eq!(
            bytes_of(&store, 7),
            before,
            "and the refused write must leave the file byte-identical"
        );
        // `change_parent` shares the path and must refuse identically.
        assert!(store.change_parent("7", "7").is_err());
        // The fixture really is in the state under test.
        assert_eq!(store.get(IssueSelector::Number(7)).unwrap().parent, Some(7));
    }

    #[test]
    fn t008_c003_setting_a_child_writes_nothing_to_the_parents_file() {
        // Child membership is derived by inverting the child's pointer; the
        // parent file must not learn about it at all.
        let (_tmp, store) = hierarchy_trio();
        let parent_before = bytes_of(&store, 1);
        store.set_parent("2", "1").unwrap();
        store.set_parent("3", "1").unwrap();
        assert_eq!(
            bytes_of(&store, 1),
            parent_before,
            "the parent's file must be untouched by its children appearing"
        );
        assert!(
            !parent_before.contains("parent:"),
            "the parent is a top of the hierarchy and has no parent itself"
        );
    }

    #[test]
    fn t008_a_legacy_file_without_the_field_is_unchanged_by_a_no_op_write() {
        // The file-format contract, seen through the write path.
        let (_tmp, store) = hierarchy_trio();
        let before = bytes_of(&store, 2);
        assert!(!before.contains("parent:"), "the fixture must be legacy");

        store.clear_parent("2").unwrap();
        assert_eq!(bytes_of(&store, 2), before, "a no-op must not add the key");
    }

    #[test]
    fn t008_an_unresolvable_selector_is_refused_before_any_write() {
        let (_tmp, store) = hierarchy_trio();
        let before = bytes_of(&store, 2);
        assert!(store.set_parent("2", "no such issue").is_err());
        assert!(store.change_parent("2", "999").is_err());
        assert_eq!(bytes_of(&store, 2), before);
    }

    #[test]
    fn t008_t008_contains_no_hierarchy_rule_of_its_own() {
        // T008's own note: "Storage must contain no hierarchy *rules*. If a check
        // appears here that also exists in the service, that is a defect."
        //
        // Asserted behaviourally rather than by reading the source: a storage
        // rejection must be **exactly** what the service says for the same
        // snapshot. If someone re-implemented a rule here, the two would drift and
        // this comparison would stop holding.
        //
        // Compared against the service *type's own* rendering, reached through the
        // `From<HierarchyError> for TixError` conversion the call site uses. An
        // earlier version of this test compared storage against a private
        // `hierarchy_error` helper — both sides went through the same function, so
        // it certified only that the helper was called, and it could not detect the
        // duplication it was meant to police (a second renderer that had drifted
        // from the first).
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("2", "1").unwrap();
        store.set_parent("3", "2").unwrap();

        let issues = store.list().unwrap();
        let views: Vec<IssueView<'_>> = issues.iter().map(Issue::issue_view).collect();
        let index = HierarchyIndex::build(&views);
        let service =
            hierarchy::set_parent(&index, 1, 3).expect_err("the service refuses this too");
        let storage = store.set_parent("1", "3").expect_err("and so does storage");

        assert_eq!(
            storage.to_string(),
            TixError::from(service).to_string(),
            "storage must surface the service's diagnosis verbatim, not its own"
        );
        // And the rendering is the shared one, not a lookalike: the kind is
        // prefixed exactly once and no diagnostic is dropped.
        let text = storage.to_string();
        assert!(
            text.contains("cycle:") && !text.contains("cycle: cycle:"),
            "a lookalike renderer or a doubled prefix: {text}"
        );
        assert!(
            text.starts_with("invalid input: "),
            "a hierarchy refusal must carry the same prefix as every other: {text}"
        );
    }

    #[test]
    fn t008_a_no_op_reports_no_written_issue_but_still_reports_the_current_parent() {
        // Pins the `ParentOutcome` contract, which its own doc comment used to
        // contradict: `written` is `None` for a no-op (matching
        // `RelationshipOutcome`), and the real state comes from `parent`.
        let (_tmp, store) = hierarchy_trio();
        store.set_parent("2", "1").unwrap();
        let again = store.set_parent("2", "1").unwrap();
        assert!(!again.changed);
        assert!(
            again.written.is_none(),
            "a no-op wrote nothing, so there is no written issue to hand back"
        );
        assert!(
            again.event.is_none(),
            "and no event, or a retry would pad the audit trail"
        );
        assert_eq!(
            again.parent,
            Some(1),
            "but the resulting state is still reported, so a caller need not re-read"
        );
    }
}