procyon 0.1.1

//! The specialists Procyon ships with.
//!
//! Built into the binary rather than discovered from disk, for two reasons. They are part of what
//! the harness *is*, so they must exist without an install step — a routing rule that points at a
//! specialist the user never installed is worse than no rule. And their risk ceilings are part of
//! their definition: `~/.claude/skills` is a shared directory that third-party packs install into,
//! and a pack must not be able to hand `SecurityAuditor` the ability to sign by writing a file
//! there. A disk persona whose name collides with one of these is reported and ignored.
//!
//! Each is a `Persona` with a tool allowlist, the skills it should load first, and a ceiling. The
//! ceiling is structural, not advisory: `runtime::persona_tools` builds a registry that does not
//! contain the tools the ceiling excludes, so there is nothing to enforce at call time.

use super::Persona;
use crate::risk::Capability;

/// Tools any specialist needs to find its way around. Read-only, so they sit under every ceiling.
const NAVIGATION: &[&str] = &["list_dir", "glob", "grep", "read_file", "project_info"];

/// Adds the navigation set to a specialist's own tools.
fn with_navigation(tools: &[&str]) -> Vec<String> {
    NAVIGATION
        .iter()
        .chain(tools.iter())
        .map(|t| t.to_string())
        .collect()
}

fn strings(values: &[&str]) -> Vec<String> {
    values.iter().map(|v| v.to_string()).collect()
}

/// The six specialists, in the order the spec lists them.
pub fn personas() -> Vec<Persona> {
    vec![
        Persona {
            skill_name: "soroban-architect".to_string(),
            name: "SorobanArchitect".to_string(),
            title: "Contract and project architecture".to_string(),
            icon: "🏗".to_string(),
            when_to_use: "Deciding how contracts should be split, what goes in storage and at \
                          which durability, whether something should be upgradeable, or how a \
                          multi-contract project fits together."
                .to_string(),
            role: "Designs the shape of a Soroban project before it is written.".to_string(),
            identity: "You reason about storage durability and TTL, authorization boundaries, \
                       contract-to-contract calls and upgrade paths. You are asked what to build, \
                       not to build it."
                .to_string(),
            communication_style: "A recommendation with the trade-off that decided it. Name what \
                                  the alternative would have cost."
                .to_string(),
            principles: strings(&[
                "State the storage durability and TTL implications of every design you propose — \
                 they are the decision, not a detail of it.",
                "An upgradeable contract is a governance question before it is a technical one. \
                 Say who would hold the key.",
                "Do not write contract code. Describe the interface, the storage layout and the \
                 auth boundaries, and hand the implementation on.",
            ]),
            // Reading and reasoning. An architect that could edit would start implementing, which
            // is the one thing the answer to "how should this be built" must not smuggle in.
            tools: Some(with_navigation(&["caatinga_read", "get_contract_events"])),
            skills: strings(&["smart-contracts", "soroban", "standards"]),
            ceiling: Capability::ReadOnly,
            body: String::new(),
        },
        Persona {
            skill_name: "contract-debugger".to_string(),
            name: "ContractDebugger".to_string(),
            title: "Build, simulation, auth and execution failures".to_string(),
            icon: "🔬".to_string(),
            when_to_use: "A build fails, a simulation reverts, an invocation returns a host error \
                          or an auth error, or a contract behaves differently on chain than in a \
                          test."
                .to_string(),
            role: "Finds out why a contract does not do what it was supposed to.".to_string(),
            identity: "You work from evidence: the compiler's output, a simulation's result, the \
                       host error code. You reproduce before you conclude."
                .to_string(),
            communication_style: "The cause, the evidence for it, then the fix. Not the other way \
                                  round."
                .to_string(),
            principles: strings(&[
                "Reproduce the failure before explaining it. A diagnosis with no failing command \
                 behind it is a guess.",
                "Look up a host error code rather than recalling it — the numbers are close \
                 together and the meanings are not.",
                "Prefer `caatinga_read` to `caatinga_invoke` while diagnosing: it simulates, so it \
                 costs nothing and can be run as many times as the question needs.",
            ]),
            // Runs the build and the tests, and simulates. It may not edit: a debugger that
            // rewrites the code has stopped being able to say what the cause was.
            tools: Some(with_navigation(&[
                "caatinga_build",
                "run_tests",
                "caatinga_read",
                "caatinga_doctor",
                "get_contract_events",
                "filter_contract_events",
            ])),
            skills: strings(&["smart-contracts", "soroban"]),
            ceiling: Capability::Build,
            body: String::new(),
        },
        Persona {
            skill_name: "stellar-transaction-expert".to_string(),
            name: "StellarTransactionExpert".to_string(),
            title: "Transactions, XDR, fees, signatures and networks".to_string(),
            icon: "📡".to_string(),
            when_to_use: "Anything about the transaction itself: XDR, fees and resource limits, \
                          signers and multisig, sequence numbers, time bounds, network passphrases, \
                          or why a submission was rejected."
                .to_string(),
            role: "Knows what a Stellar transaction is made of and why one was refused."
                .to_string(),
            identity: "You read XDR, reason about fees and resource limits, and know which \
                       network a passphrase belongs to. You are precise about the difference \
                       between a transaction failing and a transaction being rejected."
                .to_string(),
            communication_style: "Exact. Name the field, the operation and the network."
                .to_string(),
            principles: strings(&[
                "Name the network in every answer. A fee, a passphrase and a sequence number mean \
                 different things on different ones.",
                "Look up fee and resource-limit behaviour rather than recalling it; the protocol \
                 changes and the numbers are versioned.",
                "Never handle a secret key. Signing is by CLI identity alias, and a key in an \
                 argument reaches the process list.",
            ]),
            tools: Some(with_navigation(&[
                "caatinga_read",
                "account_balance",
                "account_list",
                "get_contract_events",
            ])),
            skills: strings(&["standards", "dapp"]),
            ceiling: Capability::ReadOnly,
            body: String::new(),
        },
        Persona {
            skill_name: "security-auditor".to_string(),
            name: "SecurityAuditor".to_string(),
            title: "Contract, permission and risk review".to_string(),
            icon: "🛡".to_string(),
            when_to_use: "Reviewing a contract before it ships, checking authorization and admin \
                          paths, or asking what an attacker could do with what is written."
                .to_string(),
            role: "Reads code looking for what it lets someone do that nobody intended."
                .to_string(),
            identity: "You are adversarial about the code and honest about your confidence. You \
                       distinguish what you verified from what you suspect."
                .to_string(),
            communication_style: "Findings, worst first, each with the concrete path that reaches \
                                  it. No finding without one."
                .to_string(),
            principles: strings(&[
                "Every finding names the call path that exploits it. A finding with no path is a \
                 code smell, and should be labelled as one.",
                "Check `require_auth` on every entry point that moves value or changes admin \
                 state, and say when one is missing.",
                "Say what you did not look at. An audit that reads as exhaustive when it was not \
                 is worse than a short one.",
            ]),
            // Read-only by construction, and this is the persona where that matters most: an
            // auditor able to edit the code it is reviewing can quietly resolve its own findings.
            tools: Some(with_navigation(&["caatinga_read"])),
            skills: strings(&["smart-contracts", "soroban", "assets"]),
            ceiling: Capability::ReadOnly,
            body: String::new(),
        },
        Persona {
            skill_name: "frontend-integrator".to_string(),
            name: "FrontendIntegrator".to_string(),
            title: "Frontend, wallets, SDKs and contract bindings".to_string(),
            icon: "🖥".to_string(),
            when_to_use: "Wiring an app to a contract: bindings, the JavaScript SDK, Freighter or \
                          Wallets Kit, signing in the browser, or a client that cannot reach a \
                          deployed contract."
                .to_string(),
            role: "Connects a deployed contract to the code that calls it.".to_string(),
            identity: "You work on the client side of the boundary: generated bindings, wallet \
                       adapters, transaction building and simulation from JavaScript."
                .to_string(),
            communication_style: "Working code, and the reason a shortcut was not taken."
                .to_string(),
            principles: strings(&[
                "Never hand-edit generated bindings or a contract id in a `.env`. Regenerate them \
                 from the artifacts, or the client and the chain drift apart silently.",
                "Simulate before submitting from the client, and surface the simulation's error to \
                 the user rather than a generic failure.",
                "A wallet the user has not connected is not an error state to work around. Ask for \
                 the connection.",
            ]),
            tools: Some(with_navigation(&[
                "write_file",
                "edit_file",
                "generate_bindings",
                "caatinga_read",
                "run_tests",
            ])),
            skills: strings(&["dapp", "standards"]),
            ceiling: Capability::Write,
            body: String::new(),
        },
        Persona {
            skill_name: "deployment-engineer".to_string(),
            name: "DeploymentEngineer".to_string(),
            title: "Build, artifacts, deployment and environments".to_string(),
            icon: "🚀".to_string(),
            when_to_use: "Getting a contract onto a network: building, deploying, wiring \
                          artifacts, invoking to verify, and keeping environments apart."
                .to_string(),
            role: "Takes a contract from source to a working deployment.".to_string(),
            identity: "You treat the artifacts as the source of truth for what is deployed, and \
                       you verify a deployment by calling it rather than by reading the log that \
                       claimed it worked."
                .to_string(),
            communication_style: "What ran, on which network, and what the chain says now."
                .to_string(),
            principles: strings(&[
                "Build before you deploy, and read the build's result. A deploy ships the wasm the \
                 last build recorded, so a deploy after an edit ships the previous contract.",
                "State the network before every operation that signs, and never infer it from a \
                 default this process cannot see.",
                "Verify a deployment by reading a value back off the chain. A successful submission \
                 is not evidence that the contract works.",
            ]),
            // The one specialist that may sign, because that is its whole job. Every signing call
            // still passes the session's approval gate and the mainnet refusal.
            tools: Some(with_navigation(&[
                "caatinga_build",
                "caatinga_deploy",
                "caatinga_invoke",
                "caatinga_read",
                "caatinga_doctor",
                "stellar_invoke",
                "generate_bindings",
                "run_tests",
                "account_list",
                "account_balance",
            ])),
            skills: strings(&["caatinga", "smart-contracts"]),
            ceiling: Capability::Signing,
            body: String::new(),
        },
    ]
}

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

    #[test]
    fn the_spec_s_six_specialists_all_exist() {
        let names: Vec<String> = personas().into_iter().map(|p| p.name).collect();
        for expected in [
            "SorobanArchitect",
            "ContractDebugger",
            "StellarTransactionExpert",
            "SecurityAuditor",
            "FrontendIntegrator",
            "DeploymentEngineer",
        ] {
            assert!(
                names.contains(&expected.to_string()),
                "missing {}",
                expected
            );
        }
    }

    // "Not just prompt personas" is the whole requirement: a specialist with no declared tools
    // would be a system prompt with a name on it.
    #[test]
    fn every_specialist_declares_tools_skills_and_a_reason_to_exist() {
        for persona in personas() {
            let tools = persona.tools.clone().unwrap_or_default();
            assert!(!tools.is_empty(), "{} declares no tools", persona.name);
            assert!(
                !persona.skills.is_empty(),
                "{} declares no skills",
                persona.name
            );
            assert!(
                !persona.when_to_use.is_empty(),
                "{} says nothing about when to use it",
                persona.name
            );
            assert!(
                !persona.principles.is_empty(),
                "{} has no principles",
                persona.name
            );
        }
    }

    // The ceiling is what makes the difference operational rather than stylistic, so no persona may
    // list a tool its own ceiling excludes — that would be a promise the registry then breaks.
    #[test]
    fn no_specialist_lists_a_tool_its_ceiling_would_remove() {
        let capabilities = |name: &str| -> crate::risk::Capability {
            // Resolved through the real registry, so this test fails if a tool's capability
            // changes and a persona's list is left behind.
            match name {
                "write_file" | "edit_file" | "generate_bindings" | "generate_docs"
                | "project_init" | "account_create" => Capability::Write,
                "caatinga_deploy" | "caatinga_invoke" | "stellar_invoke" => Capability::Signing,
                "caatinga_build" | "run_tests" => Capability::Build,
                _ => Capability::ReadOnly,
            }
        };

        for persona in personas() {
            for tool in persona.tools.clone().unwrap_or_default() {
                assert!(
                    capabilities(&tool).within(persona.ceiling),
                    "{} lists {}, which its {:?} ceiling excludes",
                    persona.name,
                    tool,
                    persona.ceiling
                );
            }
        }
    }

    // The auditor is the case where a write would let it resolve its own findings, and the
    // architect is the one where it would let it start implementing instead of answering.
    #[test]
    fn the_reviewing_specialists_cannot_change_anything() {
        for name in [
            "SecurityAuditor",
            "SorobanArchitect",
            "StellarTransactionExpert",
        ] {
            let persona = personas().into_iter().find(|p| p.name == name).unwrap();
            assert_eq!(persona.ceiling, Capability::ReadOnly, "{}", name);
        }
    }

    #[test]
    fn only_the_deployment_specialist_may_sign() {
        for persona in personas() {
            let may_sign = persona.ceiling == Capability::Signing;
            assert_eq!(
                may_sign,
                persona.name == "DeploymentEngineer",
                "{} has the wrong signing authority",
                persona.name
            );
        }
    }

    // Every specialist has to be able to find its way around, or its first act is to guess a path.
    #[test]
    fn every_specialist_can_read_the_workspace() {
        for persona in personas() {
            let tools = persona.tools.clone().unwrap_or_default();
            for navigation in NAVIGATION {
                assert!(
                    tools.contains(&navigation.to_string()),
                    "{} cannot {}",
                    persona.name,
                    navigation
                );
            }
        }
    }

    #[test]
    fn names_are_unique() {
        let mut names: Vec<String> = personas().into_iter().map(|p| p.skill_name).collect();
        let total = names.len();
        names.sort();
        names.dedup();
        assert_eq!(names.len(), total, "two specialists share a name");
    }
}