feat: project-level performance review (loopx Loop Engineering principle 7)

crates/agentflare-backend/src/ask_event.rs

@@ -0,0 +1,124 @@
+use crate::error::Result;
+use rusqlite::{Connection, params};
+
+/// One "the supervisor asked a human" occurrence — the persisted counterpart
+/// of `quota::decide::Decision::ask()`, which itself never writes anything
+/// (it's pure). Recorded so attention cost stops being an ephemeral side
+/// effect of a lifecycle flip and becomes queryable for performance review.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct AskEvent {
+    pub id: String,
+    pub project_id: String,
+    pub goal_item_id: Option<String>,
+    pub item_id: String,
+    pub agent: Option<String>,
+    pub reason: String,
+    pub gate_question: Option<String>,
+    pub created_at: i64,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn record(
+    conn: &Connection,
+    project_id: &str,
+    goal_item_id: Option<&str>,
+    item_id: &str,
+    agent: Option<&str>,
+    reason: &str,
+    gate_question: Option<&str>,
+    now: i64,
+) -> Result<String> {
+    let id = db_kit::ids::new_id();
+    conn.execute(
+        "INSERT INTO ask_events
+             (id, project_id, goal_item_id, item_id, agent, reason, gate_question, created_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+        params![
+            id,
+            project_id,
+            goal_item_id,
+            item_id,
+            agent,
+            reason,
+            gate_question,
+            now
+        ],
+    )?;
+    Ok(id)
+}
+
+pub fn count_since(
+    conn: &Connection,
+    project_id: &str,
+    agent: Option<&str>,
+    since: i64,
+) -> Result<i64> {
+    Ok(conn.query_row(
+        "SELECT COUNT(*) FROM ask_events
+         WHERE project_id = ?1 AND created_at >= ?2 AND (?3 IS NULL OR agent = ?3)",
+        params![project_id, since, agent],
+        |r| r.get(0),
+    )?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn seed_project(conn: &Connection) -> String {
+        let workspace = crate::workspace::create(
+            conn,
+            crate::workspace::CreateWorkspace {
+                name: "ws".into(),
+                slug: "ws".into(),
+                owner_agent: None,
+                item_label: None,
+            },
+        )
+        .unwrap();
+        let project = crate::project::create(
+            conn,
+            crate::project::CreateProject {
+                workspace_id: workspace.id,
+                name: "proj".into(),
+                identifier: "proj".into(),
+                external_source: None,
+                external_id: None,
+            },
+        )
+        .unwrap();
+        project.id
+    }
+
+    #[test]
+    fn record_then_count_since_scopes_by_project_and_agent() {
+        let conn = crate::db::open_in_memory().unwrap();
+        let pid = seed_project(&conn);
+        record(
+            &conn,
+            &pid,
+            None,
+            "item-1",
+            Some("claude-code"),
+            "gated",
+            Some("q?"),
+            100,
+        )
+        .unwrap();
+        record(
+            &conn,
+            &pid,
+            None,
+            "item-2",
+            Some("opencode"),
+            "gated",
+            None,
+            200,
+        )
+        .unwrap();
+
+        assert_eq!(count_since(&conn, &pid, None, 0).unwrap(), 2);
+        assert_eq!(count_since(&conn, &pid, Some("claude-code"), 0).unwrap(), 1);
+        assert_eq!(count_since(&conn, &pid, None, 150).unwrap(), 1);
+    }
+}

crates/agentflare-backend/src/db.rs

@@ -15,6 +15,7 @@ const MIGRATION_LIST: &[M<'static>] = &[
     M::up(include_str!("migrations/0004_item_comments.sql")),
     M::up(include_str!("migrations/0005_items_fts.sql")),
     M::up(include_str!("migrations/0006_vents.sql")),
+    M::up(include_str!("migrations/0007_ask_events.sql")),
 ];
 const MIGRATIONS: Migrations = Migrations::from_slice(MIGRATION_LIST);
 

crates/agentflare-backend/src/lib.rs

@@ -1,3 +1,4 @@
+pub mod ask_event;
 pub mod asset;
 pub mod claim;
 pub mod comment;

crates/agentflare-backend/src/migrations/0007_ask_events.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS ask_events (
+  id            TEXT PRIMARY KEY,
+  project_id    TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  goal_item_id  TEXT REFERENCES items(id) ON DELETE SET NULL,
+  item_id       TEXT NOT NULL,
+  agent         TEXT,
+  reason        TEXT NOT NULL,
+  gate_question TEXT,
+  created_at    INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ask_events_project_created ON ask_events(project_id, created_at);

src/cli/review.rs

@@ -78,6 +78,29 @@ pub enum ReviewAction {
         #[arg(long)]
         json: bool,
     },
+    /// Compute one agent's project-level performance review (quantity,
+    /// quality, cost, attention) and save it to the memory store as a
+    /// `performance_review` observation. Run `agentflare memory sync`
+    /// afterward to share it with other workstations.
+    Performance {
+        /// Backend project id (agentflare item-tracker project — run
+        /// `agentflare memory observations` or check the dashboard to find
+        /// it; this is NOT the same identifier as --repo).
+        #[arg(long)]
+        project: String,
+        /// Agent name (default: detected, same convention as `submit`).
+        #[arg(long)]
+        agent: Option<String>,
+        /// Scope quality scoring to one repo (default: current repo).
+        #[arg(long)]
+        repo: Option<String>,
+        /// Window size in days ending now, for quantity/attention/cost
+        /// (quality is always all-time — see `scores`).
+        #[arg(long, default_value = "7")]
+        days: i64,
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 impl ReviewArgs {
@@ -220,6 +243,98 @@ impl ReviewArgs {
                     }
                 }
             }
+            ReviewAction::Performance {
+                project,
+                agent,
+                repo,
+                days,
+                json,
+            } => {
+                let agent = agent.unwrap_or_else(crate::review::submitter_name);
+                let repo = repo.or_else(|| crate::claims::resolve_repo(None));
+                let now = crate::claims::now();
+                let since = now - days.max(1) * 86_400;
+
+                let backend_conn =
+                    match agentflare_backend::db::open_db(&crate::vent::paths::backend_db_path()) {
+                        Ok(c) => c,
+                        Err(e) => fail(format!("cannot open backend db: {e}")),
+                    };
+
+                let today = chrono::Local::now().date_naive();
+                let cost_start = today - chrono::Duration::days(days.max(1) - 1);
+                let cost_totals =
+                    crate::cost::summarize((cost_start, today), crate::cost::GroupBy::Project);
+                let cost_key = crate::mcp_server::AgentflareMcp::resolve_project_name();
+                let project_cost_usd = cost_totals
+                    .get(&cost_key)
+                    .map(|t| t.cost_usd)
+                    .unwrap_or(0.0);
+
+                let review = match crate::review::performance_review(
+                    &backend_conn,
+                    &conn,
+                    &project,
+                    repo.as_deref(),
+                    &agent,
+                    since,
+                    now,
+                    project_cost_usd,
+                ) {
+                    Ok(r) => r,
+                    Err(e) => fail(format!("performance_review failed: {e}")),
+                };
+
+                if json {
+                    println!(
+                        "{}",
+                        serde_json::to_string_pretty(&review).unwrap_or_default()
+                    );
+                } else {
+                    println!("{agent} — project {project} — last {days}d");
+                    println!("  completed:  {}", review.quantity_completed);
+                    match review.quality_accuracy {
+                        Some(acc) => println!(
+                            "  quality:    {:.0}% ({}/{} verified, {} round(s), all-time)",
+                            acc * 100.0,
+                            review.quality_findings,
+                            review.quality_findings,
+                            review.quality_rounds
+                        ),
+                        None => println!("  quality:    no recorded review rounds"),
+                    }
+                    println!("  attention:  {} ask(s)", review.attention_asks);
+                    println!(
+                        "  cost:       ${:.4} (whole project, all agents, {days}d window)",
+                        review.project_cost_usd
+                    );
+                }
+
+                let mem_conn = match crate::memory::store::open() {
+                    Ok(c) => c,
+                    Err(e) => fail(format!("cannot open memory store: {e}")),
+                };
+                let content = serde_json::to_string(&review).unwrap_or_default();
+                let topic_key = format!("perf_review:{project}:{agent}");
+                match crate::memory::observations::save(
+                    &mem_conn,
+                    None,
+                    "performance_review",
+                    &format!("{agent} performance — {project}"),
+                    &content,
+                    None,
+                    Some(&project),
+                    Some("workstation"),
+                    Some(&topic_key),
+                ) {
+                    Ok(_) => println!(
+                        "\nsaved — run `agentflare memory sync` to share across workstations"
+                    ),
+                    Err(e) => crate::ui::error(&format!(
+                        "warning: review computed but not saved to memory: {e}"
+                    )),
+                }
+            }
         }
     }
 }

src/mcp_server.rs

@@ -652,7 +652,7 @@ impl AgentflareMcp {
 
     /// Derives a project name from the git remote (`getappz/agentflare` →
     /// `agentflare`) or, outside a repo, the directory basename.
-    fn resolve_project_name() -> String {
+    pub(crate) fn resolve_project_name() -> String {
         if let Some(repo) = Self::run_git(&["remote", "get-url", "origin"]) {
             let normalized = crate::claims::normalize_repo(&repo);
             if let Some(name) = normalized.rsplit('/').next().filter(|s| !s.is_empty()) {

src/quota/decide.rs

@@ -217,6 +217,7 @@ pub fn decide_for_supervisor(
     mcp: &crate::mcp_server::AgentflareMcp,
     item: &agentflare_backend::item::Item,
 ) -> EffectiveAction {
+    let now = crate::claims::now();
     let decision = mcp
         .with_backend_db(|conn| decide(conn, item))
         .unwrap_or_else(|_| Decision::fail_closed("could not open backend db"));
@@ -240,6 +241,7 @@ pub fn decide_for_supervisor(
         }
         EffectiveActionInternal::Wait => EffectiveAction::Wait,
         EffectiveActionInternal::Ask => {
+            let goal_item_id = goal.as_ref().map(|(gi, _)| gi.id.clone());
             if let Some((goal_item, mut meta)) = goal {
                 meta.consecutive_self_repairs = 0;
                 if let Ok(next) = meta.lifecycle.apply(super::lifecycle::LifecycleEvent::Gate) {
@@ -249,6 +251,18 @@ pub fn decide_for_supervisor(
                     super::goal::save_goal_metadata(conn, &goal_item.id, &meta)
                 });
             }
+            let _ = mcp.with_backend_db(|conn| {
+                agentflare_backend::ask_event::record(
+                    conn,
+                    &item.project_id,
+                    goal_item_id.as_deref(),
+                    &item.id,
+                    item.assignee_agent.as_deref(),
+                    &decision.reason,
+                    decision.gate_question.as_deref(),
+                    now,
+                )
+            });
             EffectiveAction::Ask(
                 decision
                     .gate_question
@@ -455,6 +469,25 @@ mod tests {
         assert_eq!(decision.effective_action, EffectiveActionInternal::Ask);
     }
 
+    #[test]
+    fn gated_lifecycle_records_an_ask_event() {
+        let conn = test_conn();
+        let (pid, sid) = seed_project(&conn);
+        let goal = make_goal_item(&conn, &pid, &sid, GoalLifecycle::Gated, 0);
+        let todo = make_todo(&conn, &pid, &sid, &goal.id);
+
+        let decision = decide(&conn, &todo);
+        assert_eq!(decision.effective_action, EffectiveActionInternal::Ask);
+
+        // decide() itself is pure and does not write; recording happens in
+        // decide_for_supervisor, which needs an AgentflareMcp and is covered
+        // by ask_event's own unit test for the write path. This pins that
+        // decide() still reaches Ask for a gated goal, which
+        // decide_for_supervisor's Ask arm relies on to call
+        // ask_event::record.
+        assert!(decision.gate_question.is_some());
+    }
+
     #[test]
     fn active_lifecycle_with_no_vent_does_not_ask() {
         let conn = test_conn();