feat(wave16): 5 parallel agents — ledger v6 + prune dedupe + brain-view clusters + fork-watch hook + three-role pipeline

51 crates, 753 tests green (up from 744 at v0.32.0).

All 5 agents launched in parallel via substrate composed prompts. Zero
file conflicts between scopes.

## A. kei-ledger v6 — 3 performance indexes + fork_transactional API
- idx_agents_started_ts, idx_agents_status, idx_agents_fork_parent_id
- fork_transactional<F>(): atomic fork row + caller side-effect
  closes kei-fork ↔ ledger transactional gap (Wave 15 known issue)
- 30 tests (was 23)

## B. kei-prune dedupe — cluster-based retirement via kei-dna-index
- dedupe_candidates() via kei_dna_index::cluster_by(Scope)
- dedupe_strict() — intersection of scope+body clusters
- apply_retirements() reuses mark_retired
- CLI: kei-prune dedupe [--strict] [--dry-run]
- 17 tests (was 9)

## C. kei-brain-view clusters — stats + cluster visualization
- render_clusters(by: ClusterBy) — indented tree output
- render_summary() — 6-line dashboard from kei-dna-index::stats
- CLI: kei-brain-view clusters --by scope|body|role; kei-brain-view summary
- 15 tests (was 8)

## D. kei-fork watch-hook — auto-collect on .DONE marker
- watch_loop() — kei-watch subscription + auto kei-fork collect
- hooks/fork-collect-on-done.sh — foreground daemon wrapper
- dedupe via HashSet + agent_id validation
- 21 tests (was 13)

## E. three-role pipeline (Writer → Auditor → Merger)
- _roles/auditor.toml (pipeline.handoff=["merger"], claude-subagent-type=critic)
- _roles/merger.toml (leaf, git-ops scoped, infra-implementer)
- 5 new capability fragments: policy/git-ops-scope, scope/read-only,
  output/verdict, output/merge-result, verify/fork-audit
- kei-spawn: pipeline_from_role + emit_pipeline_json + scaffold_downstream_tasks
- kei-spawn: precedent::run_advisory (env-gated KEI_SPAWN_PRECEDENT_CHECK)
- CLI: kei-spawn spawn --pipeline
- 19 tests (was 10)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

_primitives/_rust/Cargo.lock

@@ -2396,6 +2396,7 @@ name = "kei-brain-view"
 version = "0.1.0"
 dependencies = [
  "clap",
+ "kei-dna-index",
  "rusqlite",
  "serde",
  "tempfile",

_primitives/_rust/kei-brain-view/Cargo.toml

@@ -18,6 +18,7 @@ rusqlite = { version = "0.31", features = ["bundled"] }
 clap = { version = "4", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 thiserror = "1"
+kei-dna-index = { path = "../kei-dna-index" }
 
 [dev-dependencies]
 tempfile = "3"

_primitives/_rust/kei-brain-view/src/clusters.rs

@@ -0,0 +1,48 @@
+//! Cluster rendering over kei-dna-index groupings.
+//!
+//! Constructor Pattern: one file = one responsibility (render clusters).
+//! Pulls cluster groupings from `kei-dna-index` and decorates each member
+//! with its current ledger status. Read-only — no schema mutation.
+
+use crate::error::BrainViewError;
+use kei_dna_index::{cluster_by, ClusterBy};
+use rusqlite::Connection;
+
+/// Render the cluster tree for `by` as an ASCII text block.
+///
+/// Each non-singleton cluster becomes a `CLUSTER <key> (N members)` header
+/// followed by `  └─ <dna> [status]` rows. Empty clusters produce `""`.
+pub fn render_clusters(
+    conn: &Connection,
+    by: ClusterBy,
+) -> Result<String, BrainViewError> {
+    let clusters = cluster_by(conn, by)?;
+    if clusters.is_empty() {
+        return Ok(String::new());
+    }
+    let mut out = String::new();
+    for c in clusters {
+        out.push_str(&format!(
+            "CLUSTER {} ({} members)\n",
+            c.key,
+            c.members.len()
+        ));
+        for dna in &c.members {
+            let status = lookup_status(conn, dna);
+            out.push_str(&format!("  └─ {}  [{}]\n", dna, status));
+        }
+    }
+    Ok(out)
+}
+
+/// Return the `agents.status` column for the row whose DNA matches.
+/// Falls back to `"unknown"` if the row is missing or the query fails —
+/// rendering must always succeed even against a sparsely-populated ledger.
+fn lookup_status(conn: &Connection, dna: &str) -> String {
+    conn.query_row(
+        "SELECT COALESCE(status,'unknown') FROM agents WHERE dna = ?1",
+        [dna],
+        |r| r.get::<_, String>(0),
+    )
+    .unwrap_or_else(|_| "unknown".to_string())
+}

_primitives/_rust/kei-brain-view/src/error.rs

@@ -27,6 +27,9 @@ pub enum BrainViewError {
     /// Requested DNA prefix matched multiple rows; caller must disambiguate.
     #[error("dna prefix {prefix} ambiguous ({count} matches)")]
     DnaAmbiguous { prefix: String, count: usize },
+
+    #[error(transparent)]
+    DnaIndex(#[from] kei_dna_index::Error),
 }
 
 pub type Result<T> = std::result::Result<T, BrainViewError>;

_primitives/_rust/kei-brain-view/src/lib.rs

@@ -8,14 +8,18 @@
 //! render, stats, lineage). `lib.rs` is a pure re-export surface so the
 //! binary and integration tests share the same types.
 
+pub mod clusters;
 pub mod error;
 pub mod graph;
 pub mod lineage;
 pub mod render;
 pub mod stats;
+pub mod summary;
 
+pub use clusters::render_clusters;
 pub use error::{BrainViewError, Result};
 pub use graph::{build_graph, resolve_dna, Graph, Node};
 pub use lineage::{lineage, Lineage};
 pub use render::{render_ascii, render_ascii_with_color, render_lineage};
 pub use stats::{compute_stats, render_stats, Stats};
+pub use summary::render_summary;

_primitives/_rust/kei-brain-view/src/main.rs

@@ -5,9 +5,10 @@
 
 use clap::{Parser, Subcommand};
 use kei_brain_view::{
-    build_graph, compute_stats, render_ascii, render_lineage, render_stats,
-    resolve_dna, Result,
+    build_graph, compute_stats, render_ascii, render_clusters, render_lineage,
+    render_stats, render_summary, resolve_dna, BrainViewError, Result,
 };
+use kei_dna_index::ClusterBy;
 use rusqlite::Connection;
 use std::path::PathBuf;
 use std::process::ExitCode;
@@ -37,6 +38,14 @@ enum Cmd {
         #[arg(long)]
         dna: String,
     },
+    /// Group DNAs by scope / body / role+caps and print the cluster tree.
+    Clusters {
+        /// One of: scope | body | role
+        #[arg(long)]
+        by: String,
+    },
+    /// One-shot aggregate summary over the ledger DNAs.
+    Summary,
 }
 
 fn main() -> ExitCode {
@@ -53,19 +62,43 @@ fn main() -> ExitCode {
 fn run(cli: Cli) -> Result<()> {
     let db_path = cli.db.unwrap_or_else(default_db_path);
     let conn = Connection::open(&db_path)?;
-    let graph = build_graph(&conn)?;
     match cli.cmd {
-        Cmd::Tree => print!("{}", render_ascii(&graph)),
-        Cmd::Stats => print!("{}", render_stats(&compute_stats(&graph))),
+        Cmd::Tree => {
+            let graph = build_graph(&conn)?;
+            print!("{}", render_ascii(&graph));
+        }
+        Cmd::Stats => {
+            let graph = build_graph(&conn)?;
+            print!("{}", render_stats(&compute_stats(&graph)));
+        }
         Cmd::Lineage { dna } => {
+            let graph = build_graph(&conn)?;
             let focus = resolve_dna(&graph, &dna)?.clone();
             let colored = std::env::var_os("NO_COLOR").is_none();
             print!("{}", render_lineage(&graph, &focus, colored)?);
         }
+        Cmd::Clusters { by } => {
+            let by = parse_cluster_by(&by)?;
+            print!("{}", render_clusters(&conn, by)?);
+        }
+        Cmd::Summary => print!("{}", render_summary(&conn)?),
     }
     Ok(())
 }
 
+fn parse_cluster_by(raw: &str) -> Result<ClusterBy> {
+    match raw.to_ascii_lowercase().as_str() {
+        "scope" => Ok(ClusterBy::Scope),
+        "body" => Ok(ClusterBy::Body),
+        "role" | "rolecaps" | "role-caps" => Ok(ClusterBy::RoleCaps),
+        other => Err(BrainViewError::DnaIndex(
+            kei_dna_index::Error::MalformedDna(format!(
+                "cluster key must be one of scope|body|role, got: {other}"
+            )),
+        )),
+    }
+}
+
 fn default_db_path() -> PathBuf {
     let home = std::env::var_os("HOME")
         .map(PathBuf::from)

_primitives/_rust/kei-brain-view/src/summary.rs

@@ -0,0 +1,31 @@
+//! Summary rendering over kei-dna-index stats.
+//!
+//! Constructor Pattern: one file = one responsibility (render summary).
+//! Thin formatter — the aggregation itself lives in `kei-dna-index::stats`.
+
+use crate::error::BrainViewError;
+use kei_dna_index::stats;
+use rusqlite::Connection;
+
+/// Format the DNA-index summary block as a single text blob.
+///
+/// All fields come verbatim from `kei_dna_index::stats`; this function is
+/// pure presentation so the numbers can be re-used elsewhere unchanged.
+pub fn render_summary(conn: &Connection) -> Result<String, BrainViewError> {
+    let s = stats(conn)?;
+    Ok(format!(
+        "=== KeiSei Brain Summary ===\n\
+         Total DNAs: {}\n\
+         Unique scopes: {}\n\
+         Unique bodies: {}\n\
+         Clusters (scope ≥2): {}\n\
+         Clusters (body ≥2): {}\n\
+         Avg cluster size: {:.1}\n",
+        s.total_dnas,
+        s.unique_scopes,
+        s.unique_bodies,
+        s.clusters_scope,
+        s.clusters_body,
+        s.avg_cluster_size
+    ))
+}

_primitives/_rust/kei-brain-view/tests/clusters_integration.rs

@@ -0,0 +1,123 @@
+//! Integration tests for `render_clusters`.
+//!
+//! Each test seeds a minimal kei-ledger-compatible `agents` table with
+//! canonical DNAs (`<role>::<caps>::<sha8-scope>::<sha8-body>-<hex8-nonce>`)
+//! and asserts on the rendered ASCII block.
+
+use kei_brain_view::render_clusters;
+use kei_dna_index::ClusterBy;
+use rusqlite::{params, Connection};
+use tempfile::TempDir;
+
+fn seed_db() -> (TempDir, Connection) {
+    let dir = tempfile::tempdir().unwrap();
+    let db = dir.path().join("ledger.sqlite");
+    let conn = Connection::open(&db).unwrap();
+    conn.execute_batch(
+        "CREATE TABLE agents (
+            id TEXT PRIMARY KEY,
+            branch TEXT NOT NULL,
+            parent_branch TEXT,
+            spec_sha TEXT NOT NULL,
+            status TEXT NOT NULL,
+            started_ts INTEGER NOT NULL,
+            finished_ts INTEGER,
+            summary TEXT,
+            worktree_path TEXT,
+            dna TEXT,
+            creator_id TEXT,
+            fork_parent_id TEXT
+        );",
+    )
+    .unwrap();
+    (dir, conn)
+}
+
+fn dna(role: &str, caps: &str, scope: &str, body: &str, nonce: &str) -> String {
+    format!("{role}::{caps}::{scope}::{body}-{nonce}")
+}
+
+fn insert(conn: &Connection, id: &str, status: &str, ts: i64, dna_str: &str) {
+    conn.execute(
+        "INSERT INTO agents
+         (id, branch, parent_branch, spec_sha, status, started_ts, dna)
+         VALUES (?1, ?2, NULL, 'deadbeef', ?3, ?4, ?5)",
+        params![id, format!("agent/{id}"), status, ts, dna_str],
+    )
+    .unwrap();
+}
+
+#[test]
+fn render_clusters_scope_shows_tree() {
+    let (_d, conn) = seed_db();
+    // Three agents sharing scope AAAAAAAA; distinct bodies + nonces.
+    let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111");
+    let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222");
+    let d3 = dna("edit", "NG-FW", "AAAAAAAA", "B3B3B3B3", "33333333");
+    insert(&conn, "a1", "running", 1, &d1);
+    insert(&conn, "a2", "done", 2, &d2);
+    insert(&conn, "a3", "failed", 3, &d3);
+
+    let out = render_clusters(&conn, ClusterBy::Scope).unwrap();
+    assert!(
+        out.contains("CLUSTER AAAAAAAA (3 members)"),
+        "header missing: {out}"
+    );
+    assert_eq!(out.matches("└─").count(), 3, "expected 3 members: {out}");
+    assert!(out.contains("[running]"));
+    assert!(out.contains("[done]"));
+    assert!(out.contains("[failed]"));
+}
+
+#[test]
+fn render_clusters_empty_returns_empty_string() {
+    let (_d, conn) = seed_db();
+    // All singleton scopes → cluster_by drops all → empty output.
+    let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111");
+    let d2 = dna("edit", "NG-FW", "CCCCCCCC", "B2B2B2B2", "22222222");
+    insert(&conn, "a1", "running", 1, &d1);
+    insert(&conn, "a2", "done", 2, &d2);
+
+    let out = render_clusters(&conn, ClusterBy::Scope).unwrap();
+    assert_eq!(out, "", "singletons must not render: {out:?}");
+}
+
+#[test]
+fn render_clusters_body_groups_by_body_sha() {
+    let (_d, conn) = seed_db();
+    // All scope/body/nonce must be 8 hex chars per split_dna's validator.
+    let d1 = dna("edit", "NG-FW", "10000001", "BEEFBEEF", "11111111");
+    let d2 = dna("edit", "NG-FW", "20000002", "BEEFBEEF", "22222222");
+    let d3 = dna("edit", "NG-FW", "30000003", "FEEDFEED", "33333333");
+    insert(&conn, "a1", "running", 1, &d1);
+    insert(&conn, "a2", "done", 2, &d2);
+    insert(&conn, "a3", "failed", 3, &d3);
+
+    let out = render_clusters(&conn, ClusterBy::Body).unwrap();
+    assert!(
+        out.contains("CLUSTER BEEFBEEF (2 members)"),
+        "body cluster missing: {out}"
+    );
+    // FEEDFEED is singleton → must not appear as header.
+    assert!(!out.contains("FEEDFEED"), "singleton leaked: {out}");
+}
+
+#[test]
+fn render_clusters_role_caps_groups_by_role() {
+    let (_d, conn) = seed_db();
+    // Two agents share role+caps "edit::NG-FW"; one differs on caps.
+    let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111");
+    let d2 = dna("edit", "NG-FW", "CCCCCCCC", "B2B2B2B2", "22222222");
+    let d3 = dna("edit", "TG-ND", "DDDDDDDD", "B3B3B3B3", "33333333");
+    insert(&conn, "a1", "running", 1, &d1);
+    insert(&conn, "a2", "done", 2, &d2);
+    insert(&conn, "a3", "failed", 3, &d3);
+
+    let out = render_clusters(&conn, ClusterBy::RoleCaps).unwrap();
+    assert!(
+        out.contains("CLUSTER edit::NG-FW (2 members)"),
+        "role cluster missing: {out}"
+    );
+    // edit::TG-ND is singleton → excluded.
+    assert!(!out.contains("edit::TG-ND"), "singleton leaked: {out}");
+}

_primitives/_rust/kei-brain-view/tests/summary_integration.rs

@@ -0,0 +1,95 @@
+//! Integration tests for `render_summary`.
+
+use kei_brain_view::render_summary;
+use rusqlite::{params, Connection};
+use tempfile::TempDir;
+
+fn seed_db() -> (TempDir, Connection) {
+    let dir = tempfile::tempdir().unwrap();
+    let db = dir.path().join("ledger.sqlite");
+    let conn = Connection::open(&db).unwrap();
+    conn.execute_batch(
+        "CREATE TABLE agents (
+            id TEXT PRIMARY KEY,
+            branch TEXT NOT NULL,
+            parent_branch TEXT,
+            spec_sha TEXT NOT NULL,
+            status TEXT NOT NULL,
+            started_ts INTEGER NOT NULL,
+            finished_ts INTEGER,
+            summary TEXT,
+            worktree_path TEXT,
+            dna TEXT,
+            creator_id TEXT,
+            fork_parent_id TEXT
+        );",
+    )
+    .unwrap();
+    (dir, conn)
+}
+
+fn dna(role: &str, caps: &str, scope: &str, body: &str, nonce: &str) -> String {
+    format!("{role}::{caps}::{scope}::{body}-{nonce}")
+}
+
+fn insert(conn: &Connection, id: &str, status: &str, ts: i64, dna_str: Option<&str>) {
+    conn.execute(
+        "INSERT INTO agents
+         (id, branch, parent_branch, spec_sha, status, started_ts, dna)
+         VALUES (?1, ?2, NULL, 'deadbeef', ?3, ?4, ?5)",
+        params![id, format!("agent/{id}"), status, ts, dna_str],
+    )
+    .unwrap();
+}
+
+#[test]
+fn render_summary_shows_all_fields() {
+    let (_d, conn) = seed_db();
+    let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111");
+    let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222");
+    let d3 = dna("edit", "NG-FW", "CCCCCCCC", "B3B3B3B3", "33333333");
+    insert(&conn, "a1", "running", 1, Some(&d1));
+    insert(&conn, "a2", "done", 2, Some(&d2));
+    insert(&conn, "a3", "failed", 3, Some(&d3));
+
+    let out = render_summary(&conn).unwrap();
+    assert!(out.contains("=== KeiSei Brain Summary ==="));
+    assert!(out.contains("Total DNAs: 3"), "{out}");
+    assert!(out.contains("Unique scopes: 2"), "{out}");
+    assert!(out.contains("Unique bodies: 3"), "{out}");
+    assert!(out.contains("Clusters (scope ≥2):"), "{out}");
+    assert!(out.contains("Clusters (body ≥2):"), "{out}");
+    assert!(out.contains("Avg cluster size:"), "{out}");
+}
+
+#[test]
+fn render_summary_empty_ledger_shows_zeros() {
+    let (_d, conn) = seed_db();
+    let out = render_summary(&conn).unwrap();
+    assert!(out.contains("Total DNAs: 0"), "{out}");
+    assert!(out.contains("Unique scopes: 0"), "{out}");
+    assert!(out.contains("Unique bodies: 0"), "{out}");
+    assert!(out.contains("Clusters (scope ≥2): 0"), "{out}");
+    assert!(out.contains("Clusters (body ≥2): 0"), "{out}");
+    assert!(out.contains("Avg cluster size: 0.0"), "{out}");
+}
+
+#[test]
+fn render_summary_ignores_malformed_dna() {
+    let (_d, conn) = seed_db();
+    // 3 valid rows + 1 malformed (missing body separator) + 1 NULL.
+    let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111");
+    let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222");
+    let d3 = dna("edit", "NG-FW", "CCCCCCCC", "B3B3B3B3", "33333333");
+    insert(&conn, "a1", "running", 1, Some(&d1));
+    insert(&conn, "a2", "done", 2, Some(&d2));
+    insert(&conn, "a3", "failed", 3, Some(&d3));
+    insert(&conn, "bad", "done", 4, Some("not-a-dna"));
+    insert(&conn, "nil", "done", 5, None);
+
+    let out = render_summary(&conn).unwrap();
+    // load_rows drops malformed + NULL silently → only 3 valid counted.
+    assert!(out.contains("Total DNAs: 3"), "{out}");
+    assert!(out.contains("Unique scopes: 2"), "{out}");
+    assert!(out.contains("Unique bodies: 3"), "{out}");
+}