release_kit/

landing.rs

//! The target-side landing model: file kinds, parameter rendering, and
//! the routing block.
//!
//! Every landable file has a declared kind — `rendered` files release-kit
//! owns and may rewrite, `seeded` files the target tunes, `state` files
//! the release automation maintains — and a `rendered` file's bytes are a
//! deterministic function of the payload plus the landing parameters, so
//! a later command can compare what is on disk against what would be
//! written. The kinds are declared here, beside the payload, never
//! inferred at runtime; a test holds the table closed over every snippet.

pub mod invariants;
pub mod manifest;

use camino::Utf8Path;
use serde::{Deserialize, Serialize};

pub use manifest::{Style, Workflow};

use crate::atomic;
use crate::diagnostic::{Diagnostic, Reason};
use crate::error::RkError;
use crate::release::{self, ReleaseManifest, ReleaseSource};

/// The complete input to a payload projection. Comparisons reconstruct it
/// from the landing record; landing verbs resolve their candidate inputs.
#[derive(Debug)]
pub struct Params {
    tech: String,
    forge: String,
    repo: String,
    workflow: Workflow,
    style: Option<Style>,
    nix: bool,
    trunk: String,
    line_prefix: String,
    security_contact: String,
    security_response: String,
}

/// Explicit invocation answers; absence falls through to configuration.
#[derive(Default)]
pub struct Inputs<'a> {
    /// Binding override.
    pub tech: Option<&'a str>,
    /// Forge override.
    pub forge: Option<&'a str>,
    /// Repository override.
    pub repo: Option<&'a str>,
    /// Workflow override.
    pub workflow: Option<Workflow>,
    /// Release style override.
    pub style: Option<Style>,
    /// Nix capability override.
    pub nix: Option<bool>,
}

/// Compatibility policy for a landing candidate.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum Purpose {
    /// A first landing.
    Init,
    /// A preview may leave the repository unresolved.
    Preview,
    /// An existing record supplies compatibility answers.
    Upgrade,
    /// A pre-record target requires an explicit release style.
    Adopt,
}

impl Params {
    /// Reconstruct every projection parameter from the record alone,
    /// including the compatibility defaults applied when it was loaded.
    #[must_use]
    pub fn from_record(record: &manifest::Manifest) -> Self {
        Self {
            tech: record.tech.clone(),
            forge: record.forge.clone(),
            repo: record.parameters.repo.clone(),
            workflow: record.parameters.workflow,
            style: record.parameters.style,
            nix: record.parameters.nix,
            trunk: record.parameters.trunk.clone(),
            line_prefix: record.parameters.line_prefix.clone(),
            security_contact: record.parameters.security_contact.clone(),
            security_response: record.parameters.security_response.clone(),
        }
    }

    /// Resolve flags, configuration, recorded compatibility inputs or detection,
    /// and finally the compiled defaults. Comparisons use `from_record` alone.
    ///
    /// # Errors
    /// Refuses unresolved identity or a style an existing target has not answered.
    pub fn resolve(
        source: &dyn ReleaseSource,
        target: &Utf8Path,
        flags: &Inputs<'_>,
        config: Option<&crate::config::Config>,
        record: Option<&manifest::Manifest>,
        purpose: Purpose,
    ) -> Result<Self, RkError> {
        let answer = |flag: Option<&str>, configured: Option<&str>, recorded: Option<&str>| {
            flag.or_else(|| configured.filter(|value| !value.is_empty()))
                .or(recorded)
                .map(str::to_owned)
        };
        let forge = answer(
            flags.forge,
            config.map(|c| c.project.forge.as_str()),
            record.map(|r| r.forge.as_str()),
        );
        let repo = answer(
            flags.repo,
            config.map(|c| c.project.repo.as_str()),
            record.map(|r| r.parameters.repo.as_str()),
        );
        let resolved = resolve(target, forge.as_deref(), repo.as_deref())?;
        let tech = answer(
            flags.tech,
            config.map(|c| c.project.tech.as_str()),
            record.map(|r| r.tech.as_str()),
        )
        .or_else(|| crate::detect::tech_of(target.as_std_path()).map(str::to_owned))
        .ok_or_else(|| {
            RkError::missing(
                Diagnostic::new(
                    Reason::TargetNotFound,
                    "no technology detected: the target has no version file",
                )
                .action("pass --tech <rust|python|bash>"),
            )
        })?;
        pair_files(source, &tech, &resolved.forge)?;
        let workflow = flags
            .workflow
            .or_else(|| config.and_then(|c| c.landing.workflow))
            .or_else(|| record.map(|r| r.parameters.workflow))
            .unwrap_or(if purpose == Purpose::Adopt {
                Workflow::Branches
            } else {
                Workflow::Worktree
            });
        let style = flags
            .style
            .or_else(|| config.and_then(|c| c.landing.style))
            .or_else(|| record.and_then(|r| r.parameters.style));
        let style = match (style, purpose) {
            (None, Purpose::Upgrade | Purpose::Adopt) => return Err(RkError::Usage("the target carries no style parameter; set landing.style in .release-kit/config.toml or pass --style <trunk|lines>".into())),
            (value, _) => Some(value.unwrap_or(Style::Trunk)),
        };
        let repo = resolved
            .repo
            .or_else(|| (purpose == Purpose::Preview).then(|| REPO_PLACEHOLDER.to_owned()))
            .ok_or_else(repo_unresolved)?;
        let trunk = config
            .and_then(|c| c.project.trunk.clone())
            .or_else(|| record.map(|r| r.parameters.trunk.clone()))
            .unwrap_or_else(|| crate::config::TRUNK_DEFAULT.to_owned());
        let line_prefix = config
            .and_then(|c| c.setup.line_prefix.clone())
            .or_else(|| record.map(|r| r.parameters.line_prefix.clone()))
            .unwrap_or_else(|| crate::config::LINE_PREFIX_DEFAULT.to_owned());
        // An explicitly present key wins, including an empty contact,
        // which is how a target resets a recorded custom contact. An
        // omitted key falls through to the record, so an upgrade under an
        // older configuration keeps the policy the target already carries.
        let security_contact = config
            .and_then(|c| c.security.contact.clone())
            .or_else(|| record.map(|r| r.parameters.security_contact.clone()))
            .unwrap_or_default();
        let security_contact =
            crate::config::canonical_contact(&security_contact).map_err(crate::config::invalid)?;
        let security_response = config
            .and_then(|c| c.security.response.clone())
            .or_else(|| record.map(|r| r.parameters.security_response.clone()))
            .unwrap_or_else(|| crate::config::RESPONSE_DEFAULT.to_owned());
        let security_response = crate::config::canonical_response(&security_response)
            .map_err(crate::config::invalid)?;
        Ok(Self {
            tech,
            forge: resolved.forge,
            repo,
            workflow,
            style,
            nix: flags
                .nix
                .or_else(|| config.and_then(|c| c.landing.nix))
                .or_else(|| record.map(|r| r.parameters.nix))
                .unwrap_or(false),
            trunk,
            line_prefix,
            security_contact,
            security_response,
        })
    }

    /// The binding selected for this landing.
    #[must_use]
    pub fn tech(&self) -> &str {
        &self.tech
    }

    /// The forge selected for this landing.
    #[must_use]
    pub fn forge(&self) -> &str {
        &self.forge
    }

    /// Whether this landing opted into Nix.
    #[must_use]
    pub const fn nix(&self) -> bool {
        self.nix
    }

    /// The project path used by parameter-bearing blocks.
    #[must_use]
    pub fn repo(&self) -> &str {
        &self.repo
    }

    /// The mode used by parameter-bearing blocks.
    #[must_use]
    pub const fn workflow(&self) -> Workflow {
        self.workflow
    }

    /// The release style used by parameter-bearing blocks.
    #[must_use]
    pub const fn style(&self) -> Option<Style> {
        self.style
    }

    /// The one permanent branch this landing writes into its artifacts.
    #[must_use]
    pub fn trunk(&self) -> &str {
        &self.trunk
    }

    /// The release-line prefix this landing writes into its artifacts.
    #[must_use]
    pub fn line_prefix(&self) -> &str {
        &self.line_prefix
    }

    /// The contact the landed policy names, empty for the forge's own
    /// authored wording.
    #[must_use]
    pub fn security_contact(&self) -> &str {
        &self.security_contact
    }

    /// The acknowledgment window the landed policy promises.
    #[must_use]
    pub fn security_response(&self) -> &str {
        &self.security_response
    }
}

#[cfg(test)]
impl Params {
    /// A parameter set for tests alone. Production code reaches `Params`
    /// through `from_record` and `resolve` and through nothing else, and
    /// this constructor is compiled out of the shipped binary.
    pub(crate) fn for_test(repo: &str, style: Option<Style>) -> Self {
        Self {
            tech: "rust".to_owned(),
            forge: "github".to_owned(),
            repo: repo.to_owned(),
            workflow: Workflow::Worktree,
            style,
            nix: false,
            trunk: crate::config::TRUNK_DEFAULT.to_owned(),
            line_prefix: crate::config::LINE_PREFIX_DEFAULT.to_owned(),
            security_contact: String::new(),
            security_response: crate::config::RESPONSE_DEFAULT.to_owned(),
        }
    }

    /// The same set with the two security parameters answered.
    pub(crate) fn for_test_security(contact: &str, response: &str) -> Self {
        Self {
            security_contact: contact.to_owned(),
            security_response: response.to_owned(),
            ..Self::for_test("acme/widget", Some(Style::Trunk))
        }
    }
}

/// Who owns a landed file's bytes after landing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Kind {
    /// release-kit owns it: a newer payload re-renders it, and a target
    /// edit is a conflict.
    Rendered,
    /// The target owns it: a starting point the project tunes, reported
    /// and never rewritten.
    Seeded,
    /// The release automation owns it: never written after the first
    /// landing, never compared.
    State,
}

impl Kind {
    /// The wire and report form.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Rendered => "rendered",
            Self::Seeded => "seeded",
            Self::State => "state",
        }
    }
}

/// The declared classification: every landable destination and its kind.
/// The workflow and pipeline files carry the release automation and the
/// OIDC permission, so release-kit owns them; the tool configurations are
/// per-project judgment; the two state files are rewritten by the release
/// automation itself.
const KINDS: [(&str, Kind); 16] = [
    (".github/workflows/release-plz.yml", Kind::Rendered),
    (".github/workflows/release-please.yml", Kind::Rendered),
    (".github/workflows/release.yml", Kind::Rendered),
    (".github/workflows/pr-title.yml", Kind::Rendered),
    (".gitlab-ci.yml", Kind::Rendered),
    ("SECURITY.md", Kind::Rendered),
    (".gitlab/ci/mr-title.yml", Kind::Rendered),
    ("release-plz.toml", Kind::Seeded),
    ("dist-workspace.toml", Kind::Seeded),
    ("release-please-config.json", Kind::Seeded),
    ("cliff.toml", Kind::Seeded),
    ("nix/package.nix", Kind::Seeded),
    ("flake.nix", Kind::Seeded),
    (".release-please-manifest.json", Kind::State),
    ("VERSION", Kind::State),
    ("flake.lock", Kind::State),
];

/// The destinations of the opt-in Nix capability, present in a projection
/// only where the landing's `nix` parameter is on.
///
/// The parameter is recorded, so `status`, `upgrade`, and `adopt` can
/// reconstruct whether these files are supposed to exist: an absent file
/// under `nix = false` is not wanted, never drifted.
///
/// The capability lands no workflow, on either forge, and each forge's
/// reason is its own. On GitHub a job gates the merge only inside the
/// workflow the required check needs, and that workflow is the target's
/// own. On GitLab the merge check is the whole pipeline, and a target's
/// jobs live in the child pipeline the rendered parent triggers, which the
/// target owns. The bindings serve the job for both.
pub const NIX_DESTINATIONS: [&str; 3] = ["nix/package.nix", "flake.nix", "flake.lock"];

/// The subset a target with a flake of its own keeps out: the seed pair,
/// whose files would sit beside a flake release-kit did not author.
///
/// The seeded package expression is not in it — it lands either way, as
/// the starting point the target integrates by hand.
pub const NIX_WITHHOLDABLE: [&str; 2] = ["flake.nix", "flake.lock"];

/// The declared kind of a destination, or `None` for a file the payload
/// does not classify.
#[must_use]
pub fn kind_of(destination: &str) -> Option<Kind> {
    if destination == AGENTS_DESTINATION
        || destination == GLOSSARY_DESTINATION
        || destination == HOOKS_DESTINATION
    {
        return Some(Kind::Rendered);
    }
    KINDS
        .iter()
        .find(|(name, _)| *name == destination)
        .map(|(_, kind)| *kind)
}

/// Every destination the payload can land, in declaration order.
///
/// The whole files and the three block destinations. The classification
/// reads it to ask whether a destination is already present at a target.
pub fn destinations() -> impl Iterator<Item = &'static str> {
    KINDS
        .iter()
        .map(|(name, _)| *name)
        .chain(BLOCK_DESTINATIONS)
}

/// The mechanical substitution sites in `rendered` files.
///
/// Known values, substituted identically everywhere each appears. The
/// owner is derived from the landing's `repo` parameter and the scope
/// shape from [`SCOPE_SHAPE`], so the landed bytes stay a deterministic
/// function of payload plus parameters.
pub const OWNER_TOKEN: &[u8] = b"OWNER";

/// The repository a preview stands in for where nothing answered.
///
/// It is a placeholder, never a project path: a plan that would render
/// it into a target is blocked, and only a preview may carry it.
pub const REPO_PLACEHOLDER: &str = "OWNER";

/// The full recorded project path, including nested namespaces.
pub const REPO_TOKEN: &[u8] = b"RK_REPO";

/// The one scope shape: the title checks' regular expression.
pub const SCOPE_SHAPE_TOKEN: &[u8] = b"RK_SCOPE_SHAPE";

/// The recorded release style: `trunk` arms the bot's request in the
/// landed release workflow, `lines` leaves every request unarmed.
pub const STYLE_TOKEN: &[u8] = b"RK_STYLE";

/// The one permanent branch. A landed release trigger, ref guard, and
/// branch guard each name it, so a target whose trunk is not `master`
/// needs its own answer in its own bytes.
pub const TRUNK_BRANCH_TOKEN: &[u8] = b"RK_TRUNK_BRANCH";

/// The release-line branch prefix, naming the lines a release trigger
/// accepts beside the trunk.
pub const LINE_PREFIX_TOKEN: &[u8] = b"RK_LINE_PREFIX";

/// The same prefix, escaped for a slash-delimited regular expression.
///
/// A GitLab rule names a line that way, and a raw `release/` would close
/// the delimiter and break the pipeline, so the two forms are two tokens.
/// This one substitutes first: the plain token is its own prefix.
pub const LINE_PREFIX_RE_TOKEN: &[u8] = b"RK_LINE_PREFIX_RE";

/// The three replaceable spans of a landed security policy, each as its
/// ordered begin and end marker.
///
/// A span is not a token. Each forge's policy carries its own authored
/// prose inside the markers, so a landing that answers neither security
/// parameter strips the markers and reproduces the file the forge's
/// snippet states, byte for byte and in that forge's own words. A landing
/// that answers one replaces the interior of the spans that fact belongs
/// to. The markers are HTML comments because the snippet is Markdown a
/// reader may open before it is ever rendered.
pub const SECURITY_SPANS: [(&[u8], &[u8]); 3] = [
    (
        b"<!--RK_SECURITY_CONTACT_BEGIN-->",
        b"<!--RK_SECURITY_CONTACT_END-->",
    ),
    (
        b"<!--RK_SECURITY_RESPONSE_BEGIN-->",
        b"<!--RK_SECURITY_RESPONSE_END-->",
    ),
    (
        b"<!--RK_SECURITY_DEADLINE_BEGIN-->",
        b"<!--RK_SECURITY_DEADLINE_END-->",
    ),
];

/// The sentence a policy with an acknowledgment window states in place of
/// the forge's best-effort wording.
fn acknowledgment(response: &str) -> String {
    format!("Maintainers acknowledge a report within {response}.")
}

/// What a policy with an acknowledgment window says about deadlines: the
/// authored sentence disclaims a response deadline, which a stated window
/// contradicts, so only the disclosure half survives.
const DISCLOSURE_ONLY: &[u8] = b"This policy commits to no disclosure deadline.";

/// The replacement for each span under one parameter set, or `None` where
/// the forge's authored interior stands.
fn security_replacements(params: &Params) -> [Option<Vec<u8>>; 3] {
    let contact = (!params.security_contact().is_empty())
        .then(|| params.security_contact().as_bytes().to_vec());
    let promised = params.security_response() != crate::config::RESPONSE_DEFAULT;
    [
        contact,
        promised.then(|| acknowledgment(params.security_response()).into_bytes()),
        promised.then(|| DISCLOSURE_ONLY.to_vec()),
    ]
}

/// One marked span replaced, or the markers alone removed.
///
/// Exactly one ordered begin and end pair is a span; anything else is a
/// payload defect a test holds, so this leaves such bytes untouched rather
/// than growing a runtime failure mode into every rendered file.
fn replace_span(baseline: &[u8], begin: &[u8], end: &[u8], value: Option<&[u8]>) -> Vec<u8> {
    let ordered = find(baseline, begin)
        .zip(find(baseline, end))
        .filter(|(start, stop)| stop > start);
    let Some((start, stop)) = ordered else {
        return baseline.to_vec();
    };
    let mut out = Vec::with_capacity(baseline.len());
    out.extend_from_slice(&baseline[..start]);
    out.extend_from_slice(value.unwrap_or_else(|| &baseline[start + begin.len()..stop]));
    out.extend_from_slice(&baseline[stop + end.len()..]);
    out
}

/// Substitute the landing parameters into a `rendered` file's bytes.
///
/// The repository's owner — the project path's first segment — replaces
/// every `OWNER` occurrence; the full path replaces `RK_REPO` last.
/// The one scope shape replaces the scope
/// token, and the recorded style replaces the style token. The scope
/// shape rests on no parameter, so it substitutes always. An unresolved
/// style leaves its token standing, which only a preview renders under:
/// an apply refuses before reaching here.
///
/// The trunk and the line prefix substitute from the same parameters, so
/// a target that renames either carries the new name in every artifact
/// that names it rather than in the binary's behavior alone.
///
/// The security policy's marked spans resolve last, after every token, so
/// a contact that happens to spell a token name lands literally rather
/// than being read as one more substitution site.
#[must_use]
pub fn render(baseline: &[u8], params: &Params) -> Vec<u8> {
    let repo = params.repo();
    let owner = repo.split('/').next().unwrap_or(repo);
    let mut out = substitute(baseline, OWNER_TOKEN, owner.as_bytes());
    if let Some(style) = params.style() {
        out = substitute(&out, STYLE_TOKEN, style.as_str().as_bytes());
    }
    out = substitute(&out, SCOPE_SHAPE_TOKEN, SCOPE_SHAPE.as_bytes());
    out = substitute(&out, TRUNK_BRANCH_TOKEN, params.trunk().as_bytes());
    let escaped = params.line_prefix().replace('/', "\\/");
    out = substitute(&out, LINE_PREFIX_RE_TOKEN, escaped.as_bytes());
    out = substitute(&out, LINE_PREFIX_TOKEN, params.line_prefix().as_bytes());
    out = substitute(&out, REPO_TOKEN, repo.as_bytes());
    for ((begin, end), value) in SECURITY_SPANS.iter().zip(security_replacements(params)) {
        out = replace_span(&out, begin, end, value.as_deref());
    }
    out
}

/// Every `token` occurrence replaced with `value`.
pub(crate) fn substitute(baseline: &[u8], token: &[u8], value: &[u8]) -> Vec<u8> {
    let mut out = Vec::with_capacity(baseline.len());
    let mut rest = baseline;
    while let Some(at) = find(rest, token) {
        out.extend_from_slice(&rest[..at]);
        out.extend_from_slice(value);
        rest = &rest[at + token.len()..];
    }
    out.extend_from_slice(rest);
    out
}

/// First occurrence of `needle` in `haystack`.
fn find(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    haystack
        .windows(needle.len())
        .position(|window| window == needle)
}

/// The destination the routing block splices into.
pub const AGENTS_DESTINATION: &str = "AGENTS.md";

/// The block's opening marker.
pub const BLOCK_BEGIN: &str = "<!-- BEGIN release-kit -->";

/// The block's closing marker.
pub const BLOCK_END: &str = "<!-- END release-kit -->";

/// The destination the glossary block splices into.
///
/// The document is the target's own vocabulary, so the block shares
/// `AGENTS.md`'s marker pair and owns nothing outside it.
pub const GLOSSARY_DESTINATION: &str = "GLOSSARY.md";

/// The destination the hook block splices into.
pub const HOOKS_DESTINATION: &str = ".pre-commit-config.yaml";

/// Every block destination, in the order a landing writes them.
///
/// A block destination owns the lines between its markers and nothing
/// else, so every verb that asks whether a destination is block-placed
/// reads this one list.
pub const BLOCK_DESTINATIONS: [&str; 3] =
    [AGENTS_DESTINATION, GLOSSARY_DESTINATION, HOOKS_DESTINATION];

/// The hook block's opening marker, a YAML comment at column zero.
pub const HOOKS_BEGIN: &str = "# BEGIN release-kit";

/// The hook block's closing marker.
pub const HOOKS_END: &str = "# END release-kit";

/// The top-level key the fresh hook file carries and the skills verify on
/// an existing one: the commit-msg and pre-push hooks run only where their
/// hook types are installed.
pub const HOOK_TYPES_LINE: &str = "default_install_hook_types: [pre-commit, commit-msg, pre-push]";

/// The authored routing-block template, `blocks/agents-block.md.in`.
const AGENTS_BLOCK: &str = "blocks/agents-block.md.in";

/// The authored glossary template, `blocks/glossary.md.in`.
const GLOSSARY_BLOCK: &str = "blocks/glossary.md.in";

/// The routing block's mode line, worktree form.
const AGENTS_LINE_WORKTREE: &str = "blocks/agents-line-worktree.md.in";

/// The routing block's mode line, branches form.
const AGENTS_LINE_BRANCHES: &str = "blocks/agents-line-branches.md.in";

/// The authored hook-block template, `blocks/pre-commit-block.yaml.in`.
const PRE_COMMIT_BLOCK: &str = "blocks/pre-commit-block.yaml.in";

/// The worktree mode's guard entry, `blocks/pre-commit-worktree-guard.yaml.in`.
const PRE_COMMIT_WORKTREE_GUARD: &str = "blocks/pre-commit-worktree-guard.yaml.in";

/// One authored block, read through the seam as text.
fn block(
    source: &dyn ReleaseSource,
    manifest: &ReleaseManifest,
    path: &str,
) -> Result<String, RkError> {
    let bytes = release::read(source, manifest, path)?;
    String::from_utf8(bytes).map_err(|_| anyhow::anyhow!("{path}: a block is UTF-8").into())
}

/// An authored block without the one final newline the repository's
/// hooks enforce on every file under `blocks/`; a test in
/// `src/embedded.rs` holds each file to exactly one.
fn authored(text: &str) -> &str {
    text.strip_suffix('\n').unwrap_or(text)
}

/// The one branch grammar.
///
/// The extended regular expression the landed
/// `rk-branch-name` hook tests, and the same anchored language
/// `rk worktree add` validates before creating anything. One owner by
/// token — `concat!` cannot interpolate a const, so [`hooks_block`]
/// substitutes it for the template's `RK_BRANCH_GRAMMAR` token.
pub const BRANCH_GRAMMAR: &str = r"^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)/[A-Za-z0-9._/-]+|([0-9]+|[A-Z][A-Z0-9]+-[0-9]+)-[A-Za-z0-9._-]+|release[-/].+)$";

/// The one commit scope shape.
///
/// A bracket expression, lowercase, admitting the digits and `_ . / -`
/// beside the letters, so `area/subarea` reads as one scope. It holds the
/// shape of a scope and never its vocabulary: the word itself is the
/// author's, guided by the routing block and by the repository's own
/// history. One owner by token — the title checks take it as
/// `RK_SCOPE_SHAPE` through [`render`], and `rk message --check` reads it
/// directly, so the desk and the forge judge one language.
pub const SCOPE_SHAPE: &str = "[a-z0-9._/-]+";

/// Whether one scope matches [`SCOPE_SHAPE`].
///
/// The predicate and the pattern are one owner, so the desk's judgment
/// cannot drift from the forge's: `rk message --check` calls this, the
/// title checks render the pattern, and a test holds the two equal over
/// every ASCII character.
#[must_use]
pub fn scope_is_shaped(scope: &str) -> bool {
    !scope.is_empty()
        && scope.chars().all(|c| {
            c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '_' | '.' | '/' | '-')
        })
}

/// The routing block for one workflow mode: the whole of target-side
/// governance, authored as `blocks/agents-block.md.in` and never grown
/// into a method chapter, read from the bundle `source` carries.
///
/// Markers included, without a
/// trailing newline and with its scope token unrendered: the template
/// with the mode's one orientation line substituted, everything else —
/// the agent-boundary line included — byte-identical across modes.
///
/// # Errors
///
/// Returns the source's failures for a bundle that does not carry the
/// block.
pub fn routing_block(source: &dyn ReleaseSource, workflow: Workflow) -> Result<String, RkError> {
    let manifest = source.manifest()?;
    let line = block(
        source,
        &manifest,
        match workflow {
            Workflow::Worktree => AGENTS_LINE_WORKTREE,
            Workflow::Branches => AGENTS_LINE_BRANCHES,
        },
    )?;
    let template = block(source, &manifest, AGENTS_BLOCK)?;
    Ok(authored(&template).replacen("RK_WORKFLOW_LINE", authored(&line), 1))
}

/// The glossary block, read from the bundle `source` carries.
///
/// Markers included and without a trailing newline, like the routing
/// block. It carries no token and no mode: every term it names expands
/// to steps of the one workflow, so the same bytes land in every target.
///
/// # Errors
///
/// Returns the source's failures for a bundle that does not carry the
/// block.
pub fn glossary_block(source: &dyn ReleaseSource) -> Result<String, RkError> {
    let manifest = source.manifest()?;
    Ok(authored(&block(source, &manifest, GLOSSARY_BLOCK)?).to_owned())
}

/// The hook block for one workflow mode, read from the bundle `source`
/// carries.
///
/// Authored as `blocks/pre-commit-block.yaml.in` with the worktree mode's
/// guard entry beside it in `blocks/pre-commit-worktree-guard.yaml.in`.
/// Markers included, without a
/// trailing newline and with its scope token unrendered. What is landed
/// is what runs: the worktree mode's block carries the location guard and
/// names the sweep-skip pair, and the branches mode's block carries no
/// guard entry at all — never an entry that reads local state to decide
/// whether to enforce. The one branch grammar substitutes here from
/// [`BRANCH_GRAMMAR`].
///
/// # Errors
///
/// Returns the source's failures for a bundle that does not carry the
/// block.
pub fn hooks_block(source: &dyn ReleaseSource, workflow: Workflow) -> Result<String, RkError> {
    let manifest = source.manifest()?;
    let (guard, skip) = match workflow {
        Workflow::Worktree => (
            format!(
                "{}\n",
                authored(&block(source, &manifest, PRE_COMMIT_WORKTREE_GUARD)?)
            ),
            "no-commit-to-branch,rk-worktree-location",
        ),
        Workflow::Branches => (String::new(), "no-commit-to-branch"),
    };
    let template = block(source, &manifest, PRE_COMMIT_BLOCK)?;
    Ok(authored(&template)
        .replacen("RK_BRANCH_GRAMMAR", BRANCH_GRAMMAR, 1)
        .replacen("RK_SWEEP_SKIP", skip, 1)
        .replacen("RK_WORKTREE_GUARD", &guard, 1))
}

/// The markers of a block destination, or `None` for a whole-file one.
#[must_use]
pub fn block_markers(destination: &str) -> Option<(&'static str, &'static str)> {
    match destination {
        AGENTS_DESTINATION | GLOSSARY_DESTINATION => Some((BLOCK_BEGIN, BLOCK_END)),
        HOOKS_DESTINATION => Some((HOOKS_BEGIN, HOOKS_END)),
        _ => None,
    }
}

/// The marked block inside a document, markers included, or `None` where
/// the text carries no complete block.
#[must_use]
pub fn extract_block<'a>(text: &'a str, begin: &str, end: &str) -> Option<&'a str> {
    let start = text.find(begin)?;
    let stop = text[start..].find(end)? + start + end.len();
    Some(&text[start..stop])
}

/// The whole document's bytes after splicing a marked block into it.
///
/// A fresh file where none exists, the block replaced in place where one
/// is marked, appended after the target's own content otherwise —
/// release-kit owns the lines inside the markers, not the document. Both
/// markdown destinations take this shape, `AGENTS.md` and the glossary.
#[must_use]
pub fn splice_marked_block(existing: Option<&[u8]>, block: &str) -> Vec<u8> {
    let block = block.as_bytes();
    let Some(text) = existing else {
        return [block, b"\n"].concat();
    };
    // Bytes, never text: the document belongs to the target and a decode
    // that replaces one invalid sequence rewrites a byte outside the
    // markers, which is the one thing a block destination never does.
    if let Some(start) = find(text, BLOCK_BEGIN.as_bytes())
        && let Some(offset) = find(&text[start..], BLOCK_END.as_bytes())
    {
        let stop = start + offset + BLOCK_END.len();
        return [&text[..start], block, &text[stop..]].concat();
    }
    // Appending keeps every byte the target wrote, trailing blank lines
    // and an absent final newline included. The only addition is the
    // separator that opens the block's own line.
    let separator: &[u8] = if text.ends_with(b"\n") {
        b"\n"
    } else {
        b"\n\n"
    };
    [text, separator, block, b"\n"].concat()
}

/// The whole `.pre-commit-config.yaml` content after splicing the
/// rendered hook block.
///
/// A fresh file carries the hook-types key, the `repos:` key, and the
/// block; a marked file takes the block in place; an unmarked file takes
/// it directly under its `repos:` line, above the target's own hooks. An
/// unmarked file with no `repos:` line is refused by name — the block's
/// entries are list items and have nowhere honest to go.
///
/// # Errors
///
/// The reason the block has no place, for the caller's refusal to carry.
pub fn splice_hooks_block(existing: Option<&str>, block: &str) -> Result<String, String> {
    let Some(text) = existing else {
        return Ok(format!("{HOOK_TYPES_LINE}\n\nrepos:\n{block}\n"));
    };
    if let Some(defect) = hooks_marker_defect(text) {
        return Err(defect);
    }
    if let Some(found) = extract_block(text, HOOKS_BEGIN, HOOKS_END) {
        return Ok(text.replacen(found, block, 1));
    }
    let mut out = String::with_capacity(text.len() + block.len() + 1);
    let mut placed = false;
    for line in text.split_inclusive('\n') {
        out.push_str(line);
        if !placed && line.trim_end() == "repos:" {
            if !out.ends_with('\n') {
                out.push('\n');
            }
            out.push_str(block);
            out.push('\n');
            placed = true;
        }
    }
    if placed {
        Ok(out)
    } else {
        Err(format!(
            "{HOOKS_DESTINATION} exists with no repos: line, so the hook block has nowhere to land"
        ))
    }
}

/// The one definition of an ill-formed hook file, shared by the splice
/// and every reader that judges one.
///
/// The hooks between the markers execute, so ownership must be
/// unambiguous: exactly one begin marker paired with exactly one end
/// marker after it, or none of either. A second begin is a second block
/// pre-commit would still run, and a marker without its pair — or an end
/// before its begin — is a block whose extent nothing can state.
#[must_use]
pub fn hooks_marker_defect(text: &str) -> Option<String> {
    let begins = text.matches(HOOKS_BEGIN).count();
    let ends = text.matches(HOOKS_END).count();
    if begins > 1 || ends > 1 {
        return Some(format!(
            "{HOOKS_DESTINATION} carries more than one release-kit marker pair; release-kit owns exactly one block"
        ));
    }
    match (text.find(HOOKS_BEGIN), text.find(HOOKS_END)) {
        (Some(begin), Some(end)) if end > begin => None,
        (None, None) => None,
        _ => Some(format!(
            "{HOOKS_DESTINATION} carries an unmatched or misordered release-kit marker, so the block's extent is ambiguous"
        )),
    }
}

/// How a projected artifact occupies its destination.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Placement {
    /// The artifact is the whole file.
    Whole,
    /// The artifact is the marked block inside the target's `AGENTS.md`.
    Block,
}

/// One artifact of the payload projection: what would land at one
/// destination, with the payload bytes it was rendered from.
#[derive(Debug)]
pub struct Entry {
    /// The destination, relative to the target root.
    pub destination: String,
    /// The declared kind.
    pub kind: Kind,
    /// Whole file, or the marked block.
    pub placement: Placement,
    /// The payload bytes before substitution — what `baseline_sha256`
    /// digests.
    pub baseline: Vec<u8>,
    /// The bytes a landing writes: substituted for `rendered` files,
    /// identical to the baseline otherwise.
    pub rendered: Vec<u8>,
}

/// The landable files of one `(technology, forge)` pair, as
/// `(destination, payload bytes)`, read from the bundle `source` carries.
///
/// # Errors
///
/// Returns [`RkError::Usage`] naming the known bindings for an unknown
/// technology, and the supported pairs for a pair with no files.
pub fn pair_files(
    source: &dyn ReleaseSource,
    tech: &str,
    forge: &str,
) -> Result<Vec<(String, Vec<u8>)>, RkError> {
    let manifest = source.manifest()?;
    let techs: Vec<String> = manifest
        .dirs_under("snippets")
        .into_iter()
        .filter(|name| !name.starts_with('_'))
        .collect();
    // The shared zone is not a technology: `_shared/<forge>` composes into
    // every pair and never names one.
    if tech.starts_with('_') || !techs.iter().any(|known| known == tech) {
        return Err(RkError::Usage(format!(
            "unknown tech '{tech}'; the bindings are: {}",
            techs.join(", ")
        )));
    }
    let pair = format!("snippets/{tech}/{forge}");
    if manifest.under(&pair).next().is_none() {
        let known: Vec<String> = techs
            .iter()
            .flat_map(|tech| {
                manifest
                    .dirs_under(&format!("snippets/{tech}"))
                    .into_iter()
                    .map(move |forge| format!("{tech}, {forge}"))
            })
            .collect();
        return Err(RkError::Usage(format!(
            "the pair ({tech}, {forge}) has no landable files; the supported pairs are: {}",
            known.join("; ")
        )));
    }
    // Payload paths carry their zone prefix; destinations do not. The
    // shared zone lands first, and a destination both zones ship is a
    // payload defect refused by name, never one zone silently winning.
    let mut files: Vec<(String, Vec<u8>)> = Vec::new();
    for (rel, artifact) in manifest.under(&format!("snippets/_shared/{forge}")) {
        files.push((rel.to_owned(), source.blob(&artifact.sha256)?));
    }
    for (rel, artifact) in manifest.under(&pair) {
        if files.iter().any(|(existing, _)| existing == rel) {
            return Err(anyhow::anyhow!(
                "the shared zone and the pair ({tech}, {forge}) both ship {rel}; the payload is defective"
            )
            .into());
        }
        files.push((rel.to_owned(), source.blob(&artifact.sha256)?));
    }
    Ok(files)
}

/// The whole payload projection for one pair, from the bundle `source`
/// carries.
///
/// Under the `repo`, `workflow`,
/// `style`, and `nix` parameters: every snippet with its kind and
/// rendered bytes, plus the routing block and the hook block — each a
/// pure function of the recorded mode — sorted by destination. The Nix
/// destinations project only where `nix` is on; a pair that ships none of
/// them honestly projects the smaller product.
///
/// # Errors
///
/// Returns the [`pair_files`] errors, and [`RkError::Other`] for a
/// snippet destination the kind table does not classify, which is a
/// defect in this binary.
pub fn projection(source: &dyn ReleaseSource, params: &Params) -> Result<Vec<Entry>, RkError> {
    let mut entries = Vec::new();
    for (destination, baseline) in pair_files(source, &params.tech, &params.forge)? {
        if !params.nix && NIX_DESTINATIONS.contains(&destination.as_str()) {
            continue;
        }
        let kind = kind_of(&destination).ok_or_else(|| {
            anyhow::anyhow!("the payload does not classify {destination}; the kind table is stale")
        })?;
        let rendered = match kind {
            Kind::Rendered => render(&baseline, params),
            Kind::Seeded | Kind::State => baseline.clone(),
        };
        entries.push(Entry {
            destination,
            kind,
            placement: Placement::Whole,
            baseline,
            rendered,
        });
    }
    // A bundle from before the glossary shipped declares no template for
    // it, and an older release stays selectable: the destination joins the
    // projection only where the selected bundle carries it.
    let mut blocks = vec![(AGENTS_DESTINATION, routing_block(source, params.workflow)?)];
    if source.manifest()?.artifact(GLOSSARY_BLOCK).is_some() {
        blocks.push((GLOSSARY_DESTINATION, glossary_block(source)?));
    }
    blocks.push((HOOKS_DESTINATION, hooks_block(source, params.workflow)?));
    for (destination, template) in blocks {
        entries.push(Entry {
            destination: destination.to_owned(),
            kind: Kind::Rendered,
            placement: Placement::Block,
            baseline: template.as_bytes().to_vec(),
            rendered: render(template.as_bytes(), params),
        });
    }
    entries.sort_by(|a, b| a.destination.cmp(&b.destination));
    Ok(entries)
}

/// Why the whole Nix capability stays out of a landing, or `None` where
/// the target's crate shape supports the seed.
///
/// The gate holds every structural prerequisite the seed relies on, not
/// only evaluation: the package expression reads `Cargo.toml` through
/// `importTOML` and throws without `../Cargo.lock`, and the seed flake's
/// smoke check runs the crate's binary, which only an implicit
/// `src/main.rs` or an explicit `[[bin]]` entry produces. A shape
/// missing any of these would land files that fail on their first
/// evaluation or first check, so the landing reports the smaller product
/// with the missing piece named instead.
#[must_use]
pub fn nix_unsupported_shape(target: &Utf8Path) -> Option<String> {
    let Ok(text) = std::fs::read_to_string(target.join("Cargo.toml")) else {
        return Some(
            "the target has no readable Cargo.toml, which the seeded package expression reads; no Nix file lands".to_owned(),
        );
    };
    let Ok(table) = text.parse::<toml::Table>() else {
        return Some(
            "the target's Cargo.toml does not parse, and the seeded package expression reads it; no Nix file lands".to_owned(),
        );
    };
    if !table.contains_key("package") {
        return Some(
            "the target's Cargo.toml has no [package] table; the seed supports a single crate, so no Nix file lands".to_owned(),
        );
    }
    if !target.join("Cargo.lock").is_file() {
        return Some(
            "the target has no Cargo.lock, which the seeded package expression builds from; commit one, then opt in".to_owned(),
        );
    }
    let implicit_bin = target.join("src/main.rs").is_file()
        && table
            .get("package")
            .and_then(toml::Value::as_table)
            .and_then(|package| package.get("autobins"))
            .and_then(toml::Value::as_bool)
            != Some(false);
    let explicit_bins = table.get("bin").and_then(toml::Value::as_array);
    if explicit_bins.is_none() && !implicit_bin {
        return Some(
            "the target declares no binary — no effective src/main.rs and no [[bin]] entry — and the seed flake's smoke check runs one; no Nix file lands".to_owned(),
        );
    }
    // The seed's mainProgram is the first [[bin]] entry; one whose
    // required-features a default build does not enable produces no
    // executable, so the smoke check would fail on a green landing. A
    // requirement the default feature set covers builds normally and
    // passes.
    if let Some(bins) = explicit_bins {
        let required = bins
            .first()
            .and_then(toml::Value::as_table)
            .and_then(|bin| bin.get("required-features"))
            .and_then(toml::Value::as_array);
        if let Some(required) = required {
            let enabled = default_features(&table);
            let missing = required
                .iter()
                .filter_map(toml::Value::as_str)
                .any(|feature| !enabled.contains(feature));
            if missing {
                return Some(
                    "the target's first [[bin]] entry requires features a default build does not enable; no Nix file lands".to_owned(),
                );
            }
        }
    }
    None
}

/// Whether any feature's list carries a `dep:name` edge, which is what
/// suppresses the optional dependency's implicit same-named feature.
fn dep_edge_suppresses(features: &toml::Table, name: &str) -> bool {
    let edge = format!("dep:{name}");
    features.values().any(|list| {
        list.as_array().is_some_and(|entries| {
            entries
                .iter()
                .filter_map(toml::Value::as_str)
                .any(|entry| entry == edge)
        })
    })
}

/// Whether `name` is declared an optional dependency, in any of the
/// dependency tables a binary's build reads.
fn is_optional_dependency(table: &toml::Table, name: &str) -> bool {
    ["dependencies", "build-dependencies"]
        .iter()
        .any(|section| {
            table
                .get(*section)
                .and_then(toml::Value::as_table)
                .and_then(|dependencies| dependencies.get(name))
                .and_then(toml::Value::as_table)
                .and_then(|dependency| dependency.get("optional"))
                .and_then(toml::Value::as_bool)
                == Some(true)
        })
}

/// The features a default build enables: the `default` feature resolved
/// through the `[features]` table's own enables — an approximation of
/// cargo's default resolution for the documented supported shapes, erring
/// toward withholding where the semantics run deeper. Dependency forms —
/// `dep:name`, weak `name?/feature` — are not feature names here and are
/// skipped; the closure is bounded by the table's size.
fn default_features(table: &toml::Table) -> std::collections::BTreeSet<String> {
    let Some(features) = table.get("features").and_then(toml::Value::as_table) else {
        return std::collections::BTreeSet::new();
    };
    let mut enabled = std::collections::BTreeSet::new();
    let mut queue = vec!["default".to_owned()];
    while let Some(name) = queue.pop() {
        if !enabled.insert(name.clone()) {
            continue;
        }
        if let Some(implies) = features.get(&name).and_then(toml::Value::as_array) {
            for implied in implies.iter().filter_map(toml::Value::as_str) {
                if implied.starts_with("dep:") || implied.contains("?/") {
                    // `dep:name` enables the dependency without a feature
                    // of this crate; a weak `name?/feature` edge enables
                    // nothing by itself.
                    continue;
                }
                if let Some((package, _)) = implied.split_once('/') {
                    // A strong `name/feature` edge activates this crate's
                    // same-named feature only for an optional dependency,
                    // and only where that feature exists: declared
                    // explicitly, or implicit and not suppressed by a
                    // `dep:` edge anywhere in the table. A non-optional
                    // dependency's edge enables a feature of the
                    // dependency and nothing of this crate.
                    let feature_exists =
                        features.contains_key(package) || !dep_edge_suppresses(features, package);
                    if is_optional_dependency(table, package) && feature_exists {
                        queue.push(package.to_owned());
                    }
                } else {
                    queue.push(implied.to_owned());
                }
            }
        }
    }
    enabled
}

/// Why the flake half of the Nix capability stays out of this landing, or
/// `None` where the pair lands whole.
///
/// The pair is all-or-nothing: a target that already carries a
/// `flake.nix` or `flake.lock` of its own keeps its pair, because a seed
/// lock beside a foreign flake describes the wrong input graph. A pair
/// the record names is release-kit's own landing and is never withheld.
///
/// # Errors
///
/// Any read failure other than the files being absent.
pub fn nix_withheld(
    target: &Utf8Path,
    recorded: Option<&manifest::Manifest>,
) -> std::io::Result<Option<String>> {
    if recorded.is_some_and(|record| record.file("flake.nix").is_some()) {
        return Ok(None);
    }
    let mut present = Vec::new();
    for name in ["flake.nix", "flake.lock"] {
        match std::fs::symlink_metadata(target.join(name).as_std_path()) {
            Ok(_) => present.push(name),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
            Err(e) => return Err(e),
        }
    }
    if present.is_empty() {
        return Ok(None);
    }
    Ok(Some(format!(
        "the target already carries {}; its flake pair stays its own",
        present.join(" and ")
    )))
}

/// One destination a landing withholds, with why.
#[derive(Debug, Clone, Serialize)]
pub struct Withheld {
    /// The destination that stays out.
    pub path: String,
    /// The reason, stated once per destination so a machine reader needs
    /// no join.
    pub reason: String,
}

/// The Nix destinations an opted-in landing withholds at this target, with
/// the one reason, or `None` where the capability lands whole.
///
/// The judgment [`withhold_nix`] applies, exposed as a value so a planner
/// can read it without an entry list: an unsupported crate shape names
/// the whole capability, and a flake pair of the target's own names the
/// pair.
///
/// # Errors
///
/// Any read failure from the pair check other than absence.
pub fn nix_withholding(
    target: &Utf8Path,
    recorded: Option<&manifest::Manifest>,
) -> Result<Option<(&'static [&'static str], String)>, RkError> {
    if let Some(reason) = nix_unsupported_shape(target) {
        return Ok(Some((&NIX_DESTINATIONS[..], reason)));
    }
    if let Some(reason) = nix_withheld(target, recorded)? {
        return Ok(Some((&NIX_WITHHOLDABLE[..], reason)));
    }
    Ok(None)
}

/// Drop the Nix destinations this target cannot take from a projection,
/// naming each with its reason.
///
/// The one judgment every landing verb shares, so a preview, an apply, an
/// upgrade, and an adoption all withhold identically: an unsupported
/// crate shape withholds the whole capability, and a flake pair of the
/// target's own withholds the pair and the workflow while the seeded
/// package expression still lands.
///
/// # Errors
///
/// Any read failure from the pair check other than absence.
pub fn withhold_nix(
    target: &Utf8Path,
    nix: bool,
    recorded: Option<&manifest::Manifest>,
    entries: &mut Vec<Entry>,
) -> Result<Vec<Withheld>, RkError> {
    if !nix {
        return Ok(Vec::new());
    }
    let Some((set, reason)) = nix_withholding(target, recorded)? else {
        return Ok(Vec::new());
    };
    let mut withheld = Vec::new();
    entries.retain(|entry| {
        if set.contains(&entry.destination.as_str()) {
            withheld.push(Withheld {
                path: entry.destination.clone(),
                reason: reason.clone(),
            });
            false
        } else {
            true
        }
    });
    Ok(withheld)
}

/// The bytes an entry's destination currently holds: the whole file, or
/// the marked block extracted from the target's `AGENTS.md`. `None` means
/// the file — or the block — is absent.
///
/// # Errors
///
/// Any read failure other than the file being absent.
pub fn read_destination(target: &Utf8Path, entry: &Entry) -> std::io::Result<Option<Vec<u8>>> {
    read_recorded(target, &entry.destination)
}

/// The bytes a recorded destination currently holds, by the placement
/// its name implies.
///
/// The marked block for `AGENTS.md` and `.pre-commit-config.yaml`, the
/// whole file otherwise. `None` means the file — or the block — is
/// absent.
///
/// # Errors
///
/// Any read failure other than the file being absent.
pub fn read_recorded(target: &Utf8Path, destination: &str) -> std::io::Result<Option<Vec<u8>>> {
    let path = target.join(destination);
    let bytes = match std::fs::read(&path) {
        Ok(bytes) => bytes,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };
    if let Some((begin, end)) = block_markers(destination) {
        let text = String::from_utf8_lossy(&bytes);
        Ok(extract_block(&text, begin, end).map(|block| block.as_bytes().to_vec()))
    } else {
        Ok(Some(bytes))
    }
}

/// What one detection pass resolved for a target-side verb, with the
/// override flags applied.
#[derive(Debug)]
pub struct Resolved {
    /// The forge whose payload applies.
    pub forge: String,
    /// The project path, where a flag or the remote names one.
    pub repo: Option<String>,
}

/// Resolve forge and repository in one pass: the flags override, the
/// `origin` remote answers otherwise.
///
/// An unrecognized host refuses rather than defaulting — landing one
/// forge's files into the other forge's project is a half-configured
/// repository that looks done.
///
/// # Errors
///
/// Returns [`RkError::Usage`] for an unknown `--forge` value, and a
/// refusal naming the override when no forge resolves.
pub fn resolve(
    target: &Utf8Path,
    forge_flag: Option<&str>,
    repo_flag: Option<&str>,
) -> Result<Resolved, RkError> {
    let forge_flag = forge_flag
        .map(|name| {
            crate::detect::Forge::parse(name).ok_or_else(|| {
                RkError::Usage(format!(
                    "unknown forge '{name}'; the forges are: github, gitlab"
                ))
            })
        })
        .transpose()?;
    let detected = crate::detect::detect(target.as_std_path());
    let forge = forge_flag
        .or(detected.forge)
        .map(|forge| forge.as_str().to_owned())
        .ok_or_else(|| {
            let message = detected.host.map_or_else(
                || "no forge detected: the target has no origin remote".to_owned(),
                |host| format!("no forge detected: the host {host} is not recognized"),
            );
            RkError::refusal(
                Diagnostic::new(Reason::ForgeUndetected, message)
                    .expected("a github.com or gitlab remote, or --forge")
                    .action("pass --forge <github|gitlab>"),
            )
        })?;
    Ok(Resolved {
        forge,
        repo: repo_flag.map(str::to_owned).or(detected.repo),
    })
}

/// The refusal a verb answers when it needs the `repo` parameter and
/// neither a flag nor the remote supplies one.
#[must_use]
pub fn repo_unresolved() -> RkError {
    RkError::missing(
        Diagnostic::new(
            Reason::ForgeUndetected,
            "no repository detected: the target has no origin remote",
        )
        .expected("an origin remote naming the project")
        .action("pass --repo <path>"),
    )
}

/// Land one entry: the whole file through the temp-plus-rename writer, or
/// the block spliced into its document and the whole document rewritten
/// the same way.
///
/// # Errors
///
/// Any write failure; the destination then holds what it held. An
/// unspliceable hook file surfaces as an error here only as a backstop —
/// [`hooks_splice_refusal`] is the check a verb runs before any write.
pub fn write_destination(target: &Utf8Path, entry: &Entry) -> std::io::Result<()> {
    let path = target.join(&entry.destination);
    match entry.placement {
        Placement::Whole => atomic::write(path.as_std_path(), &entry.rendered),
        Placement::Block => {
            let existing = match std::fs::read(&path) {
                Ok(bytes) => Some(bytes),
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
                Err(e) => return Err(e),
            };
            // The block is release-kit's own text; the document is the
            // target's bytes and is never decoded.
            let block = String::from_utf8_lossy(&entry.rendered).into_owned();
            if entry.destination == HOOKS_DESTINATION {
                let text = existing.map(|bytes| String::from_utf8_lossy(&bytes).into_owned());
                let spliced =
                    splice_hooks_block(text.as_deref(), &block).map_err(std::io::Error::other)?;
                atomic::write(path.as_std_path(), spliced.as_bytes())
            } else {
                let spliced = splice_marked_block(existing.as_deref(), &block);
                atomic::write(path.as_std_path(), &spliced)
            }
        }
    }
}

/// The hook file's defect, read from the target: `None` for a missing
/// file or one the block can land in.
///
/// The one judgment every verb shares, covering every splice refusal —
/// ill-formed markers, and an unmarked file offering the block no
/// `repos:` line. Status reports it as rendered drift, upgrade collects
/// it as a conflict in preview and apply alike so no landing dies
/// half-written, and adopt lists it with its mismatches.
///
/// # Errors
///
/// Any read failure other than the file being absent.
pub fn hooks_file_defect(
    source: &dyn ReleaseSource,
    target: &Utf8Path,
) -> Result<Option<String>, RkError> {
    let path = target.join(HOOKS_DESTINATION);
    match std::fs::read(&path) {
        Ok(bytes) => {
            let text = String::from_utf8_lossy(&bytes);
            let manifest = source.manifest()?;
            let template = block(source, &manifest, PRE_COMMIT_BLOCK)?;
            Ok(splice_hooks_block(Some(&text), authored(&template)).err())
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(e) => Err(e.into()),
    }
}

/// The refusal a landing verb answers before writing anything, where
/// the target's hook file offers the block no place.
///
/// Checked ahead of every write so the all-or-nothing property holds and
/// no landing dies half-written into `.pre-commit-config.yaml`.
///
/// # Errors
///
/// [`RkError::Refusal`] naming the file, and any read failure.
pub fn hooks_splice_refusal(source: &dyn ReleaseSource, target: &Utf8Path) -> Result<(), RkError> {
    hooks_file_defect(source, target)?.map_or(Ok(()), |reason| {
        Err(RkError::refusal(
            Diagnostic::new(
                Reason::StateDrift,
                format!("{reason}, and nothing was written"),
            )
            .expected("a .pre-commit-config.yaml the block can land in, or none")
            .action(format!(
                "resolve it in {}, then re-run",
                target.join(HOOKS_DESTINATION)
            ))
            .target_state("unchanged"),
        ))
    })
}

#[cfg(test)]
mod tests {
    use super::{
        AGENTS_DESTINATION, BLOCK_BEGIN, BLOCK_DESTINATIONS, BLOCK_END, BRANCH_GRAMMAR,
        GLOSSARY_DESTINATION, HOOK_TYPES_LINE, HOOKS_BEGIN, HOOKS_DESTINATION, HOOKS_END, Kind,
        SCOPE_SHAPE, Style, Workflow, extract_block, kind_of, render, splice_hooks_block,
        splice_marked_block,
    };
    use crate::embedded;
    use crate::release::EmbeddedReleaseSource;

    /// The embedded bundle, which every test here reads through the seam.
    const SOURCE: EmbeddedReleaseSource = EmbeddedReleaseSource;

    fn pair_files(
        tech: &str,
        forge: &str,
    ) -> Result<Vec<(String, Vec<u8>)>, crate::error::RkError> {
        super::pair_files(&SOURCE, tech, forge)
    }

    fn projection(params: &super::Params) -> Result<Vec<super::Entry>, crate::error::RkError> {
        super::projection(&SOURCE, params)
    }

    fn routing_block(workflow: Workflow) -> String {
        super::routing_block(&SOURCE, workflow).expect("the embedded bundle carries the block")
    }

    fn hooks_block(workflow: Workflow) -> String {
        super::hooks_block(&SOURCE, workflow).expect("the embedded bundle carries the block")
    }

    fn glossary_block() -> String {
        super::glossary_block(&SOURCE).expect("the embedded bundle carries the block")
    }

    /// The splice returns the document's bytes; every assertion below
    /// reads them back as text, which every fixture here is.
    fn spliced(existing: Option<&str>, block: &str) -> String {
        String::from_utf8(splice_marked_block(existing.map(str::as_bytes), block))
            .expect("the fixtures are text")
    }

    #[test]
    fn private_reporting_path_tokens_are_reproducible() {
        for repo in [
            "acme/widget",
            "acme/group/widget",
            "acme/OWNER-RK_STYLE-RK_SCOPE_SHAPE",
        ] {
            assert_eq!(
                super::render(
                    b"RK_REPO RK_REPO OWNER RK_STYLE RK_SCOPE_SHAPE",
                    &super::Params::for_test(repo, Some(super::Style::Trunk))
                ),
                format!("{repo} {repo} acme trunk {}", super::SCOPE_SHAPE).as_bytes()
            );
        }
        assert_eq!(super::kind_of("SECURITY.md"), Some(super::Kind::Rendered));
    }

    /// Both forge policies carry exactly one ordered pair of every
    /// security marker. The span renderer treats anything else as a
    /// payload defect and leaves the bytes alone, so this test is what
    /// keeps a defect out of a release rather than out of one landing.
    #[test]
    fn each_forge_policy_carries_one_ordered_pair_of_every_span() {
        for forge in ["github", "gitlab"] {
            let bytes = embedded::SNIPPETS
                .get_file(format!("_shared/{forge}/SECURITY.md"))
                .expect("the policy ships")
                .contents();
            let text = String::from_utf8_lossy(bytes);
            for (begin, end) in super::SECURITY_SPANS {
                let begin = String::from_utf8_lossy(begin);
                let end = String::from_utf8_lossy(end);
                assert_eq!(text.matches(begin.as_ref()).count(), 1, "{forge} {begin}");
                assert_eq!(text.matches(end.as_ref()).count(), 1, "{forge} {end}");
                assert!(
                    text.find(begin.as_ref()) < text.find(end.as_ref()),
                    "{forge}: {begin} must precede {end}"
                );
            }
        }
    }

    /// The default answers reproduce each forge's authored policy exactly,
    /// markers removed and each forge's own wording kept; an answered one
    /// states it; and a contact spelling a token name lands literally,
    /// because the spans resolve after every substitution.
    #[test]
    fn the_security_spans_render_per_answer() {
        for forge in ["github", "gitlab"] {
            let bytes = embedded::SNIPPETS
                .get_file(format!("_shared/{forge}/SECURITY.md"))
                .expect("the policy ships")
                .contents();
            let authored = String::from_utf8_lossy(bytes);
            let stripped = {
                let mut text = authored.clone().into_owned();
                for (begin, end) in super::SECURITY_SPANS {
                    text = text.replace(&String::from_utf8_lossy(begin).into_owned(), "");
                    text = text.replace(&String::from_utf8_lossy(end).into_owned(), "");
                }
                text
            };
            let default = super::Params {
                forge: forge.to_owned(),
                ..super::Params::for_test_security("", crate::config::RESPONSE_DEFAULT)
            };
            let rendered = String::from_utf8(render(bytes, &default)).expect("text");
            assert_eq!(
                rendered,
                stripped.replace("RK_REPO", "acme/widget"),
                "{forge}: the default answers must reproduce the authored policy"
            );
            assert!(!rendered.contains("RK_SECURITY"), "{forge}: {rendered}");

            let answered = super::Params {
                forge: forge.to_owned(),
                ..super::Params::for_test_security("OWNER RK_REPO <team@acme.example>", "14 days")
            };
            let rendered = String::from_utf8(render(bytes, &answered)).expect("text");
            assert!(
                rendered.contains("OWNER RK_REPO <team@acme.example>"),
                "{forge}: a contact spelling a token name lands literally: {rendered}"
            );
            assert!(
                rendered.contains("Maintainers acknowledge a report within 14 days."),
                "{forge}: {rendered}"
            );
            assert!(
                rendered.contains("This policy commits to no disclosure deadline."),
                "{forge}: {rendered}"
            );
            assert!(
                !rendered.contains("best-effort basis"),
                "{forge}: a stated window replaces the best-effort sentence: {rendered}"
            );
            assert!(
                !rendered.contains("no response or disclosure deadline"),
                "{forge}: a stated window contradicts the response disclaimer: {rendered}"
            );
        }
    }

    /// A defective span leaves the bytes alone rather than producing a
    /// half-written sentence: the payload test above is what catches one.
    #[test]
    fn a_defective_span_renders_unchanged() {
        let (begin, end) = super::SECURITY_SPANS[0];
        let begin = String::from_utf8_lossy(begin).into_owned();
        let end = String::from_utf8_lossy(end).into_owned();
        let params = super::Params::for_test_security("team@acme.example", "1 day");
        for baseline in [
            format!("contact {begin}a maintainer\n"),
            format!("contact a maintainer{end}\n"),
            format!("contact {end}a maintainer{begin}\n"),
            "contact a maintainer\n".to_owned(),
        ] {
            assert_eq!(
                render(baseline.as_bytes(), &params),
                baseline.as_bytes(),
                "{baseline}"
            );
        }
    }

    /// Every snippet destination has a declared kind: a new landable file
    /// without a classification fails here, not at a landing. The shared
    /// zone's files are enumerated the same way.
    #[test]
    fn the_kind_table_closes_over_every_snippet() {
        for tech_dir in embedded::SNIPPETS.dirs() {
            for pair_dir in tech_dir.dirs() {
                let prefix = format!("{}/", pair_dir.path().to_string_lossy());
                for (path, _) in embedded::walk(pair_dir) {
                    let destination = path.strip_prefix(&prefix).unwrap_or(&path);
                    assert!(
                        kind_of(destination).is_some(),
                        "{destination}: no declared kind"
                    );
                }
            }
        }
        for block in BLOCK_DESTINATIONS {
            assert_eq!(kind_of(block), Some(Kind::Rendered), "{block}");
        }
        assert_eq!(kind_of("something-else.txt"), None);
    }

    /// Substitution is total and derives from the repo parameter's first
    /// segment, so a nested GitLab project path still yields its root
    /// namespace. The scope shape rests on no parameter, so it renders
    /// under every landing.
    #[test]
    fn rendering_substitutes_every_owner_occurrence() {
        let baseline = b"if: repository_owner == 'OWNER'\n# OWNER again: OWNER\n";
        let rendered = render(baseline, &super::Params::for_test("acme/sub/widget", None));
        let text = String::from_utf8(rendered).expect("rendered bytes stay text");
        assert_eq!(text, "if: repository_owner == 'acme'\n# acme again: acme\n");

        let baseline = b"match (RK_SCOPE_SHAPE)\n";
        let rendered = render(baseline, &super::Params::for_test("acme/widget", None));
        let text = String::from_utf8(rendered).expect("rendered bytes stay text");
        assert_eq!(text, format!("match ({SCOPE_SHAPE})\n"));
    }

    /// The one scope shape is a bracket expression an extended regular
    /// expression takes verbatim: lowercase, and with the `-` last, where
    /// it stands for itself rather than opening a range.
    #[test]
    fn the_scope_shape_drops_into_the_title_check() {
        assert_eq!(SCOPE_SHAPE, "[a-z0-9._/-]+");
        assert!(
            !SCOPE_SHAPE.contains('\''),
            "the title checks single-quote it"
        );
    }

    /// The predicate `rk message --check` calls and the pattern the title
    /// checks render admit exactly the same characters. The pattern is
    /// expanded here from its own text, so editing one owner without the
    /// other fails: the desk and the forge judge one language.
    #[test]
    fn the_scope_predicate_and_the_rendered_pattern_agree() {
        let body = SCOPE_SHAPE
            .strip_prefix('[')
            .and_then(|rest| rest.strip_suffix("]+"))
            .expect("the shape is one bracket expression, repeated");
        let chars: Vec<char> = body.chars().collect();
        let mut admitted = std::collections::BTreeSet::new();
        let mut at = 0;
        while at < chars.len() {
            // A `-` with a neighbour on each side opens a range; last, it
            // stands for itself, which is why the shape ends with it.
            if at + 2 < chars.len() && chars[at + 1] == '-' {
                for c in chars[at]..=chars[at + 2] {
                    admitted.insert(c);
                }
                at += 3;
            } else {
                admitted.insert(chars[at]);
                at += 1;
            }
        }
        for byte in 0..=127u8 {
            let c = char::from(byte);
            assert_eq!(
                super::scope_is_shaped(&c.to_string()),
                admitted.contains(&c),
                "the predicate and {SCOPE_SHAPE} disagree on {c:?}"
            );
        }
        assert!(super::scope_is_shaped("guides/release"));
        assert!(!super::scope_is_shaped(""), "a scope is never empty");
        assert!(!super::scope_is_shaped("Specs Ugly"));
    }

    /// The shared zone composes into every pair, lands first, and is
    /// absent from the technology listing an unknown tech names.
    #[test]
    fn the_shared_zone_composes_into_the_pair() {
        let files = pair_files("rust", "github").expect("the pair lists");
        assert!(
            files
                .iter()
                .any(|(dest, _)| dest == ".github/workflows/pr-title.yml"),
            "the shared title check lands with the pair"
        );
        let files = pair_files("rust", "gitlab").expect("the pair lists");
        assert!(
            files
                .iter()
                .any(|(dest, _)| dest == ".gitlab/ci/mr-title.yml"),
            "the shared title job lands with the pair"
        );
        let err = pair_files("_shared", "github").expect_err("the shared zone is no tech");
        let listing = err.to_string();
        let bindings = listing
            .split("the bindings are:")
            .nth(1)
            .expect("the refusal lists the bindings");
        assert!(!bindings.contains("_shared"), "{listing}");
    }

    /// A loaded record reaches the projection unchanged, including old
    /// records' absent style and the two workflow modes.
    #[test]
    fn params_from_a_record_round_trips() {
        use super::{Params, manifest};
        let dir = tempfile::tempdir().expect("a scratch target exists");
        let target = camino::Utf8Path::from_path(dir.path()).expect("utf-8 path");
        for tech in ["rust", "bash"] {
            for forge in ["github", "gitlab"] {
                for workflow in [Workflow::Branches, Workflow::Worktree] {
                    for style in [None, Some(Style::Trunk), Some(Style::Lines)] {
                        for nix in [false, true] {
                            let record = manifest::Manifest {
                                schema_version: manifest::SCHEMA_VERSION,
                                rk_version: "0.1.0".to_owned(),
                                payload_sha256: crate::digest::Digest::of(b""),
                                origin: "init".to_owned(),
                                tech: tech.to_owned(),
                                forge: forge.to_owned(),
                                landed_at: "2026-08-29T00:00:00Z".to_owned(),
                                parameters: manifest::Parameters {
                                    repo: "acme/team/widget".to_owned(),
                                    workflow,
                                    style,
                                    nix,
                                    trunk: crate::config::TRUNK_DEFAULT.to_owned(),
                                    line_prefix: crate::config::LINE_PREFIX_DEFAULT.to_owned(),
                                    security_contact: String::new(),
                                    security_response: crate::config::RESPONSE_DEFAULT.to_owned(),
                                },
                                files: Vec::new(),
                                pins: std::collections::BTreeMap::new(),
                            };
                            manifest::write(target, &record).expect("the record writes");
                            let loaded = manifest::load(target)
                                .expect("the record loads")
                                .expect("the record exists");
                            let params = Params::from_record(&loaded);
                            assert_eq!(params.tech, tech);
                            assert_eq!(params.forge, forge);
                            assert_eq!(params.repo(), "acme/team/widget");
                            assert_eq!(params.workflow(), workflow);
                            assert_eq!(params.style(), style);
                            assert_eq!(params.nix, nix);
                            let entries = projection(&params).expect("the record projects");
                            let mut expected: Vec<_> = pair_files(tech, forge)
                                .expect("the pair lists")
                                .into_iter()
                                .filter(|(path, _)| {
                                    nix || !super::NIX_DESTINATIONS.contains(&path.as_str())
                                })
                                .collect();
                            let routing = routing_block(workflow);
                            let hooks = hooks_block(workflow);
                            let glossary = glossary_block();
                            expected.push((AGENTS_DESTINATION.to_owned(), routing.into_bytes()));
                            expected.push((GLOSSARY_DESTINATION.to_owned(), glossary.into_bytes()));
                            expected.push((HOOKS_DESTINATION.to_owned(), hooks.into_bytes()));
                            expected.sort_by(|a, b| a.0.cmp(&b.0));
                            assert_eq!(entries.len(), expected.len());
                            for (entry, (destination, baseline)) in entries.iter().zip(expected) {
                                assert_eq!(entry.destination, destination);
                                assert_eq!(entry.baseline, baseline);
                                let rendered = match entry.kind {
                                    Kind::Rendered => super::render(
                                        &baseline,
                                        &super::Params::for_test("acme/team/widget", style),
                                    ),
                                    Kind::Seeded | Kind::State => baseline.clone(),
                                };
                                assert_eq!(entry.rendered, rendered, "{destination}");
                            }
                        }
                    }
                }
            }
        }
    }

    fn resolved_test_params(
        tech: &str,
        resolved: &super::Resolved,
        workflow: Workflow,
        style: Option<Style>,
        nix: bool,
    ) -> Result<super::Params, crate::error::RkError> {
        super::Params::resolve(
            &SOURCE,
            camino::Utf8Path::new("."),
            &super::Inputs {
                tech: Some(tech),
                forge: Some(&resolved.forge),
                repo: resolved.repo.as_deref(),
                workflow: Some(workflow),
                style,
                nix: Some(nix),
            },
            None,
            None,
            super::Purpose::Init,
        )
    }

    /// A rendered projection carries no unsubstituted token and no
    /// mechanical sentinel; the one judgment sentinel stays in its seeded
    /// file.
    #[test]
    fn a_projection_renders_owned_files_and_keeps_seeded_judgment() {
        let entries = projection(
            &resolved_test_params(
                "rust",
                &super::Resolved {
                    forge: "github".to_owned(),
                    repo: Some("acme/widget".to_owned()),
                },
                Workflow::Branches,
                Some(Style::Trunk),
                false,
            )
            .expect("the parameters resolve"),
        )
        .expect("the pair projects");
        let workflow = entries
            .iter()
            .find(|entry| entry.destination.ends_with("release-plz.yml"))
            .expect("the workflow projects");
        assert_eq!(workflow.kind, Kind::Rendered);
        let text = String::from_utf8_lossy(&workflow.rendered);
        assert!(!text.contains("OWNER"), "an owner token survived rendering");
        assert!(text.contains("'acme'"));
        assert!(!text.contains("TODO(release-kit)"));
        let title = entries
            .iter()
            .find(|entry| entry.destination.ends_with("pr-title.yml"))
            .expect("the title check projects");
        let text = String::from_utf8_lossy(&title.rendered);
        assert!(text.contains(SCOPE_SHAPE), "{text}");
        assert!(
            !text.contains("RK_SCOPE_SHAPE"),
            "a scope token survived: {text}"
        );
        let seeded = entries
            .iter()
            .find(|entry| entry.destination == "release-plz.toml")
            .expect("the seeded file projects");
        assert_eq!(seeded.kind, Kind::Seeded);
        assert_eq!(seeded.rendered, seeded.baseline);
        assert!(String::from_utf8_lossy(&seeded.rendered).contains("TODO(release-kit)"));
        for block in BLOCK_DESTINATIONS {
            let entry = entries
                .iter()
                .find(|entry| entry.destination == block)
                .expect("every block is part of the projection");
            let text = String::from_utf8_lossy(&entry.rendered);
            assert!(
                !text.contains("RK_SCOPE_SHAPE"),
                "{block} kept a token: {text}"
            );
        }
    }

    /// The Nix destinations project only under the opt-in: off, none of
    /// them appears; on, the rust pairs carry them — the gitlab pair too,
    /// minus the workflow, which is a forge file the gitlab payload does
    /// not ship — and a pair without them projects the smaller product.
    #[test]
    fn the_nix_destinations_project_only_under_the_opt_in() {
        use super::NIX_DESTINATIONS;
        let paths = |nix: bool, forge: &str| -> Vec<String> {
            projection(
                &resolved_test_params(
                    "rust",
                    &super::Resolved {
                        forge: forge.to_owned(),
                        repo: Some("acme/widget".to_owned()),
                    },
                    Workflow::Worktree,
                    Some(Style::Trunk),
                    nix,
                )
                .expect("the parameters resolve"),
            )
            .expect("the pair projects")
            .into_iter()
            .map(|entry| entry.destination)
            .collect()
        };
        let off = paths(false, "github");
        for destination in NIX_DESTINATIONS {
            assert!(!off.contains(&destination.to_owned()), "{destination}");
        }
        let on = paths(true, "github");
        for destination in ["nix/package.nix", "flake.nix", "flake.lock"] {
            assert!(on.contains(&destination.to_owned()), "{destination}");
        }
        // The capability lands no workflow, so both forges land the same
        // set: a job proving the build holds a merge only inside the
        // workflow the required check needs, and that one is the
        // target's own.
        let gitlab = paths(true, "gitlab");
        assert!(gitlab.contains(&"nix/package.nix".to_owned()));
        assert!(
            !on.iter()
                .chain(gitlab.iter())
                .any(|destination| destination.contains("nix.yml"))
        );
        let bash = projection(
            &resolved_test_params(
                "bash",
                &super::Resolved {
                    forge: "github".to_owned(),
                    repo: Some("acme/widget".to_owned()),
                },
                Workflow::Worktree,
                Some(Style::Trunk),
                true,
            )
            .expect("the parameters resolve"),
        )
        .expect("an out-of-matrix pair projects the smaller product");
        assert!(
            bash.iter()
                .all(|entry| !NIX_DESTINATIONS.contains(&entry.destination.as_str()))
        );
    }

    /// The github and gitlab copies of the forge-independent Nix payload
    /// stay byte-identical: the loader composes exactly two layers and has
    /// no technology-wide zone, so the duplication is deliberate and this
    /// parity test is what keeps it honest.
    #[test]
    fn the_nix_seeds_are_identical_across_forge_pairs() {
        for name in ["nix/package.nix", "flake.nix", "flake.lock"] {
            let github = embedded::SNIPPETS
                .get_file(format!("rust/github/{name}"))
                .expect("the github copy ships")
                .contents();
            let gitlab = embedded::SNIPPETS
                .get_file(format!("rust/gitlab/{name}"))
                .expect("the gitlab copy ships")
                .contents();
            assert_eq!(github, gitlab, "{name} diverged between the pairs");
        }
    }

    /// The withhold judgment: a flake pair of the target's own withholds
    /// the pair and the workflow while the package expression lands, a
    /// crate shape the seed does not support withholds everything, and a
    /// clean single-crate target withholds nothing.
    #[test]
    fn the_nix_withhold_judgment_covers_the_three_shapes() {
        use super::{NIX_DESTINATIONS, withhold_nix};
        let dir = tempfile::tempdir().expect("a scratch target exists");
        let target = camino::Utf8Path::from_path(dir.path()).expect("utf-8 path");
        let entries = || {
            projection(
                &resolved_test_params(
                    "rust",
                    &super::Resolved {
                        forge: "github".to_owned(),
                        repo: Some("acme/widget".to_owned()),
                    },
                    Workflow::Worktree,
                    Some(Style::Trunk),
                    true,
                )
                .expect("the parameters resolve"),
            )
            .expect("the pair projects")
        };

        // No Cargo.toml: the whole capability is withheld by name.
        let mut all = entries();
        let withheld = withhold_nix(target, true, None, &mut all).expect("the judgment runs");
        let paths: Vec<&str> = withheld.iter().map(|w| w.path.as_str()).collect();
        assert_eq!(paths, ["flake.lock", "flake.nix", "nix/package.nix"]);
        assert!(
            all.iter()
                .all(|entry| !NIX_DESTINATIONS.contains(&entry.destination.as_str()))
        );

        // A single crate with its own flake: the seed pair is withheld,
        // and the package expression still lands.
        std::fs::write(
            target.join("Cargo.toml"),
            "[package]\nname = \"widget\"\nversion = \"0.1.0\"\n",
        )
        .expect("the crate manifest writes");
        std::fs::write(target.join("Cargo.lock"), "version = 4\n").expect("the lock writes");
        std::fs::create_dir_all(target.join("src")).expect("the src dir exists");
        std::fs::write(target.join("src/main.rs"), "fn main() {}\n").expect("the main writes");
        std::fs::write(target.join("flake.nix"), "{ }\n").expect("the flake writes");
        let mut all = entries();
        let withheld = withhold_nix(target, true, None, &mut all).expect("the judgment runs");
        let paths: Vec<&str> = withheld.iter().map(|w| w.path.as_str()).collect();
        assert_eq!(paths, ["flake.lock", "flake.nix"]);
        assert!(
            all.iter()
                .any(|entry| entry.destination == "nix/package.nix")
        );

        // A clean single crate: nothing is withheld.
        std::fs::remove_file(target.join("flake.nix")).expect("the flake removes");
        let mut all = entries();
        let withheld = withhold_nix(target, true, None, &mut all).expect("the judgment runs");
        assert!(withheld.is_empty());
        assert!(all.iter().any(|entry| entry.destination == "flake.nix"));

        // Off, the judgment does not even look.
        let mut all = entries();
        let withheld = withhold_nix(target, false, None, &mut all).expect("the judgment runs");
        assert!(withheld.is_empty());
    }

    /// The glossary takes the same three shapes the routing block does,
    /// and the marker pair it shares with `AGENTS.md` is what makes one
    /// splice serve both.
    #[test]
    fn the_glossary_splices_into_every_shape() {
        let owned = glossary_block();
        let block = owned.as_str();

        let fresh = spliced(None, block);
        assert_eq!(fresh, format!("{block}\n"));
        assert_eq!(extract_block(&fresh, BLOCK_BEGIN, BLOCK_END), Some(block));

        let own = "# Glossary\n\n- `spike` — a throwaway branch.\n";
        let appended = spliced(Some(own), block);
        assert!(appended.starts_with(own));
        assert_eq!(
            extract_block(&appended, BLOCK_BEGIN, BLOCK_END),
            Some(block)
        );

        let stale = appended.replace("full-implement", "do-everything");
        let refreshed = spliced(Some(&stale), block);
        assert_eq!(
            extract_block(&refreshed, BLOCK_BEGIN, BLOCK_END),
            Some(block)
        );
        assert_eq!(
            refreshed.matches("BEGIN release-kit").count(),
            1,
            "a re-splice must replace, not accumulate"
        );
    }

    /// Every line the target wrote below the end marker survives a
    /// re-splice byte for byte: the block owns its marked lines and the
    /// document belongs to the target.
    #[test]
    fn the_glossary_leaves_the_targets_region_alone() {
        let owned = glossary_block();
        let block = owned.as_str();
        let below = "\n## Our own terms\n\n- `spike` — a throwaway branch, never merged.\n";
        let landed = format!("{block}\n{below}");

        let refreshed = spliced(Some(&landed), block);
        assert!(
            refreshed.ends_with(below),
            "the target's own region changed: {refreshed}"
        );
        assert_eq!(
            extract_block(&refreshed, BLOCK_BEGIN, BLOCK_END),
            Some(block)
        );
    }

    /// Appending keeps the document whole: trailing spaces, blank lines,
    /// and a missing final newline are the target's bytes, and a block
    /// that owns its marked lines alone rewrites none of them.
    #[test]
    fn an_append_rewrites_no_byte_the_target_wrote() {
        let owned = glossary_block();
        let block = owned.as_str();
        for own in [
            "# Glossary\n\n- `spike` — throwaway.   \n\n\n",
            "# Glossary\n\n- `spike` — throwaway.",
            "# Glossary\r\n\r\n- `spike` — throwaway.\r\n",
        ] {
            let appended = spliced(Some(own), block);
            assert!(
                appended.starts_with(own),
                "the target's bytes changed: {appended:?}"
            );
            assert_eq!(
                extract_block(&appended, BLOCK_BEGIN, BLOCK_END),
                Some(block),
                "{appended:?}"
            );
            let marker = appended.find(BLOCK_BEGIN).expect("the block landed");
            assert!(
                appended[..marker].ends_with('\n'),
                "the block must open its own line: {appended:?}"
            );
        }
    }

    /// A document the target wrote is bytes, not text. A splice that
    /// decoded it would replace an invalid sequence with U+FFFD and
    /// rewrite a byte outside the markers, which the rule forbids.
    #[test]
    fn a_splice_decodes_no_byte_the_target_wrote() {
        let owned = glossary_block();
        let block = owned.as_str();

        // Appending: the invalid byte sits in the target's own document.
        let own = b"# Glossary\n\ncaf\xe9\n";
        let appended = splice_marked_block(Some(own), block);
        assert!(
            appended.starts_with(own),
            "the target's bytes changed: {appended:?}"
        );
        assert!(!appended.contains(&0xEF), "a replacement character landed");

        // Replacing: the invalid byte sits below the end marker.
        let mut landed = Vec::new();
        landed.extend_from_slice(block.replace("full-implement", "do-everything").as_bytes());
        landed.extend_from_slice(b"\n\ncaf\xe9\n");
        let refreshed = splice_marked_block(Some(&landed), block);
        assert!(
            refreshed.ends_with(b"\n\ncaf\xe9\n"),
            "the target's region below the markers changed: {refreshed:?}"
        );
        assert!(refreshed.starts_with(block.as_bytes()), "{refreshed:?}");
    }

    /// The glossary carries no parameter, so the same bytes land in
    /// every target: no token survives it and no mode changes it.
    #[test]
    fn the_glossary_block_carries_no_parameter() {
        let block = glossary_block();
        assert!(block.starts_with(BLOCK_BEGIN), "{block}");
        assert!(block.ends_with(BLOCK_END), "{block}");
        assert!(!block.contains("RK_"), "a token survived: {block}");
        assert!(!block.contains("OWNER"), "an owner token survived: {block}");
        for term in [
            "implement-and-request",
            "implement-and-merge",
            "full-implement",
        ] {
            assert!(block.contains(term), "{term} is missing from {block}");
        }
        assert!(
            routing_block(Workflow::Worktree).contains(GLOSSARY_DESTINATION),
            "the routing block must name the destination it indexes"
        );
    }

    #[test]
    fn the_block_splices_into_every_agents_shape() {
        let owned = routing_block(Workflow::Branches);
        let block = owned.as_str();
        let fresh = spliced(None, block);
        assert_eq!(fresh, format!("{block}\n"));
        assert_eq!(extract_block(&fresh, BLOCK_BEGIN, BLOCK_END), Some(block));

        let appended = spliced(Some("# My project\n\nOwn rules.\n"), block);
        assert!(appended.starts_with("# My project\n\nOwn rules.\n\n<!-- BEGIN release-kit -->"));
        assert_eq!(
            extract_block(&appended, BLOCK_BEGIN, BLOCK_END),
            Some(block)
        );

        let stale = appended.replace("Never author a tag", "Do author a tag");
        let refreshed = spliced(Some(&stale), block);
        assert_eq!(
            extract_block(&refreshed, BLOCK_BEGIN, BLOCK_END),
            Some(block)
        );
        assert!(refreshed.starts_with("# My project"));
        assert_eq!(
            refreshed.matches("BEGIN release-kit").count(),
            1,
            "a re-splice must replace, not accumulate"
        );
    }

    /// The hook block lands under `repos:` in every honest shape and
    /// refuses the one dishonest shape by name.
    #[test]
    fn the_hook_block_splices_under_repos() {
        let owned = hooks_block(Workflow::Branches);
        let block = owned.as_str();
        let fresh = splice_hooks_block(None, block).expect("a fresh file splices");
        assert!(fresh.starts_with(HOOK_TYPES_LINE));
        assert!(fresh.contains("\nrepos:\n# BEGIN release-kit\n"));
        assert_eq!(extract_block(&fresh, HOOKS_BEGIN, HOOKS_END), Some(block));

        let own =
            "repos:\n  - repo: https://example.com/own\n    rev: v1\n    hooks:\n      - id: own\n";
        let spliced = splice_hooks_block(Some(own), block).expect("an unmarked file splices");
        assert!(spliced.starts_with("repos:\n# BEGIN release-kit\n"));
        assert!(spliced.contains("- id: own"), "the target's hooks survive");
        assert!(
            !spliced.contains(HOOK_TYPES_LINE),
            "an existing file's top level is the skills' duty, not the splice's"
        );

        let stale = spliced.replace("--force-scope", "--no-scope");
        let refreshed = splice_hooks_block(Some(&stale), block).expect("a marked file re-splices");
        assert_eq!(
            extract_block(&refreshed, HOOKS_BEGIN, HOOKS_END),
            Some(block)
        );
        assert_eq!(refreshed.matches(HOOKS_BEGIN).count(), 1);

        let err = splice_hooks_block(Some("minimum_pre_commit_version: '3.2.0'\n"), block)
            .expect_err("no repos: line refuses");
        assert!(err.contains("repos:"), "{err}");

        // The hooks between the markers execute, so ownership is exactly
        // one well-formed block: a duplicate or an unmatched marker
        // refuses rather than leaving a stale block active.
        let doubled = format!("repos:\n{block}\n{block}\n");
        let err = splice_hooks_block(Some(&doubled), block).expect_err("a second block refuses");
        assert!(err.contains("one block"), "{err}");
        let unmatched = "repos:\n# BEGIN release-kit\n  - repo: local\n";
        let err =
            splice_hooks_block(Some(unmatched), block).expect_err("an unmatched marker refuses");
        assert!(err.contains("unmatched"), "{err}");
    }

    /// Both modes of both blocks: the guard entry and the skip pair exist
    /// exactly in the worktree mode, one orientation line differs in the
    /// routing block, the rest is byte-identical, no mode token survives
    /// substitution, and the rendered grammar is [`BRANCH_GRAMMAR`], the
    /// one owner.
    #[test]
    fn the_blocks_render_per_mode_and_carry_the_one_grammar() {
        let worktree_hooks = hooks_block(Workflow::Worktree);
        let branches_hooks = hooks_block(Workflow::Branches);
        assert!(worktree_hooks.contains("- id: rk-worktree-location"));
        assert!(
            worktree_hooks.contains("SKIP=no-commit-to-branch,rk-worktree-location"),
            "{worktree_hooks}"
        );
        assert!(!branches_hooks.contains("rk-worktree-location"));
        assert!(branches_hooks.contains("SKIP=no-commit-to-branch in"));
        for block in [&worktree_hooks, &branches_hooks] {
            assert!(block.contains(BRANCH_GRAMMAR), "the grammar has one owner");
            for token in ["RK_BRANCH_GRAMMAR", "RK_SWEEP_SKIP", "RK_WORKTREE_GUARD"] {
                assert!(!block.contains(token), "{token} survived: {block}");
            }
        }
        // A hook entry renders as a YAML plain scalar, where a colon
        // followed by a space ends the scalar and breaks the whole file
        // — the defect dogfood caught in the guard's refusal messages —
        // so no entry value may carry one.
        for block in [&worktree_hooks, &branches_hooks] {
            for line in block.lines() {
                if let Some(value) = line.trim_start().strip_prefix("entry: ") {
                    assert!(
                        !value.contains(": "),
                        "an entry value breaks the YAML plain scalar: {line}"
                    );
                }
            }
        }
        let guard_line = worktree_hooks
            .lines()
            .position(|line| line.contains("id: rk-worktree-location"))
            .expect("the guard entry exists");
        let name_line = worktree_hooks
            .lines()
            .position(|line| line.contains("id: rk-branch-name"))
            .expect("the name hook exists");
        assert!(
            guard_line > name_line,
            "the guard lands directly after rk-branch-name"
        );

        let worktree_routing = routing_block(Workflow::Worktree);
        let branches_routing = routing_block(Workflow::Branches);
        assert!(worktree_routing.contains("This project works in worktrees"));
        assert!(branches_routing.contains("Branches are worked in the main checkout"));
        for block in [&worktree_routing, &branches_routing] {
            assert!(block.contains("Create or remove a worktree"));
            assert!(block.contains("`rk worktree add <branch>`"));
            assert!(!block.contains("RK_WORKFLOW_LINE"), "{block}");
        }
        let differing: Vec<(&str, &str)> = worktree_routing
            .lines()
            .zip(branches_routing.lines())
            .filter(|(a, b)| a != b)
            .collect();
        assert_eq!(
            differing.len(),
            1,
            "exactly one routing line differs per mode: {differing:?}"
        );
    }

    /// One definition of an ill-formed hook file, for every reader: the
    /// well-formed shapes pass and each ambiguous shape names a defect.
    #[test]
    fn the_hook_marker_defects_are_named() {
        use super::hooks_marker_defect;
        let owned = hooks_block(Workflow::Branches);
        let block = owned.as_str();
        assert_eq!(hooks_marker_defect(""), None);
        assert_eq!(hooks_marker_defect(&format!("repos:\n{block}\n")), None);
        for (case, text) in [
            (
                "a second begin",
                format!("repos:\n{block}\n# BEGIN release-kit\n"),
            ),
            (
                "a second end",
                format!("repos:\n{block}\n# END release-kit\n"),
            ),
            (
                "an unpaired begin",
                "repos:\n# BEGIN release-kit\n".to_owned(),
            ),
            ("an unpaired end", "repos:\n# END release-kit\n".to_owned()),
            (
                "an end before its begin",
                "repos:\n# END release-kit\n# BEGIN release-kit\n".to_owned(),
            ),
        ] {
            assert!(
                hooks_marker_defect(&text).is_some(),
                "{case} must be a defect"
            );
        }
    }
}