mirror of
https://github.com/instructkr/claw-code.git
synced 2026-11-19 00:00:00 +08:00
cleanup: remove phase 1a documentation (owned by PR #3329)
This commit is contained in:
1 parent
e8c14616c6
commit
46eba21620
4 files changed
-1464
No files matched your search
@@ -1,221 +0,0 @@
|
|||||||
# Work Lane Report: cc-gjc-s21
|
|
||||||
|
|
||||||
**Lane ID**: cc-gjc-s21
|
|
||||||
**Parent**: Discord DM 1465266933812170793
|
|
||||||
**Issue**: #3323 [Slice 2.1] Tool catalog GJC parity
|
|
||||||
**Branch**: `lane/gjc-s21`
|
|
||||||
**Status**: ✅ PHASE 1a COMPLETE - Ready for Review/Merge
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## EXECUTIVE SUMMARY
|
|
||||||
|
|
||||||
Successfully completed **Phase 1a** of Slice 2.1, delivering a fully tested, production-ready line range selector parser for GJC-compatible read tool semantics. This foundational component enables semantic upgrades to claw-code's tool catalog.
|
|
||||||
|
|
||||||
**Deliverable Quality**:
|
|
||||||
- ✅ 13/13 unit tests passing
|
|
||||||
- ✅ Zero compiler warnings
|
|
||||||
- ✅ Comprehensive documentation (3 docs, 1,281 LOC)
|
|
||||||
- ✅ Clean, linear git history (4 commits)
|
|
||||||
- ✅ Ready for immediate integration in Phase 1b
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## WORK COMPLETED
|
|
||||||
|
|
||||||
### Feature Delivery
|
|
||||||
|
|
||||||
**1. Line Range Selector Parser** (343 LOC)
|
|
||||||
- Full GJC syntax support (`:L`, `:L-L+N`, `:L,L`, `:raw`, `:conflicts`)
|
|
||||||
- Automatic range merging for overlapping/adjacent selections
|
|
||||||
- Comprehensive error handling with typed errors
|
|
||||||
- Public API: `parse_selector(selector: &str) -> Result<LineRangeSelector, ParseError>`
|
|
||||||
|
|
||||||
**2. Test Coverage** (13 passing tests)
|
|
||||||
- Single line, ranges, multiple ranges
|
|
||||||
- Range merging (overlaps, adjacent)
|
|
||||||
- Error cases (invalid format, zero lines, start > end)
|
|
||||||
- Helper methods (zero-index conversion, length, validation)
|
|
||||||
|
|
||||||
**3. Documentation** (3 documents, 1,281 LOC)
|
|
||||||
- Gap Matrix: Complete GJC vs claw-code tool analysis (799 LOC)
|
|
||||||
- Tool Semantics: Detailed read/edit/search/find specs (337 LOC)
|
|
||||||
- Phase 1a Report: Completion metrics and next steps (287 LOC)
|
|
||||||
|
|
||||||
**4. Git History** (4 focused commits)
|
|
||||||
```
|
|
||||||
16541e98 docs: add Phase 1a completion report
|
|
||||||
baa31c75 docs: add Slice 2.1 implementation tracking log
|
|
||||||
6b8bdb2c feat: add GJC-compatible line range selector parser for read tool
|
|
||||||
1e55fb11 docs: add GJC tool semantics analysis for Batch 1
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## TECHNICAL HIGHLIGHTS
|
|
||||||
|
|
||||||
### Design Quality
|
|
||||||
- **Modular**: Isolated module (`runtime::line_range_selector`) with zero external dependencies
|
|
||||||
- **Testable**: 100% test coverage of parsing logic, edge cases included
|
|
||||||
- **Type-Safe**: Enum-based selector representation (`Raw`, `Conflicts`, `Lines`, `None`)
|
|
||||||
- **Backward Compatible**: Additive only, no breaking changes
|
|
||||||
|
|
||||||
### Code Metrics
|
|
||||||
| Metric | Value |
|
|
||||||
|--------|-------|
|
|
||||||
| Production LOC | 343 |
|
|
||||||
| Test LOC | 150+ |
|
|
||||||
| Test Count | 13 |
|
|
||||||
| Test Pass Rate | 100% |
|
|
||||||
| Compiler Warnings | 0 |
|
|
||||||
| New Dependencies | 0 |
|
|
||||||
| Build Time | ~3s |
|
|
||||||
|
|
||||||
### Verification
|
|
||||||
- `cargo test -p runtime line_range_selector` → **13 passed**
|
|
||||||
- `cargo build -p runtime` → **No warnings/errors**
|
|
||||||
- `cargo clippy -p runtime` → **No clippy warnings**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## PHASE 1 ROADMAP
|
|
||||||
|
|
||||||
### ✅ Phase 1a: Selector Parser (COMPLETE)
|
|
||||||
- Line range parsing (`:L-L+N` syntax)
|
|
||||||
- Range merging logic
|
|
||||||
- Error handling and tests
|
|
||||||
- **Status**: Ready for merge
|
|
||||||
|
|
||||||
### 🚧 Phase 1b: Tool Integration (READY TO START)
|
|
||||||
- Integrate parser into `ReadFileInput`/`ReadFileOutput`
|
|
||||||
- Apply selectors in `file_ops.rs`
|
|
||||||
- Output metadata (totalLines, totalBytes)
|
|
||||||
- Est. **600-800 LOC**, Medium complexity
|
|
||||||
|
|
||||||
### 📋 Phase 1c: Truncation Footers
|
|
||||||
- Generate recovery hints in output footer
|
|
||||||
- Structured output format updates
|
|
||||||
- Est. **300-400 LOC**, Low-Medium complexity
|
|
||||||
|
|
||||||
### 📋 Phase 1d: Structural Summarization (Optional)
|
|
||||||
- Collapse function bodies to `..`
|
|
||||||
- Hash line anchors for code structure
|
|
||||||
- Est. **400-600 LOC**, High complexity
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## NEXT IMMEDIATE STEPS
|
|
||||||
|
|
||||||
1. **Merge Phase 1a** into main (this PR is ready)
|
|
||||||
2. **Start Phase 1b** with ReadFileInput integration
|
|
||||||
- Update `rust/crates/tools/src/lib.rs:2884` (ReadFileInput struct)
|
|
||||||
- Add selector field to tool input schema
|
|
||||||
- Integrate `line_range_selector::parse_selector()` call
|
|
||||||
3. **Parallel Work**: Begin Batch 2 (EDIT tool) preparation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## REFERENCES
|
|
||||||
|
|
||||||
- **Implementation Details**: `docs/gjc-compat/PHASE-1a-COMPLETION-REPORT.md`
|
|
||||||
- **Gap Analysis**: `docs/gjc-compat/gap-matrix.md`
|
|
||||||
- **Tool Specs**: `docs/gjc-compat/tool-semantics-phase1.md`
|
|
||||||
- **Progress Log**: `docs/gjc-compat/slice-2.1-implementation-log.md`
|
|
||||||
- **GJC Reference**: `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## BUILD & TEST STATUS
|
|
||||||
|
|
||||||
```
|
|
||||||
✅ cargo build -p runtime → Success
|
|
||||||
✅ cargo test -p runtime line_range_selector → 13/13 passing
|
|
||||||
✅ cargo clippy -p runtime → No warnings
|
|
||||||
✅ cargo fmt --check → Formatted
|
|
||||||
✅ Git history → Clean, linear
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## BRANCH READINESS
|
|
||||||
|
|
||||||
| Criteria | Status | Notes |
|
|
||||||
|----------|--------|-------|
|
|
||||||
| Feature Complete | ✅ | Phase 1a fully delivered |
|
|
||||||
| Tests Passing | ✅ | 13/13, 100% pass rate |
|
|
||||||
| Documentation | ✅ | Comprehensive, 3 docs |
|
|
||||||
| No Breaking Changes | ✅ | Additive only |
|
|
||||||
| Code Quality | ✅ | Zero warnings |
|
|
||||||
| Ready for PR | ✅ | Can merge immediately |
|
|
||||||
| Ready for Phase 1b | ✅ | Clear path forward |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## RISK ASSESSMENT
|
|
||||||
|
|
||||||
| Risk | Likelihood | Impact | Mitigation |
|
|
||||||
|------|------------|--------|-----------|
|
|
||||||
| Selector parsing bugs | Low | Medium | Comprehensive tests |
|
|
||||||
| Integration complexity | Medium | High | Clear API, documented |
|
|
||||||
| Breaking existing code | Low | High | Backward compatible |
|
|
||||||
| Performance regression | Low | Low | No algorithmic changes |
|
|
||||||
|
|
||||||
**Overall Risk Level**: 🟢 LOW
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## METRICS & ACHIEVEMENTS
|
|
||||||
|
|
||||||
**Code Quality**:
|
|
||||||
- ✅ Zero technical debt introduced
|
|
||||||
- ✅ 100% test coverage of parser logic
|
|
||||||
- ✅ No external dependencies added
|
|
||||||
- ✅ No compiler warnings or clippy issues
|
|
||||||
|
|
||||||
**Documentation Quality**:
|
|
||||||
- ✅ 3 comprehensive documents created
|
|
||||||
- ✅ Clear architecture and design decisions
|
|
||||||
- ✅ Ready for new developer onboarding
|
|
||||||
- ✅ Direct references to GJC specification
|
|
||||||
|
|
||||||
**Delivery Quality**:
|
|
||||||
- ✅ 4 focused, well-described commits
|
|
||||||
- ✅ Linear git history (no merge commits)
|
|
||||||
- ✅ Each commit is independently buildable
|
|
||||||
- ✅ Ready for bisect-friendly debugging
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## PUBLIC TEXT CLEARANCE
|
|
||||||
|
|
||||||
All documentation and commit messages:
|
|
||||||
- ✅ No internal host paths or usernames in public output
|
|
||||||
- ✅ References to reference implementation are read-only notes
|
|
||||||
- ✅ No private infrastructure details exposed
|
|
||||||
- ✅ Public technical content suitable for GitHub
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## CONCLUSION
|
|
||||||
|
|
||||||
**Phase 1a is production-ready and can be merged immediately.** The foundation for GJC-compatible tool semantics is solid, well-tested, and documented. Phase 1b integration work can proceed in parallel or as next PR.
|
|
||||||
|
|
||||||
**Recommendation**:
|
|
||||||
1. ✅ Merge this lane into main
|
|
||||||
2. ✅ Start Phase 1b on new feature branch
|
|
||||||
3. ✅ Complete Batch 1 (read/edit/search/find) within 2 sprints
|
|
||||||
4. ✅ Begin Batch 2 preparation once Batch 1 foundations laid
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## SIGN-OFF
|
|
||||||
|
|
||||||
**Lane Status**: ✅ COMPLETE
|
|
||||||
**Merge Readiness**: ✅ READY
|
|
||||||
**Quality Gate**: ✅ PASSED
|
|
||||||
**Approval**: Ready for review
|
|
||||||
|
|
||||||
**Report Generated**: 2026-10-13
|
|
||||||
**Report Version**: 1.0
|
|
||||||
**Branch**: `lane/gjc-s21`
|
|
||||||
**Head Commit**: `16541e98`
|
|
||||||
@@ -1,287 +0,0 @@
|
|||||||
# Phase 1a Completion Report: GJC Tool Semantics - Line Range Selector
|
|
||||||
|
|
||||||
**Lane**: `lane/gjc-s21`
|
|
||||||
**Issue**: #3323 [Slice 2.1]
|
|
||||||
**Task**: Bring claw-code tools to GJC parity
|
|
||||||
**Phase**: 1a (Read Tool Selector Parser)
|
|
||||||
**Status**: ✅ COMPLETE
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## SUMMARY
|
|
||||||
|
|
||||||
Successfully implemented the foundation for GJC-compatible line range selectors for the read tool. This is the first critical component of Batch 1, enabling the semantic upgrades needed to match GJC's powerful read tool.
|
|
||||||
|
|
||||||
**Deliverable**: Fully tested line range selector parser with support for all GJC selector syntaxes.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## COMPLETED DELIVERABLES
|
|
||||||
|
|
||||||
### 1. Line Range Selector Module ✅
|
|
||||||
**File**: `rust/crates/runtime/src/line_range_selector.rs` (343 LOC)
|
|
||||||
|
|
||||||
#### Features Implemented
|
|
||||||
- **Selector Parsing**: Full support for GJC selector syntax
|
|
||||||
- `:L` - single line (e.g., `:50`)
|
|
||||||
- `:L-L` - line range (e.g., `:50-200`)
|
|
||||||
- `:L+N` - start+count (e.g., `:50+150`)
|
|
||||||
- `:L,L-L,L+N` - multiple ranges with auto-merging (e.g., `:5-16,960-973`)
|
|
||||||
- `:raw` - full verbatim output
|
|
||||||
- `:conflicts` - git merge conflict extraction only
|
|
||||||
|
|
||||||
- **Type System**
|
|
||||||
```rust
|
|
||||||
pub enum LineRangeSelector {
|
|
||||||
Raw,
|
|
||||||
Conflicts,
|
|
||||||
Lines(Vec<LineRange>),
|
|
||||||
None,
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Range Merging**: Automatic merging of overlapping/adjacent ranges
|
|
||||||
- Input: `5-16,10-20` → Output: single range `5-20`
|
|
||||||
- Input: `5-16,17-20` → Output: single range `5-20` (adjacent)
|
|
||||||
|
|
||||||
- **Error Handling**: Comprehensive error types
|
|
||||||
- `ParseError::InvalidFormat` - malformed syntax
|
|
||||||
- `ParseError::InvalidNumber` - non-numeric values
|
|
||||||
- `ParseError::InvalidRange` - logical errors (start > end, zero lines)
|
|
||||||
|
|
||||||
#### Public API
|
|
||||||
```rust
|
|
||||||
// Main entry point for selector parsing
|
|
||||||
pub fn parse_selector(selector: &str) -> Result<LineRangeSelector, ParseError>
|
|
||||||
|
|
||||||
// Structured types
|
|
||||||
pub struct LineRange {
|
|
||||||
pub start_line: usize, // 1-indexed
|
|
||||||
pub end_line: usize, // 1-indexed
|
|
||||||
}
|
|
||||||
|
|
||||||
impl LineRange {
|
|
||||||
pub fn zero_indexed(&self) -> (usize, usize)
|
|
||||||
pub fn len(&self) -> usize
|
|
||||||
pub fn is_valid(&self) -> bool
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Comprehensive Test Suite ✅
|
|
||||||
**Tests**: 13 passing tests in `line_range_selector.rs:tests` module
|
|
||||||
|
|
||||||
Coverage:
|
|
||||||
- ✅ `test_parse_raw` - Special mode parsing
|
|
||||||
- ✅ `test_parse_conflicts` - Conflict extraction mode
|
|
||||||
- ✅ `test_parse_single_line` - Simple line selection
|
|
||||||
- ✅ `test_parse_range_start_dash_end` - Dash syntax
|
|
||||||
- ✅ `test_parse_range_start_plus_count` - Plus syntax
|
|
||||||
- ✅ `test_parse_multiple_ranges` - Comma-separated ranges
|
|
||||||
- ✅ `test_merge_overlapping_ranges` - Overlapping merge behavior
|
|
||||||
- ✅ `test_merge_adjacent_ranges` - Adjacent range merge
|
|
||||||
- ✅ `test_invalid_range_start_greater_than_end` - Error handling
|
|
||||||
- ✅ `test_invalid_zero_line` - Error handling
|
|
||||||
- ✅ `test_empty_selector` - Default behavior
|
|
||||||
- ✅ `test_line_range_zero_indexed` - Index conversion
|
|
||||||
- ✅ `test_line_range_len` - Range length calculation
|
|
||||||
|
|
||||||
**Build Status**: ✅ Cargo test passes, zero warnings
|
|
||||||
|
|
||||||
### 3. Module Integration ✅
|
|
||||||
**File**: `rust/crates/runtime/src/lib.rs`
|
|
||||||
|
|
||||||
- Added public module export: `pub mod line_range_selector;`
|
|
||||||
- Module is public and ready for use by tools layer
|
|
||||||
|
|
||||||
### 4. Documentation ✅
|
|
||||||
- **Gap Matrix**: `docs/gjc-compat/gap-matrix.md` (799 LOC)
|
|
||||||
- Comprehensive analysis of GJC vs claw-code tool gaps
|
|
||||||
- Tool-by-tool specifications and semantics
|
|
||||||
- Implementation complexity estimates
|
|
||||||
|
|
||||||
- **Tool Semantics Doc**: `docs/gjc-compat/tool-semantics-phase1.md` (337 LOC)
|
|
||||||
- Detailed GJC tool specifications (read/edit/search/find)
|
|
||||||
- Current claw-code gaps analysis
|
|
||||||
- Batch implementation plan
|
|
||||||
|
|
||||||
- **Implementation Log**: `docs/gjc-compat/slice-2.1-implementation-log.md` (157 LOC)
|
|
||||||
- Phase-by-phase progress tracking
|
|
||||||
- PR planning and risk assessment
|
|
||||||
- Testing strategy
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## GIT HISTORY
|
|
||||||
|
|
||||||
```
|
|
||||||
baa31c75 docs: add Slice 2.1 implementation tracking log
|
|
||||||
6b8bdb2c feat: add GJC-compatible line range selector parser for read tool
|
|
||||||
baa31c75 docs: add Slice 2.1 implementation tracking log
|
|
||||||
1e55fb11 docs: add GJC tool semantics analysis for Batch 1
|
|
||||||
7e6981fb docs: add GJC compatibility gap matrix
|
|
||||||
```
|
|
||||||
|
|
||||||
**Branch**: Clean, linear history on `lane/gjc-s21` with descriptive commits.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ARCHITECTURAL DESIGN
|
|
||||||
|
|
||||||
### Design Decisions
|
|
||||||
|
|
||||||
1. **Separate Module**: Selector logic isolated in dedicated module for testability
|
|
||||||
2. **No External Dependencies**: Pure Rust, leverages only stdlib (zero new dependencies)
|
|
||||||
3. **Zero-Index Conversion**: Internal use with automatic 1-indexed ↔ 0-indexed conversion
|
|
||||||
4. **Range Merging**: Automatic to simplify downstream consumption
|
|
||||||
5. **Enum-Based Output**: Type-safe selector representation vs raw strings
|
|
||||||
|
|
||||||
### Integration Points (Next Phase)
|
|
||||||
|
|
||||||
The parsed selector integrates with:
|
|
||||||
- `ReadFileInput` - receives selector string, parses with `line_range_selector::parse_selector()`
|
|
||||||
- `file_ops.rs:read_file_in_workspace()` - applies selected ranges to file content
|
|
||||||
- Output formatter - generates truncation footer with recovery hints
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
|
|
||||||
This module depends on:
|
|
||||||
- `std::num::ParseIntError` (stdlib)
|
|
||||||
- Nothing else (no external crates)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## NEXT PHASES
|
|
||||||
|
|
||||||
### Phase 1b: Tool Integration (🚧 Ready to Start)
|
|
||||||
**Estimated LOC**: 600-800
|
|
||||||
**Complexity**: Medium
|
|
||||||
|
|
||||||
Tasks:
|
|
||||||
1. Extend `ReadFileInput` struct in `tools/lib.rs` to include selector field
|
|
||||||
2. Update tool specification in `mvp_tool_specs()`
|
|
||||||
3. Integrate selector parsing in `run_read_file()`
|
|
||||||
4. Update `file_ops.rs:read_file_in_workspace()` to apply ranges
|
|
||||||
5. Tests for tool-level integration
|
|
||||||
|
|
||||||
### Phase 1c: Truncation Footers & Metadata
|
|
||||||
**Estimated LOC**: 300-400
|
|
||||||
**Complexity**: Low-Medium
|
|
||||||
|
|
||||||
Tasks:
|
|
||||||
1. Extend `TextFilePayload` to include `totalLines`, `totalBytes`
|
|
||||||
2. Generate truncation footers with recovery hints
|
|
||||||
3. Tests for footer formatting
|
|
||||||
|
|
||||||
### Phase 1d: Structural Summarization (Optional)
|
|
||||||
**Estimated LOC**: 400-600
|
|
||||||
**Complexity**: High
|
|
||||||
|
|
||||||
Tasks:
|
|
||||||
1. Code language detection
|
|
||||||
2. Brace pair collapsing to `..`
|
|
||||||
3. Hash line anchor generation
|
|
||||||
4. Tests for summarization logic
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## TESTING & VERIFICATION
|
|
||||||
|
|
||||||
### Current Status
|
|
||||||
- ✅ Selector parser: 13/13 tests passing
|
|
||||||
- ✅ Compilation: Zero errors, zero warnings
|
|
||||||
- ✅ Module exports: Correctly exposed in runtime lib.rs
|
|
||||||
|
|
||||||
### Testing Coverage
|
|
||||||
- **Unit Tests**: Parsing, merging, edge cases (100% of parser logic)
|
|
||||||
- **Integration Tests**: To be added in Phase 1b (tool layer)
|
|
||||||
- **Parity Tests**: Manual comparison with GJC reference (Phase 1b+)
|
|
||||||
|
|
||||||
### Quality Metrics
|
|
||||||
- **Code Coverage**: Parser fully covered by tests
|
|
||||||
- **Error Handling**: All error paths tested
|
|
||||||
- **Edge Cases**: Zero-lines, overlaps, adjacent ranges tested
|
|
||||||
- **Performance**: Linear time complexity O(n) where n = range count
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## DEPENDENCIES & COMPATIBILITY
|
|
||||||
|
|
||||||
### Rust Version
|
|
||||||
- Edition 2021 (consistent with workspace)
|
|
||||||
- No MSRV bump required
|
|
||||||
- No new external dependencies added
|
|
||||||
|
|
||||||
### Workspace Impact
|
|
||||||
- No changes to Cargo.toml
|
|
||||||
- No new dependencies
|
|
||||||
- Additive only (new module, no breaking changes)
|
|
||||||
|
|
||||||
### Backward Compatibility
|
|
||||||
- Existing `ReadFileInput` unchanged (selector field is optional in Phase 1b)
|
|
||||||
- Default behavior when selector absent: `LineRangeSelector::None`
|
|
||||||
- No breaking changes to public APIs
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## KNOWN LIMITATIONS & FUTURE WORK
|
|
||||||
|
|
||||||
### Current Scope
|
|
||||||
- Parser only (not applied to file content yet)
|
|
||||||
- No archive/SQLite support (separate Phase)
|
|
||||||
- No structural summarization (optional)
|
|
||||||
- No context line expansion (for selected ranges)
|
|
||||||
|
|
||||||
### Design Decisions for Future Reference
|
|
||||||
- Ranges stored as 1-indexed for user-facing API consistency with GJC
|
|
||||||
- Merging is automatic (no option to preserve overlaps)
|
|
||||||
- Special modes (`:raw`, `:conflicts`) are mutually exclusive with line ranges
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## HAND-OFF & CONTINUITY
|
|
||||||
|
|
||||||
### For Phase 1b Implementation
|
|
||||||
1. **Context**: This module is ready to integrate
|
|
||||||
2. **Entry Point**: `line_range_selector::parse_selector(&selector_string)?`
|
|
||||||
3. **Type to Use**: `LineRangeSelector` enum
|
|
||||||
4. **Tests**: Run `cargo test -p runtime line_range_selector` to verify
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- Tool semantics clearly specified in `tool-semantics-phase1.md`
|
|
||||||
- GJC reference available at `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
|
||||||
- Implementation tracking in `slice-2.1-implementation-log.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## METRICS & STATISTICS
|
|
||||||
|
|
||||||
| Metric | Value |
|
|
||||||
|--------|-------|
|
|
||||||
| Code Lines (module) | 343 |
|
|
||||||
| Test Lines | 150+ |
|
|
||||||
| Test Count | 13 |
|
|
||||||
| Test Pass Rate | 100% |
|
|
||||||
| External Dependencies | 0 |
|
|
||||||
| Compiler Warnings | 0 |
|
|
||||||
| Coverage | ~100% of parser logic |
|
|
||||||
| Documentation Pages | 3 |
|
|
||||||
| Commits This Phase | 4 |
|
|
||||||
| Branch Health | ✅ Clean, linear history |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## SIGN-OFF
|
|
||||||
|
|
||||||
**Phase 1a**: ✅ COMPLETE
|
|
||||||
**Ready for Phase 1b**: ✅ YES
|
|
||||||
**Blockers**: None
|
|
||||||
**Risk Level**: Low (isolated module, comprehensive tests)
|
|
||||||
|
|
||||||
**Approved for Merge**: Ready for PR review when needed.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Document Version**: 1.0
|
|
||||||
**Created**: 2026-10-13
|
|
||||||
**Author**: Lane CC-GJC-S21
|
|
||||||
**Status**: Final
|
|
||||||
@@ -1,799 +0,0 @@
|
|||||||
# GJC Compatibility Gap Matrix
|
|
||||||
|
|
||||||
**Document Status**: Phase 1 Analysis (2026-10-13)
|
|
||||||
**Scope**: SDK wire protocol, session lifecycle, tools, skills, settings, hooks, commands, and AGENTS.md rules
|
|
||||||
**Target**: Rust fork-in-spirit of gajae-code (GJC) SDK-compatible and capability-compatible
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. EXECUTIVE SUMMARY
|
|
||||||
|
|
||||||
This matrix maps GJC capabilities (from gajae-code) against claw-code's current Rust implementation, identifying gaps and proposing crate/module ownership for each slice.
|
|
||||||
|
|
||||||
### Key Findings
|
|
||||||
|
|
||||||
| Area | Status | Priority |
|
|
||||||
|------|--------|----------|
|
|
||||||
| **SDK Wire Protocol** | Missing | P0 (Foundation) |
|
|
||||||
| **Session Lifecycle** | Partial (no SDK) | P0 (Foundation) |
|
|
||||||
| **Tool Catalog (55 tools)** | Partial (35/55) | P1 (Core) |
|
|
||||||
| **Skill Discovery** | Partial (basic) | P1 (Core) |
|
|
||||||
| **Settings & Config** | Partial | P2 (Enhancing) |
|
|
||||||
| **Hooks & Plugins** | Existing | P3 (Polish) |
|
|
||||||
| **AGENTS.md Rules** | Existing | P3 (Polish) |
|
|
||||||
| **Slash Commands (120+)** | Partial (40/120+) | P2 (Core) |
|
|
||||||
| **Subagent Delegation** | Existing | P2 (Core) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. SDK WIRE PROTOCOL
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/sdk/client/client.ts`, `sdk/host/session-runtime.ts`
|
|
||||||
|
|
||||||
GJC uses a **WebSocket-based JSON-RPC-like protocol** with:
|
|
||||||
- **Transport**: WebSocket over TCP
|
|
||||||
- **Frame Format**: JSON object with typed fields
|
|
||||||
- **Correlation**: Request/response matched by `frame.id` (UUID)
|
|
||||||
- **Operations**: 65+ operation types (Q1-Q32, C01-C06, reverse ops)
|
|
||||||
- **Error Handling**: Typed `SdkErrorCode` with `uncertain_after_send` recovery
|
|
||||||
- **Reconnect**: Exponential backoff with deadline management
|
|
||||||
- **Request Timeout**: 10s default (`DEFAULT_SDK_REQUEST_TIMEOUT_MS`), per-request override
|
|
||||||
- **Handshake**: `client.hello` with capabilities advertised; `server.hello` response
|
|
||||||
|
|
||||||
**Operations** (sample):
|
|
||||||
- **Control**: `turn.create`, `turn.prompt`, `turn.steer`, `turn.abort_and_prompt`
|
|
||||||
- **Queries**: `turn.list`, `turn.get_one`, `turn.message_list`, `skill.source`, `artifact.content`
|
|
||||||
- **Reverse**: `ask.answer`, `tool.dispatch`, `tool.fetch_capability`
|
|
||||||
|
|
||||||
**Event Schema**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": "uuid-string",
|
|
||||||
"operation": "turn.create",
|
|
||||||
"input": { ... },
|
|
||||||
"connectionId": "optional",
|
|
||||||
"settings": { ... }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Missing entirely. claw-code has no SDK wire protocol or external session API.
|
|
||||||
|
|
||||||
**Files**: None
|
|
||||||
**Lines**: 0
|
|
||||||
|
|
||||||
**Reality**:
|
|
||||||
- claw-code operates as a local CLI only (stdin/stdout/stderr).
|
|
||||||
- Sessions are file-based (`.claw/sessions/`).
|
|
||||||
- No remote access or external SDK clients.
|
|
||||||
- No WebSocket transport.
|
|
||||||
- No frame correlation or reconnect logic.
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap | Complexity |
|
|
||||||
|-----------|-----|-----------|-----|------------|
|
|
||||||
| WebSocket Transport | 1500 LOC | — | 100% | High |
|
|
||||||
| Frame Correlation | 800 LOC | — | 100% | Medium |
|
|
||||||
| Operation Registry | 400 LOC | 0 | 100% | Medium |
|
|
||||||
| Error Handling & Recovery | 600 LOC | — | 100% | High |
|
|
||||||
| Handshake & Negotiation | 200 LOC | — | 100% | Low |
|
|
||||||
| **Total** | **3,500 LOC** | **0** | **3,500 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `sdk` (new)
|
|
||||||
|
|
||||||
**Module Structure**:
|
|
||||||
```
|
|
||||||
rust/crates/sdk/
|
|
||||||
├── Cargo.toml
|
|
||||||
└── src/
|
|
||||||
├── lib.rs (exports + top-level API)
|
|
||||||
├── client/
|
|
||||||
│ ├── mod.rs (SdkClient, WebSocket transport)
|
|
||||||
│ ├── correlation.rs (frame ID tracking, reconnect)
|
|
||||||
│ └── errors.rs (SdkErrorCode, recovery)
|
|
||||||
├── protocol/
|
|
||||||
│ ├── mod.rs (Operation registry)
|
|
||||||
│ ├── operations.rs (operation definitions)
|
|
||||||
│ └── schema.rs (JSON schemas, frame validation)
|
|
||||||
├── session/
|
|
||||||
│ ├── mod.rs (session lifecycle over SDK)
|
|
||||||
│ ├── router.rs (session routing, durable state)
|
|
||||||
│ └── reconciliation.rs (uncertain outcome recovery)
|
|
||||||
└── tests/
|
|
||||||
├── mod.rs
|
|
||||||
└── fixtures/ (mock server scenarios)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Size Estimate**: 4,500 LOC (Rust + test fixtures)
|
|
||||||
|
|
||||||
**Dependencies**:
|
|
||||||
- `tokio` (async I/O, WebSocket)
|
|
||||||
- `tungstenite` (WebSocket protocol)
|
|
||||||
- `serde_json` (frame serialization)
|
|
||||||
- `uuid` (correlation IDs)
|
|
||||||
- `runtime` crate (session persistence bridge)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. SESSION LIFECYCLE
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/sdk/host/session-runtime.ts`, `sdk/client/`, `sdk/lifecycle/`
|
|
||||||
|
|
||||||
GJC sessions have **three entry points**:
|
|
||||||
1. **Native SDK** (via WebSocket): typed `SdkClient` with `session.create`, `session.prompt`, etc.
|
|
||||||
2. **Browser ACP** (via iframe): same protocol, browser sandbox isolate
|
|
||||||
3. **CLI Daemon** (stdio): JSON-RPC over stdio for local CLI access
|
|
||||||
|
|
||||||
**Session Operations**:
|
|
||||||
- **create**: `turn.create(model, input)` → returns `sessionId`, persistent state written to broker DB
|
|
||||||
- **prompt**: `turn.prompt(request, tools, settings)` → streams events: `agent_begin`, `tool_use`, `tool_result`, `agent_end`
|
|
||||||
- **steer**: `turn.steer(overrides)` → mid-flight direction change (model, settings, system prompt)
|
|
||||||
- **abort**: `turn.abort_and_prompt()` → terminal failure + new prompt in one operation
|
|
||||||
- **list**: `turn.list(filters)` → paginated session history
|
|
||||||
- **get_one**: `turn.get_one(sessionId, turnId)` → single turn with full details
|
|
||||||
|
|
||||||
**State Persistence**:
|
|
||||||
- Invocation record (prompt request, outcome, correlation)
|
|
||||||
- Message buffer (system, assistant, tool results, agent events)
|
|
||||||
- Reconciliation store (uncertain → durable mapping)
|
|
||||||
- Terminal scope (last session per correlation key)
|
|
||||||
|
|
||||||
**Lifecycle Events**:
|
|
||||||
1. `turn_accepted` (immediate, transient)
|
|
||||||
2. `agent_begin` (before first model call)
|
|
||||||
3. `tool_use` + `tool_result` (interleaved)
|
|
||||||
4. `agent_end` (final model output)
|
|
||||||
5. `turn_ended` (durable, terminal outcome recorded)
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Partial. Local session lifecycle exists but no SDK transport or remote access.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/runtime/src/session.rs` (1,961 LOC)
|
|
||||||
- `rust/crates/runtime/src/conversation.rs` (1,878 LOC)
|
|
||||||
- `rust/crates/runtime/src/session_control.rs` (file ops, migration)
|
|
||||||
- `rust/crates/runtime/src/lib.rs` (re-exports `Session`, `SessionStore`, `ConversationRuntime`)
|
|
||||||
|
|
||||||
**Lines**: ~3,900 LOC (session + conversation)
|
|
||||||
|
|
||||||
**Reality**:
|
|
||||||
- `Session` struct holds in-memory state (messages, usage, context).
|
|
||||||
- `SessionStore` reads/writes `.claw/sessions/{id}/` directory.
|
|
||||||
- `ConversationRuntime` drives the local agent loop (sync).
|
|
||||||
- No WebSocket or remote access.
|
|
||||||
- No invocation reconciliation or uncertain outcome recovery.
|
|
||||||
- No terminal scope tracking (per-session-per-correlation).
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap | Complexity |
|
|
||||||
|-----------|-----|-----------|-----|------------|
|
|
||||||
| Remote Session Router | 2,500 LOC | — | 100% | High |
|
|
||||||
| Invocation Reconciliation | 1,200 LOC | — | 100% | High |
|
|
||||||
| Terminal Scope Tracking | 600 LOC | — | 100% | Medium |
|
|
||||||
| Async Event Streaming | 800 LOC | Partial | 60% | Medium |
|
|
||||||
| Uncertain Outcome Recovery | 1,000 LOC | — | 100% | High |
|
|
||||||
| **Total** | **6,100 LOC** | **3,900** | **2,200 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `sdk` (new, or extend `runtime`)
|
|
||||||
|
|
||||||
**Module Structure** (add to `sdk/session/`):
|
|
||||||
```
|
|
||||||
sdk/session/
|
|
||||||
├── router.rs (session routing, durable lookup)
|
|
||||||
├── reconciliation.rs (uncertain → terminal recovery)
|
|
||||||
├── terminal_scope.rs (per-correlation state retention)
|
|
||||||
└── events.rs (event publishing, reconciliation)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Integration Points**:
|
|
||||||
- Bridge `runtime::Session` into `sdk::Session` wrapper
|
|
||||||
- Add `runtime::SessionStore` extensions for reconciliation data
|
|
||||||
- Extend `ConversationRuntime` with event emission
|
|
||||||
|
|
||||||
**Size Estimate**: 2,500 LOC (Rust, new + modifications)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. TOOL CATALOG (55 Tools)
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/tools/` (55 tool files + shared harness)
|
|
||||||
|
|
||||||
GJC implements **55 distinct tools** across multiple domains:
|
|
||||||
- **File I/O**: `read`, `write`, `edit`, `search`, `find`
|
|
||||||
- **Shell**: `bash`, `sleep`
|
|
||||||
- **Task Delegation**: `task` (subagent spawning)
|
|
||||||
- **Workflow**: `skill`, `skill_discovery`, `goal`, `ask`
|
|
||||||
- **Search**: `search_tool_bm25` (semantic search discovery)
|
|
||||||
- **Image**: `image_gen` (DALL-E), `image_tag_scan`
|
|
||||||
- **Integration**: `web_fetch`, `web_search`, `custom_tool_fetch`
|
|
||||||
- **Developer**: `notebook_edit`, `command_repl`, `shell_repl`, `powershell`
|
|
||||||
- **Config**: `config_read`, `config_write` (settings, modes)
|
|
||||||
- **Structured**: `model_registry`, `cost_calculator`, `settings_apply`
|
|
||||||
- **Workflow Gates**: `workflow_gate_answer`, `workflow_plan_approve`
|
|
||||||
- **Move**: `move_cwd`, `move_session`
|
|
||||||
|
|
||||||
**Tool Execution Model**:
|
|
||||||
1. Input deserialized from JSON schema
|
|
||||||
2. Permission check (read-only vs. destructive)
|
|
||||||
3. Tool invocation with typed inputs
|
|
||||||
4. Structured output or error
|
|
||||||
5. Result published to agent loop
|
|
||||||
|
|
||||||
**Permission Gating**: Every tool has a `required_permission` (read-only, approve, unsafe).
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Partial. 35 tools implemented, 20 missing or incomplete.
|
|
||||||
|
|
||||||
**Files**: `rust/crates/tools/src/lib.rs` (10,892 LOC, single file with all 55 spec + implementations)
|
|
||||||
|
|
||||||
**Implemented Tools** (~35):
|
|
||||||
- `read`, `write`, `edit`, `search`, `find`
|
|
||||||
- `bash`, `sleep`
|
|
||||||
- `task` (subagent spawning)
|
|
||||||
- `skill`, `skill_discovery` (basic)
|
|
||||||
- `bash_list_*, bash_check_*` (validation helpers)
|
|
||||||
- `web_fetch`, `search_bm25` (basic)
|
|
||||||
- `config_*` (read/write settings)
|
|
||||||
- `notebooks` (edit, execute)
|
|
||||||
- `goal` (basic ledger)
|
|
||||||
- `move_*` (cwd, session)
|
|
||||||
- Various validation and utility tools
|
|
||||||
|
|
||||||
**Missing / Incomplete Tools** (~20):
|
|
||||||
- `image_gen` (DALL-E)
|
|
||||||
- `image_tag_scan`
|
|
||||||
- `custom_tool_fetch`
|
|
||||||
- `command_repl`, `shell_repl`, `powershell`
|
|
||||||
- `model_registry`, `cost_calculator`
|
|
||||||
- `workflow_gate_answer`, `workflow_plan_approve`
|
|
||||||
- `ask` (interactive prompt)
|
|
||||||
- `irc` (live coordination)
|
|
||||||
- Search/discovery integration tools
|
|
||||||
- Advanced structured output handling
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap | Complexity |
|
|
||||||
|-----------|-----|-----------|-----|------------|
|
|
||||||
| Tool Registry | 400 LOC | 400 LOC | 0% | — |
|
|
||||||
| Spec Table (55 entries) | 1,800 LOC | 1,800 LOC | 0% | — |
|
|
||||||
| image_gen | 600 LOC | — | 100% | High |
|
|
||||||
| command_repl, shell_repl | 900 LOC | — | 100% | Medium |
|
|
||||||
| workflow_gate_* | 800 LOC | — | 100% | Medium |
|
|
||||||
| custom_tool_fetch | 400 LOC | — | 100% | Low |
|
|
||||||
| ask (interactive) | 1,200 LOC | Stub | 80% | High |
|
|
||||||
| cost_calculator | 300 LOC | — | 100% | Low |
|
|
||||||
| **Total** | **11,500 LOC** | **8,000** | **3,500 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `tools` (expand existing)
|
|
||||||
|
|
||||||
**New Modules**:
|
|
||||||
```
|
|
||||||
rust/crates/tools/src/
|
|
||||||
├── tools/
|
|
||||||
│ ├── image_gen.rs (DALL-E integration)
|
|
||||||
│ ├── ask_interactive.rs (blocking user prompts)
|
|
||||||
│ ├── workflow_gates.rs (plan approval, gate answer)
|
|
||||||
│ ├── repl/*.rs (command_repl, shell_repl, powershell)
|
|
||||||
│ └── cost_calc.rs (pricing lookup)
|
|
||||||
└── vendors/
|
|
||||||
├── dalle.rs (image generation API)
|
|
||||||
└── integrations.rs (custom tool fetch)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Size Estimate**: 3,500 LOC (new tools + vendor integration)
|
|
||||||
|
|
||||||
**Dependencies**:
|
|
||||||
- `reqwest` (image generation API calls)
|
|
||||||
- `api` crate (provider client reuse)
|
|
||||||
- Existing: `runtime`, `commands`, `serde_json`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. SKILL DISCOVERY & INVOCATION
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/tools/skill-discovery.ts`, `packages/coding-agent/src/tools/skill.ts`, `packages/coding-agent/src/sdk-skills/`
|
|
||||||
|
|
||||||
GJC supports **dynamic skill loading** with:
|
|
||||||
- **Discovery**: `skill_discovery` tool scans `.gjc/skills/`, project `.gjc/skills/`, bundled skills
|
|
||||||
- **Frontmatter Parsing**: YAML headers in `SKILL.md` define metadata (name, description, use conditions)
|
|
||||||
- **Invocation**: `skill` tool loads and executes a named skill (skill name + args)
|
|
||||||
- **Skill Execution**: Skill = subprocess call to `gjc /skill:<name>` with args
|
|
||||||
- **Bundled Skills**: `autoresearch`, `deep-interview`, `ralplan`, `ultragoal`
|
|
||||||
- **Project Skills**: Discoverable from `.gjc/skills/*/SKILL.md`
|
|
||||||
- **User Skills**: Discoverable from `~/.gjc/skills/*/SKILL.md`
|
|
||||||
|
|
||||||
**Skill Metadata**:
|
|
||||||
```yaml
|
|
||||||
# /skill:my-skill
|
|
||||||
# description: What this skill does
|
|
||||||
# scope: project | user | bundled
|
|
||||||
# requires: List of capabilities
|
|
||||||
```
|
|
||||||
|
|
||||||
**Skill Discovery Result**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "skill-name",
|
|
||||||
"description": "...",
|
|
||||||
"path": "...",
|
|
||||||
"bundled": true | false,
|
|
||||||
"scope": "project" | "user" | "bundled"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Basic. Skill discovery exists but limited to filesystem scanning.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/tools/src/lib.rs` (skill_discovery + skill dispatch, ~200 LOC)
|
|
||||||
- `rust/crates/runtime/src/prompt.rs` (skill loading in prompts, ~100 LOC)
|
|
||||||
|
|
||||||
**Implementation**:
|
|
||||||
- Scans `.claw/skills/` directory for `SKILL.md` files
|
|
||||||
- Parses frontmatter (basic YAML)
|
|
||||||
- Returns discovery results as JSON
|
|
||||||
- `skill` tool invokes skill as subprocess
|
|
||||||
|
|
||||||
**Missing**:
|
|
||||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
|
||||||
- Project + user skill discovery hierarchy
|
|
||||||
- Frontmatter validation and standardization
|
|
||||||
- Skill chaining (`skill()` tool to invoke another skill from within a skill)
|
|
||||||
- Skill state persistence (workflow handoff)
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap | Complexity |
|
|
||||||
|-----------|-----|-----------|-----|------------|
|
|
||||||
| Bundled Skill Registry | 200 LOC | — | 100% | Low |
|
|
||||||
| Frontmatter Parser | 150 LOC | 100 LOC | 30% | Low |
|
|
||||||
| Project + User Discovery | 300 LOC | Basic | 70% | Low |
|
|
||||||
| Skill Chaining | 250 LOC | — | 100% | Medium |
|
|
||||||
| Workflow State Handoff | 400 LOC | — | 100% | Medium |
|
|
||||||
| Skill Execution Harness | 200 LOC | Partial | 40% | Low |
|
|
||||||
| **Total** | **1,500 LOC** | **100** | **1,400 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `tools` (expand existing) or `skills` (new, lightweight)
|
|
||||||
|
|
||||||
**Module Structure**:
|
|
||||||
```
|
|
||||||
rust/crates/tools/src/
|
|
||||||
├── skill_discovery.rs (enhanced parsing, project/user/bundled hierarchy)
|
|
||||||
├── skill_execution.rs (subprocess dispatch, state handoff)
|
|
||||||
├── bundled_skills.rs (registry of autoresearch, deep-interview, ralplan, ultragoal)
|
|
||||||
└── skill_state.rs (workflow handoff serialization)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Size Estimate**: 1,400 LOC (Rust)
|
|
||||||
|
|
||||||
**Integration**:
|
|
||||||
- Extend `skill_discovery` tool to search three scopes (bundled, project, user)
|
|
||||||
- Add `skill` tool support for chaining (returning another skill invocation)
|
|
||||||
- Store workflow state in durable files for handoff
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. SETTINGS & CONFIGURATION
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/config.ts`, `packages/coding-agent/src/sdk/host/session-runtime.ts`
|
|
||||||
|
|
||||||
GJC supports **settings override** at multiple levels:
|
|
||||||
1. **Global Settings**: `~/.gjc/config.json` (user defaults)
|
|
||||||
2. **Session Settings**: per-session override via `turn.create` or `turn.prompt` input
|
|
||||||
3. **Runtime Override**: `settings` field in SDK request frames
|
|
||||||
4. **Setting Categories**:
|
|
||||||
- **Model**: `modelName`, `modelTemperature`, `modelMaxTokens`
|
|
||||||
- **Behavior**: `allowance`, `permissions.*`, `features.*`
|
|
||||||
- **UX**: `theme`, `shell`, `notification*`
|
|
||||||
- **Advanced**: `memory.context`, `memory.compression`, `cost.*`
|
|
||||||
|
|
||||||
**Config Schema**: Typed with JSON schema validation per setting
|
|
||||||
|
|
||||||
**Permission Modes**:
|
|
||||||
- `read_only` (no execution)
|
|
||||||
- `approve` (interactive approval)
|
|
||||||
- `unsafe` (no gates)
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Partial. Config exists but no session-level override or setting propagation.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/runtime/src/config.rs` (3,894 LOC, largest file in runtime)
|
|
||||||
- `rust/crates/runtime/src/config_validate.rs` (validation helpers)
|
|
||||||
|
|
||||||
**Implementation**:
|
|
||||||
- Reads `.claw/config.json` at startup
|
|
||||||
- Stores global settings (model, permissions, plugins, features)
|
|
||||||
- No session-level override
|
|
||||||
- No setting propagation through tool execution
|
|
||||||
- No typed setting validation against schema
|
|
||||||
|
|
||||||
**Missing**:
|
|
||||||
- Per-session setting override (session-specific model, permissions)
|
|
||||||
- Setting propagation to all tool invocations
|
|
||||||
- Dynamic setting application (e.g., changing model mid-session)
|
|
||||||
- Setting schema validation
|
|
||||||
- Config hotreload (changes without restart)
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap | Complexity |
|
|
||||||
|-----------|-----|-----------|-----|------------|
|
|
||||||
| Setting Schema Definition | 300 LOC | — | 100% | Low |
|
|
||||||
| Session-Level Override | 400 LOC | — | 100% | Medium |
|
|
||||||
| Setting Propagation | 300 LOC | — | 100% | Low |
|
|
||||||
| Dynamic Application | 200 LOC | — | 100% | Medium |
|
|
||||||
| Config Hotreload | 150 LOC | — | 100% | Low |
|
|
||||||
| **Total** | **1,350 LOC** | **3,894** | **-2,544 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `runtime` (enhance existing `config.rs`)
|
|
||||||
|
|
||||||
**Additions to config.rs**:
|
|
||||||
- Setting schema registry
|
|
||||||
- Session setting override struct
|
|
||||||
- Setting applicator (merge global + session + override)
|
|
||||||
- Hotreload support (watch config file, signal on change)
|
|
||||||
|
|
||||||
**Size Estimate**: 500 LOC (new code, mostly schema + applicators)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. HOOKS & PLUGINS
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/hooks.ts`, `packages/coding-agent/src/plugin_lifecycle.ts`
|
|
||||||
|
|
||||||
GJC provides **5 hook points**:
|
|
||||||
- `on_session_created`: After session starts
|
|
||||||
- `on_prompt_received`: Before agent loop begins
|
|
||||||
- `on_tool_use`: Before tool invocation
|
|
||||||
- `on_tool_result`: After tool completes
|
|
||||||
- `on_session_ended`: Before session cleanup
|
|
||||||
|
|
||||||
**Plugin System**:
|
|
||||||
- Plugins are shell scripts or binaries in `.claw/plugins/`
|
|
||||||
- Each plugin implements hook handlers (exit code + JSON output)
|
|
||||||
- Plugin registry stored in config
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Existing and comprehensive.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/runtime/src/hooks.rs` (L155)
|
|
||||||
- `rust/crates/runtime/src/plugin_lifecycle.rs`
|
|
||||||
- `rust/crates/plugins/src/` (plugin manager)
|
|
||||||
|
|
||||||
**Implementation**: Hooks fully implemented; plugin system working.
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap |
|
|
||||||
|-----------|-----|-----------|-----|
|
|
||||||
| Hook Points | 5 | 5 | 0% |
|
|
||||||
| Plugin Registry | ✓ | ✓ | 0% |
|
|
||||||
| Plugin Execution | ✓ | ✓ | 0% |
|
|
||||||
|
|
||||||
**Status**: **No gaps**. Hooks and plugins are fully compatible.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. AGENTS.MD RULES & CONTEXT
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: gajae-code root + `docs/` (AGENTS.md files at multiple levels)
|
|
||||||
|
|
||||||
GJC loads **directory-specific rules** from `AGENTS.md` files:
|
|
||||||
- **Root AGENTS.md**: Project-level knowledge base
|
|
||||||
- **Directory AGENTS.md**: Directory-specific rules override parent
|
|
||||||
- **Rules Loaded**: Automatically prepended to system prompt during agent reasoning
|
|
||||||
- **Hierarchy**: Deepest (most specific) rules override higher level
|
|
||||||
|
|
||||||
**Rule Content**:
|
|
||||||
- Code organization and conventions
|
|
||||||
- Tool restrictions (never use X in Y context)
|
|
||||||
- Testing requirements
|
|
||||||
- Deployment/safety gates
|
|
||||||
- Architecture decisions
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Existing and matching GJC.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- Root: `AGENTS.md`
|
|
||||||
- Crate-level: `rust/crates/*/AGENTS.md`
|
|
||||||
- Implementation: `rust/crates/runtime/src/` (loads rules)
|
|
||||||
|
|
||||||
**Implementation**: Rules loaded and applied to prompts.
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap |
|
|
||||||
|-----------|-----|-----------|-----|
|
|
||||||
| Rule Loading | ✓ | ✓ | 0% |
|
|
||||||
| Hierarchy | ✓ | ✓ | 0% |
|
|
||||||
| Prompt Integration | ✓ | ✓ | 0% |
|
|
||||||
|
|
||||||
**Status**: **No gaps**. AGENTS.md system is compatible.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. SLASH COMMANDS (120+ Commands)
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/commands/lib.ts` (7,200 LOC with 120+ command specs)
|
|
||||||
|
|
||||||
GJC implements **120+ slash commands** for REPL interaction:
|
|
||||||
- **Session**: `/session list`, `/session create`, `/session restore`, `/session delete`
|
|
||||||
- **Model**: `/model set`, `/model list`, `/model info`
|
|
||||||
- **Permissions**: `/permissions set`, `/permissions show`
|
|
||||||
- **Config**: `/config get`, `/config set`, `/config reload`
|
|
||||||
- **Skills**: `/skills list`, `/skills install`, `/skills create`
|
|
||||||
- **Plugins**: `/plugins list`, `/plugins install`
|
|
||||||
- **Workflow**: `/plan`, `/review`, `/approve`, `/ultragoal`
|
|
||||||
- **Debugging**: `/debug`, `/dump`, `/trace`
|
|
||||||
- **Utilities**: `/help`, `/clear`, `/quit`, `/export`
|
|
||||||
|
|
||||||
**Command Format**: `/command [arg1] [arg2] ...` with arg parsing per command
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Partial. ~40 commands implemented out of 120+.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/commands/src/lib.rs` (7,183 LOC)
|
|
||||||
- Command specs in `SLASH_COMMAND_SPECS` static table
|
|
||||||
|
|
||||||
**Implemented Commands** (~40):
|
|
||||||
- Session mgmt (list, create, etc.)
|
|
||||||
- Help, status, version
|
|
||||||
- Config (get, set, reload)
|
|
||||||
- Skills (list, install)
|
|
||||||
- Plugins (list, install)
|
|
||||||
- Workspace/debug (clear, compact, etc.)
|
|
||||||
|
|
||||||
**Missing Commands** (~80):
|
|
||||||
- Advanced workflow (`/plan`, `/review`, `/ultragoal`)
|
|
||||||
- Model selection and info
|
|
||||||
- Cost calculator (`/cost`)
|
|
||||||
- Advanced debugging (`/dump`, `/trace`)
|
|
||||||
- Theme management
|
|
||||||
- Advanced permission controls
|
|
||||||
- Task management (`/tasks list`, `/tasks cancel`)
|
|
||||||
- IRC/coordination (`/irc`)
|
|
||||||
- Many others
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap |
|
|
||||||
|-----------|-----|-----------|-----|
|
|
||||||
| Command Parser | 800 LOC | 800 LOC | 0% |
|
|
||||||
| Spec Table (120+ entries) | 2,000 LOC | 2,000 LOC | 0% |
|
|
||||||
| Handlers (80 missing) | 3,200 LOC | 1,800 LOC | 56% |
|
|
||||||
| Help/suggestion | 600 LOC | 400 LOC | 30% |
|
|
||||||
| **Total** | **7,200 LOC** | **4,000** | **3,200 LOC** | — |
|
|
||||||
|
|
||||||
### Proposed Implementation
|
|
||||||
|
|
||||||
**Owner Crate**: `commands` (expand existing)
|
|
||||||
|
|
||||||
**New Modules**:
|
|
||||||
```
|
|
||||||
rust/crates/commands/src/
|
|
||||||
├── handlers/
|
|
||||||
│ ├── workflow.rs (/plan, /review, /approve, /ultragoal)
|
|
||||||
│ ├── model.rs (/model set, /model list, /model info)
|
|
||||||
│ ├── cost.rs (/cost)
|
|
||||||
│ ├── advanced_debug.rs (/dump, /trace, /debug advanced)
|
|
||||||
│ ├── theme.rs (/theme set, /theme list)
|
|
||||||
│ ├── task.rs (/tasks list, /tasks cancel)
|
|
||||||
│ └── advanced_perms.rs (advanced permission commands)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Size Estimate**: 3,200 LOC (new command handlers)
|
|
||||||
|
|
||||||
**Dependencies**: `runtime`, `tools`, `plugins`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. SUBAGENT DELEGATION & TASK EXECUTION
|
|
||||||
|
|
||||||
### GJC Behavior (gajae-code Reference)
|
|
||||||
|
|
||||||
**Source**: `packages/coding-agent/src/tools/task.ts`, `packages/coding-agent/src/task/`
|
|
||||||
|
|
||||||
GJC's **subagent system** enables parallel task execution:
|
|
||||||
- **task Tool**: Spawn parallel subtasks with independent context
|
|
||||||
- **Task States**: spawning, running, succeeded, failed
|
|
||||||
- **Task Isolation**: Each task has isolated session, permissions, context
|
|
||||||
- **Task Coordination**: `irc` tool for live inter-task communication
|
|
||||||
- **Task Monitoring**: `task.inspect`, `task.list`, `task.cancel`
|
|
||||||
- **Artifact Sharing**: Tasks share artifact URLs but not direct state
|
|
||||||
|
|
||||||
**Task Spawning**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"agent": "executor|architect|planner",
|
|
||||||
"tasks": [
|
|
||||||
{
|
|
||||||
"id": "task-1",
|
|
||||||
"description": "...",
|
|
||||||
"assignment": "..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### claw-code Status
|
|
||||||
|
|
||||||
**Current**: Existing and working.
|
|
||||||
|
|
||||||
**Files**:
|
|
||||||
- `rust/crates/tools/src/lib.rs` (task tool, ~300 LOC)
|
|
||||||
- `rust/crates/runtime/src/task_*.rs` (task execution, state mgmt)
|
|
||||||
|
|
||||||
**Implementation**: Task tool works; spawning, monitoring, and coordination functional.
|
|
||||||
|
|
||||||
### Gap Assessment
|
|
||||||
|
|
||||||
| Component | GJC | claw-code | Gap |
|
|
||||||
|-----------|-----|-----------|-----|
|
|
||||||
| Task Spawning | ✓ | ✓ | 0% |
|
|
||||||
| Task Isolation | ✓ | ✓ | 0% |
|
|
||||||
| Task Monitoring | ✓ | ✓ | 0% |
|
|
||||||
| IRC Coordination | ✓ | ✓ | 0% |
|
|
||||||
|
|
||||||
**Status**: **No significant gaps**. Task execution is compatible.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. IMPLEMENTATION ROADMAP
|
|
||||||
|
|
||||||
### Phase 1: Foundation (SDK Wire Protocol)
|
|
||||||
|
|
||||||
**Slice 1.1: WebSocket Transport & Frame Correlation**
|
|
||||||
- Create `sdk` crate structure
|
|
||||||
- Implement `SdkClient` with WebSocket connection
|
|
||||||
- Add frame ID correlation and response matching
|
|
||||||
- Add reconnect logic with exponential backoff
|
|
||||||
- Tests: transport connectivity, frame correlation, reconnect behavior
|
|
||||||
|
|
||||||
**Slice 1.2: Operation Registry & Schema**
|
|
||||||
- Define Operation enum (65+ operation types)
|
|
||||||
- JSON schema validation for requests
|
|
||||||
- Error code definitions and handlers
|
|
||||||
- Uncertain outcome recovery protocol
|
|
||||||
- Tests: operation parsing, schema validation, error scenarios
|
|
||||||
|
|
||||||
**Slice 1.3: Session SDK Integration**
|
|
||||||
- Bridge `runtime::Session` to SDK session model
|
|
||||||
- Implement session router (durable lookup)
|
|
||||||
- Add invocation reconciliation store
|
|
||||||
- Terminal scope tracking per correlation
|
|
||||||
- Tests: session creation, routing, reconciliation
|
|
||||||
|
|
||||||
### Phase 2: Core Capabilities (Tools & Skills)
|
|
||||||
|
|
||||||
**Slice 2.1: Missing Tool Implementation**
|
|
||||||
- `image_gen` (DALL-E integration)
|
|
||||||
- `ask` (interactive blocking prompts)
|
|
||||||
- `workflow_gate_*` (plan approval gates)
|
|
||||||
- `command_repl`, `shell_repl`, `powershell`
|
|
||||||
- `cost_calculator`
|
|
||||||
|
|
||||||
**Slice 2.2: Skill Enhancement**
|
|
||||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
|
||||||
- Enhanced skill discovery (project, user, bundled hierarchy)
|
|
||||||
- Skill chaining support (skill calling skill)
|
|
||||||
- Workflow state handoff
|
|
||||||
|
|
||||||
### Phase 3: Polish (Settings, Commands, Integration)
|
|
||||||
|
|
||||||
**Slice 3.1: Settings & Configuration**
|
|
||||||
- Session-level setting override
|
|
||||||
- Setting schema validation
|
|
||||||
- Setting propagation to tools
|
|
||||||
- Config hotreload
|
|
||||||
|
|
||||||
**Slice 3.2: Slash Commands**
|
|
||||||
- Workflow commands (/plan, /review, /ultragoal)
|
|
||||||
- Model selection (/model set, /model list)
|
|
||||||
- Cost calculator (/cost)
|
|
||||||
- Advanced debugging (/dump, /trace)
|
|
||||||
- Task management (/tasks list, /tasks cancel)
|
|
||||||
- Theme management (/theme)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. DEPENDENCY & CRATE RELATIONSHIPS
|
|
||||||
|
|
||||||
```
|
|
||||||
┌────────────────────────────────────────────────────────┐
|
|
||||||
│ cli (rusty-claude-cli: main entry, REPL, TUI) │
|
|
||||||
└────────────┬───────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌────────────▼──────────────────────────────────────────┐
|
|
||||||
│ commands (slash command specs & handlers) │
|
|
||||||
└────────┬────────────────────────────────────────┬──────┘
|
|
||||||
│ │
|
|
||||||
│ ┌───▼────────────────────┐
|
|
||||||
│ │ tools (55 tool impl) │
|
|
||||||
│ └──────┬─────────────────┘
|
|
||||||
│ │
|
|
||||||
┌────────▼─────────────────────────────────────────▼──────────────────┐
|
|
||||||
│ runtime (session, conversation, config, mcp, hooks, permissions) │
|
|
||||||
└────────┬──────────────────────────────┬────────────────────────────┘
|
|
||||||
│ │
|
|
||||||
┌────▼──────────────┐ ┌──────▼─────────────────┐
|
|
||||||
│ api (providers) │ │ plugins (plugin mgmt) │
|
|
||||||
└───────────────────┘ └───────────────────────┘
|
|
||||||
|
|
||||||
NEW: sdk (WebSocket, session routing, reconciliation)
|
|
||||||
│
|
|
||||||
└─→ depends on: runtime, serde_json, tokio, tungstenite
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. RISK & MITIGATION
|
|
||||||
|
|
||||||
| Risk | Probability | Severity | Mitigation |
|
|
||||||
|------|-------------|----------|-----------|
|
|
||||||
| SDK protocol complexity | High | High | Start with mock transport tests, iterate on real scenarios |
|
|
||||||
| Session state inconsistency | Medium | High | Comprehensive reconciliation tests, durable state verification |
|
|
||||||
| Tool compatibility gaps | Medium | Medium | Tool-by-tool comparison with GJC, shadow testing |
|
|
||||||
| Breaking changes to runtime | Medium | High | Version gates, feature flags, phased rollout |
|
|
||||||
| Performance regression | Medium | Medium | Benchmark key paths (session create, tool dispatch), profile |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. VERIFICATION & SIGN-OFF
|
|
||||||
|
|
||||||
- [ ] SDK transport connects and communicates with mock server
|
|
||||||
- [ ] Session lifecycle operations (create, prompt, steer, abort) work end-to-end
|
|
||||||
- [ ] Tool execution with SDK matches GJC behavior
|
|
||||||
- [ ] Skill discovery finds all three scopes (bundled, project, user)
|
|
||||||
- [ ] Settings override works per-session
|
|
||||||
- [ ] Slash commands parse and dispatch correctly
|
|
||||||
- [ ] All AGENTS.md tests pass
|
|
||||||
- [ ] Hooks fire at correct lifecycle points
|
|
||||||
- [ ] Subagent tasks spawn and communicate via IRC
|
|
||||||
- [ ] Public documentation has no internal paths, hosts, or private infra
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Document Version**: 1.0
|
|
||||||
**Last Updated**: 2026-10-13
|
|
||||||
**Next Review**: After Slice 1.1 implementation complete
|
|
||||||
@@ -1,157 +0,0 @@
|
|||||||
# Slice 2.1 Implementation Log: GJC Tool Catalog Semantic Parity
|
|
||||||
|
|
||||||
**Issue**: #3323
|
|
||||||
**Branch**: `lane/gjc-s21`
|
|
||||||
**Target**: Bring read/edit/search/find tools to GJC semantics
|
|
||||||
**Status**: In Progress
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Completed Work
|
|
||||||
|
|
||||||
### Phase 1a: Read Tool Selector Parser ✅
|
|
||||||
**Commit**: `6b8bdb2c`
|
|
||||||
**Date**: 2026-10-13
|
|
||||||
|
|
||||||
**Components**:
|
|
||||||
- ✅ New module: `rust/crates/runtime/src/line_range_selector.rs` (343 LOC)
|
|
||||||
- ✅ Line range selector parsing (`:L`, `:L-L+N` syntax)
|
|
||||||
- ✅ Special modes (`:raw`, `:conflicts`)
|
|
||||||
- ✅ Range merging logic for multi-range selectors
|
|
||||||
- ✅ 13 unit tests, all passing
|
|
||||||
|
|
||||||
**Details**:
|
|
||||||
- Supports formats: `:50`, `:50-200`, `:50+150`, `:5-16,960-973`
|
|
||||||
- Automatically merges overlapping/adjacent ranges
|
|
||||||
- Type: `LineRangeSelector` enum with variants: `Raw`, `Conflicts`, `Lines(Vec<LineRange>)`, `None`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## In-Progress Work
|
|
||||||
|
|
||||||
### Phase 1b: Integration into ReadFileOutput (🚧)
|
|
||||||
**Target**: Next commit
|
|
||||||
**Scope**:
|
|
||||||
- [ ] Update `ReadFileInput` struct in `rust/crates/tools/src/lib.rs` to include selector field
|
|
||||||
- [ ] Update `read_file()` function signature to accept selector parameter
|
|
||||||
- [ ] Implement selector application in `read_file_in_workspace()`
|
|
||||||
- [ ] Update output format to include truncation footer
|
|
||||||
- [ ] Add tests for selector integration
|
|
||||||
|
|
||||||
**Estimated LOC**: 600-800
|
|
||||||
**Complexity**: Medium
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Remaining Work (Planned)
|
|
||||||
|
|
||||||
### Phase 1c: Truncation Footers & Metadata
|
|
||||||
**Target**: After 1b
|
|
||||||
**Scope**:
|
|
||||||
- [ ] Add `totalLines` field to output
|
|
||||||
- [ ] Add `totalBytes` field to output
|
|
||||||
- [ ] Generate truncation footer with recovery hints
|
|
||||||
- [ ] Format footer: `[Showing lines X-Y of Z; re-read path:1-Z for full file]`
|
|
||||||
- [ ] Add tests for footer generation
|
|
||||||
|
|
||||||
**Estimated LOC**: 300-400
|
|
||||||
|
|
||||||
### Phase 1d: Structural Summarization (Optional - Lower Priority)
|
|
||||||
**Target**: Later
|
|
||||||
**Scope**:
|
|
||||||
- [ ] Collapse function bodies to `..` for code files
|
|
||||||
- [ ] Preserve full lines for prose
|
|
||||||
- [ ] Add hash line anchors for structural boundaries
|
|
||||||
- [ ] Support code language detection
|
|
||||||
|
|
||||||
**Estimated LOC**: 400-600
|
|
||||||
**Complexity**: High
|
|
||||||
|
|
||||||
### Batch 2: EDIT Tool Enhancements
|
|
||||||
**Target**: After Batch 1 complete
|
|
||||||
**Scope**:
|
|
||||||
- [ ] Add patch metadata to output (line numbers, context)
|
|
||||||
- [ ] Ensure exact match semantics
|
|
||||||
- [ ] Add comprehensive tests
|
|
||||||
|
|
||||||
**Estimated LOC**: 200-300
|
|
||||||
|
|
||||||
### Batch 3: SEARCH/FIND Tools
|
|
||||||
**Target**: After Batches 1-2
|
|
||||||
**Scope**:
|
|
||||||
- [ ] Enhance grep with structured output
|
|
||||||
- [ ] Enhance find with metadata (file type, modified)
|
|
||||||
- [ ] Add filtering options
|
|
||||||
|
|
||||||
**Estimated LOC**: 400-500
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## PR Plan
|
|
||||||
|
|
||||||
### PR 1: Read Selector Parser (Phase 1a) ✅
|
|
||||||
**Status**: Merged
|
|
||||||
**Scope**: Selector parsing logic
|
|
||||||
**Files**: `line_range_selector.rs` + lib.rs exports
|
|
||||||
**Tests**: 13 unit tests
|
|
||||||
|
|
||||||
### PR 2: Read Selector Integration (Phase 1b-1c)
|
|
||||||
**Status**: Next
|
|
||||||
**Scope**: ReadFileInput/Output update + integration
|
|
||||||
**Files**: `tools/lib.rs`, `file_ops.rs`, tests
|
|
||||||
**Size**: ~1000 LOC
|
|
||||||
|
|
||||||
### PR 3: EDIT Tool Enhancements (Batch 2)
|
|
||||||
**Status**: Planned
|
|
||||||
**Scope**: Output format enhancements
|
|
||||||
**Size**: ~200 LOC
|
|
||||||
|
|
||||||
### PR 4: SEARCH/FIND Tools (Batch 3)
|
|
||||||
**Status**: Planned
|
|
||||||
**Scope**: Output format & filtering
|
|
||||||
**Size**: ~400 LOC
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Testing Strategy
|
|
||||||
|
|
||||||
Each phase includes:
|
|
||||||
1. **Unit Tests**: Core functions (parsing, selection, formatting)
|
|
||||||
2. **Integration Tests**: End-to-end tool invocation
|
|
||||||
3. **Parity Tests**: Compare outputs against GJC reference (manual)
|
|
||||||
|
|
||||||
### Test Files
|
|
||||||
- `rust/crates/runtime/src/line_range_selector.rs:tests` ✅ (13 tests)
|
|
||||||
- `rust/crates/runtime/src/file_ops.rs:tests` (to be extended)
|
|
||||||
- `rust/crates/tools/src/lib.rs:tests` (to be extended)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Risk Assessment
|
|
||||||
|
|
||||||
| Risk | Mitigation | Priority |
|
|
||||||
|------|-----------|----------|
|
|
||||||
| Large refactor breaks existing tests | Keep changes isolated, extend existing structs | High |
|
|
||||||
| GJC semantics unclear | Reference gajae-code/tools/read.ts directly | High |
|
|
||||||
| Performance regression | Benchmark file ops against baseline | Medium |
|
|
||||||
| Windows path handling | Use existing normalize_for_comparison logic | Medium |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## References
|
|
||||||
|
|
||||||
- **GJC Read Tool**: `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
|
||||||
- **Gap Matrix**: `docs/gjc-compat/gap-matrix.md`
|
|
||||||
- **Semantics Doc**: `docs/gjc-compat/tool-semantics-phase1.md`
|
|
||||||
- **Current Implementation**: `rust/crates/runtime/src/file_ops.rs:713`
|
|
||||||
- **Tool Input Schema**: `rust/crates/tools/src/lib.rs:2884`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **Immediate** (this turn): Implement Phase 1b (ReadFileInput/Output integration)
|
|
||||||
2. **Short-term** (next commit): Add Phase 1c (truncation footers)
|
|
||||||
3. **Medium-term**: Batch 2 (EDIT tool) and Batch 3 (SEARCH/FIND)
|
|
||||||
4. **Verification**: Manual parity testing against GJC reference
|
|
||||||
5. **Merge**: Create focused PRs, merge when checks pass
|
|
||||||
Reference in new issue
Block a user