iris: the lint over a portal site, as its own repo

question_lint becomes `iris check`, needs_replay becomes `iris
replay`, and the needs module and local-checkout loaders come with
them. Portal is a library dependency pinned to the release iris
matches (v0.3.36), so every type iris reads is the site's own and the
two never disagree about what a page is. `iris --path questions`
still works, so a content repo's one-line CI needs only a new path.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L4jrCgLiKKHAEFuZUJjckH

src/check.rs

@@ -0,0 +1,225 @@
+//! Headless schema-check binary - loads content and `aggregates.yaml`
+//! (from a Gitea repo URL or a local directory) and validates them
+//! exactly the way `content::watch_for_reload`/`main.rs`'s boot path
+//! do, with no NATS, OIDC, web server, or JetStream connection
+//! involved. Built once by portal's own deploy workflow and run
+//! directly by `questions`' own CI (same bare-metal runner/host,
+//! published to a stable path - no artifact download needed), rather
+//! than compiled there - keeps that repo's CI coupling to "run a
+//! static binary," not "build a Rust workspace."
+
+use crate::local::{load_aggregates_from_dir, load_from_dir, load_needs_from_dir, load_site_from_dir};
+use crate::needs;
+use portal::{aggregates, content};
+
+pub async fn run(argv: Vec<String>) -> anyhow::Result<()> {
+    let mut args = argv.into_iter();
+    let mut repo: Option<String> = None;
+    let mut branch = "main".to_string();
+    let mut subdir = "questions".to_string();
+    let mut path: Option<String> = None;
+    let mut tasks_out: Option<String> = None;
+    let mut answers_in: Option<String> = None;
+    let mut min_accuracy: f64 = 0.0;
+    let mut skim = false;
+    let mut sim_out: Option<String> = None;
+
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--repo" => repo = args.next(),
+            "--branch" => branch = args.next().unwrap_or(branch),
+            "--subdir" => subdir = args.next().unwrap_or(subdir),
+            "--path" => path = args.next(),
+            "--needs-tasks" => tasks_out = args.next(),
+            "--skim" => skim = true,
+            "--needs-sim" => sim_out = args.next(),
+            "--needs-score" => answers_in = args.next(),
+            "--min-accuracy" => {
+                min_accuracy = args.next().and_then(|v| v.parse().ok()).unwrap_or(min_accuracy)
+            }
+            other => {
+                eprintln!("unknown argument: {other}");
+                std::process::exit(2);
+            }
+        }
+    }
+
+    let (questions, aggregates_map, site, needs_raw) = if let Some(dir) = path {
+        (
+            load_from_dir(&dir)?,
+            load_aggregates_from_dir(&dir)?,
+            load_site_from_dir(&dir)?,
+            load_needs_from_dir(&dir)?,
+        )
+    } else if let Some(repo_url) = repo {
+        let questions = content::load_questions_from_gitea(&repo_url, &branch, &subdir).await?;
+        let aggregates_map = content::load_aggregates_from_gitea(&repo_url, &branch).await?;
+        // load_site_from_gitea already validates; a missing file is
+        // the default config, same as at portal boot.
+        let site = content::load_site_from_gitea(&repo_url, &branch).await?;
+        let needs_raw = content::load_needs_from_gitea(&repo_url, &branch).await?;
+        (questions, aggregates_map, site, needs_raw)
+    } else {
+        eprintln!(
+            "usage: iris check (--repo <gitea-url> [--branch main] [--subdir questions] | --path <local-dir>) [--needs-tasks <out.jsonl> [--skim]] [--needs-sim <model.json>] [--needs-score <answers.jsonl> [--min-accuracy 0.8]]"
+        );
+        std::process::exit(2);
+    };
+
+    if let Err(e) = site.validate() {
+        eprintln!("FAIL: {e}");
+        std::process::exit(1);
+    }
+    let aggregates_map = content::with_builtin_aggregates(aggregates_map);
+    match content::validate_questions(&questions, &aggregates_map) {
+        Ok(()) => {
+            // The runtime's own event desk: a repo announcing pages
+            // (Question.event) should read portal_events somewhere, or
+            // "post what happened" tasks pile up unseen. Warn, don't
+            // fail - the runtime creates the records either way.
+            if questions.values().any(|q| q.event.is_some())
+                && !content::bucket_is_read(&questions, content::EVENTS_BUCKET)
+            {
+                eprintln!(
+                    "WARN: pages carry `event:` but no kv resource reads bucket {:?} - add a desk so summaries get posted",
+                    content::EVENTS_BUCKET
+                );
+            }
+            println!(
+                "OK: {} question(s), {} aggregate(s) valid",
+                questions.len(),
+                aggregates_map.len()
+            );
+            check_needs(
+                needs_raw.as_deref(),
+                &questions,
+                &aggregates_map,
+                tasks_out.as_deref(),
+                skim,
+                sim_out.as_deref(),
+                answers_in.as_deref(),
+                min_accuracy,
+            )
+        }
+        Err(e) => {
+            eprintln!("FAIL: {e}");
+            std::process::exit(1);
+        }
+    }
+}
+
+/// The business-needs pass (see `portal::needs`): structure always,
+/// then the wording tasks written out and/or an engine's answers
+/// scored, when asked. A repo without `needs.yaml` skips all of it.
+fn check_needs(
+    raw: Option<&str>,
+    questions: &std::collections::HashMap<String, content::Question>,
+    aggregates_map: &std::collections::HashMap<String, aggregates::AggregateSchema>,
+    tasks_out: Option<&str>,
+    skim: bool,
+    sim_out: Option<&str>,
+    answers_in: Option<&str>,
+    min_accuracy: f64,
+) -> anyhow::Result<()> {
+    let Some(raw) = raw else {
+        if tasks_out.is_some() || answers_in.is_some() {
+            eprintln!("FAIL: --needs-tasks/--needs-score given, but the repo has no needs.yaml");
+            std::process::exit(1);
+        }
+        return Ok(());
+    };
+    let file = match needs::parse(raw) {
+        Ok(file) => file,
+        Err(e) => {
+            eprintln!("FAIL: {e}");
+            std::process::exit(1);
+        }
+    };
+    let findings = needs::check(&file, questions, aggregates_map);
+    let mut failed = 0;
+    for finding in &findings {
+        let level = match finding.level {
+            needs::Level::Fail => {
+                failed += 1;
+                "FAIL"
+            }
+            needs::Level::Warn => "WARN",
+        };
+        eprintln!("{level}: need {:?}: {}", finding.need, finding.message);
+    }
+    for need in &file.needs {
+        if let Some(path) = needs::path_for(questions, need) {
+            let steps: Vec<String> = path
+                .iter()
+                .map(|s| format!("{} [{}]", s.page, s.alternative))
+                .collect();
+            println!("need {:?}: {} -> {:?}", need.id, steps.join(" -> "), need.lands_in);
+        }
+    }
+    if failed == 0 {
+        let planned = file.needs.iter().filter(|n| n.planned).count();
+        println!(
+            "OK: {} need(s) structurally met, {} planned, {} persona(s)",
+            file.needs.len() - planned,
+            planned,
+            file.personas.len()
+        );
+    }
+    // The wording pass still runs for the needs that do have a path -
+    // a closed flow elsewhere is no reason to stop grading the rest.
+
+    if let Some(out) = sim_out {
+        let model = needs::sim_model(&file, questions, aggregates_map);
+        std::fs::write(out, serde_json::to_string_pretty(&model)?)
+            .map_err(|e| anyhow::anyhow!("writing {out}: {e}"))?;
+        println!("wrote the simulation model to {out}");
+    }
+    let tasks = needs::tasks(&file, questions, skim);
+    if let Some(out) = tasks_out {
+        let mut lines = String::new();
+        for task in &tasks {
+            lines.push_str(&serde_json::to_string(task)?);
+            lines.push('\n');
+        }
+        std::fs::write(out, lines).map_err(|e| anyhow::anyhow!("writing {out}: {e}"))?;
+        println!("wrote {} wording task(s) to {out}", tasks.len());
+    }
+    if let Some(path) = answers_in {
+        let raw = std::fs::read_to_string(path).map_err(|e| anyhow::anyhow!("reading {path}: {e}"))?;
+        let mut answers = Vec::new();
+        for (n, line) in raw.lines().enumerate().filter(|(_, l)| !l.trim().is_empty()) {
+            answers.push(
+                serde_json::from_str::<needs::Answer>(line)
+                    .map_err(|e| anyhow::anyhow!("{path}:{}: {e}", n + 1))?,
+            );
+        }
+        let score = needs::score(&tasks, &answers, 0.6);
+        for (id, picked, expected, confidence) in &score.misroutes {
+            eprintln!(
+                "MISROUTE: {id}: picked {picked:?}{}, the need is met by {expected:?}",
+                confidence.map(|c| format!(" ({c:.2})")).unwrap_or_default()
+            );
+        }
+        for (id, confidence) in &score.hesitant {
+            eprintln!("HESITANT: {id}: right, at {confidence:.2}");
+        }
+        for id in &score.unanswered {
+            eprintln!("UNANSWERED: {id}");
+        }
+        println!(
+            "wording: {}/{} routed right ({:.0}%)",
+            score.correct,
+            score.total,
+            score.accuracy() * 100.0
+        );
+        if score.accuracy() < min_accuracy {
+            eprintln!("FAIL: below --min-accuracy {min_accuracy}");
+            std::process::exit(1);
+        }
+    }
+    if failed > 0 {
+        eprintln!("FAIL: {failed} unmet business need finding(s)");
+        std::process::exit(1);
+    }
+    Ok(())
+}