Complete Phase 9 gamma with audit bundle v3 and six-workflow CI matrix.

rsasaki0109 · rsasaki0109 · commit efebad912a41 · 2026-06-15T01:40:36.000+09:00
Unify agent verification across all workflows, isolate STAC overlay paths for tests, and document Phase 10 federated catalog roadmap.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -21,40 +21,43 @@ jobs:
       - name: Build workspace
         run: cargo build --workspace
       - name: Test workspace
-        run: cargo test --workspace
+        run: cargo test --workspace -- --test-threads=1
       - name: MVP workflow smoke
         run: cargo run -p genegis-cli -- workflow run nagoya-density
       - name: MVP execute pipeline
         run: cargo run -p genegis-cli -- workflow run nagoya-density --execute
       - name: MVP ask intent pipeline
         run: cargo run -p genegis-cli -- ask "名古屋市の人口密度を表示" --no-html
-      - name: Phase 8 gamma — agent workflow matrix
+      - name: Phase 9 gamma — six-workflow agent matrix
         run: |
           cargo run -p genegis-cli -- agent run "名古屋市の人口密度を表示"
           cargo run -p genegis-cli -- agent run "ローカルCOGデモのメタデータを表示"
           cargo run -p genegis-cli -- agent run "リモートCOGデモのメタデータを表示"
           cargo run -p genegis-cli -- agent run "名古屋 wards GeoParquet を検証"
-      - name: Phase 9 beta — discovery + GeoParquet density smoke
-        run: |
           cargo run -p genegis-cli -- agent run "外部STAC examples/stac/sample-collection.json を fetch"
           cargo run -p genegis-cli -- agent run "名古屋 GeoParquet 人口密度を表示"
-          cargo run -p genegis-cli -- workflow run nagoya-geoparquet-density --execute
+      - name: Phase 9 gamma — ask + overlay smoke
+        run: |
+          cargo run -p genegis-cli -- ask "名古屋 GeoParquet 人口密度を表示" --no-html
           cargo run -p genegis-cli -- catalog stac import examples/stac/sample-item.json
+          cargo run -p genegis-cli -- workflow run nagoya-geoparquet-density --execute
       - name: Agent human gate smoke
         run: |
           cargo run -p genegis-cli -- agent plan "名古屋市の人口密度を表示"
           cargo run -p genegis-cli -- agent execute
-      - name: Agent audit export smoke (STAC bundle v2)
+      - name: Agent audit export smoke (STAC bundle v3)
         run: |
           cargo run -p genegis-cli -- agent export-audit -o /tmp/genegis-audit-bundle.json
           python3 - <<'PY'
           import json
           from pathlib import Path
           bundle = json.loads(Path("/tmp/genegis-audit-bundle.json").read_text())
-          assert bundle["schema"] == "genegis-audit-bundle-v2", bundle["schema"]
+          assert bundle["schema"] == "genegis-audit-bundle-v3", bundle["schema"]
           stac = bundle["stac"]
-          assert stac["collection"]["item_count"] == 5
-          assert len(stac["items"]) == 5
+          assert stac["alpha"]["collection"]["item_count"] == 5
+          assert len(stac["alpha"]["items"]) == 5
+          assert stac["overlay"]["record_count"] >= 1
+          assert len(stac["merged"]["items"]) >= 6
           PY
       - name: STAC collection smoke
         run: cargo run -p genegis-cli -- catalog stac list
diff --git a/apps/desktop/ui/index.html b/apps/desktop/ui/index.html
@@ -10,7 +10,7 @@
     <header class="topbar">
       <div class="brand">
         <strong>GeneGIS</strong>
-        <span>AI-native GIS Workbench · Phase 9 beta</span>
+        <span>AI-native GIS Workbench · Phase 9 gamma</span>
       </div>
     </header>
 
diff --git a/crates/genegis-agent/src/audit.rs b/crates/genegis-agent/src/audit.rs
@@ -2,13 +2,16 @@
 
 use std::path::Path;
 
-use genegis_catalog::{alpha_catalog, bind_stac_item, browse_alpha_stac_collection};
+use genegis_catalog::{
+    alpha_catalog, bind_stac_item, browse_alpha_stac_collection, extended_catalog,
+    load_catalog_overlay, Catalog, DatasetRecord,
+};
 use serde_json::Value;
 
 use crate::error::AgentError;
 use crate::model::AgentRun;
 
-pub const AUDIT_BUNDLE_SCHEMA: &str = "genegis-audit-bundle-v2";
+pub const AUDIT_BUNDLE_SCHEMA: &str = "genegis-audit-bundle-v3";
 
 /// Collab-side fields included in an audit bundle.
 #[derive(Debug, Clone)]
@@ -28,23 +31,42 @@ impl AuditCollabSnapshot {
     }
 }
 
-/// Build STAC collection + item snapshot from the alpha catalog.
+fn stac_items_for_catalog(catalog: &Catalog) -> Result<Vec<Value>, AgentError> {
+    catalog
+        .list()
+        .into_iter()
+        .map(|record| {
+            bind_stac_item(catalog, &record.id)
+                .map_err(|err| AgentError::Message(err.to_string()))
+                .and_then(|item| {
+                    serde_json::to_value(item).map_err(|err| AgentError::Json(err.to_string()))
+                })
+        })
+        .collect()
+}
+
+/// Build STAC alpha, overlay, and merged catalog snapshots for audit export.
 pub fn build_audit_stac_snapshot() -> Result<Value, AgentError> {
-    let catalog = alpha_catalog();
-    let collection = browse_alpha_stac_collection(&catalog);
-    let mut items = Vec::new();
-
-    for record in catalog.list() {
-        let item = bind_stac_item(&catalog, &record.id)
-            .map_err(|err| AgentError::Message(err.to_string()))?;
-        items.push(
-            serde_json::to_value(item).map_err(|err| AgentError::Json(err.to_string()))?,
-        );
-    }
+    let alpha = alpha_catalog();
+    let merged = extended_catalog();
+    let overlay = load_catalog_overlay();
+
+    let alpha_collection = browse_alpha_stac_collection(&alpha);
+    let merged_collection = browse_alpha_stac_collection(&merged);
 
     Ok(serde_json::json!({
-        "collection": collection.summary_json(),
-        "items": items,
+        "alpha": {
+            "collection": alpha_collection.summary_json(),
+            "items": stac_items_for_catalog(&alpha)?,
+        },
+        "overlay": {
+            "record_count": overlay.len(),
+            "records": overlay.iter().map(DatasetRecord::summary_json).collect::<Vec<_>>(),
+        },
+        "merged": {
+            "collection": merged_collection.summary_json(),
+            "items": stac_items_for_catalog(&merged)?,
+        },
     }))
 }
 
@@ -105,14 +127,21 @@ mod tests {
 
         let stac = bundle.get("stac").expect("stac");
         assert_eq!(
-            stac.pointer("/collection/item_count").and_then(Value::as_u64),
+            stac.pointer("/alpha/collection/item_count")
+                .and_then(Value::as_u64),
             Some(5)
         );
-        let items = stac
-            .get("items")
+        let alpha_items = stac
+            .pointer("/alpha/items")
             .and_then(Value::as_array)
-            .expect("stac items");
-        assert_eq!(items.len(), 5);
+            .expect("alpha items");
+        assert_eq!(alpha_items.len(), 5);
+        assert!(stac.get("overlay").is_some());
+        assert_eq!(
+            stac.pointer("/merged/collection/item_count")
+                .and_then(Value::as_u64),
+            Some(5)
+        );
 
         let runs = bundle
             .get("agent_runs")
@@ -131,7 +160,7 @@ mod tests {
     fn audit_stac_snapshot_includes_local_cog_item() {
         let stac = build_audit_stac_snapshot().expect("stac");
         let items = stac
-            .get("items")
+            .pointer("/alpha/items")
             .and_then(Value::as_array)
             .expect("items");
         assert!(
diff --git a/crates/genegis-ai/src/planner.rs b/crates/genegis-ai/src/planner.rs
@@ -171,7 +171,7 @@ mod tests {
         let plan = plan_from_prompt("名古屋 GeoParquet 人口密度を表示").expect("plan");
         assert_eq!(plan.resolved.workflow_id, WorkflowId::NagoyaGeoparquetDensity);
         assert_eq!(plan.resolved.dataset_id, NAGOYA_WARDS_GEOPARQUET_ID);
-        assert_eq!(plan.workflow.steps.len(), 7);
+        assert_eq!(plan.workflow.steps.len(), 8);
     }
 
     #[test]
diff --git a/crates/genegis-catalog/src/external_stac.rs b/crates/genegis-catalog/src/external_stac.rs
@@ -11,6 +11,15 @@ use crate::stac::{StacCollection, StacItem};
 /// Default overlay path for imported STAC items.
 pub const CATALOG_OVERLAY_PATH: &str = ".genegis/catalog-overlay.json";
 
+/// Environment variable override for overlay path (tests / CI isolation).
+pub const CATALOG_OVERLAY_ENV: &str = "GENEGIS_CATALOG_OVERLAY_PATH";
+
+pub fn catalog_overlay_path() -> PathBuf {
+    std::env::var(CATALOG_OVERLAY_ENV)
+        .map(PathBuf::from)
+        .unwrap_or_else(|_| PathBuf::from(CATALOG_OVERLAY_PATH))
+}
+
 /// Fetch JSON bytes from an HTTP(S) URL or local filesystem path.
 pub fn fetch_json_bytes(uri: &str) -> Result<Vec<u8>, CatalogError> {
     let normalized = resolve_catalog_url(uri);
@@ -110,11 +119,11 @@ fn format_from_media_type(media_type: &str) -> DatasetFormat {
 
 /// Load imported dataset records from the overlay file.
 pub fn load_catalog_overlay() -> Vec<DatasetRecord> {
-    let path = Path::new(CATALOG_OVERLAY_PATH);
+    let path = catalog_overlay_path();
     if !path.exists() {
         return Vec::new();
     }
-    let json = match std::fs::read_to_string(path) {
+    let json = match std::fs::read_to_string(&path) {
         Ok(json) => json,
         Err(_) => return Vec::new(),
     };
@@ -123,7 +132,7 @@ pub fn load_catalog_overlay() -> Vec<DatasetRecord> {
 
 /// Persist imported dataset records to the overlay file.
 pub fn save_catalog_overlay(records: &[DatasetRecord]) -> Result<(), CatalogError> {
-    let path = Path::new(CATALOG_OVERLAY_PATH);
+    let path = catalog_overlay_path();
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)
             .map_err(|err| CatalogError::Remote(format!("overlay dir: {err}")))?;
@@ -211,33 +220,27 @@ mod tests {
 
     #[test]
     fn imports_sample_stac_item_to_overlay() {
-        let overlay_path = Path::new(CATALOG_OVERLAY_PATH);
-        let backup = overlay_path.exists().then(|| std::fs::read(overlay_path).expect("read"));
-        let _guard = RestoreOverlay { backup };
+        let overlay_path = std::env::temp_dir().join(format!(
+            "genegis-overlay-test-{}.json",
+            std::process::id()
+        ));
+        std::env::set_var(CATALOG_OVERLAY_ENV, &overlay_path);
+        let _guard = RestoreOverlayEnv;
 
         let record = import_stac_item_url(&sample_item_path()).expect("import");
         assert_eq!(record.id, "genegis-sample-external-item");
         assert!(record.uri.ends_with("nagoya-wards.geojson"));
 
         let overlay = load_catalog_overlay();
         assert!(overlay.iter().any(|entry| entry.id == record.id));
+        let _ = std::fs::remove_file(&overlay_path);
     }
 
-    struct RestoreOverlay {
-        backup: Option<Vec<u8>>,
-    }
+    struct RestoreOverlayEnv;
 
-    impl Drop for RestoreOverlay {
+    impl Drop for RestoreOverlayEnv {
         fn drop(&mut self) {
-            let path = Path::new(CATALOG_OVERLAY_PATH);
-            match &self.backup {
-                Some(bytes) => {
-                    let _ = std::fs::write(path, bytes);
-                }
-                None => {
-                    let _ = std::fs::remove_file(path);
-                }
-            }
+            let _ = std::env::remove_var(CATALOG_OVERLAY_ENV);
         }
     }
 }
diff --git a/crates/genegis-catalog/src/lib.rs b/crates/genegis-catalog/src/lib.rs
@@ -14,7 +14,7 @@ pub use catalog::{
 };
 pub use external_stac::{
     fetch_stac_collection, fetch_stac_item, import_stac_item_url, load_catalog_overlay,
-    resolve_catalog_url, CATALOG_OVERLAY_PATH,
+    resolve_catalog_url, catalog_overlay_path, CATALOG_OVERLAY_ENV, CATALOG_OVERLAY_PATH,
 };
 pub use dataset::{DatasetFormat, DatasetRecord};
 pub use error::CatalogError;
diff --git a/crates/genegis-workflow/src/graph.rs b/crates/genegis-workflow/src/graph.rs
@@ -126,6 +126,10 @@ pub fn nagoya_geoparquet_template() -> GeoWorkflow {
             serde_json::json!({ "tags": ["nagoya", "geoparquet", "demo"] }),
         ),
         WorkflowStep::new("LoadGeoParquet", serde_json::json!({ "format": "geoparquet" })),
+        WorkflowStep::new(
+            "VerifyFeatureCount",
+            serde_json::json!({ "expected": 16, "field": "ward_name" }),
+        ),
         WorkflowStep::new("AttachSources", serde_json::json!({})),
     ];
     workflow
diff --git a/docs/guides/agent-orchestration.md b/docs/guides/agent-orchestration.md
@@ -41,17 +41,29 @@ Pending plans are stored at `.genegis/agent-plan.json`. Runs are stored at `.gen
 2. Sidebar → **Agent trace** → **Plan only** saves a pending plan.
 3. **Approve & execute** runs catalog → analysis → DuckDB verify without re-planning.
 4. Collab comments and project provenance record `agent_run_id` on failure or success.
+5. **External STAC** panel — fetch collection JSON or import STAC items into `.genegis/catalog-overlay.json`.
 
 ## Tool allowlist
 
-Planner tools: `parse_intent`, `resolve_workflow`, `stac_browse`, `stac_bind`, `llm_plan_workflow`, `plan_workflow`.
+Planner tools: `parse_intent`, `resolve_workflow`, `stac_browse`, `stac_bind`, `stac_fetch`, `llm_plan_workflow`, `plan_workflow`.
 
-Executor tools: `catalog_resolve`, `run_nagoya_density`, `run_remote_cog_metadata`, `run_local_cog_metadata`, `verify_retry`.
+Executor tools: `catalog_resolve`, `run_nagoya_density`, `run_remote_cog_metadata`, `run_local_cog_metadata`, `run_geoparquet_read`, `run_geoparquet_density`, `run_stac_fetch`, `verify_retry`.
 
-Verifier tools: `duckdb_verify` (Nagoya density), `cog_metadata_verify` (remote COG metadata).
+Verifier tools: `duckdb_verify`, `cog_metadata_verify`, `geoparquet_feature_verify`, `stac_collection_verify`.
 
 Unknown tools are rejected before execution (see `crates/genegis-agent/src/tool_registry.rs`).
 
+## Verification matrix (Phase 9)
+
+| Workflow | Execute tool | Verifier | Offline? |
+|----------|--------------|----------|----------|
+| `nagoya-density` | `run_nagoya_density` | `duckdb_verify` | Yes |
+| `remote-cog-demo` | `run_remote_cog_metadata` | `cog_metadata_verify` | Needs HTTP |
+| `local-cog-demo` | `run_local_cog_metadata` | `cog_metadata_verify` | Yes |
+| `nagoya-geoparquet` | `run_geoparquet_read` | `geoparquet_feature_verify` | Yes (fixture) |
+| `nagoya-geoparquet-density` | `run_geoparquet_density` | `duckdb_verify` | Yes (fixture) |
+| `external-stac-demo` | `run_stac_fetch` | `stac_collection_verify` | Yes (sample JSON) |
+
 ## Server API
 
 ```bash
@@ -61,7 +73,7 @@ curl http://127.0.0.1:7813/api/agent/runs/5bcfb044-7170-4aa1-b652-8f774d8cb28f
 curl -X POST http://127.0.0.1:7813/api/agent/runs -H 'Content-Type: application/json' -d @.genegis/agent-run.json
 ```
 
-Workbench proxies the same flow at `/api/agent/plan`, `/api/agent/execute`, `/api/agent/retry`, and `/api/agent/runs/latest`.
+Workbench proxies the same flow at `/api/agent/plan`, `/api/agent/execute`, `/api/agent/retry`, and `/api/agent/runs/latest`. STAC overlay APIs: `/api/stac/fetch`, `/api/stac/import`, `/api/stac/overlay`.
 
 Tauri desktop uses the same UI with `invoke` commands (`agent_plan`, `agent_execute`, `agent_retry`, `agent_runs_list`, …).
 
@@ -72,7 +84,7 @@ genegis agent export-audit -o .genegis/audit-bundle.json
 genegis collab provenance list
 ```
 
-Bundle includes collab summary, comments, provenance entries, agent run index, and STAC collection/items. Schema: `genegis-audit-bundle-v2` (see `crates/genegis-agent/src/audit.rs`).
+Bundle includes collab summary, comments, provenance entries, agent run index, and STAC snapshots (`alpha`, `overlay`, `merged`). Schema: `genegis-audit-bundle-v3` (see `crates/genegis-agent/src/audit.rs`).
 
 ## Provenance
 
@@ -85,5 +97,6 @@ Successful or pending agent runs append to `Workspace.provenance` inside the col
 ## References
 
 - [`docs/roadmap/phase-6-autonomous.md`](../roadmap/phase-6-autonomous.md)
+- [`docs/roadmap/phase-9-external-data.md`](../roadmap/phase-9-external-data.md)
 - [`docs/adrs/0003-agent-trust-boundary.md`](../adrs/0003-agent-trust-boundary.md)
 - [`crates/genegis-agent/`](../../crates/genegis-agent/)
diff --git a/docs/roadmap/phase-10-federated-catalog.md b/docs/roadmap/phase-10-federated-catalog.md
@@ -0,0 +1,20 @@
+# Phase 10: Federated Catalog Search (TBD)
+
+**Goal:** Search and bind datasets across federated STAC endpoints and cloud GeoParquet assets.
+
+**Status:** Draft placeholder — scope to be defined after Phase 9 gamma release.
+
+## Candidate tracks
+
+| Track | Focus |
+|-------|--------|
+| **Catalog** | Federated STAC search + merge into overlay |
+| **Storage** | Cloud GeoParquet range-read execution |
+| **Agent** | Multi-source workflow binding |
+| **Workbench** | Federated discovery UI |
+
+## North star (unchanged)
+
+「名古屋市の人口密度を表示」 — offline rule planner + DuckDB verification must keep passing in CI.
+
+See [`phase-9-external-data.md`](phase-9-external-data.md).
diff --git a/docs/roadmap/phase-8-intent-expansion.md b/docs/roadmap/phase-8-intent-expansion.md
@@ -81,6 +81,6 @@ genegis workflow run remote-cog-demo --execute
 
 ## Next
 
-Phase 9 — external STAC discovery and GeoParquet workflows (TBD): draft `docs/roadmap/phase-9-external-data.md`
+Phase 9 — external STAC discovery and GeoParquet workflows: see [`phase-9-external-data.md`](phase-9-external-data.md).
 
 See [`phase-7-release.md`](phase-7-release.md) and [`docs/guides/agent-orchestration.md`](../guides/agent-orchestration.md).
diff --git a/docs/roadmap/phase-9-external-data.md b/docs/roadmap/phase-9-external-data.md

Original file line number	Diff line number	Diff line change
`@@ -171,7 +171,7 @@ mod tests {`
`171`	`171`	`let plan = plan_from_prompt("名古屋 GeoParquet 人口密度を表示").expect("plan");`
`172`	`172`	`assert_eq!(plan.resolved.workflow_id, WorkflowId::NagoyaGeoparquetDensity);`
`173`	`173`	`assert_eq!(plan.resolved.dataset_id, NAGOYA_WARDS_GEOPARQUET_ID);`
`174`		`- assert_eq!(plan.workflow.steps.len(), 7);`
	`174`	`+ assert_eq!(plan.workflow.steps.len(), 8);`
`175`	`175`	`}`
`176`	`176`
`177`	`177`	`#[test]`