From baa31c7515e3d51fc9fd356b5c29505e2b52d19e Mon Sep 17 00:00:00 2001 From: clawdbot Date: Mon, 12 Oct 2026 23:41:37 +0000 Subject: [PATCH] docs: add Slice 2.1 implementation tracking log --- .../slice-2.1-implementation-log.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 docs/gjc-compat/slice-2.1-implementation-log.md diff --git a/docs/gjc-compat/slice-2.1-implementation-log.md b/docs/gjc-compat/slice-2.1-implementation-log.md new file mode 100644 index 00000000..0360ff46 --- /dev/null +++ b/docs/gjc-compat/slice-2.1-implementation-log.md @@ -0,0 +1,157 @@ +# 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)`, `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