claw/docs/superpowers/plans/2026-04-06-scene-skill-runtime-routing-plan.md

# Scene Skill Runtime Routing Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a first scene-routing slice that recognizes staged business scenes from natural language and dispatches them through browser-backed execution, with `fault-details-report` using direct browser execution and `95598-repair-city-dispatch` using agent-mediated browser execution.

**Architecture:** Introduce a small registry module that loads the first staged `scene.json` contracts plus runtime dispatch policy from the external `skill_staging` root. Route matched scenes through one of two paths: `direct_browser` scenes execute through compat orchestration without the model choosing tools, while `agent_browser` scenes stay in the existing agent flow but get scene-specific browser-first prompt injection. Both modes must still execute through the existing `BrowserScriptSkillTool` / browser backend path so the final business action uses browser-internal methods.

**Tech Stack:** Rust, serde/JSON metadata loading, existing compat orchestration/runtime/workflow layers, browser-backed skill tools, focused `cargo test` coverage.

---

## File Map

**Create:**
- `src/runtime/scene_registry.rs` — load staged scene metadata, attach runtime dispatch policy, expose matching helpers for the first slice.
- `tests/scene_registry_test.rs` — focused tests for registry loading, matching, and policy behavior.

**Modify:**
- `src/runtime/mod.rs` — export the new scene registry module/types used by runtime and compat layers.
- `src/compat/config_adapter.rs` — verify the moved external `skill_staging` root resolves to the staged `skills` child, and only change path resolution if a targeted regression proves it is insufficient.
- `src/runtime/engine.rs` — inject scene-specific browser-first contracts for `agent_browser` scenes and keep existing Zhihu prompt behavior intact.
- `src/compat/workflow_executor.rs` — extend route detection and direct execution support for `fault-details-report` using the browser-backed skill path.
- `src/compat/orchestration.rs` — let primary orchestration prefer direct execution for `direct_browser` scenes while leaving `agent_browser` scenes in the agent path.
- `src/compat/browser_script_skill_tool.rs` — expose the thinnest reusable browser-backed execution helper needed so direct scene execution can reuse the same `browser_script` semantics instead of drifting into a duplicate local path.
- `src/compat/runtime.rs` — ensure runtime sees the staged skills root and continues exposing browser-backed scene tools.
- `tests/compat_config_test.rs` — add path-resolution coverage for the staged external root.
- `tests/runtime_profile_test.rs` — add scene-specific instruction contract assertions.
- `tests/browser_script_skill_tool_test.rs` — add coverage for any new reusable direct-execution helper introduced in the browser-script layer.
- `tests/compat_runtime_test.rs` — add orchestration/direct-route coverage for the new scene behavior.

**Reference:**
- `docs/superpowers/specs/2026-04-06-scene-skill-runtime-routing-design.md`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\fault-details-report\scene.json`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\95598-repair-city-dispatch\scene.json`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\SKILL.toml`
- `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\95598-repair-city-dispatch\SKILL.toml`

### Task 1: Add Scene Registry And Matching

**Files:**
- Create: `src/runtime/scene_registry.rs`
- Modify: `src/runtime/mod.rs`
- Test: `tests/scene_registry_test.rs`

- [ ] **Step 1: Write the failing registry tests**

Add tests that prove the first-slice registry can:
- load `fault-details-report` with `dispatch_mode = direct_browser`
- load `95598-repair-city-dispatch` with `dispatch_mode = agent_browser`
- match natural-language phrases like `导出故障明细` and `95598抢修市指监测`
- ignore missing/broken scene files without panicking

Example assertions to include:

```rust
assert_eq!(entry.scene_id, "fault-details-report");
assert_eq!(entry.dispatch_mode, DispatchMode::DirectBrowser);
assert_eq!(entry.tool_name(), "fault-details-report.collect_fault_details");
assert_eq!(entry.expected_domain, "__scene_fault_details__");
```

```rust
assert_eq!(matched.scene_id, "95598-repair-city-dispatch");
assert_eq!(matched.dispatch_mode, DispatchMode::AgentBrowser);
```

- [ ] **Step 2: Run the new registry tests to verify they fail**

Run:
```bash
cargo test scene_registry --test scene_registry_test -- --nocapture
```

Expected: FAIL because `src/runtime/scene_registry.rs` and the exported registry APIs do not exist yet.

- [ ] **Step 3: Implement the minimal scene registry module**

Create `src/runtime/scene_registry.rs` with:
- a small deserialized scene metadata struct for `scene.json`
- a `DispatchMode` enum
- a single runtime registry-entry struct combining scene metadata plus runtime policy
- first-slice hardcoded runtime policy for the two initial scenes
- helper methods like:

```rust
pub fn load_first_slice_scene_registry() -> Vec<SceneRegistryEntry>
pub fn match_scene_instruction(instruction: &str) -> Option<SceneRegistryEntry>
```

Use deterministic keyword/alias matching only. Do not add embeddings, fuzzy search, or generic scoring infrastructure beyond what the spec requires.

- [ ] **Step 4: Export the registry from `src/runtime/mod.rs`**

Expose the new types/helpers needed by runtime and compat layers, for example:

```rust
mod scene_registry;

pub use scene_registry::{
    load_first_slice_scene_registry,
    match_scene_instruction,
    DispatchMode,
    SceneRegistryEntry,
};
```

- [ ] **Step 5: Run the registry tests to verify they pass**

Run:
```bash
cargo test scene_registry --test scene_registry_test -- --nocapture
```

Expected: PASS

- [ ] **Step 6: Commit Task 1**

```bash
git add src/runtime/scene_registry.rs src/runtime/mod.rs tests/scene_registry_test.rs
git commit -m "feat: add staged scene registry matching"
```

### Task 2: Verify Staged Skills Root Resolution

**Files:**
- Modify if needed: `src/compat/config_adapter.rs:94`
- Modify if needed: `src/compat/runtime.rs:152`
- Test: `tests/compat_config_test.rs`

- [ ] **Step 1: Write the targeted staged-root path test**

Add a focused test that proves an external configured `skill_staging` root resolves to its `skills` child and preserves current nested-skills behavior.

Add a test shape like:

```rust
let staged_root = root.join("external/skill_staging");
fs::create_dir_all(staged_root.join("skills")).unwrap();
fs::create_dir_all(staged_root.join("scenes")).unwrap();

let settings = DeepSeekSettings {
    api_key: "key".to_string(),
    base_url: "https://api.deepseek.com".to_string(),
    model: "deepseek-chat".to_string(),
    skills_dir: Some(staged_root.clone()),
};

assert_eq!(resolve_skills_dir(&root, &settings), staged_root.join("skills"));
```

- [ ] **Step 2: Run the focused config test and record the actual result**

Run:
```bash
cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture
```

Expected: either
- PASS immediately, proving current path resolution already supports the staged-root contract, or
- FAIL with a concrete staged-root regression that justifies a minimal config fix.

- [ ] **Step 3: Only if the staged-root test fails, implement the narrowest config fix**

If the test fails, update `src/compat/config_adapter.rs` so configured external staged roots resolve to the staged skill package directory used by runtime skill loading. Keep the change narrow:
- preserve current behavior for normal `skills` roots
- add the smallest extra branch needed for the failing staged-root case
- do not create a broad path-discovery system

- [ ] **Step 4: Verify runtime alignment with the resolved staged skills root**

Confirm `src/compat/runtime.rs` still uses the resolved `skills_dir` as-is. If no runtime code change is needed after the test outcome, leave the file untouched and rely on test coverage.

- [ ] **Step 5: Run the focused config tests to verify they pass**

Run:
```bash
cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture
```

Expected: PASS

- [ ] **Step 6: Commit Task 2**

```bash
git add src/compat/config_adapter.rs src/compat/runtime.rs tests/compat_config_test.rs
git commit -m "test: verify staged scene skill root resolution"
```

### Task 3: Inject Agent-Browser Scene Contract For 95598

**Files:**
- Modify: `src/runtime/engine.rs:135`
- Test: `tests/runtime_profile_test.rs`

- [ ] **Step 1: Write the failing instruction-contract tests**

Add focused tests proving that when the instruction matches `95598-repair-city-dispatch`, `RuntimeEngine::build_instruction(...)` includes a scene-specific browser contract requiring the tool `95598-repair-city-dispatch.collect_repair_orders` first.

Example assertion pattern:

```rust
let instruction = engine.build_instruction(
    "请做95598抢修市指监测",
    Some("https://example.invalid/dispatch"),
    Some("95598抢修-市指"),
    true,
);

assert!(instruction.contains("95598-repair-city-dispatch.collect_repair_orders"));
assert!(instruction.contains("browser workflow, not a text-only task"));
assert!(instruction.contains("generic browser probing only after"));
```

Also add a negative control showing unrelated tasks do not receive this scene contract.

- [ ] **Step 2: Run the focused runtime-profile tests to verify they fail**

Run:
```bash
cargo test --test runtime_profile_test 95598 -- --nocapture
```

Expected: FAIL because no scene-specific contract is injected yet.

- [ ] **Step 3: Implement minimal scene-aware prompt injection**

Update `src/runtime/engine.rs` to:
- query the new scene matcher
- when the matched scene is `agent_browser`, append a scene execution contract section
- preserve existing Zhihu prompt sections unchanged

Keep the contract explicit and narrow, for example:

```text
Scene execution contract:
- Matched scene: 95598-repair-city-dispatch
- Required tool: 95598-repair-city-dispatch.collect_repair_orders
- This is a browser workflow, not a text-only task.
- Business data must come from the matched browser-backed scene tool.
- Only use generic browser probing after the matched scene tool fails.
```

Do not add hard allowed-tool narrowing in this task; slice one only promises instruction-level enforcement.

- [ ] **Step 4: Run the focused runtime-profile tests to verify they pass**

Run:
```bash
cargo test --test runtime_profile_test 95598 -- --nocapture
```

Expected: PASS

- [ ] **Step 5: Commit Task 3**

```bash
git add src/runtime/engine.rs tests/runtime_profile_test.rs
git commit -m "feat: inject 95598 scene browser contract"
```

### Task 4: Add Direct Browser Route For Fault Details

**Files:**
- Modify: `src/compat/workflow_executor.rs:58`
- Modify: `src/compat/orchestration.rs:9`
- Modify: `src/compat/browser_script_skill_tool.rs:101`
- Test: `tests/browser_script_skill_tool_test.rs`
- Test: `tests/compat_runtime_test.rs`

- [ ] **Step 1: Write the failing route-detection tests**

Add focused tests that prove:
- natural language like `导出故障明细` is detected as a direct scene route
- primary orchestration is selected for that scene
- missing scene metadata leaves unrelated routing unchanged

Target the existing routing seams with test shapes like:

```rust
assert!(sgclaw::compat::orchestration::should_use_primary_orchestration(
    "导出故障明细",
    Some("https://example.invalid/fault"),
    Some("故障明细"),
));
```

and a focused route assertion using the new route enum variant.

- [ ] **Step 2: Run the focused route tests to verify they fail**

Run:
```bash
cargo test --test compat_runtime_test fault_details -- --nocapture
```

Expected: FAIL because no direct scene route exists yet.

- [ ] **Step 3: Write the failing browser-script helper tests**

Add focused tests in `tests/browser_script_skill_tool_test.rs` for the thinnest reusable helper needed by direct scene execution. The tests should prove that the helper:
- reads the packaged script from the skill root
- wraps args exactly like `BrowserScriptSkillTool`
- invokes browser `Eval`
- returns normalized serialized output
- fails clearly when required fields like `expected_domain` are missing

- [ ] **Step 4: Run the focused browser-script helper tests to verify they fail**

Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture
```

Expected: FAIL because the reusable helper does not exist yet.

- [ ] **Step 5: Implement the reusable browser-backed execution helper**

Update `src/compat/browser_script_skill_tool.rs` with the smallest reusable helper that direct scene execution can call while preserving the same `browser_script` semantics as normal skill execution. Keep it narrow:
- reuse the same script loading and wrapping rules
- require explicit `expected_domain`
- return normalized serialized output
- do not introduce a second browser-script execution model

- [ ] **Step 6: Implement the direct fault-details route on top of that helper**

Update `src/compat/workflow_executor.rs` to:
- introduce a new direct route variant for `fault-details-report`
- extend `detect_route(...)` to return it when the scene matcher says `direct_browser`
- build required args from scene runtime policy
- call the reusable browser-script execution helper
- return normalized serialized tool output

If required scene args cannot be derived safely, return a clear failure instead of guessing.

- [ ] **Step 7: Wire primary orchestration to prefer the new direct scene route**

Update `src/compat/orchestration.rs` so `should_use_primary_orchestration(...)` and the direct execution branch treat the new `fault-details-report` route like the existing direct Zhihu routes.

- [ ] **Step 8: Run the focused direct-route and helper tests to verify they pass**

Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture
```

Expected: PASS

- [ ] **Step 9: Commit Task 4**

```bash
git add src/compat/browser_script_skill_tool.rs src/compat/workflow_executor.rs src/compat/orchestration.rs tests/browser_script_skill_tool_test.rs tests/compat_runtime_test.rs
git commit -m "feat: add direct fault-details scene routing"
```

### Task 5: Verify Tool Exposure, Browser-Surface Fallback, And Mixed Routing Together

**Files:**
- Modify if needed: `src/compat/runtime.rs:142`
- Test: `tests/compat_runtime_test.rs`
- Test: `tests/runtime_profile_test.rs`
- Test: `tests/scene_registry_test.rs`

- [ ] **Step 1: Write the failing integration-shape tests**

Add focused assertions that prove the mixed-mode design works together:
- staged browser-backed tool names are exposed
- `fault-details-report` uses direct routing
- `95598-repair-city-dispatch` stays in the agent path but gets scene-specific browser-first instruction injection
- browser-surface-disabled turns do not gain scene browser contracts
- browser-surface-disabled turns do not trigger `direct_browser` scene execution
- missing scene metadata preserves unchanged runtime behavior for unrelated tasks
- unrelated Zhihu behavior still works the same way

Use existing test seams instead of broad integration scaffolding.

- [ ] **Step 2: Run the focused mixed-routing tests to verify they fail**

Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture
```

Expected: FAIL until the mixed-routing assertions are implemented.

- [ ] **Step 3: Make the minimum runtime adjustments needed**

Only if required by the tests, adjust `src/compat/runtime.rs` so the loaded staged skills from the resolved external root are visible in the same way as existing browser-backed skills. Keep the shape of `build_browser_script_skill_tools(...)` and runtime tool assembly intact.

- [ ] **Step 4: Run the focused mixed-routing tests to verify they pass**

Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture
```

Expected: PASS

- [ ] **Step 5: Run the broader targeted verification sweep**

Run:
```bash
cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture
```

Expected: PASS

- [ ] **Step 6: Commit Task 5**

```bash
git add src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_runtime_test.rs tests/runtime_profile_test.rs
git commit -m "feat: wire staged scene mixed routing"
```

### Task 6: Final Verification And Handoff

**Files:**
- Verify: `src/runtime/scene_registry.rs`
- Verify: `src/compat/config_adapter.rs`
- Verify: `src/runtime/engine.rs`
- Verify: `src/compat/workflow_executor.rs`
- Verify: `src/compat/orchestration.rs`
- Verify: `tests/scene_registry_test.rs`
- Verify: `tests/compat_config_test.rs`
- Verify: `tests/runtime_profile_test.rs`
- Verify: `tests/compat_runtime_test.rs`

- [ ] **Step 1: Run the full focused verification set**

Run:
```bash
cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test -- --nocapture
```

Expected: PASS

- [ ] **Step 2: If any test fails, fix only the minimal root cause and re-run the same command**

Do not broaden scope. Keep fixes limited to scene registry, path resolution, prompt injection, or direct routing.

- [ ] **Step 3: Review the resulting diff against the spec**

Manually verify:
- `fault-details-report` is direct-browser
- `95598-repair-city-dispatch` is agent-browser
- both still use browser-backed execution semantics
- no broad Zhihu refactor slipped in
- the new scene-routing abstraction stays registry-driven

- [ ] **Step 4: Commit the final verification pass**

```bash
git add src/runtime/scene_registry.rs src/runtime/mod.rs src/compat/config_adapter.rs src/runtime/engine.rs src/compat/workflow_executor.rs src/compat/orchestration.rs src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_config_test.rs tests/runtime_profile_test.rs tests/compat_runtime_test.rs
git commit -m "test: verify scene skill runtime routing"
```