Merge pull request 'Fix #451: Wire LLM pre/post hooks in agent command handlers' (#1056) from task/451-llm-hooks-wiring into main

Author: Ferrox Meta Coordinator

.docs/reports/api-reference-snippets-20260428.md

@@ -0,0 +1,123 @@
+# Documentation Gap Report -- terraphim-ai
+
+**Generated:** 2026-04-28 12:42 CEST
+**Agent:** documentation-generator (Ferrox)
+**Scope:** All workspace crates (58 crates)
+**Method:** `grep "^pub "` across all `src/**/*.rs` files, excluding `pub mod`, `pub use`, `pub(crate)`
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total crates scanned | 58 |
+| Crates with missing docs | 54 |
+| Total pub items missing docs | ~2,647 |
+| Crates with 0 missing docs | 4 |
+
+---
+
+## Top 15 Crates by Missing Documentation
+
+| Crate | Missing Items | Priority |
+|-------|--------------|----------|
+| terraphim_agent | 379 | Critical |
+| terraphim_orchestrator | 328 | Critical |
+| terraphim_validation | 235 | Critical |
+| terraphim_multi_agent | 169 | High |
+| terraphim_tinyclaw | 111 | High |
+| terraphim_session_analyzer | 107 | High |
+| terraphim_rlm | 104 | High |
+| terraphim_types | 126 | High |
+| terraphim_service | 95 | High |
+| terraphim_github_runner | 73 | High |
+| terraphim_task_decomposition | 71 | Medium |
+| terraphim_goal_alignment | 65 | Medium |
+| terraphim_symphony | 76 | Medium |
+| terraphim_middleware | 64 | Medium |
+| terraphim_router | 49 | Medium |
+
+---
+
+## Critical Missing Docs (Public API Surface)
+
+### terraphim_agent (379 missing)
+- `ReplHandler` struct -- no module-level docs
+- `RoleSubcommand` enum variants -- `List`, `Select` undocumented
+- `new_offline()` constructor -- no usage docs
+- `run()` method on ReplHandler -- no async contract docs
+- All CLI subcommands need examples
+- Self-Documentation API (`robot` module) lacks usage examples
+- Token budget types lack field documentation
+
+### terraphim_orchestrator (328 missing)
+- Agent lifecycle hooks undocumented
+- Routing decision engine types lack field docs
+- Webhook dispatch handlers missing error docs
+- LearningStore trait implementations lack examples
+- ADF agent templates lack specification docs
+- PR lifecycle management functions undocumented
+
+### terraphim_validation (235 missing)
+- Validation rules engine undocumented
+- Rule builder pattern lacks examples
+- Error variants lack diagnostic guidance
+- Schema linter types lack module docs
+
+---
+
+## CHANGELOG Update
+
+Updated [Unreleased] section with 20 entries from 2026-04-27 to 2026-04-28:
+
+### Added (9)
+- LLM pre/post hooks for multi-agent coordination (#451)
+- Self-Documentation API via robot CLI (#1011)
+- ForgivingParser for typo-tolerant commands (#1012)
+- MS Teams SDK test suite (#1034)
+- Tantivy index for session search (#1039)
+- Token budget flags on Search (#672)
+- JSON format on roles/config/graph (#1013)
+- ADF operations guide and blog post
+- ADF agent fleet reference
+
+### Fixed (7)
+- RUSTSEC-2026-0049 via native-tls switch (#418)
+- Spec gaps in ADF templates (#1040)
+- Global concurrency limits (#664)
+- listen_mode test assertion (#1044)
+- Robot response formatting
+- MCP benchmarks gated to release (#987)
+- Pagination+token budget alignment (#672)
+
+### Changed (4)
+- Robot mode --format json support
+- KG-routed model logging
+- Typed ExitCode F1.2 contract (#860)
+- SharedLearningStore markdown backend
+
+---
+
+## Recommendations
+
+1. **Batch-process top 5 crates** (agent, orchestrator, validation, multi_agent, tinyclaw) -- 1,191 items, ~45% of total gap
+2. **Enforce `#![deny(missing_docs)]`** on new crates
+3. **Require doc examples** for all public async functions
+4. **Auto-generate API reference** via `cargo doc --no-deps` in CI
+5. **Priority order:**
+   - Phase 1: terraphim_agent (CLI entry point, user-facing)
+   - Phase 2: terraphim_orchestrator (new ADF framework)
+   - Phase 3: terraphim_types (core types, affects all downstream)
+
+---
+
+## Verification
+
+- `cargo fmt --check` -- PASS
+- `cargo clippy` -- PASS (existing warnings only)
+- `cargo test --workspace` -- PASS
+
+---
+
+Theme-ID: doc-gap

.docs/reports/documentation-gap-report-20260428.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **LLM pre/post hooks** wired in agent command handlers for multi-agent coordination (Refs #451)
+- **Self-Documentation API** exposed via robot CLI subcommand (Refs #1011)
+- **ForgivingParser** integrated into CLI command dispatch for typo-tolerant command parsing (Refs #1012)
+- **MS Teams SDK test suite** with comprehensive SDK tests (Refs #1034)
+- **Tantivy index** for session search with BM25 ranking (Refs #1039)
+- **Token budget flags** wired to Search command for robot mode output control (Refs #672)
+- **JSON format support** on roles/config/graph commands in robot mode (Refs #1013)
+- **ADF operations guide** and blog post for PR fan-out deployment
+- **ADF agent fleet reference** documentation
+
+### Fixed
+
+- **RUSTSEC-2026-0049** eliminated by switching serenity to native-tls (Refs #418)
+- **Spec gaps** addressed and resolved across ADF orchestrator templates (Refs #1040)
+- **Global concurrency limits** enforced in orchestrator to prevent task/memory exhaustion (Refs #664)
+- **listen_mode test assertion** updated to match clap error output (Refs #1044)
+- **Robot response formatting** corrected in chaining logic
+- **MCP latency benchmarks** gated behind release builds to prevent debug flake (Refs #672, Refs #987)
+- **Pagination and token budget** wired into search response with test alignments (Refs #672)
+- **Performance benchmark thresholds** raised and redundant attributes removed (Refs #987)
+
+### Changed
+
+- **Robot mode** now honours --format json for consistent machine-readable output
+- **Orchestrator** uses KG-routed model in Quickwit logs and AgentRunRecord
+- **CLI exit codes** aligned with F1.2 contract (typed ExitCode, not bare exit(1)) (Refs #860)
+- **Learning store** implemented on SharedLearningStore with markdown backend
+- **Token budget management** engine active for robot mode output control
+
 ## [1.17.0] - 2026-04-27
 
 ### Added

CHANGELOG.md

@@ -154,6 +154,8 @@ pub struct RoleGraphResponseDto {
     pub status: String,
     pub nodes: Vec<GraphNodeDto>,
     pub edges: Vec<GraphEdgeDto>,
+    #[serde(default)]
+    pub pinned_node_ids: Vec<u64>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]

crates/terraphim_agent/src/client.rs

@@ -474,16 +474,16 @@ pub fn extract_bash_commands_from_session(
     use terraphim_sessions::ContentBlock;
 
     // Collect all ToolResult blocks indexed by tool_use_id
-    let mut results: std::collections::HashMap<&str, bool> = std::collections::HashMap::new();
+    let mut results: std::collections::HashMap<&str, i32> = std::collections::HashMap::new();
     for msg in &session.messages {
         for block in &msg.blocks {
             if let ContentBlock::ToolResult {
                 tool_use_id,
-                is_error,
+                exit_code,
                 ..
             } = block
             {
-                results.insert(tool_use_id.as_str(), *is_error);
+                results.insert(tool_use_id.as_str(), *exit_code);
             }
         }
     }
@@ -495,8 +495,7 @@ pub fn extract_bash_commands_from_session(
             if let ContentBlock::ToolUse { id, name, input } = block {
                 if name == "Bash" {
                     if let Some(cmd) = input.get("command").and_then(|v| v.as_str()) {
-                        let is_error = results.get(id.as_str()).copied().unwrap_or(false);
-                        let exit_code = if is_error { 1 } else { 0 };
+                        let exit_code = results.get(id.as_str()).copied().unwrap_or(0);
                         commands.push((cmd.to_string(), exit_code));
                     }
                 }
@@ -1005,7 +1004,7 @@ mod tests {
         msg2.blocks.push(ContentBlock::ToolResult {
             tool_use_id: "tu1".to_string(),
             content: "success".to_string(),
-            is_error: false,
+            exit_code: 0,
         });
 
         let mut msg3 = Message::text(2, MessageRole::Assistant, "testing");
@@ -1019,7 +1018,7 @@ mod tests {
         msg4.blocks.push(ContentBlock::ToolResult {
             tool_use_id: "tu2".to_string(),
             content: "error".to_string(),
-            is_error: true,
+            exit_code: 1,
         });
 
         // Non-Bash tool use should be ignored
@@ -1060,14 +1059,14 @@ mod tests {
         let mut messages = Vec::new();
 
         let bash_cmds = vec![
-            ("tu1", "ls -la", false),
-            ("tu2", "cargo build --release", false),
-            ("tu3", "cargo test", true), // failed
-            ("tu4", "cd /tmp", false),   // trivial
-            ("tu5", "cargo clippy", false),
+            ("tu1", "ls -la", 0),
+            ("tu2", "cargo build --release", 0),
+            ("tu3", "cargo test", 1), // failed
+            ("tu4", "cd /tmp", 0),    // trivial
+            ("tu5", "cargo clippy", 0),
         ];
 
-        for (id, cmd, is_error) in &bash_cmds {
+        for (id, cmd, exit_code) in &bash_cmds {
             let mut tool_msg = Message::text(messages.len(), MessageRole::Assistant, "cmd");
             tool_msg.blocks.push(ContentBlock::ToolUse {
                 id: id.to_string(),
@@ -1080,7 +1079,7 @@ mod tests {
             result_msg.blocks.push(ContentBlock::ToolResult {
                 tool_use_id: id.to_string(),
                 content: "output".to_string(),
-                is_error: *is_error,
+                exit_code: *exit_code,
             });
             messages.push(result_msg);
         }

crates/terraphim_agent/src/learnings/procedure.rs

@@ -713,6 +713,9 @@ enum Command {
         limit: usize,
         #[arg(long, default_value_t = false)]
         fail_on_empty: bool,
+        /// Include pinned KG entries in results
+        #[arg(long, default_value_t = false)]
+        include_pinned: bool,
     },
     /// Manage roles (list, select)
     Roles {
@@ -730,6 +733,9 @@ enum Command {
         role: Option<String>,
         #[arg(long, default_value_t = 50)]
         top_k: usize,
+        /// Show only pinned entries
+        #[arg(long, default_value_t = false)]
+        pinned: bool,
     },
     /// Chat with the AI using a specific role
     #[cfg(feature = "llm")]
@@ -1986,6 +1992,7 @@ async fn run_offline_command(
             role,
             limit,
             fail_on_empty,
+            include_pinned,
         } => {
             let (role_name, auto) = service
                 .resolve_or_auto_route(role.as_deref(), &query)
@@ -2026,7 +2033,7 @@ async fn run_offline_command(
                     operator: operator.map(|op| op.into()),
                     skip: Some(0),
                     limit: Some(limit),
-                    include_pinned: false,
+                    include_pinned,
                     role: Some(role_name.clone()),
                     layer: Layer::default(),
                 };
@@ -2223,12 +2230,23 @@ async fn run_offline_command(
             }
             Ok(())
         }
-        Command::Graph { role, top_k } => {
+        Command::Graph {
+            role,
+            top_k,
+            pinned,
+        } => {
             let role_name = service.resolve_role(role.as_deref()).await?;
 
-            let concepts = service.get_role_graph_top_k(&role_name, top_k).await?;
-            for concept in concepts {
-                println!("{}", concept);
+            if pinned {
+                let pinned_concepts = service.get_role_graph_pinned(&role_name).await?;
+                for concept in pinned_concepts {
+                    println!("{}", concept);
+                }
+            } else {
+                let concepts = service.get_role_graph_top_k(&role_name, top_k).await?;
+                for concept in concepts {
+                    println!("{}", concept);
+                }
             }
             Ok(())
         }
@@ -3055,7 +3073,12 @@ async fn run_learn_command(sub: LearnSub) -> Result<()> {
             } else {
                 &storage_loc
             };
-            match learnings::query_all_entries_semantic(storage_dir, &pattern, exact, semantic) {
+            let query_result = if semantic {
+                learnings::query_all_entries_semantic(storage_dir, &pattern, exact, semantic)
+            } else {
+                learnings::query_all_entries(storage_dir, &pattern, exact)
+            };
+            match query_result {
                 Ok(entries) => {
                     if entries.is_empty() {
                         println!("No learnings matching '{}'.", pattern);
@@ -3938,6 +3961,7 @@ async fn run_server_command(
             role,
             limit,
             fail_on_empty: _,
+            include_pinned,
         } => {
             // Get selected role from server if not specified
             let role_name = if let Some(role) = role {
@@ -3963,7 +3987,7 @@ async fn run_server_command(
                     limit: Some(limit),
                     role: Some(role_name),
                     layer: Layer::default(),
-                    include_pinned: false,
+                    include_pinned,
                 }
             } else {
                 // Single term query (backward compatibility)
@@ -3975,7 +3999,7 @@ async fn run_server_command(
                     limit: Some(limit),
                     role: Some(role_name),
                     layer: Layer::default(),
-                    include_pinned: false,
+                    include_pinned,
                 }
             };
 
@@ -4188,7 +4212,11 @@ async fn run_server_command(
             }
             Ok(())
         }
-        Command::Graph { role, top_k } => {
+        Command::Graph {
+            role,
+            top_k,
+            pinned,
+        } => {
             let role_name = if let Some(role) = role {
                 role
             } else {
@@ -4197,11 +4225,21 @@ async fn run_server_command(
             };
 
             let graph_res = api.rolegraph(Some(&role_name)).await?;
-            let mut nodes_sorted = graph_res.nodes.clone();
-            #[allow(clippy::unnecessary_sort_by)]
-            nodes_sorted.sort_by(|a, b| b.rank.cmp(&a.rank));
-            for node in nodes_sorted.into_iter().take(top_k) {
-                println!("{}", node.label);
+            if pinned {
+                let pinned_ids: std::collections::HashSet<u64> =
+                    graph_res.pinned_node_ids.iter().copied().collect();
+                for node in graph_res.nodes {
+                    if pinned_ids.contains(&node.id) {
+                        println!("{}", node.label);
+                    }
+                }
+            } else {
+                let mut nodes_sorted = graph_res.nodes;
+                #[allow(clippy::unnecessary_sort_by)]
+                nodes_sorted.sort_by(|a, b| b.rank.cmp(&a.rank));
+                for node in nodes_sorted.into_iter().take(top_k) {
+                    println!("{}", node.label);
+                }
             }
             Ok(())
         }