Skip to content

The design language that makes your AI harness better at design.

JavaScript
26.9 KB
Raw Blame
//! JS: lib/staleness-deep.mjs (Tier 2, doctor only)

use crate::context::{extract_platform, TargetCandidate};
use crate::design_parser::parse_design_md;
use crate::jsp;
use crate::signals::git_run;
use crate::staleness::{check_native_platform_evidence, finding, js_truthy, to_relative, unique_roots, Finding};
use crate::util::{exists, js_trim, read_json, safe_read};
use once_cell::sync::Lazy;
use regex::Regex;
use serde_json::{Map, Value};

const VISUAL_SOURCE_DIRS: [&str; 7] = ["src", "app", "pages", "components", "site", "styles", "public"];
const LEGACY_LIVE_PATHS: [&str; 2] = [".impeccable-live.json", ".impeccable-live"];

fn git(args: &[&str], cwd: &str) -> Option<String> {
    git_run(args, cwd, true, Some(5000))
}

/// JS: checkDesignDrift
pub fn check_design_drift(design_path: Option<&str>, project_root: &str, threshold: usize) -> Vec<Finding> {
    let Some(design_path) = design_path else { return vec![] };
    if project_root.is_empty() {
        return vec![];
    }
    match git(&["rev-parse", "--is-inside-work-tree"], project_root) {
        Some(s) if !s.is_empty() => {}
        _ => return vec![],
    }
    let rel_design = to_relative(Some(design_path), project_root).unwrap();
    let last = match git(&["log", "-1", "--format=%H", "--", &rel_design], project_root) {
        Some(s) if !s.is_empty() => s,
        _ => return vec![],
    };
    let dirs: Vec<&str> = VISUAL_SOURCE_DIRS.iter().copied().filter(|d| exists(&jsp::join(&[project_root, d]))).collect();
    if dirs.is_empty() {
        return vec![];
    }
    let mut args: Vec<&str> = vec!["log", "--oneline"];
    let range = format!("{}..HEAD", last);
    args.push(&range);
    args.push("--");
    args.extend(dirs.iter());
    let Some(log) = git(&args, project_root) else { return vec![] };
    let commits = if log.is_empty() { 0 } else { log.split('\n').filter(|l| !l.is_empty()).count() };
    if commits < threshold {
        return vec![];
    }
    let when = git(&["log", "-1", "--format=%ad", "--date=short", "--", &rel_design], project_root).filter(|s| !s.is_empty());
    vec![finding(
        "design-md-drift",
        "DESIGN.md",
        Some(rel_design.clone()),
        "route",
        format!(
            "{} commits have touched {} since {} was last edited{}. This counts commits, not contradictions: it says the document is worth re-reading, not that it is wrong.",
            commits,
            dirs.join(", "),
            rel_design,
            when.map(|w| format!(" ({})", w)).unwrap_or_default()
        ),
        "Read DESIGN.md against the current tokens and components before trusting it as authority. If it has genuinely drifted, `document` regenerates it from the code.".to_string(),
    )]
}

fn has_coverage_value(v: Option<&Value>) -> bool {
    match v {
        None | Some(Value::Null) => false,
        Some(Value::Array(a)) => a.iter().any(|x| has_coverage_value(Some(x))),
        Some(Value::Object(o)) => o.values().any(|x| has_coverage_value(Some(x))),
        Some(Value::String(s)) => {
            let t = js_trim(s);
            if t.is_empty() {
                return false;
            }
            // /^(?:\[\s*\]|\{\s*\})$/
            let inner_empty = |open: char, close: char| -> bool {
                t.starts_with(open) && t.ends_with(close) && t.len() >= 2 && t[1..t.len() - 1].chars().all(|c| c.is_whitespace())
            };
            !(inner_empty('[', ']') || inner_empty('{', '}'))
        }
        _ => false,
    }
}

const SEED_MARKER_TAIL: &str = "impeccable document once there's code to capture the actual tokens and components. -->";

/// JS: checkDesignCoverage
pub fn check_design_coverage(design: Option<&str>, design_path: Option<&str>) -> Vec<Finding> {
    let Some(design) = design.filter(|d| !d.is_empty()) else { return vec![] };
    let model = parse_design_md(design);
    let is_seed = ["/", "$"].iter().any(|p| {
        design.contains(&format!("<!-- SEED: established with the user before implementation; re-run {}{}", p, SEED_MARKER_TAIL))
    });
    let required: Vec<&str> = if is_seed { vec!["colors", "typography"] } else { vec!["colors", "typography", "components"] };
    let missing: Vec<&str> = required
        .into_iter()
        .filter(|s| !model.has_section(s) && !has_coverage_value(model.frontmatter.as_ref().and_then(|f| f.get(*s))))
        .collect();
    if missing.is_empty() {
        return vec![];
    }
    vec![finding(
        "design-md-coverage",
        "DESIGN.md",
        design_path.map(|s| s.to_string()),
        "mention",
        format!(
            "{} has no {} section. Agents generating new screens get no normative guidance for those, and the live design panel renders generic approximations in their place.",
            design_path.filter(|p| !p.is_empty()).unwrap_or("DESIGN.md"),
            missing.join(", ")
        ),
        "Ask whether the section never applied or was never written. `document` fills it from the code if the project has the answer in its CSS.".to_string(),
    )]
}

fn wrap_ticks(items: &[String]) -> String {
    items.iter().map(|k| format!("`{}`", k)).collect::<Vec<_>>().join(", ")
}

/// JS String(x) for config list entries.
fn js_string(v: &Value) -> String {
    match v {
        Value::Null => "null".to_string(),
        Value::String(s) => s.clone(),
        other => crate::critique_storage::js_string_value(other),
    }
}

/// JS: checkDetectorIgnores
pub fn check_detector_ignores(project_root: &str, known_rule_ids: Option<&[String]>) -> Vec<Finding> {
    let mut out = Vec::new();
    if project_root.is_empty() {
        return out;
    }
    for name in ["config.json", "config.local.json"] {
        let fp = jsp::join(&[project_root, ".impeccable", name]);
        let Some(raw) = read_json(&fp) else { continue };
        let Some(detector) = raw.get("detector") else { continue };
        if !js_truthy(detector) || !(detector.is_object() || detector.is_array()) {
            continue;
        }
        let rel = to_relative(Some(&fp), project_root).unwrap();
        if let (Some(known), Some(rules)) = (known_rule_ids, detector.get("ignoreRules").and_then(|v| v.as_array())) {
            let unknown: Vec<String> = rules
                .iter()
                .map(|r| js_trim(&js_string_or_empty(r)).to_lowercase())
                .filter(|r| !r.is_empty() && r != "*" && !known.contains(r))
                .collect();
            if !unknown.is_empty() {
                out.push(finding(
                    "detector-ignore-rules-unknown",
                    "config.json",
                    Some(rel.clone()),
                    "mention",
                    format!(
                        "{} ignores rule id(s) the detector does not have: {}. Either the rule was renamed or removed, or the id was mistyped and has never suppressed anything.",
                        rel,
                        wrap_ticks(&unknown)
                    ),
                    "Report the exact ids. Removing them is safe; keeping a dead ignore hides that the rule is gone.".to_string(),
                ));
            }
        }
        if let Some(files) = detector.get("ignoreFiles").and_then(|v| v.as_array()) {
            let missing: Vec<String> = files
                .iter()
                .map(|e| js_trim(&js_string_or_empty(e)).to_string())
                .filter(|e| !e.is_empty() && !e.contains('*') && !exists(&jsp::join(&[project_root, e])))
                .collect();
            if !missing.is_empty() {
                out.push(finding(
                    "detector-ignore-files-missing",
                    "config.json",
                    Some(rel.clone()),
                    "mention",
                    format!("{} ignores file path(s) that no longer exist: {}.", rel, wrap_ticks(&missing)),
                    "Ask whether the file moved (repoint the entry) or was deleted (drop it). A stale entry silently stops covering the file that replaced it.".to_string(),
                ));
            }
        }
    }
    out
}

/// `String(rule || '')`
fn js_string_or_empty(v: &Value) -> String {
    if js_truthy(v) {
        js_string(v)
    } else {
        String::new()
    }
}

fn collect_hook_commands(v: &Value, out: &mut Vec<String>) {
    match v {
        Value::String(s) => {
            if crate::hook_markers::is_design_hook_command(s) {
                out.push(s.clone());
            }
        }
        Value::Array(a) => {
            for e in a {
                collect_hook_commands(e, out);
            }
        }
        Value::Object(o) => {
            for e in o.values() {
                collect_hook_commands(e, out);
            }
        }
        _ => {}
    }
}

static PLACEHOLDER: Lazy<Regex> = Lazy::new(|| Regex::new(r"\$\{[^}]*\}|\$[A-Za-z_]").unwrap());

/// The `.mjs` script (JS-era manifests) or the launcher (binary-era
/// manifests) a hook command runs; see `hook_markers`.
fn hook_script_token_from(command: &str) -> Option<String> {
    crate::hook_markers::hook_program_token(command)
}

fn resolve_hook_script_path(token: &str, root: &str) -> Option<String> {
    if token.is_empty() {
        return None;
    }
    if token.contains("$(") || token.contains('`') {
        return None;
    }
    let expanded = token.replace("${CLAUDE_PROJECT_DIR}", root);
    if PLACEHOLDER.is_match(&expanded) {
        return None;
    }
    Some(if jsp::is_absolute(&expanded) { expanded } else { jsp::join(&[root, &expanded]) })
}

/// JS: checkHookInstallation
pub fn check_hook_installation(
    project_root: &str,
    repo_root: Option<&str>,
    provider_id: &str,
    user_manifest: Option<&str>,
) -> Vec<Finding> {
    let mut out = Vec::new();
    let manifests = crate::context_cli::hook_manifests_for(provider_id);
    if manifests.is_empty() {
        return out;
    }
    let project_roots = unique_roots(project_root, repo_root);
    let mut entries: Vec<(&str, String, bool)> = Vec::new();
    for root in &project_roots {
        for rel in manifests {
            entries.push((root, jsp::join(&[root, rel]), false));
        }
    }
    if let Some(mp) = user_manifest {
        let mp = jsp::resolve(mp, &[]);
        if !entries.iter().any(|(_, existing, _)| *existing == mp) {
            entries.push((project_root, mp, true));
        }
    }
    let mut installed_at: Option<String> = None;
    for (root, mp, is_user) in &entries {
        let Some(raw) = read_json(mp) else { continue };
        let Some(hooks) = raw.get("hooks") else { continue };
        if !js_truthy(hooks) {
            continue;
        }
        let mut commands = Vec::new();
        collect_hook_commands(hooks, &mut commands);
        if commands.is_empty() {
            continue;
        }
        let base = if project_root.is_empty() { *root } else { project_root };
        installed_at = to_relative(Some(mp), base);
        let broken: Vec<&String> = commands
            .iter()
            .filter(|c| {
                let Some(token) = hook_script_token_from(c) else { return false };
                let Some(abs) = resolve_hook_script_path(&token, root) else { return false };
                !exists(&abs)
            })
            .collect();
        if provider_id == "cursor" && crate::hook_markers::cursor_manifest_has_retired_gate(&raw) {
            let ia = installed_at.clone().unwrap();
            out.push(finding(
                "cursor-hook-pre-edit-gate",
                "hook manifest",
                Some(ia.clone()),
                "auto",
                format!(
                    "{} still runs the design hook as Cursor's `preToolUse` write gate, which is retired. Cursor now runs it after each edit on `postToolUse` and hands the findings to the agent as context.",
                    ia
                ),
                "Move the entry to `postToolUse`: `impeccable doctor --fix`, `impeccable hooks on`, or the next `impeccable update` does it.".to_string(),
            ));
        }
        if !broken.is_empty() {
            let ia = installed_at.clone().unwrap();
            out.push(finding(
                "hook-script-missing",
                "hook manifest",
                Some(ia.clone()),
                "mention",
                format!(
                    "{} installs the design hook, but its script path does not exist: {}. The hook runs as a no-op, so UI edits have been going unscanned while the project looks covered.",
                    ia,
                    broken.iter().map(|c| format!("`{}`", c)).collect::<Vec<_>>().join(", ")
                ),
                // `update --user` rewrites only Claude's user manifest; other
                // providers get project hooks, and a launcher entry in their
                // home file is never repointed.
                if *is_user && provider_id == "claude-code" {
                    "Reinstall with `impeccable update --user`, which rewrites this user-level manifest against the skill's current location."
                } else if *is_user {
                    "Edit this user-level manifest by hand: point the command at the installed skill's launcher, or remove the Impeccable entry. `impeccable update --user` installs project hooks and does not repoint this file."
                } else {
                    "Reinstall with `impeccable hooks on`, which rewrites the manifest against the skill's current location."
                }
                .to_string(),
            ));
        }
    }
    if let Some(ia) = installed_at {
        for root in &project_roots {
            for name in ["config.json", "config.local.json"] {
                let cp = jsp::join(&[root, ".impeccable", name]);
                let Some(raw) = read_json(&cp) else { continue };
                let Some(hook) = raw.get("hook") else { continue };
                if js_truthy(hook) && hook.get("enabled") == Some(&Value::Bool(false)) {
                    let base = if project_root.is_empty() { root.as_str() } else { project_root };
                    out.push(finding(
                        "hook-enabled-conflict",
                        "config.json",
                        to_relative(Some(&cp), base),
                        "mention",
                        format!(
                            "{} installs the design hook while this config sets `hook.enabled: false`, so the hook fires and then declines to scan.",
                            ia
                        ),
                        "Ask which was intended: `impeccable hooks on` to enable, or `impeccable hooks off` to uninstall the manifest entry as well.".to_string(),
                    ));
                    return out;
                }
            }
        }
    }
    out
}

/// JS: checkLegacyLiveState
pub fn check_legacy_live_state(project_root: &str) -> Vec<Finding> {
    if project_root.is_empty() {
        return vec![];
    }
    let present: Vec<&str> = LEGACY_LIVE_PATHS.iter().copied().filter(|rel| exists(&jsp::join(&[project_root, rel]))).collect();
    if present.is_empty() {
        return vec![];
    }
    vec![finding(
        "legacy-live-state",
        "live state",
        Some(present.join(", ")),
        "auto",
        format!(
            "Live-mode state sits in retired location(s): {}. Current live mode writes under `.impeccable/live/`.",
            present.iter().map(|r| format!("`{}`", r)).collect::<Vec<_>>().join(", ")
        ),
        "These are read only through backward-compatible fallbacks and are safe to delete once no live session is running. No user decision is needed.".to_string(),
    )]
}

pub struct WorkspaceRow {
    pub name: String,
    pub path: String,
    pub product_status: &'static str,
    pub product_path: Option<String>,
    pub design_status: &'static str,
    pub design_path: Option<String>,
    pub platform: Option<String>,
}

impl WorkspaceRow {
    pub fn to_value(&self) -> Value {
        let mut m = Map::new();
        m.insert("name".into(), Value::String(self.name.clone()));
        m.insert("path".into(), Value::String(self.path.clone()));
        m.insert("productStatus".into(), Value::String(self.product_status.to_string()));
        m.insert("productPath".into(), self.product_path.clone().map(Value::String).unwrap_or(Value::Null));
        m.insert("designStatus".into(), Value::String(self.design_status.to_string()));
        m.insert("designPath".into(), self.design_path.clone().map(Value::String).unwrap_or(Value::Null));
        m.insert("platform".into(), self.platform.clone().map(Value::String).unwrap_or(Value::Null));
        Value::Object(m)
    }
}

/// JS: checkWorkspaces
pub fn check_workspaces(repo_root: &str, candidates: &[TargetCandidate]) -> (Vec<Finding>, Vec<WorkspaceRow>) {
    if repo_root.is_empty() || candidates.is_empty() {
        return (vec![], vec![]);
    }
    let mut findings = Vec::new();
    let mut workspaces = Vec::new();
    for c in candidates {
        let workspace_root = jsp::join(&[repo_root, &c.path]);
        let product_path = c.product_path.as_deref().map(|p| jsp::join(&[repo_root, p]));
        let product = product_path.as_deref().and_then(safe_read);
        let platform = extract_platform(product.as_deref());
        workspaces.push(WorkspaceRow {
            name: c.name.clone(),
            path: c.path.clone(),
            product_status: c.product_status,
            product_path: c.product_path.clone(),
            design_status: c.design_status,
            design_path: c.design_path.clone(),
            platform: platform.clone().or_else(|| {
                if product.as_deref().map(|p| !p.is_empty()).unwrap_or(false) {
                    Some("web (default)".to_string())
                } else {
                    None
                }
            }),
        });
        let native = check_native_platform_evidence(&workspace_root, platform.as_deref(), product.as_deref(), c.product_path.as_deref());
        for entry in native {
            let inherited = c.product_status == "inherited";
            findings.push(finding(
                "workspace-platform-native-evidence",
                "PRODUCT.md",
                Some(c.product_path.clone().unwrap_or_else(|| format!("{}/PRODUCT.md", c.path))),
                "mention",
                format!(
                    "Workspace `{}` {} that resolves to web, but the workspace itself carries native build files. {}",
                    c.path,
                    if inherited { "inherits the repo-root PRODUCT.md" } else { "has a PRODUCT.md" },
                    entry.summary
                ),
                if inherited {
                    format!(
                        "Give `{}` its own PRODUCT.md with the right `## Platform`. An inherited record cannot describe two platforms at once.",
                        c.path
                    )
                } else {
                    entry.fix
                },
            ));
        }
    }
    let inherited: Vec<&WorkspaceRow> = workspaces.iter().filter(|w| w.product_status == "inherited").collect();
    if !inherited.is_empty() {
        findings.push(finding(
            "workspace-context-inherited",
            "PRODUCT.md",
            None,
            "mention",
            format!(
                "{} of {} workspace(s) inherit the repo-root PRODUCT.md: {}. Inheritance is intended; whether one record truthfully describes these apps is not something this check can tell.",
                inherited.len(),
                workspaces.len(),
                inherited.iter().map(|w| format!("`{}`", w.path)).collect::<Vec<_>>().join(", ")
            ),
            "Ask the user whether the inherited record describes each app. Where it does not, `init` in that workspace writes a child PRODUCT.md that overrides it.".to_string(),
        ));
    }
    (findings, workspaces)
}

/// JS: loadKnownRuleIds -> the bundled registry, lowercased ids.
pub fn load_known_rule_ids() -> Option<Vec<String>> {
    Some(impeccable_core::registry::ANTIPATTERNS.iter().map(|r| r.id.to_lowercase()).collect())
}

#[cfg(test)]
mod tests {
    use super::check_hook_installation;

    static TMP_SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

    fn tmp() -> String {
        let base = std::env::temp_dir().join(format!(
            "impeccable-doctor-hook-{}-{}-{}",
            std::process::id(),
            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
            // A per-process counter: Windows' clock is coarse enough that two
            // parallel tests can share a nanosecond stamp and then delete each
            // other's directories.
            TMP_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
        ));
        std::fs::create_dir_all(&base).unwrap();
        // Like Node's `realpathSync`: on Windows, `canonicalize` yields a
        // `\\?\` verbatim path, which the kernel takes literally, so the `/`
        // separators a hook command appends would not resolve under it.
        let real = std::fs::canonicalize(&base).unwrap().to_string_lossy().into_owned();
        real.strip_prefix(r"\\?\").map(str::to_string).unwrap_or(real)
    }

    fn write(root: &str, rel: &str, body: &str) {
        let p = std::path::Path::new(root).join(rel);
        std::fs::create_dir_all(p.parent().unwrap()).unwrap();
        std::fs::write(p, body).unwrap();
    }

    #[test]
    fn hook_script_missing_resolves_launcher_and_legacy_forms() {
        let root = tmp();
        // Launcher form pointing at a launcher that exists: no finding.
        write(&root, ".claude/skills/impeccable/scripts/impeccable", "#!/bin/sh\n");
        write(
            &root,
            ".claude/settings.local.json",
            r#"{"hooks":{"PostToolUse":[{"hooks":[{"type":"command","command":"\"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable\" hook"}]}]}}"#,
        );
        assert!(check_hook_installation(&root, None, "claude-code", None).is_empty());

        // Launcher form pointing at a missing launcher: reported.
        write(
            &root,
            ".claude/settings.local.json",
            r#"{"hooks":{"PostToolUse":[{"hooks":[{"type":"command","command":"\"${CLAUDE_PROJECT_DIR}/.other/skills/impeccable/scripts/impeccable\" hook"}]}]}}"#,
        );
        let f = check_hook_installation(&root, None, "claude-code", None);
        assert_eq!(f.len(), 1, "{f:?}");
        assert_eq!(f[0].id, "hook-script-missing");

        // Legacy .mjs form is still resolved: reported when the script is gone.
        write(
            &root,
            ".claude/settings.local.json",
            r#"{"hooks":{"PostToolUse":[{"hooks":[{"type":"command","command":"node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\""}]}]}}"#,
        );
        let f = check_hook_installation(&root, None, "claude-code", None);
        assert_eq!(f.len(), 1, "{f:?}");
        write(&root, ".claude/skills/impeccable/scripts/hook.mjs", "");
        assert!(check_hook_installation(&root, None, "claude-code", None).is_empty());
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn cursor_gate_is_an_auto_finding_and_the_post_edit_hook_is_not() {
        let root = tmp();
        write(&root, ".cursor/skills/impeccable/scripts/impeccable", "#!/bin/sh\n");
        write(&root, ".cursor/hooks.json", r#"{"version":1,"hooks":{"preToolUse":[{"command":"\".cursor/skills/impeccable/scripts/impeccable\" hook-before-edit","timeout":5}]}}"#);
        let f = check_hook_installation(&root, None, "cursor", None);
        assert_eq!(f.len(), 1, "{:?}", f.iter().map(|x| &x.id).collect::<Vec<_>>());
        assert_eq!(f[0].id, "cursor-hook-pre-edit-gate");
        assert_eq!(f[0].severity, "auto");
        write(&root, ".cursor/hooks.json", r#"{"version":1,"hooks":{"postToolUse":[{"command":"\".cursor/skills/impeccable/scripts/impeccable\" hook","matcher":"^Write$","timeout":5}]}}"#);
        assert!(check_hook_installation(&root, None, "cursor", None).is_empty());
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn user_scope_claude_hook_is_checked_from_home() {
        let root = tmp();
        let project = crate::jsp::join(&[&root, "project"]);
        let home = crate::jsp::join(&[&root, "home"]);
        std::fs::create_dir_all(&project).unwrap();
        let launcher = crate::jsp::join(&[
            &home,
            ".claude",
            "skills",
            "impeccable",
            "scripts",
            "impeccable",
        ]);
        let manifest = crate::jsp::join(&[&home, ".claude", "settings.json"]);
        write(&home, ".claude/skills/impeccable/scripts/impeccable", "#!/bin/sh\n");
        write(
            &home,
            ".claude/settings.json",
            &serde_json::json!({
                "hooks": {
                    "PostToolUse": [{
                        "hooks": [{
                            "type": "command",
                            "command": format!("\"{launcher}\" hook"),
                        }],
                    }],
                },
            })
            .to_string(),
        );
        write(
            &home,
            ".claude/settings.local.json",
            r#"{"hooks":{"PostToolUse":[{"hooks":[{"type":"command","command":"\"/missing/user-local/impeccable\" hook"}]}]}}"#,
        );
        assert!(check_hook_installation(&project, None, "claude-code", Some(&manifest)).is_empty());

        std::fs::remove_file(&launcher).unwrap();
        let findings = check_hook_installation(&project, None, "claude-code", Some(&manifest));
        assert_eq!(findings.len(), 1, "{findings:?}");
        assert_eq!(findings[0].id, "hook-script-missing");
        assert!(findings[0].fix.starts_with("Reinstall with `impeccable update --user`"), "{:?}", findings[0].fix);
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn user_scope_codex_hook_is_checked_from_codex_home() {
        let root = tmp();
        let project = crate::jsp::join(&[&root, "project"]);
        let home = crate::jsp::join(&[&root, "home"]);
        std::fs::create_dir_all(&project).unwrap();
        let launcher = crate::jsp::join(&[&home, ".agents", "skills", "impeccable", "scripts", "impeccable"]);
        let manifest = crate::jsp::join(&[&root, "codex-home", "hooks.json"]);
        write(&home, ".agents/skills/impeccable/scripts/impeccable", "#!/bin/sh\n");
        write(
            &root,
            "codex-home/hooks.json",
            &serde_json::json!({
                "hooks": {
                    "Stop": [{
                        "hooks": [{
                            "type": "command",
                            "command": format!("[ ! -f '{launcher}' ] || '{launcher}' hook"),
                        }],
                    }],
                },
            })
            .to_string(),
        );
        assert!(check_hook_installation(&project, None, "codex", Some(&manifest)).is_empty());

        std::fs::remove_file(&launcher).unwrap();
        let findings = check_hook_installation(&project, None, "codex", Some(&manifest));
        assert_eq!(findings.len(), 1, "{findings:?}");
        assert_eq!(findings[0].id, "hook-script-missing");
        assert!(findings[0].fix.contains("by hand"), "{:?}", findings[0].fix);
        let _ = std::fs::remove_dir_all(&root);
    }
}