Skip to content

HANDOVER.md

Latest commit

 

History

History
258 lines (184 loc) · 7.29 KB

HANDOVER.md

File metadata and controls

258 lines (184 loc) · 7.29 KB

Handover

Project Goal

This repository is a clean-room Rust rewrite of:

  • StartripAI/a-fork-of-instructor-claude-code as the primary repo1 structural and behavioral baseline
  • ultraworkers/claw-code-parity as the repo2 compatibility baseline

The working rule is:

  • mirror public behavior and internal module boundaries
  • preserve root src/ structure parity with repo1
  • do not copy upstream source, prose, or line-by-line implementation

Current Status

As of 2026-04-03, the workspace is in a good handoff state:

  • repo1 behavioral coverage: 100.0
  • repo1 structural coverage: 100.0
  • repo1 structural gate: true
  • repo2 command coverage: 100.0
  • repo2 tool coverage: 100.0
  • repo2 real tool coverage: 100.0
  • repo2 moderate tool coverage: 100.0
  • repo2 promoted stub count: 17

Authoritative manifest:

  • parity_manifest.toml

Primary reference repos used during freeze/score:

  • repo1: /Users/star/proj_out/_refs/a-fork-of-instructor-claude-code
  • repo2: /Users/star/proj_out/_refs/claw-code-parity

Repository Shape

The repository now has two layers:

  1. Root package clawcode

    • main binary lives at src/main.rs
    • root src/ mirrors repo1 layout
    • root modules increasingly own application behavior

  2. Helper crates under crates/

    • still provide lower-level implementations and compatibility scaffolding
    • should continue shrinking in application ownership over time

Important note:

  • this directory is not a Git repository right now
  • git status from the repo root fails because .git is absent

Root-Owned Areas

These are already meaningfully owned by root src/:

  • CLI startup chain
    • src/main.rs
    • src/entrypoints/cli.rs
    • src/entrypoints/init.rs
    • src/entrypoints/server.rs
    • src/entrypoints/remote.rs
    • src/entrypoints/repl.rs
    • src/entrypoints/voice.rs
  • command dispatch surface
    • src/commands.rs
    • src/commands/mod.rs
    • root-owned command modules under src/commands/*/mod.rs
  • bridge and services wrappers
    • src/bridge/*
    • src/services/*
  • root query wrapper
    • src/QueryEngine.rs
  • root tool registry and first migrated tool tranche
    • src/tools.rs
    • src/tools/mod.rs
    • src/tools/shared/mod.rs
    • root-owned tool modules:
      • ConfigTool
      • EnterPlanModeTool
      • ExitPlanModeTool
      • EnterWorktreeTool
      • ExitWorktreeTool
      • FileReadTool
      • FileWriteTool
      • FileEditTool
      • GlobTool
      • GrepTool
      • SleepTool
      • SyntheticOutputTool
      • TodoWriteTool
      • ToolSearchTool
      • testing

Important Recent Changes

1. Root CLI owns startup

The root package now owns the main startup path. crates/claw-cli is a thin wrapper over root:

  • root startup: src/main.rs -> src/entrypoints/cli.rs
  • wrapper only: crates/claw-cli/src/lib.rs

2. Root commands own more behavior

src/commands.rs intercepts a substantial set of commands before falling back to the helper crate. Root command modules now exist in repo1-style directories.

3. Root tools now have a real registry

src/tools.rs now exposes RootToolRegistry, which:

  • merges root-owned tool specs with fallback helper-crate specs
  • resolves aliases at the root layer
  • dispatches selected tools through clean-room root implementations
  • falls back to crates/tools for the rest

4. Root QueryEngine uses root tools for direct tool execution

src/QueryEngine.rs now keeps a root tool registry and routes:

  • tool_specs()
  • run_tool(...)

through root ownership instead of directly exposing helper-crate tools.

5. Runtime bootstrap now respects the current launch directory

crates/runtime/src/lib.rs was corrected so config.cwd is overwritten with the actual current startup directory. This fixed a real bug where:

  • doctor
  • direct tool execution
  • workspace path resolution

could accidentally use a stale persisted directory from an older session.

Known Caveat

The biggest remaining ownership gap is this:

  • direct tool execution through root QueryEngine::run_tool(...) now uses the root tool registry
  • but prompt execution inside crates/runtime::AppRuntime::execute_prompt(...) still uses the helper-crate ToolRegistry

That means there are currently two tool paths:

  1. Root path
    • used by root wrappers and direct root tool calls
  2. Runtime helper path
    • used by provider-driven tool loops inside AppRuntime

This is still behaviorally correct under current tests and harness scores, but it is the most important remaining clean-room migration target if the goal is "full internal rewrite" rather than only parity.

Recommended Next Steps

Priority 1: unify runtime tool ownership

Best next move:

  • migrate AppRuntime so provider tool loops use root-owned tool dispatch
  • remove the split between RootToolRegistry and helper-crate runtime tool execution

Likely touch points:

  • src/QueryEngine.rs
  • src/tools.rs
  • crates/runtime/src/lib.rs

Priority 2: keep moving application orchestration into root src/

Good next subsystems to deepen:

  • components
  • hooks
  • ink
  • screens
  • additional tools/*

Priority 3: continue turning mirrored anchors into real modules

Many repo1-style paths exist already for structural parity. The best ongoing migration pattern is:

  • keep the path
  • add a real mod.rs
  • move one responsibility at a time into root
  • keep helper crates as thin implementations only

Verification Commands

Use these commands after any meaningful migration:

cargo fmt
cargo test --workspace
cargo run -p compat-harness -- freeze --repo1 /Users/star/proj_out/_refs/a-fork-of-instructor-claude-code --repo2 /Users/star/proj_out/_refs/claw-code-parity --out /Users/star/proj_out/clawcode/parity_manifest.toml
cargo run -p compat-harness -- score --manifest /Users/star/proj_out/clawcode/parity_manifest.toml
cargo run -- --output-format json doctor
cargo run -- --output-format json prompt /mcp

Useful smoke checks:

cargo run -- prompt /skills
cargo run -- prompt '/memory root-owned note'
cargo run -- prompt /clear
cargo run -- prompt /diff

Current Expected Verification State

At handoff time, these are expected to pass:

  • cargo test --workspace
  • cargo run -p compat-harness -- score --manifest /Users/star/proj_out/clawcode/parity_manifest.toml
  • cargo run -- --output-format json doctor
  • cargo run -- --output-format json prompt /mcp

Expected score highlights:

  • repo1 command coverage 100.0
  • repo1 tool coverage 100.0
  • repo1 structural gate true
  • repo2 command coverage 100.0
  • repo2 tool coverage 100.0

Expected doctor highlights:

  • "cwd": "/Users/star/proj_out/clawcode"
  • root binary starts from current workspace

High-Value Files

If someone is resuming this work, start here:

  • Cargo.toml
  • src/main.rs
  • src/lib.rs
  • src/entrypoints/cli.rs
  • src/commands.rs
  • src/commands/mod.rs
  • src/tools.rs
  • src/tools/mod.rs
  • src/tools/shared/mod.rs
  • src/QueryEngine.rs
  • crates/runtime/src/lib.rs
  • crates/compat-harness/src/main.rs
  • parity_manifest.toml

Working Principles

  • keep the rewrite clean-room
  • do not copy upstream code or wording
  • preserve repo1-shaped paths and responsibilities
  • prefer moving ownership into root src/ rather than adding new application logic to helper crates
  • do not accept harness score regression during migration