Knowledge: add durable handoff report

Author: artwalker

docs/book/src/reference/cli.md

@@ -285,6 +285,7 @@ Use `--json` for machine-readable automation output, and add `--compact` when yo
 
 ```bash
 sonechka knowledge status [--json] [--compact]
+sonechka knowledge handoff [--json] [--compact] [--output <path>] [--export-latest]
 ```
 
 Use this when you want one CLI report for how durable project knowledge is currently moving between sessions, topic memories, `MEMORY.md`, and reusable skills.
@@ -303,6 +304,29 @@ The report includes:
 
 Use `--json` for machine-readable output, add `--compact` for single-line JSON, and pass `--output <path>` when you want the report written directly to disk for cron or dashboard ingestion.
 
+## `sonechka knowledge handoff`
+
+```bash
+sonechka knowledge handoff [--json] [--compact] [--output <path>] [--export-latest]
+```
+
+Use this when you want one durable handoff snapshot that combines:
+
+- the current `knowledge status` view
+- the latest session continuity snapshot
+- the current `health continuity` trust posture
+
+The report includes:
+
+- `schema_version` and `generated_at_unix_ms`
+- `status` and `handoff_ready`
+- `blocking_surfaces`
+- `recommended_command`
+- `continuity_handoff` with trust level, source, and summary
+- embedded `knowledge_flow`, `session_continuity`, and `health_continuity` payloads
+
+Use `--export-latest` when you want the handoff snapshot written to `~/.sonechka/exports/knowledge-handoff/latest.json`.
+
 ## `sonechka knowledge refresh`
 
 ```bash

src/main.rs

@@ -463,6 +463,21 @@ enum KnowledgeCommands {
         #[arg(long)]
         output: Option<std::path::PathBuf>,
     },
+    /// Refresh a durable knowledge handoff snapshot across knowledge, session, and continuity surfaces
+    Handoff {
+        /// Emit machine-readable JSON
+        #[arg(long, default_value_t = false)]
+        json: bool,
+        /// Emit compact JSON instead of pretty-printed JSON
+        #[arg(long, default_value_t = false)]
+        compact: bool,
+        /// Write the handoff report to a file path instead of only printing it
+        #[arg(long)]
+        output: Option<std::path::PathBuf>,
+        /// Write the handoff report to ~/.sonechka/exports/knowledge-handoff/latest.json
+        #[arg(long, default_value_t = false)]
+        export_latest: bool,
+    },
     /// Refresh the latest machine-readable knowledge-flow snapshot only
     Refresh {
         /// Emit compact JSON instead of pretty-printed JSON for the refreshed snapshot
@@ -2025,6 +2040,27 @@ async fn main() -> anyhow::Result<()> {
                     tool::render_knowledge_flow_refresh(output.as_deref(), compact)?
                 );
             }
+            KnowledgeCommands::Handoff {
+                json,
+                compact,
+                output,
+                export_latest,
+            } => {
+                let report = build_knowledge_handoff_report()?;
+                if let Some(path) =
+                    resolve_knowledge_handoff_output_path(output.as_deref(), export_latest)
+                {
+                    println!("{}", write_json_to_path(&path, &report, compact)?);
+                    if json {
+                        return Ok(());
+                    }
+                }
+                if json {
+                    print_json(&report, compact)?;
+                } else {
+                    println!("{}", render_knowledge_handoff_report_text(&report));
+                }
+            }
         },
         Some(Commands::Health { action }) => match action {
             HealthCommands::Status {
@@ -3701,6 +3737,27 @@ struct OperatorReleaseReport {
     operator_refresh: OperatorRefreshReport,
 }
 
+#[derive(Debug, Serialize)]
+struct KnowledgeHandoffContinuityReport {
+    trust_level: Option<String>,
+    source: Option<String>,
+    summary: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+struct KnowledgeHandoffReport {
+    schema_version: String,
+    generated_at_unix_ms: u128,
+    status: String,
+    handoff_ready: bool,
+    blocking_surfaces: Vec<String>,
+    recommended_command: String,
+    knowledge_flow: serde_json::Value,
+    session_continuity: serde_json::Value,
+    health_continuity: serde_json::Value,
+    continuity_handoff: KnowledgeHandoffContinuityReport,
+}
+
 fn operator_artifact_refs() -> Vec<OperatorArtifactRef> {
     [
         (
@@ -3869,6 +3926,71 @@ fn build_operator_release_report(
     })
 }
 
+fn build_knowledge_handoff_report() -> anyhow::Result<KnowledgeHandoffReport> {
+    let knowledge_flow: serde_json::Value =
+        serde_json::from_str(&tool::render_knowledge_flow_status_json(true)?)?;
+    let session_continuity: serde_json::Value =
+        serde_json::from_str(&tool::render_session_status_json(None, true)?)?;
+    let health_continuity: serde_json::Value =
+        serde_json::from_str(&tool::render_health_continuity_json(true)?)?;
+
+    let trust_level = health_continuity
+        .get("handoff")
+        .and_then(|value| value.get("continuity"))
+        .and_then(|value| value.get("trust_level"))
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned);
+    let source = health_continuity
+        .get("handoff")
+        .and_then(|value| value.get("continuity"))
+        .and_then(|value| value.get("source"))
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned);
+    let summary = health_continuity
+        .get("handoff")
+        .and_then(|value| value.get("continuity"))
+        .and_then(|value| value.get("summary"))
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned);
+
+    let mut blocking_surfaces = Vec::new();
+    let trusted = trust_level.as_deref() == Some("trusted");
+    if !trusted {
+        blocking_surfaces.push("continuity".to_string());
+    }
+    let handoff_ready = blocking_surfaces.is_empty();
+    let recommended_command = if trusted {
+        knowledge_flow
+            .get("recommended_command")
+            .and_then(|value| value.as_str())
+            .unwrap_or("sonechka knowledge status")
+            .to_string()
+    } else {
+        "sonechka health continuity --json --compact".to_string()
+    };
+
+    Ok(KnowledgeHandoffReport {
+        schema_version: "knowledge-handoff-report.v1".to_string(),
+        generated_at_unix_ms: report_generated_at_unix_ms(),
+        status: if handoff_ready {
+            "ready".to_string()
+        } else {
+            "action-needed".to_string()
+        },
+        handoff_ready,
+        blocking_surfaces,
+        recommended_command,
+        continuity_handoff: KnowledgeHandoffContinuityReport {
+            trust_level,
+            source,
+            summary,
+        },
+        knowledge_flow,
+        session_continuity,
+        health_continuity,
+    })
+}
+
 fn render_operator_status_report_text(report: &OperatorStatusReport) -> String {
     let advisor_profile = report
         .provider_routing
@@ -4027,6 +4149,68 @@ fn render_operator_release_report_text(report: &OperatorReleaseReport) -> String
     )
 }
 
+fn render_knowledge_handoff_report_text(report: &KnowledgeHandoffReport) -> String {
+    let trust_level = report
+        .continuity_handoff
+        .trust_level
+        .as_deref()
+        .unwrap_or("unknown");
+    let source = report
+        .continuity_handoff
+        .source
+        .as_deref()
+        .unwrap_or("unknown");
+    let summary = report
+        .continuity_handoff
+        .summary
+        .as_deref()
+        .unwrap_or("No continuity summary available.");
+    let mut lines = vec![
+        "Knowledge handoff".to_string(),
+        format!("- status: {}", report.status),
+        format!(
+            "- handoff ready: {}",
+            if report.handoff_ready { "yes" } else { "no" }
+        ),
+        format!(
+            "- blocking surfaces: {}",
+            if report.blocking_surfaces.is_empty() {
+                "none".to_string()
+            } else {
+                report.blocking_surfaces.join(", ")
+            }
+        ),
+        format!("- continuity trust: {}", trust_level),
+        format!("- continuity source: {}", source),
+        format!("- recommended command: {}", report.recommended_command),
+        String::new(),
+        "Continuity handoff".to_string(),
+        format!("- {}", summary),
+    ];
+    if let Some(session_id) = report
+        .session_continuity
+        .get("session_id")
+        .and_then(|value| value.as_str())
+    {
+        lines.push(String::new());
+        lines.push("Latest session".to_string());
+        lines.push(format!("- session id: {}", session_id));
+    }
+    if let Some(command) = report
+        .knowledge_flow
+        .get("recommended_command")
+        .and_then(|value| value.as_str())
+    {
+        lines.push(String::new());
+        lines.push("Knowledge flow".to_string());
+        lines.push(format!("- recommended command: {}", command));
+    }
+    lines.join(
+        "
+",
+    )
+}
+
 fn report_generated_at_unix_ms() -> u128 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -4346,6 +4530,13 @@ fn operator_report_latest_path(report_family: &str) -> std::path::PathBuf {
         .join("latest.json")
 }
 
+fn knowledge_handoff_latest_path() -> std::path::PathBuf {
+    config::config_dir()
+        .join("exports")
+        .join("knowledge-handoff")
+        .join("latest.json")
+}
+
 fn resolve_operator_report_output_path(
     output: Option<&std::path::Path>,
     export_latest: bool,
@@ -4356,6 +4547,15 @@ fn resolve_operator_report_output_path(
         .or_else(|| export_latest.then(|| operator_report_latest_path(report_family)))
 }
 
+fn resolve_knowledge_handoff_output_path(
+    output: Option<&std::path::Path>,
+    export_latest: bool,
+) -> Option<std::path::PathBuf> {
+    output
+        .map(std::path::Path::to_path_buf)
+        .or_else(|| export_latest.then(knowledge_handoff_latest_path))
+}
+
 fn print_json<T: Serialize>(value: &T, compact: bool) -> anyhow::Result<()> {
     let body = if compact {
         serde_json::to_string(value)?

tests/plugin_cli.rs

@@ -7357,6 +7357,69 @@ fn knowledge_refresh_honors_output_path_and_compact_json() {
     assert_eq!(body["topic_memory"]["topic_files"], 1);
 }
 
+#[test]
+fn knowledge_handoff_json_embeds_continuity_and_exports_latest_snapshot() {
+    let home = tempdir().unwrap();
+    let config_dir = home.path().join(".sonechka");
+    seed_background_continuity_fixture(&config_dir);
+
+    let output = Command::cargo_bin("sonechka")
+        .unwrap()
+        .env("HOME", home.path())
+        .arg("knowledge")
+        .arg("handoff")
+        .arg("--json")
+        .arg("--compact")
+        .arg("--export-latest")
+        .output()
+        .unwrap();
+
+    assert!(output.status.success());
+    assert!(String::from_utf8_lossy(&output.stdout).contains("Wrote report to"));
+
+    let latest_path = config_dir
+        .join("exports")
+        .join("knowledge-handoff")
+        .join("latest.json");
+    assert!(latest_path.exists());
+    let body: Value =
+        serde_json::from_str(&std::fs::read_to_string(&latest_path).unwrap()).unwrap();
+    assert_eq!(body["schema_version"], "knowledge-handoff-report.v1");
+    assert_eq!(body["status"], "ready");
+    assert_eq!(body["handoff_ready"], true);
+    assert_eq!(body["blocking_surfaces"], json!([]));
+    assert_eq!(body["continuity_handoff"]["trust_level"], "trusted");
+    assert_eq!(
+        body["knowledge_flow"]["schema_version"],
+        "knowledge-flow-status.v1"
+    );
+    assert_eq!(
+        body["health_continuity"]["schema_version"],
+        "health-continuity.v1"
+    );
+}
+
+#[test]
+fn knowledge_handoff_text_flags_continuity_blockers() {
+    let home = tempdir().unwrap();
+
+    Command::cargo_bin("sonechka")
+        .unwrap()
+        .env("HOME", home.path())
+        .arg("knowledge")
+        .arg("handoff")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Knowledge handoff"))
+        .stdout(predicate::str::contains("status: action-needed"))
+        .stdout(predicate::str::contains("handoff ready: no"))
+        .stdout(predicate::str::contains("blocking surfaces: continuity"))
+        .stdout(predicate::str::contains(
+            "recommended command: sonechka health continuity --json --compact",
+        ))
+        .stdout(predicate::str::contains("Continuity handoff"));
+}
+
 #[test]
 fn policy_status_reports_models_and_recent_review_evidence() {
     let home = tempdir().unwrap();