omh 0.3.0

//! Composing the rules file, rather than replacing it.
//!
//! omh mounts its rules read-only over the filenames each harness reads, which
//! keeps omh's staging out of the user's commit — and, until this module
//! existed, also hid the project's own `AGENTS.md` for the length of the
//! session. The agent ran without ever reading the conventions the repo had
//! written down, and nothing said so: the file was intact on disk, so the guard
//! that watched the disk stayed green.
//!
//! The guard that watched the disk is `a_repos_own_rules_file_survives_staging`
//! — it proves the file is intact for the user's diff, which was mistaken for
//! the whole obligation.
//!
//! So the mount stays and the *document* grows: the project's rules are read
//! from the host worktree, which the mount only shadows *inside* the container,
//! and composed into what the harness is given.

use crate::adapter::{Adapter, Binding, Capability};
use crate::profile::Paths;
use anyhow::{Context, Result};
use std::path::Path;
use std::process::Command;

/// The filename omh reads on the project's side. Harness-neutral on purpose:
/// what the *container* sees is the adapter's business, and an adapter that
/// reads something else says so in `path` and `also`.
const CANONICAL: &str = "AGENTS.md";

/// Where a section's text came from.
///
/// An enum rather than a string because the two kinds answer different
/// questions and callers already needed to tell them apart — a test asserting
/// `!body.contains("<repo>/")` is string-sniffing a discriminant.
#[derive(Debug, PartialEq)]
enum Origin {
    /// A rule from your catalogue, named by the file you filed it under.
    ///
    /// A name rather than a layer: when content lived in three directories of
    /// identical shape the only useful thing a marker could say was which of
    /// them it came from, and with one catalogue that stops being a question.
    /// `tdd` is what you actually want to see attributed.
    Catalogue { name: String },
    /// The project's own file. `from_base` is the branch it was read from when
    /// the worktree had no copy — the agent is otherwise told its own branch
    /// says something it does not.
    Project {
        name: String,
        from_base: Option<String>,
    },
    /// omh's own, generated from the base manifest. Named by entry, so the
    /// marker is something `omh why` can answer for rather than a label.
    Omh { name: String },
}

impl std::fmt::Display for Origin {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Catalogue { name } => write!(f, "{name}"),
            Self::Project {
                name,
                from_base: Some(base),
            } => write!(f, "{base}:{name}"),
            Self::Project {
                name,
                from_base: None,
            } => write!(f, "<repo>/{name}"),
            // `base:` rather than `omh:` — the marker already opens with
            // `<!-- omh:`, and it names the base set the section came from.
            Self::Omh { name } => write!(f, "base:{name}"),
        }
    }
}

/// One contribution to the composed document, and where it came from.
#[derive(Debug, PartialEq)]
struct Section {
    origin: Origin,
    body: String,
}

/// What the launcher has to tell the user, if anything. `notices()` is empty
/// when nothing was unusual — `Report::default()` is *not* that test, because
/// `composed` is set on the ordinary path too.
///
/// Composing a file the user did not name is a fallback, and a fallback nobody
/// is told about is indistinguishable from a bug — that is the whole reason
/// this is returned rather than handled quietly.
///
/// `composed` is stored and `read_instead` derived from it, rather than the
/// other way round. Storing only the unusual case made two things
/// unrepresentable that the launcher needed: which file actually won, and the
/// fact that `read_instead == Some("AGENTS.md")` is nonsense.
#[derive(Debug, Default, PartialEq)]
pub struct Report {
    /// The declared name whose bytes were composed. `None` when the project has
    /// no rules file of its own.
    pub composed: Option<String>,
    /// A declared name with different content that lost. Never `composed`.
    pub not_composed: Option<String>,
}

impl Report {
    /// The composed name, when it is not the canonical one — the only case
    /// worth telling the user about.
    pub fn read_instead(&self) -> Option<&str> {
        self.composed.as_deref().filter(|n| *n != CANONICAL)
    }

    /// What to tell the user, ready to print. Empty when nothing is unusual.
    ///
    /// Here rather than at the call site because there are three of them —
    /// `run`, `attach` and `doctor` all compose — and only one was printing.
    /// A fallback announced on one path out of three is the failure this type
    /// exists to prevent, wearing the type that was supposed to prevent it.
    pub fn notices(&self) -> Vec<String> {
        let mut out = Vec::new();
        if let Some(name) = self.read_instead() {
            out.push(format!("composed {name} — rename it to {CANONICAL}"));
        }
        // Names both files. The winner is not always `AGENTS.md`: from a
        // session's second launch the canonical name may hold omh's own
        // placeholder, so a hardcoded "differs from AGENTS.md" could name a
        // file that was never compared.
        if let Some(lost) = &self.not_composed {
            let won = self.composed.as_deref().unwrap_or(CANONICAL);
            out.push(format!(
                "warning: {lost} differs from {won} and was not composed"
            ));
        }
        out
    }
}

/// The whole rules document for one launch, plus what to say about it.
///
/// `worktree` rather than the repo root: a session works on its own checkout,
/// and a branch that has just written its rules should be governed by them.
pub fn compose(
    paths: &Paths,
    adapter: &Adapter,
    worktree: &Path,
    base: Option<&str>,
    own: &[crate::base::Section],
    selection: &crate::selection::Selection,
) -> Result<(String, Report)> {
    let (project, report) = match adapter.supports(Capability::Rules) {
        Some(binding) => project(binding, paths, worktree, base)?,
        // No adapter omh ships omits `rules`, so this is unreachable today —
        // but the binding is where the filenames come from, so its absence has
        // to mean "no project section" rather than a panic. `plan` composes
        // before it drops capabilities, so it cannot be relied on to filter
        // this out first.
        None => (None, Report::default()),
    };

    let mut sections = Vec::new();
    // Yours first: they are how you work everywhere, and the project's file is
    // the specific case that qualifies them.
    for (name, body) in catalogue(paths, selection)? {
        sections.push(Section {
            origin: Origin::Catalogue { name },
            body,
        });
    }
    sections.extend(project);

    // omh's own last: they describe the sandbox — what git does here, where
    // notes go, which graph answers what — and a convention the project wrote
    // down should not have omh's account of the box sitting in front of it.
    for section in own {
        sections.push(Section {
            origin: Origin::Omh {
                name: section.name.to_string(),
            },
            body: section.body.clone(),
        });
    }

    Ok((render(&sections), report))
}

/// The project's own rules, and what to report about finding them.
fn project(
    binding: &Binding,
    paths: &Paths,
    worktree: &Path,
    base: Option<&str>,
) -> Result<(Option<Section>, Report)> {
    let mut report = Report::default();
    let mut found: Option<(String, Found)> = None;
    for name in candidates(binding) {
        let Some(candidate) = body(paths, worktree, base, &name)? else {
            continue;
        };
        match &found {
            None => found = Some((name, candidate)),
            // A second name holding the same rules is the common
            // one-points-at-the-other case, and warning about it would train
            // people to ignore the warning that matters. Compared trimmed,
            // because an editor's trailing newline is not a disagreement.
            Some((_, chosen)) if chosen.body.trim() == candidate.body.trim() => {}
            // First conflict only. `Report` names one loser, and with the
            // shipped adapters there cannot be a second.
            Some(_) if report.not_composed.is_none() => {
                report.not_composed = Some(name);
            }
            Some(_) => {}
        }
    }

    let Some((name, found)) = found else {
        return Ok((None, report));
    };
    report.composed = Some(name.clone());
    Ok((
        Some(Section {
            origin: Origin::Project {
                name,
                from_base: found.from_base,
            },
            body: found.body,
        }),
        report,
    ))
}

/// A rules body and where it was read from.
struct Found {
    body: String,
    /// The branch, when the worktree had no copy and `git show` supplied it.
    from_base: Option<String>,
}

/// Filenames to look for, canonical first.
///
/// Taken from the adapter rather than written here: the harness that reads
/// `CLAUDE.md` is a fact the adapter already records, and duplicating it would
/// give omh two places to disagree with itself.
fn candidates(binding: &Binding) -> Vec<String> {
    let mut names: Vec<String> = std::iter::once(&binding.path)
        .chain(binding.also.iter())
        .filter_map(|t| {
            Path::new(t)
                .file_name()
                .map(|n| n.to_string_lossy().into_owned())
        })
        .collect();
    // Canonical first, then the adapter's own order — `path` is its primary by
    // definition and `also` is a list it wrote deliberately. Sorting the tail
    // alphabetically instead silently promoted whichever `also` entry sorted
    // first over the adapter's declared `path`.
    let mut seen = std::collections::BTreeSet::new();
    names.retain(|n| seen.insert(n.clone()));
    if let Some(i) = names.iter().position(|n| n == CANONICAL) {
        names[..=i].rotate_right(1);
    }
    names
}

/// The branch's copy if the worktree has one, otherwise the base branch's.
///
/// Branch-first because a session that has just written an `AGENTS.md` the base
/// branch does not have yet should be governed by it.
fn body(paths: &Paths, worktree: &Path, base: Option<&str>, name: &str) -> Result<Option<Found>> {
    // Blank is absent, and the distinction is load-bearing rather than tidy.
    // `place_destination` puts an empty file at every declared name that does
    // not already have one, because docker will not create a mountpoint inside
    // `/work` — so from a session's second launch onward omh's own placeholder
    // is sitting in the worktree. Read as content it outranks the real rules
    // under the canonical name, and a repo keeping its rules in `CLAUDE.md` lost
    // them, with the only warning naming `CLAUDE.md` as the conflict: omh
    // reporting its own placeholder as the project's rules.
    //
    // A file with nothing in it states no rules under any reading, so there is
    // no case where treating it as absent loses something the user wrote.
    if let Some(body) = read(&worktree.join(name))?.filter(|b| !b.trim().is_empty()) {
        return Ok(Some(Found {
            body,
            from_base: None,
        }));
    }
    let Some(base) = base else {
        return Ok(None);
    };
    show(&paths.repo, base, name)
}

/// `git show <base>:<name>`, distinguishing "not on that branch" from a git
/// that could not answer.
///
/// The first is ordinary — most repos have no rules file — and the second is
/// the `config::read_layer` lesson applied to a subprocess: reporting a broken
/// repository, a missing git or an unresolvable ref as "the project has no
/// rules" is the silent degradation this codebase refuses everywhere else.
/// git says which it is by exit code: 128 with `does not exist` or `unknown
/// revision` on stderr is absence, anything else is a failure worth stopping
/// for.
fn show(repo: &Path, base: &str, name: &str) -> Result<Option<Found>> {
    // Asked as two questions, both answered by exit codes rather than by
    // git's prose. Matching on stderr text was the first attempt and it is
    // wrong twice over: the wording differs between git versions — `invalid
    // object name` and `unknown revision` are the same condition — and it is
    // translated under a non-English locale, so the classification silently
    // inverts on somebody else's machine.
    let git = |args: &[&str]| {
        Command::new("git")
            .current_dir(repo)
            .args(args)
            .output()
            .with_context(|| format!("running git {}", args.join(" ")))
    };

    // Is there a repository at all? Absent from a branch is ordinary; no
    // repository behind `paths.repo` is not — `Paths::discover` refuses to
    // build one without a `.git` above it, so reaching this means something is
    // genuinely wrong, and reporting it as "the project has no rules" is the
    // silent degradation this codebase refuses.
    let inside = git(&["rev-parse", "--git-dir"])?;
    if !inside.status.success() {
        anyhow::bail!(
            "git show {base}:{name}: {}",
            String::from_utf8_lossy(&inside.stderr).trim()
        );
    }

    // Does the path exist at that revision? Non-zero covers every ordinary
    // absence at once: the file is not on the branch, the branch does not
    // exist, or the repo has no commits yet.
    let spec = format!("{base}:{name}");
    if !git(&["cat-file", "-e", &spec])?.status.success() {
        return Ok(None);
    }

    let out = git(&["show", &spec])?;
    if !out.status.success() {
        anyhow::bail!(
            "git show {spec}: {}",
            String::from_utf8_lossy(&out.stderr).trim()
        );
    }
    Ok(Some(Found {
        body: String::from_utf8_lossy(&out.stdout).into_owned(),
        from_base: Some(base.to_string()),
    }))
}

/// Absent and unreadable are different answers.
///
/// `config::read_layer` exists for this reason: `let Ok(..) else { continue }`
/// made a `chmod 000` file report as "not declared", and the resulting advice
/// was a closed loop that exited 0.
fn read(path: &Path) -> Result<Option<String>> {
    match std::fs::read_to_string(path) {
        Ok(body) => Ok(Some(body)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(e) => Err(e).with_context(|| format!("reading {}", path.display())),
    }
}

/// The marker prefix. One place, because `render` writes it and `neutralise`
/// has to recognise exactly what `render` writes.
const MARKER: &str = "<!-- omh:";

/// Each section says where it came from, so the agent — and anyone reading the
/// staged file — can tell a project convention from omh's own instruction.
///
/// A body that contains the marker syntax has it neutralised first. Provenance
/// only means something if omh is the only writer of it: a project's own
/// `AGENTS.md` could otherwise open with `<!-- omh: personal -->` and attribute
/// whatever followed to the user's own profile. Cheap to do, and the whole
/// point of the marker rests on it.
fn render(sections: &[Section]) -> String {
    sections
        .iter()
        .map(|s| {
            format!(
                "{MARKER} {} -->\n{}",
                s.origin,
                neutralise(s.body.trim_end())
            )
        })
        .collect::<Vec<_>>()
        .join("\n\n")
}

fn neutralise(body: &str) -> String {
    body.replace(MARKER, "<!-- omh\u{200b}:")
}

/// Your rules, in the order `[use]` names them.
///
/// Rules build on each other — a general one followed by its exception reads
/// differently reversed — and the only place that ordering can really come from
/// is a list somebody wrote. So `[use].rules` **is** the order, and filename
/// order is what a repo that has not written one falls back to: still *some*
/// order, and a stable one beats whatever `read_dir` happens to return.
///
/// `.md` only, and blank files are dropped for the reason `body` gives: a file
/// with nothing in it states no rules, and emitting a bare marker with no text
/// under it attributes silence to somebody.
fn catalogue(
    paths: &Paths,
    selection: &crate::selection::Selection,
) -> Result<Vec<(String, String)>> {
    let dir = paths.root.join(Capability::Rules.source());
    let entries = match std::fs::read_dir(&dir) {
        Ok(entries) => entries,
        // Absent is not unreadable — `config::read_layer` records what
        // conflating them cost. A catalogue with no rules is the ordinary state
        // of a fresh install; one omh cannot read is a session composed without
        // rules the user believes it has.
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(e).with_context(|| format!("reading {}", dir.display())),
    };

    let mut out = Vec::new();
    for entry in entries {
        let path = entry
            .with_context(|| format!("reading {}", dir.display()))?
            .path();
        if !path.extension().is_some_and(|e| e == "md") {
            continue;
        }
        let Some(body) = read(&path)?.filter(|b| !b.trim().is_empty()) else {
            continue;
        };
        let name = crate::profile::entry_name(path.file_name().unwrap_or_default());
        // A manifest name is omh's, on or off — an error naming both rather
        // than a file that composes. The same rule `render::merge_hooks`
        // applies to a hook file, and it became this module's business when
        // `kind = "rules"` made rules sections manifest entries.
        //
        // Left composing, such a file was wrong four ways at once: it reached
        // the document even when `[use]` did not name it, because `allows`
        // short-circuits for anything omh owns; it sorted *ahead of* everything
        // the repo declared, because `position()` answers `None`; it could not
        // be removed, since `[use]` refuses to name it; and it arrived beside
        // omh's own section for the same feature, delivering one notice twice.
        if let Some(feature) = selection.owner(Capability::Rules, &name) {
            anyhow::bail!(
                "{}: `{name}` is a name omh ships, so this file answers to nothing \
                 — it is not composed, and it does not override omh's. Rename it, \
                 or switch the feature off with `omh repo disable {feature}` if \
                 what you want is omh's gone.",
                path.display()
            );
        }
        if !selection.allows(Capability::Rules, &name) {
            continue;
        }
        out.push((name, body));
    }
    match selection.order(Capability::Rules) {
        // The declared order. A name the list does not mention cannot be here:
        // `allows` dropped it, and the one case that used to slip past — a file
        // bearing a manifest name, which `allows` waves through — is refused
        // above rather than sorted. Nothing is appended after the listed ones,
        // or "these rules, in this order" would quietly become "these first".
        Some(order) => out.sort_by_key(|(name, _)| order.iter().position(|n| n == name)),
        None => out.sort(),
    }
    Ok(out)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::{Path, PathBuf};

    const ADAPTERS: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/adapters");

    struct Fx {
        _dir: tempfile::TempDir,
        paths: Paths,
        worktree: PathBuf,
    }

    /// The real `claude` adapter, so the filenames under test are the ones
    /// omh actually ships rather than a fixture's idea of them.
    fn claude() -> Adapter {
        Adapter::find(Path::new(ADAPTERS), "claude").unwrap()
    }

    fn fixture() -> Fx {
        let dir = tempfile::tempdir().unwrap();
        let paths = Paths {
            root: dir.path().join("home"),
            repo: dir.path().join("repo"),
        };
        let worktree = dir.path().join("wt");
        std::fs::create_dir_all(&worktree).unwrap();
        Fx {
            _dir: dir,
            paths,
            worktree,
        }
    }

    fn write(path: PathBuf, body: &str) {
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(path, body).unwrap();
    }

    /// A rule in your catalogue: a named file, one of several you hold.
    fn catalogue(fx: &Fx, name: &str, body: &str) {
        write(fx.paths.root.join("rules").join(format!("{name}.md")), body);
    }

    /// No base: these cases are about files, and consulting git would drag a
    /// repository into tests that do not need one. No sections either: what omh
    /// generates is the same on every launch, and every case here is about
    /// something else.
    fn composed(fx: &Fx) -> (String, Report) {
        compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &[],
            &Default::default(),
        )
        .unwrap()
    }

    /// A rules file answering to a manifest name is an error naming both — the
    /// same rule `render::merge_hooks` applies to a hook file, for the same
    /// reason and now that rules are manifest entries too.
    ///
    /// Left composing, such a file was wrong in four directions at once. It
    /// reached the document even when `[use]` did not name it, because
    /// `Selection::allows` short-circuits for anything omh owns. It sorted
    /// **ahead of every rule the repo declared**, because `position()` answers
    /// `None` and `None < Some(_)` — in a document whose entire premise is that
    /// order is meaning. It could not be removed: `[use]` refuses to name it and
    /// `omh unuse` refuses to take it out. And it arrived *beside* omh's own
    /// generated section for the same feature, delivering the git notice twice
    /// — the drift `GIT_ABSENT` exists as a single string to prevent.
    ///
    /// The comment that used to sit on the sort asserted this could not happen.
    #[test]
    fn a_rules_file_answering_to_a_manifest_name_is_an_error_naming_both() {
        let fx = fixture();
        catalogue(&fx, "git-rules", "my own version");
        catalogue(&fx, "tdd", "test first");

        let owned = std::collections::BTreeMap::from([(
            Capability::Rules,
            std::collections::BTreeMap::from([("git-rules".to_string(), "git-notice".to_string())]),
        )]);
        let err = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &[],
            &crate::selection::Selection::owning(owned),
        )
        .expect_err("a manifest name is not something a file may claim");
        let msg = format!("{err:#}");
        assert!(msg.contains("git-rules.md"), "name the file: {msg}");
        assert!(msg.contains("git-notice"), "and whose name it is: {msg}");
    }

    /// omh's sections reach the agent once.
    ///
    /// P2 generated them from the manifest but left `.omh/profile/AGENTS.md`
    /// composed as a layer, so every repo initialised before generation paid
    /// all three twice per turn and the git notice the manifest calls a single
    /// string arrived as two. That was accepted for one phase with this test
    /// asserting the duplication, so the state had a guard to turn red rather
    /// than a comment to remember.
    #[test]
    fn omhs_sections_reach_the_agent_once() {
        let fx = fixture();
        let git = crate::base::sections()
            .into_iter()
            .find(|s| s.name == "git-rules")
            .expect("git-rules is a section omh ships");
        // The file that used to carry it, in the place that used to be read.
        write(
            fx.paths.repo.join(".omh/profile").join(CANONICAL),
            &git.body,
        );

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &crate::base::sections(),
            &Default::default(),
        )
        .unwrap();

        assert_eq!(
            body.matches(crate::base::GIT_ABSENT).count(),
            1,
            "the generated one, and nothing else:\n{body}"
        );
    }

    /// Rules are a directory of named files, which is what makes selecting them
    /// mean something: `tdd.md` and `commit-style.md` are separate things you
    /// hold, and a repo takes the ones that apply to it.
    #[test]
    fn the_catalogue_composes_every_rule_it_holds() {
        let fx = fixture();
        catalogue(&fx, "tdd", "test first");
        catalogue(&fx, "commit-style", "conventional commits");

        let (body, _) = composed(&fx);
        assert!(body.contains("test first"), "{body}");
        assert!(body.contains("conventional commits"), "{body}");
    }

    /// Filename order is the **fallback**, for a repo that has not written a
    /// list. `[use].rules` is the order when there is one — rules build on each
    /// other, and a general one followed by its exception reads differently
    /// reversed — but a repo that has not curated must still get a stable order
    /// rather than whatever `read_dir` returns.
    #[test]
    fn catalogue_rules_compose_in_filename_order() {
        let fx = fixture();
        catalogue(&fx, "02-second", "second");
        catalogue(&fx, "01-first", "first");

        let (body, _) = composed(&fx);
        assert!(
            body.find("first").unwrap() < body.find("second").unwrap(),
            "{body}"
        );
    }

    /// Each section says whose rule it is, by the name you filed it under —
    /// a marker reading `personal` said which of three identical directories
    /// it came from, which stops being a question worth answering when there
    /// is one.
    #[test]
    fn a_catalogue_rule_is_marked_with_its_name() {
        let fx = fixture();
        catalogue(&fx, "tdd", "test first");
        let (body, _) = composed(&fx);
        assert!(body.contains("<!-- omh: tdd -->"), "{body}");
    }

    /// omh's own sections close the document, after your catalogue and after
    /// the project's own rules.
    ///
    /// Last because they describe the sandbox rather than the work: what git
    /// does here, where notes go, which graph to ask. A convention the project
    /// wrote down should be read first, and anything omh has to say about the
    /// box it is running in should not be sitting in front of it.
    #[test]
    fn omhs_sections_close_the_document() {
        let fx = fixture();
        catalogue(&fx, "tdd", "YOURS");
        write(fx.worktree.join("AGENTS.md"), "PROJECT");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &crate::base::sections(),
            &Default::default(),
        )
        .unwrap();
        let at = |needle: &str| {
            body.find(needle)
                .unwrap_or_else(|| panic!("{needle} missing:\n{body}"))
        };

        for section in crate::base::sections() {
            assert!(
                at(section.body.trim_end()) > at("PROJECT"),
                "{} must come after the project's own:\n{body}",
                section.name
            );
        }
    }

    /// Position, not presence. A `contains` assertion stays green when the
    /// order is wrong, and the order is the whole question.
    ///
    /// Yours first because they are how you work everywhere and the project's
    /// file is the specific case that qualifies them; omh's last because they
    /// describe the box rather than the work.
    #[test]
    fn sections_are_ordered_catalogue_project_omh() {
        let fx = fixture();
        catalogue(&fx, "tdd", "YOURS");
        write(fx.worktree.join("AGENTS.md"), "PROJECT");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &crate::base::sections(),
            &Default::default(),
        )
        .unwrap();
        let at = |needle: &str| {
            body.find(needle)
                .unwrap_or_else(|| panic!("{needle} missing:\n{body}"))
        };

        assert!(
            at("YOURS") < at("PROJECT"),
            "yours before the project's:\n{body}"
        );
        assert!(
            at("PROJECT") < at(crate::base::GIT_ABSENT),
            "the project's before omh's:\n{body}"
        );
    }

    /// Three sources reach the agent as one document with no seam. Without a
    /// marker per section, a project convention and an omh instruction are the
    /// same kind of sentence to whoever reads it next.
    #[test]
    fn each_section_names_where_it_came_from() {
        let fx = fixture();
        catalogue(&fx, "tdd", "YOURS");
        write(fx.worktree.join("AGENTS.md"), "PROJECT");

        let (body, _) = composed(&fx);

        assert!(body.contains("<!-- omh: tdd -->"), "got:\n{body}");
        assert!(
            body.contains("<!-- omh: <repo>/AGENTS.md -->"),
            "got:\n{body}"
        );
    }

    /// Most repos that have used Claude Code have a `CLAUDE.md` and no
    /// `AGENTS.md`. Refusing to read it would leave the agent with no project
    /// rules at all, which is worse than the bug being fixed — so it is composed
    /// and the user is told which file was used.
    #[test]
    fn claude_md_is_composed_when_agents_md_is_absent() {
        let fx = fixture();
        write(fx.worktree.join("CLAUDE.md"), "PROJECT VIA CLAUDE");

        let (body, report) = composed(&fx);

        assert!(body.contains("PROJECT VIA CLAUDE"), "got:\n{body}");
        assert_eq!(report.read_instead(), Some("CLAUDE.md"));
        assert_eq!(report.not_composed, None);
    }

    /// `AGENTS.md` is canonical, so it wins — but silently dropping the other
    /// file is how a repo loses rules it believes are in force.
    #[test]
    fn agents_md_wins_when_both_exist_and_claude_is_reported() {
        let fx = fixture();
        write(fx.worktree.join("AGENTS.md"), "THE CANONICAL ONE");
        write(fx.worktree.join("CLAUDE.md"), "SOMETHING ELSE ENTIRELY");

        let (body, report) = composed(&fx);

        assert!(body.contains("THE CANONICAL ONE"), "got:\n{body}");
        assert!(!body.contains("SOMETHING ELSE ENTIRELY"), "got:\n{body}");
        assert_eq!(report.not_composed.as_deref(), Some("CLAUDE.md"));
        assert_eq!(report.read_instead(), None, "it read the canonical name");
    }

    /// The common shape is one file pointing at the other, or a symlink-like
    /// copy. Warning about it every launch trains people to ignore the warning
    /// that matters.
    ///
    /// Asserts the document too: staying quiet while dropping the rules would
    /// pass a report-only assertion, and that is the original bug wearing a
    /// clean report.
    #[test]
    fn identical_agents_and_claude_stay_quiet() {
        let fx = fixture();
        write(fx.worktree.join("AGENTS.md"), "SAME BYTES");
        write(fx.worktree.join("CLAUDE.md"), "SAME BYTES");

        let (body, report) = composed(&fx);

        assert!(
            report.notices().is_empty(),
            "identical files are not a problem: {:?}",
            report.notices()
        );
        assert_eq!(
            body.matches("SAME BYTES").count(),
            1,
            "composed once, not dropped and not doubled:\n{body}"
        );
    }

    /// One file copying the other is the shape this is meant to tolerate, and
    /// an editor that adds a trailing newline is the ordinary way the copies
    /// stop being byte-identical. Comparing raw bytes while blankness is
    /// `trim`-based meant the warning fired on every launch for a repo that had
    /// done nothing wrong.
    #[test]
    fn a_trailing_newline_is_not_a_difference() {
        let fx = fixture();
        write(fx.worktree.join("AGENTS.md"), "SAME BYTES");
        write(fx.worktree.join("CLAUDE.md"), "SAME BYTES\n");

        let (_, report) = composed(&fx);

        assert!(
            report.notices().is_empty(),
            "a newline is not a conflict: {:?}",
            report.notices()
        );
    }

    /// The warning has to name both files, and the composed one is not always
    /// `AGENTS.md`: from a session's second launch the canonical name may hold
    /// omh's own placeholder, so the winner is whatever was read.
    #[test]
    fn the_report_names_the_file_it_composed() {
        let fx = fixture();
        write(fx.worktree.join("CLAUDE.md"), "THE ONE THAT WON");

        let (_, report) = composed(&fx);

        assert_eq!(report.composed.as_deref(), Some("CLAUDE.md"));
        assert_eq!(report.read_instead(), Some("CLAUDE.md"), "not canonical");
    }

    /// `read_instead` is derived, so it cannot disagree with what was composed —
    /// the canonical name is never something to tell the user about.
    #[test]
    fn composing_the_canonical_name_is_not_worth_saying() {
        let fx = fixture();
        write(fx.worktree.join("AGENTS.md"), "CANONICAL");

        let (_, report) = composed(&fx);

        assert_eq!(report.composed.as_deref(), Some("AGENTS.md"));
        assert_eq!(report.read_instead(), None);
    }

    /// An unreadable rules file is not an absent one. `config::read_layer`
    /// exists because conflating them made `omh why` answer "not installed
    /// here" about an installed server and advise a command that no-ops — a
    /// closed loop, exit 0. This module has a second copy of that logic and
    /// needs the same guard.
    #[test]
    #[cfg(unix)]
    fn an_unreadable_rules_file_is_an_error_not_an_absence() {
        use std::os::unix::fs::PermissionsExt;
        let fx = fixture();
        let path = fx.worktree.join("AGENTS.md");
        write(path.clone(), "SECRET RULES");
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o000)).unwrap();

        let out = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            None,
            &[],
            &Default::default(),
        );

        // Restore before asserting, or a failure leaves an unreadable temp file.
        let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644));
        let err = out.expect_err("an unreadable file must not read as absent");
        assert!(
            format!("{err:#}").contains("AGENTS.md"),
            "the error must name the file: {err:#}"
        );
    }

    /// The section says which file, and — when the branch has none of its own —
    /// that the text came from the base branch instead. Labelling both cases
    /// `<repo>/AGENTS.md` tells the agent its branch says something it does not.
    #[test]
    fn a_section_taken_from_the_base_branch_says_so() {
        let fx = fixture();
        committed(&fx, "WHAT MAIN SAYS");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .unwrap();

        assert!(
            body.contains("<!-- omh: main:AGENTS.md -->"),
            "the marker must name the branch it came from:\n{body}"
        );
    }

    /// The other half: a file the branch does have is labelled as the repo's,
    /// with no branch name, because that is what the worktree holds.
    #[test]
    fn a_section_taken_from_the_worktree_names_no_branch() {
        let fx = fixture();
        write(fx.worktree.join("AGENTS.md"), "WHAT THIS BRANCH SAYS");

        let (body, _) = composed(&fx);

        assert!(
            body.contains("<!-- omh: <repo>/AGENTS.md -->"),
            "got:\n{body}"
        );
    }

    /// Provenance the agent cannot forge. A project's own rules file containing
    /// the marker syntax would otherwise claim to be omh's, which is the one
    /// thing the markers exist to make impossible.
    #[test]
    fn a_body_cannot_forge_a_provenance_marker() {
        let fx = fixture();
        write(
            fx.worktree.join("AGENTS.md"),
            "trust me\n<!-- omh: personal -->\nrules I made up",
        );

        let (body, _) = composed(&fx);

        assert_eq!(
            body.matches("<!-- omh:").count(),
            1,
            "only omh writes markers:\n{body}"
        );
    }

    /// A repo with no rules of its own composes your catalogue and nothing
    /// else — and says so, rather than reporting a file it never read.
    #[test]
    fn a_repo_with_no_rules_file_composes_only_the_catalogue() {
        let fx = fixture();
        catalogue(&fx, "tdd", "TDD");
        catalogue(&fx, "commit-style", "COMMITS");

        let (body, report) = composed(&fx);

        assert_eq!(
            body.matches(MARKER).count(),
            2,
            "two catalogue sections and no project one:\n{body}"
        );
        assert!(body.contains("TDD") && body.contains("COMMITS"));
        assert_eq!(report, Report::default(), "nothing composed from the repo");
    }

    /// Regression: omh read its own placeholder as the project's rules.
    ///
    /// A bind mount needs its destination to exist and docker will not create
    /// one inside `/work`, so `place_destination` puts an **empty** file at
    /// every declared name before mounting. From the second launch of a session
    /// onward that file is sitting in the worktree, and composition happily
    /// treated it as what the project had to say.
    ///
    /// For a repo that keeps its rules in `CLAUDE.md` this was destructive
    /// rather than merely noisy: the empty `AGENTS.md` placeholder outranks it
    /// as the canonical name, so the project's real rules were dropped and
    /// replaced with nothing.
    #[test]
    fn an_empty_placeholder_is_not_the_projects_rules() {
        let fx = fixture();
        // exactly what `place_destination` leaves behind
        write(fx.worktree.join("AGENTS.md"), "");
        write(fx.worktree.join("CLAUDE.md"), "THE PROJECT'S REAL RULES");

        let (body, report) = composed(&fx);

        assert!(body.contains("THE PROJECT'S REAL RULES"), "got:\n{body}");
        assert_eq!(report.read_instead(), Some("CLAUDE.md"));
        assert_eq!(
            report.not_composed, None,
            "a file omh created itself is not a conflict to report"
        );
    }

    /// The same placeholder, seen from the other side: it must not suppress the
    /// default branch either, or a session gets no project rules at all from its
    /// second launch on.
    #[test]
    fn an_empty_placeholder_does_not_suppress_the_default_branch() {
        let fx = fixture();
        committed(&fx, "WHAT MAIN SAYS");
        write(fx.worktree.join("AGENTS.md"), "   \n");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .unwrap();

        assert!(body.contains("WHAT MAIN SAYS"), "got:\n{body}");
    }

    // ── against a real repository ───────────────────────────────────────────
    //
    // `git show` is the half of this that no filesystem fixture can reach, and
    // the half that decides what a session sees when its branch has no rules
    // file of its own.

    fn git(cwd: &Path, args: &[&str]) {
        let out = std::process::Command::new("git")
            .current_dir(cwd)
            .args(args)
            .output()
            .unwrap();
        assert!(
            out.status.success(),
            "git {}: {}",
            args.join(" "),
            String::from_utf8_lossy(&out.stderr)
        );
    }

    /// A repo whose default branch commits `AGENTS.md`.
    fn committed(fx: &Fx, body: &str) {
        std::fs::create_dir_all(&fx.paths.repo).unwrap();
        for args in [
            vec!["init", "-q", "-b", "main"],
            vec!["config", "user.email", "t@example.com"],
            vec!["config", "user.name", "t"],
        ] {
            git(&fx.paths.repo, &args);
        }
        std::fs::write(fx.paths.repo.join("AGENTS.md"), body).unwrap();
        git(&fx.paths.repo, &["add", "AGENTS.md"]);
        git(&fx.paths.repo, &["commit", "-q", "-m", "rules"]);
    }

    /// A session that has just written its own rules should be governed by
    /// them. Reading the default branch first would hand the agent the rules it
    /// is in the middle of replacing.
    #[test]
    fn the_worktree_copy_wins_over_the_default_branch() {
        let fx = fixture();
        committed(&fx, "WHAT MAIN SAYS");
        write(fx.worktree.join("AGENTS.md"), "WHAT THIS BRANCH SAYS");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .unwrap();

        assert!(body.contains("WHAT THIS BRANCH SAYS"), "got:\n{body}");
        assert!(!body.contains("WHAT MAIN SAYS"), "got:\n{body}");
    }

    /// The case the filesystem cannot answer: a session branch that deleted the
    /// rules file, or a worktree checked out before it existed. Falling back to
    /// the default branch is what keeps the project's conventions in force.
    #[test]
    fn the_default_branch_supplies_it_when_the_worktree_has_none() {
        let fx = fixture();
        committed(&fx, "WHAT MAIN SAYS");

        let (body, _) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .unwrap();

        assert!(body.contains("WHAT MAIN SAYS"), "got:\n{body}");
    }

    /// A repo initialised but not yet committed to has nothing to show, and
    /// that is an ordinary state rather than a reason to refuse to launch.
    #[test]
    fn a_repo_with_no_commits_still_composes() {
        let fx = fixture();
        catalogue(&fx, "tdd", "YOURS");
        std::fs::create_dir_all(&fx.paths.repo).unwrap();
        git(&fx.paths.repo, &["init", "-q", "-b", "main"]);

        let (body, report) = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .unwrap();

        assert!(body.contains("YOURS"), "got:\n{body}");
        assert!(report.notices().is_empty());
    }

    /// The other half of the same call, and the one the old code could not
    /// express: a git that cannot answer is not a project without rules.
    ///
    /// `config::read_layer` is the precedent — conflating "absent" with
    /// "unreadable" made `omh why` advise a command that no-ops, a closed loop
    /// exiting 0. `Paths::discover` guarantees a `.git` above the repo, so
    /// reaching this means something is genuinely wrong and saying so is the
    /// only useful thing left.
    #[test]
    fn a_git_that_cannot_answer_is_an_error_not_an_absence() {
        let fx = fixture();
        std::fs::create_dir_all(&fx.paths.repo).unwrap(); // deliberately not a repo

        let err = compose(
            &fx.paths,
            &claude(),
            &fx.worktree,
            Some("main"),
            &[],
            &Default::default(),
        )
        .expect_err("a broken repository must not read as 'no rules'");

        let msg = format!("{err:#}");
        assert!(msg.contains("git show"), "must name what it ran: {msg}");
        assert!(
            msg.contains("not a git repository"),
            "must pass git's own reason through: {msg}"
        );
    }
}