# SGClaw ZeroClaw Core Realignment Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Rebuild `sgclaw` as a security-hardened zeroclaw runtime where the browser is a privileged tool surface and client host, not the product's defining execution model.

**Architecture:** `zeroclaw` remains the real agent core for prompt building, skills, memory, tool routing, autonomy, and execution loops. `sgclaw` adds a security envelope around zeroclaw: hardened configuration defaults, MAC-validated pipe communication, browser-host revalidation, and constrained exposure of privileged tools. The browser stays important, but only as one protected execution surface.

**Tech Stack:** Rust, vendored `zeroclaw`, SuperRPA browser pipe protocol, Chromium WebUI/overlay, JSON config, HMAC/MAC policy rules.

## Scope Guard

- In scope:
  - zeroclaw-first runtime restructuring
  - security and tool policy layering
  - browser pipe re-framing as privileged tool surface
  - documentation correction before code changes
  - browser UI wording and observability alignment
- Out of scope:
  - broad UI redesign before the runtime contract is fixed
  - indiscriminately enabling every zeroclaw built-in tool
  - keeping parallel browser-only and zeroclaw-first runtime stacks long-term

## Task 1: Rewrite The Product Docs Before Touching Runtime Code

**Files:**
- Modify: `docs/README.md`
- Modify: `docs/L0-产品白皮书与能力全景层.md`
- Modify: `docs/L1-系统架构与安全模型层.md`
- Modify: `docs/L2-核心模块与接口契约层.md`
- Modify: `docs/L3-数据流与Skill体系层.md`
- Modify: `docs/L4-工程实现与部署拓扑层.md`
- Modify: `docs/L5-提示词分布与安全改造方案.md`
- Modify: `docs/浏览器对接标准.md`

**Intent:**
- Make the docs the single source of truth before implementation starts.
- Remove the misleading framing that `sgclaw` is fundamentally a browser execution core.
- Replace it with the correct framing: `sgclaw` is a security-hardened zeroclaw distribution with a privileged browser execution surface.

**Step 1: Add a docs checklist in the plan branch**

Checklist to apply consistently across the docs:

```text
1. zeroclaw is the runtime core
2. sgclaw adds security policy and protected execution surfaces
3. browser pipe is one privileged tool surface, not the whole runtime
4. docs must distinguish current implementation gaps from target architecture
5. no doc may imply that browser-only compat is the desired end state
```

**Step 2: Update the architecture docs**

Required wording changes:

- Replace phrases equivalent to “浏览器智能体执行内核” with wording equivalent to “安全加固后的 zeroclaw runtime”.
- Reframe `compat` as a temporary adaptation layer, not the final product identity.
- Clarify that `browser_action` is a protected tool contract, not the only capability sgClaw should ever have.
- Clarify that prompt治理、安全摘要、skills、memory、routing should stay aligned with zeroclaw-native mechanisms.

**Step 3: Run doc consistency checks**

Run:

```bash
rg -n "浏览器智能体执行内核|单一 `browser_action` 工具|兼容执行器" docs
rg -n "zeroclaw.*核心|特权工具面|安全加固" docs
```

Expected:
- The first command should only return historical or explicitly marked current-state references.
- The second command should show the new target framing in the mainline docs.

**Step 4: Commit**

```bash
git add docs/README.md docs/L0-产品白皮书与能力全景层.md docs/L1-系统架构与安全模型层.md docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md docs/L4-工程实现与部署拓扑层.md docs/L5-提示词分布与安全改造方案.md docs/浏览器对接标准.md
git commit -m "docs: redefine sgclaw as hardened zeroclaw runtime"
```

## Task 2: Introduce A Zeroclaw-First Runtime Module

**Files:**
- Create: `src/runtime/mod.rs`
- Create: `src/runtime/profile.rs`
- Create: `src/runtime/tool_policy.rs`
- Create: `src/runtime/engine.rs`
- Modify: `src/lib.rs`
- Test: `tests/runtime_profile_test.rs`

**Intent:**
- Create a real runtime namespace that represents sgClaw’s zeroclaw-first architecture.
- Stop letting `compat/runtime.rs` be the place where product architecture is defined.

**Step 1: Write the failing tests**

Create `tests/runtime_profile_test.rs` with at least:

```rust
#[test]
fn browser_attached_profile_exposes_browser_surface_without_becoming_browser_only() {
    let profile = RuntimeProfile::BrowserAttached;
    let policy = ToolPolicy::for_profile(profile);

    assert!(policy.allowed_tools.contains("browser_action"));
    assert!(policy.may_use_non_browser_tools);
}

#[test]
fn general_assistant_profile_does_not_require_browser_surface() {
    let profile = RuntimeProfile::GeneralAssistant;
    let policy = ToolPolicy::for_profile(profile);

    assert!(!policy.requires_browser_surface);
}
```

**Step 2: Run the tests to confirm failure**

Run:

```bash
cargo test --test runtime_profile_test -- --nocapture
```

Expected:
- Fail with unresolved imports or missing types for `RuntimeProfile` and `ToolPolicy`.

**Step 3: Add the minimal runtime module**

Implement the first-pass skeleton:

```rust
pub enum RuntimeProfile {
    BrowserAttached,
    BrowserHeavy,
    GeneralAssistant,
}

pub struct ToolPolicy {
    pub requires_browser_surface: bool,
    pub may_use_non_browser_tools: bool,
    pub allowed_tools: Vec<String>,
}
```

**Step 4: Re-run the focused tests**

Run:

```bash
cargo test --test runtime_profile_test -- --nocapture
```

Expected:
- Both new tests pass.

**Step 5: Commit**

```bash
git add src/runtime/mod.rs src/runtime/profile.rs src/runtime/tool_policy.rs src/runtime/engine.rs src/lib.rs tests/runtime_profile_test.rs
git commit -m "feat: add zeroclaw-first runtime module skeleton"
```

## Task 3: Replace DeepSeek-Only Settings With Zeroclaw-First SGClaw Settings

**Files:**
- Modify: `src/config/settings.rs`
- Modify: `src/config/mod.rs`
- Modify: `src/compat/config_adapter.rs`
- Test: `tests/compat_config_test.rs`
- Test: `tests/compat_memory_test.rs`
- Test: `tests/compat_cron_test.rs`

**Intent:**
- Stop treating browser config as only a DeepSeek shim.
- Introduce sgClaw settings that can express zeroclaw-first runtime behavior while staying backward-compatible with the existing `sgclaw_config.json`.

**Step 1: Add the failing config tests**

Add tests beside the existing ones in `tests/compat_config_test.rs`:

```rust
#[test]
fn sgclaw_settings_default_to_compact_skills_and_browser_attached_profile() {
    let settings = SgClawSettings::from_legacy_deepseek_fields(
        "sk-test".into(),
        "https://api.deepseek.com".into(),
        "deepseek-chat".into(),
        None,
    ).unwrap();

    assert_eq!(settings.runtime_profile, RuntimeProfile::BrowserAttached);
    assert_eq!(settings.skills_prompt_mode, SkillsPromptMode::Compact);
}

#[test]
fn sgclaw_settings_load_new_runtime_fields_from_browser_config() {
    // write config with runtimeProfile / skillsPromptMode / allowedToolProfiles
}
```

**Step 2: Run the focused tests**

Run:

```bash
cargo test --test compat_config_test -- --nocapture
```

Expected:
- Fail because `SgClawSettings`, `RuntimeProfile`, or new parsing fields do not exist yet.

**Step 3: Implement backward-compatible settings expansion**

Minimal target shape:

```rust
pub struct SgClawSettings {
    pub provider_api_key: String,
    pub provider_base_url: String,
    pub provider_model: String,
    pub skills_dir: Option<PathBuf>,
    pub skills_prompt_mode: SkillsPromptMode,
    pub runtime_profile: RuntimeProfile,
}
```

Compatibility rules:
- Existing `apiKey/baseUrl/model/skillsDir` continue to load.
- New fields such as `skillsPromptMode` and `runtimeProfile` are optional.
- Defaults should be hardened, not legacy-full-prompt by accident.

**Step 4: Run the config and adapter tests**

Run:

```bash
cargo test --test compat_config_test -- --nocapture
cargo test --test compat_memory_test -- --nocapture
cargo test --test compat_cron_test -- --nocapture
```

Expected:
- All pass.

**Step 5: Commit**

```bash
git add src/config/settings.rs src/config/mod.rs src/compat/config_adapter.rs tests/compat_config_test.rs tests/compat_memory_test.rs tests/compat_cron_test.rs
git commit -m "feat: add zeroclaw-first sgclaw settings model"
```

## Task 4: Rebuild The Execution Path Around The New Runtime Engine

**Files:**
- Modify: `src/compat/runtime.rs`
- Modify: `src/agent/mod.rs`
- Modify: `src/compat/event_bridge.rs`
- Test: `tests/compat_runtime_test.rs`

**Intent:**
- Make `compat/runtime.rs` a thin bridge into the new runtime engine instead of the place where the product’s core execution policy lives.
- Keep browser-originated tasks attached to a browser surface, but do not collapse the runtime into a browser-only tool list.

**Step 1: Add the failing runtime tests**

Extend `tests/compat_runtime_test.rs` with at least:

```rust
#[test]
fn compat_runtime_can_complete_a_text_only_turn_without_browser_tool_calls() {
    // provider returns direct assistant content
    // no BrowserMessage::Response is queued
    // summary should still succeed
}

#[test]
fn compat_runtime_allows_read_skill_under_compact_mode_policy() {
    // configure compact skills mode
    // verify the runtime tool policy includes read_skill
}
```

**Step 2: Run the focused runtime test file**

Run:

```bash
cargo test --test compat_runtime_test -- --nocapture
```

Expected:
- Fail because the current runtime still hardcodes browser-only exposure or cannot express the new policy.

**Step 3: Refactor the runtime path**

Implementation target:

- `src/agent/mod.rs` decides the runtime profile and passes browser context into the runtime engine.
- `src/compat/runtime.rs` becomes a compatibility bridge, not the architecture center.
- `src/runtime/engine.rs` owns:
  - zeroclaw agent creation
  - tool registration
  - skill loading
  - runtime profile application
  - browser contract prompt injection only when browser surface is actually present

**Step 4: Re-run the focused runtime tests**

Run:

```bash
cargo test --test compat_runtime_test -- --nocapture
```

Expected:
- Existing compat runtime tests still pass.
- New text-only / compact-skill tests pass.

**Step 5: Commit**

```bash
git add src/compat/runtime.rs src/agent/mod.rs src/compat/event_bridge.rs tests/compat_runtime_test.rs
git commit -m "refactor: route browser requests through zeroclaw-first runtime engine"
```

## Task 5: Treat The Browser Pipe As A Privileged Tool Surface

**Files:**
- Modify: `src/compat/browser_tool_adapter.rs`
- Modify: `src/pipe/protocol.rs`
- Modify: `src/pipe/browser_tool.rs`
- Modify: `src/security/mac_policy.rs`
- Test: `tests/compat_browser_tool_test.rs`
- Test: `tests/browser_tool_test.rs`
- Test: `tests/pipe_protocol_test.rs`
- Test: `tests/pipe_handshake_test.rs`

**Intent:**
- Keep the browser powerful, but explicitly as a protected external execution surface.
- Preserve the current HMAC/MAC/rules boundary while making it obvious in code that browser execution is not synonymous with runtime execution.

**Step 1: Add the failing tests**

Examples:

```rust
#[test]
fn browser_tool_contract_is_marked_as_privileged_surface_in_policy_metadata() {
    // assert runtime metadata treats browser tool separately from generic tools
}

#[test]
fn browser_submit_task_can_carry_browser_context_without_forcing_browser_only_execution() {
    // protocol/adapter level test
}
```

**Step 2: Run the safety-related tests**

Run:

```bash
cargo test --test compat_browser_tool_test -- --nocapture
cargo test --test browser_tool_test -- --nocapture
cargo test --test pipe_protocol_test -- --nocapture
cargo test --test pipe_handshake_test -- --nocapture
```

Expected:
- Fail on new privilege/metadata expectations before implementation.

**Step 3: Implement the policy split**

Implementation target:
- keep `browser_action` schema constrained
- keep `MacPolicy` as the final guard on outbound browser commands
- annotate browser surface metadata in the runtime/tool policy layer
- avoid leaking browser-only assumptions into generic runtime config

**Step 4: Re-run the focused browser safety tests**

Run the same four commands from Step 2.

Expected:
- All pass.

**Step 5: Commit**

```bash
git add src/compat/browser_tool_adapter.rs src/pipe/protocol.rs src/pipe/browser_tool.rs src/security/mac_policy.rs tests/compat_browser_tool_test.rs tests/browser_tool_test.rs tests/pipe_protocol_test.rs tests/pipe_handshake_test.rs
git commit -m "feat: model browser pipe as privileged runtime surface"
```

## Task 6: Restore Zeroclaw-Native Skills Instead Of Browser-Specific Skill Prompt Hacks

**Files:**
- Modify: `src/runtime/engine.rs`
- Modify: `src/compat/event_bridge.rs`
- Modify: `src/agent/mod.rs`
- Test: `tests/compat_runtime_test.rs`
- Test: `tests/skill_lib_validation_test.py`

**Intent:**
- Make skill loading and skill usage follow zeroclaw-native behavior first.
- Prefer compact mode plus `read_skill` when safe.
- Make skill usage observable in runtime logs so the browser UI can explain what happened.

**Step 1: Add the failing skill-observability tests**

Add tests for:
- compact mode includes `read_skill`
- runtime logs show when `read_skill` or skill-defined tools are invoked
- configured `skillsDir` still resolves both repo-root and nested `skills/` layouts

**Step 2: Run the skill-related tests**

Run:

```bash
cargo test --test compat_runtime_test -- --nocapture
python3 tests/skill_lib_validation_test.py
```

Expected:
- New observability assertions fail before implementation.

**Step 3: Implement the minimal skill-first runtime behavior**

Implementation target:
- compact skills mode becomes the sgClaw default unless explicitly overridden
- `read_skill` is allowed when the active tool policy permits it
- runtime logs include loaded skill names and actual skill/tool usage

**Step 4: Re-run the skill tests**

Run the same two commands from Step 2.

Expected:
- Both pass.

**Step 5: Commit**

```bash
git add src/runtime/engine.rs src/compat/event_bridge.rs src/agent/mod.rs tests/compat_runtime_test.rs tests/skill_lib_validation_test.py
git commit -m "feat: restore zeroclaw-native skill flow and observability"
```

## Task 7: Remove Or Quarantine The Legacy Parallel Runtime Paths

**Files:**
- Modify or delete: `src/agent/runtime.rs`
- Modify or delete: `src/agent/planner.rs`
- Modify: `tests/agent_runtime_test.rs`
- Modify: `tests/planner_test.rs`
- Modify: `docs/L2-核心模块与接口契约层.md`
- Modify: `docs/L3-数据流与Skill体系层.md`

**Intent:**
- Stop shipping multiple conceptual runtimes.
- If the light runtime/planner path still has value, mark it as legacy/dev-only.
- If it has no production value, remove it after the zeroclaw-first runtime is stable.

**Step 1: Decide the disposition**

Choose one:

```text
A. delete planner/runtime legacy path
B. keep as explicit legacy/dev-only module with zero production routing
```

Recommendation: `B` first, then `A` after one clean release cycle.

**Step 2: Add the failing cleanup tests**

Examples:
- production browser path never routes into planner fallback
- docs no longer describe planner fallback as the primary model-enabled path

**Step 3: Run the legacy-path tests**

Run:

```bash
cargo test --test agent_runtime_test -- --nocapture
cargo test --test planner_test -- --nocapture
```

Expected:
- Fail once the cleanup assertions are added.

**Step 4: Apply the cleanup**

Implementation target:
- remove production routing dependency
- rename or mark legacy modules clearly
- update docs to match the new reality

**Step 5: Re-run the legacy-path tests and commit**

Run the same two commands, then:

```bash
git add src/agent/runtime.rs src/agent/planner.rs tests/agent_runtime_test.rs tests/planner_test.rs docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md
git commit -m "refactor: quarantine legacy browser-only runtime paths"
```

## Task 8: Align The Browser UI With The New Runtime Truth

**Files:**
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js`
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
- Modify: `/home/zyl/projects/superRpa/src/AGENTS.md`

**Intent:**
- Make the browser UI an honest client of the runtime.
- Stop labeling all tasks as “网页执行” when the runtime may have solved them through non-browser zeroclaw capabilities.

**Step 1: Add the UI contract checklist**

Checklist:

```text
1. UI shows runtime profile or capability mode
2. UI can show whether browser tools were actually used
3. UI can show when skills were read or invoked
4. wording does not imply browser is the whole runtime
```

**Step 2: Implement the label and observability changes**

Examples:
- replace fixed “网页执行” copy with runtime-derived capability wording
- add a compact “本轮调用”/“能力来源” section
- avoid implying every successful task came from page automation

**Step 3: Verify browser resources**

Run:

```bash
node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome
```

Expected:
- All pass.

**Step 4: Commit**

```bash
git -C /home/zyl/projects/superRpa/src add chrome/browser/resources/superrpa/sgclaw_overlay.js chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts AGENTS.md
git -C /home/zyl/projects/superRpa/src commit -m "feat: align browser ui with zeroclaw-first runtime"
```

## Final Verification Matrix

Run, in order:

```bash
cargo test --test runtime_profile_test -- --nocapture
cargo test --test compat_config_test -- --nocapture
cargo test --test compat_runtime_test -- --nocapture
cargo test --test compat_browser_tool_test -- --nocapture
cargo test --test browser_tool_test -- --nocapture
cargo test --test pipe_protocol_test -- --nocapture
cargo test --test pipe_handshake_test -- --nocapture
cargo test --test agent_runtime_test -- --nocapture
cargo test --test planner_test -- --nocapture
python3 tests/skill_lib_validation_test.py
```

If local Cargo registry state is unstable, use the Chromium hermetic wrapper instead:

```bash
python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml -- --nocapture
```

Then verify browser integration:

```bash
node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome
```

## Success Criteria

- The docs say the right thing before the code change begins.
- `sgclaw` behaves like a security-hardened zeroclaw runtime, not a browser-only compat shell.
- The browser pipe remains central for protected execution, but it is no longer mistaken for the whole product architecture.
- Skills, prompt building, memory, routing, and tool policy all flow through zeroclaw-native mechanisms first.
- The UI becomes a thin, honest client of the shared runtime.
