docs: add trace-id eventness lanes and bump to 0.2.7

marcnulu · marcnulu · commit 103b266077f6 · 2026-03-03T10:49:50.000-08:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "recur"
-version = "0.2.6"
+version = "0.2.7"
 edition = "2021"
 authors = ["User Level Up Contributors"]
 description = "Recursive hierarchical search tool for modern codebases - Honoring Dennis Ritchie's 1968 thesis (58 years of recursive hierarchies)"
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <div align="center">
   <h1>recur</h1>
-  <div class="version">v0.2.6</div>
+  <div class="version">v0.2.7</div>
   <p>
     <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
     <a href="https://www.rust-lang.org/"><img alt="Rust 1.70+" src="https://img.shields.io/badge/rust-1.70%2B-blue.svg"></a>
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-a.0.2.6
+a.0.2.7
diff --git a/docs/main.improvement.8.todo.future-plan.md b/docs/main.improvement.8.todo.future-plan.md
@@ -6,3 +6,12 @@ Improvement 8 is planned for future work.
 
 Reference:
 - `README.CORE.IMPROVEMENT8.md`
+
+Active lane (2026-03-03):
+- `docs/main.improvement.8.trace-id.todo.current.md`
+
+Current focus:
+- Build-now `trace-id` MVP (command surface + built-in heuristics + tests)
+
+Deferred from Improvement 8 to Improvement 9:
+- `docs/main.improvement.9.trace-id.todo.future-plan.md`
diff --git a/docs/main.improvement.8.trace-id.todo.current.md b/docs/main.improvement.8.trace-id.todo.current.md
@@ -0,0 +1,52 @@
+# Improvement 8: trace-id MVP
+
+Status: `todo.current` (active)
+Date: 2026-03-03
+
+## Goal
+
+Implement a build-now `trace-id` MVP that can trace hierarchical identifier flow using built-in heuristics and existing recur infrastructure.
+
+## In Scope (Now)
+
+1. Add `recur trace-id` CLI command surface.
+2. Implement built-in role classification for identifier matches:
+   - `define`
+   - `produce`
+   - `consume`
+   - `trigger`
+3. Support scope/ext/stdin filtering consistent with existing content-search commands.
+4. Add JSON output and human-readable terminal output for traced identifier flows.
+5. Reuse traversal guardrails (`--depth-guard`, `--force`) where applicable.
+6. Add unit and Julia integration tests for MVP behavior.
+
+## Out of Scope (Deferred)
+
+Deferred to Improvement 9:
+
+1. Project-custom heuristic config (`.recur/trace-id.toml`).
+2. `merge --edge-type` semantic lane stitching.
+3. Full multi-lane composition across call/route/config graphs.
+
+## Working Files
+
+- `src/main.rs`
+- `src/main_command_trace_id_impl.rs` (new)
+- `src/search.rs` (trace-id support)
+- `src/output.rs` (trace-id formatting)
+- `julia-tests/main.command.trace-id.test.jl` (new)
+- `julia-tests/runtests.trace-id.jl` (new)
+- `docs/main.command.trace-id.readme.md` (new)
+
+## Success Criteria
+
+1. `recur trace-id --help` documents command usage and examples.
+2. `recur trace-id "<id>" --scope "**"` produces stable JSON and terminal output.
+3. MVP tests pass for define/produce/consume/trigger detection.
+4. No regressions in existing `trace`, `id`, and `merge` command behavior.
+
+## Related
+
+- `docs/main.improvement.8.trace-id.todo.current.reference.md`
+- `docs/main.improvement.8.trace-id.todo.trigger.event.md`
+- `docs/main.improvement.9.trace-id.todo.future-plan.md`
diff --git a/docs/main.improvement.8.trace-id.todo.current.reference.md b/docs/main.improvement.8.trace-id.todo.current.reference.md
@@ -0,0 +1,38 @@
+# Reference: Improvement 8 trace-id MVP
+
+## Primary Inputs
+
+- `ulu_docs/recur-agent.static-analysis.md`
+- `ulu_docs/recur-agent.trace-id.proposal.md`
+
+## Existing Implementation References
+
+- `src/main_command_id_impl.rs` - identifier pattern scanning entrypoint
+- `src/main_command_trace_impl.rs` - command shape, scope/ext/stdin flow, guardrails
+- `src/main_command_trace_stats_impl.rs` - structured metrics pipeline patterns
+- `src/search.rs` - reusable search primitives and trace graph data structures
+- `src/output.rs` - JSON and terminal formatter patterns
+- `src/main_command_merge_impl.rs` - current merge behavior and JSON input contracts
+- `julia-tests/runtests.id.jl` - identifier command test style
+- `julia-tests/runtests.trace.jl` - trace command test style
+- `julia-tests/runtests.trace-stats.jl` - command contract and metrics assertions
+
+## How to Study
+
+```bash
+cat src/main_command_id_impl.rs
+cat src/main_command_trace_impl.rs
+cat src/main_command_trace_stats_impl.rs
+cat src/search.rs
+cat src/output.rs
+cat julia-tests/runtests.id.jl
+cat julia-tests/runtests.trace.jl
+cat julia-tests/runtests.trace-stats.jl
+```
+
+## Recommended Approach
+
+1. Start with a standalone command module `main_command_trace_id_impl.rs` that mirrors `id` and `trace` command ergonomics.
+2. Implement MVP heuristics in code first (no config file yet).
+3. Emit an output shape that can later compose with merge (include node role metadata), but do not add `merge --edge-type` in this phase.
+4. Keep the MVP narrow and test-backed; defer cross-lane semantic composition to Improvement 9.
diff --git a/docs/main.improvement.8.trace-id.todo.trigger.event.md b/docs/main.improvement.8.trace-id.todo.trigger.event.md
@@ -0,0 +1,52 @@
+# Trigger Events: Improvement 8 trace-id MVP
+
+## On Start
+
+```bash
+recur files "**.current" -d docs/
+recur tree "main.improvement.8" -d docs/
+cat docs/main.improvement.8.trace-id.todo.current.md
+cat docs/main.improvement.8.trace-id.todo.current.reference.md
+```
+
+## During Work
+
+```bash
+# Command + search lanes
+recur find "TraceStats {" --scope "**" -d src/
+recur find "Id {" --scope "**" -d src/
+recur files "main_command_*_impl" -d src/ --sep _
+
+# Verify target command lanes as they are added
+recur files "main_command_trace_id_*" -d src/ --sep _
+recur files "main.command.trace-id.**" -d docs/
+
+# Tight implementation loop
+cargo test --bin recur
+```
+
+## On Validate
+
+```bash
+# Focused lane checks
+julia julia-tests/main.command.id.test.jl
+julia julia-tests/main.command.trace.test.jl
+julia julia-tests/main.command.trace-stats.test.jl
+
+# New lane checks (after files are added)
+julia julia-tests/main.command.trace-id.test.jl
+```
+
+## On Complete
+
+```bash
+cargo test
+
+# cleanup ephemerals
+rm docs/main.improvement.8.trace-id.todo.current.md
+rm docs/main.improvement.8.trace-id.todo.current.reference.md
+rm docs/main.improvement.8.trace-id.todo.trigger.event.md
+
+# completion marker to add:
+# docs/main.improvement.8.trace-id.complete.md
+```
diff --git a/docs/main.improvement.9.todo.future-plan.md b/docs/main.improvement.9.todo.future-plan.md
@@ -19,3 +19,6 @@ Next TODO:
 1. Keep dot notation as the default canonical format for semantic IDs.
 2. Use `docs/main.semantic.names.txt` as the centralized `.todo.tracking` queue.
 3. Resolve queued IDs through file-layer commands (`recur files` / `recur tree`) before in-file analysis.
+
+Deferred lane added:
+- `docs/main.improvement.9.trace-id.todo.future-plan.md`
diff --git a/docs/main.improvement.9.trace-id.todo.future-plan.md b/docs/main.improvement.9.trace-id.todo.future-plan.md
@@ -0,0 +1,36 @@
+# Improvement 9: trace-id Deferred Scope
+
+Status: `todo.future-plan`
+Date: 2026-03-03
+
+## Purpose
+
+Track post-MVP `trace-id` work that is intentionally deferred while Improvement 8 delivers the build-now command.
+
+## Deferred Items
+
+1. Project-custom heuristic configuration:
+   - `.recur/trace-id.toml`
+   - load-order strategy (project-local, user-level, defaults)
+2. Merge semantic edge typing:
+   - `merge --edge-type`
+   - lane-aware joins for call/route/config composition
+3. Rich multi-lane composition workflow:
+   - `trace` + `trace-id` + `flatten` merged into a single semantic graph view
+4. Additional performance and false-positive hardening across large codebases.
+
+## Hand-off from Improvement 8
+
+Prerequisite:
+- `docs/main.improvement.8.trace-id.complete.md` exists with MVP completion evidence.
+
+Inputs from MVP:
+- command JSON schema shape
+- built-in heuristic behavior
+- test fixtures and known edge cases
+
+## Related
+
+- `docs/main.improvement.8.trace-id.todo.current.md`
+- `docs/main.improvement.8.todo.future-plan.md`
+- `docs/main.improvement.9.todo.future-plan.md`
diff --git a/julia-expert/references/recur-playbook.md b/julia-expert/references/recur-playbook.md
@@ -19,6 +19,29 @@ The same query-first workflow is portable to external projects (including Visual
 
 **Key Principle:** Don't search manually or remember where things are. Use recur to discover what to work on, what to reference, and what's of interest.
 
+## Search vs State (Use the Right Layer)
+
+Recur solves two different problems. Pick the layer before you pick the command:
+
+- Search and analysis (solve code and behavior issues): `find`, `id`, `callers`, `callees`, `trace`, `trace-stats`, `flatten`
+- State and workflow tracking (manage active work): `files`, `tree`, `stats`, `related`, `children`, `merge`, suffix-based eventness files
+
+When debugging or proving safety, use search tools first. Use state tools to track and hand off work.
+
+## Skim-Then-Explore Rule
+
+Before deep work in an unfamiliar subsystem, spend 5 minutes finding existing guidance and then explore organically:
+
+```bash
+# Find local guides/checklists first
+recur files "**agent**" -d docs/
+recur files "**readme**" -d docs/
+
+# Then start real discovery
+recur files "**.current" -d docs/
+recur find "<symbol-or-text>" --scope "**" -d src/
+```
+
 ## stdin/stdout Piping (Composability!)
 
 **Recur is a Unix-style composable tool** - all commands support `--stdin` to read file paths and output to stdout.
@@ -72,6 +95,8 @@ recur files "**.current" -d docs/ | ConvertFrom-Json | ForEach-Object { Get-Item
 
 **PowerShell tip:** `recur files` already outputs a JSON array by default in normal pipelines. Use `ConvertFrom-Json` before object operations; only add `--json` when you need to force machine format explicitly.
 
+**Pipeline tip:** In non-terminal pipelines, recur output is machine-oriented. When scripting, assume JSON and parse it explicitly (`ConvertFrom-Json` or `jq`) unless you intentionally force text.
+
 ## Core Recur Commands
 
 ### File Discovery
@@ -98,6 +123,32 @@ recur find "StdinCapable" --scope "main_command_**" -d src/ --sep _
 recur find "pattern" --scope "**" -C 2
 ```
 
+### Static Analysis (Bug-Finding Commands)
+```bash
+# Hierarchical identifiers inside file content (dot-path strings)
+recur id "ulu.topic.dot.**" --ext .cs
+
+# Who calls this? (impact before rename/remove)
+recur callers "FunctionName" --scope "**" --ext .rs --count
+
+# What does this call? (dependency inspection)
+recur callees "FunctionName" --scope "**" --ext .rs
+
+# Multi-level call graph (use --pick when names are ambiguous)
+recur trace "FunctionName" --scope "**" --ext .rs --depth 2 --direction both
+recur trace "FunctionName" --scope "**" --ext .rs --pick 1
+
+# Complexity hotspots and circular-risk lanes
+recur trace-stats --scope "**" --ext .rs --sort-by risk --top 10
+recur trace-stats --scope "**" --ext .rs --filter circular-only
+```
+
+**Static analysis guardrails:**
+- `callers`/`callees`/`trace` are text-based analysis, not full AST/type resolution.
+- If `trace` reports multiple matches, use `--pick <N>` instead of rewriting the query.
+- `trace` and `trace-stats` have traversal guardrails (`--depth-guard`, `--force`) for safe defaults on large scopes.
+- If `callees` shows little or no downstream detail for a function that mostly calls external libraries, switch to source reading for that boundary.
+
 ### Related Files
 ```bash
 # Find siblings in hierarchy
@@ -240,6 +291,29 @@ recur files "main_command_<name>_*" -d src/ --sep _
 recur tree "main.command.<name>" -d docs/
 ```
 
+### Stale Eventness Detection
+
+Eventness files are only useful while they are fresh:
+
+- If both `.current` and `.complete` exist for the same work item, delete `.current` immediately.
+- If a `.current` file is old and no longer actionable, either refresh it with new resume context or close it.
+- Keep `.current` files concrete: last error, file/line, hypothesis, and next command.
+
+```bash
+# Detect overlap/staleness
+recur files "**.current" -d docs/
+recur files "**.complete" -d docs/
+```
+
+```powershell
+# Age check using git history (better than filesystem mtime)
+$files = recur files "**.current" -d docs/ | ConvertFrom-Json
+foreach ($f in $files) {
+  $age = git log -1 --format="%ar" -- $f
+  Write-Host "$age  $f"
+}
+```
+
 **3. Complete Work**
 ```bash
 # Clean up ephemeral files
@@ -261,7 +335,7 @@ recur files "**.current" -d docs/
 - `main.improvement.<n>.todo.md` - Improvement tracking
 
 **Ephemeral (delete when done):**
-- `main.command.<name>.todo.current.md` - Active work marker
+- `main.command.<name>.todo.current.md` - Active work marker with resume context (error, file/line, hypothesis, next step)
 - `main.command.<name>.todo.current.reference.md` - Reference pointer to working implementations
 - `main.command.<name>.todo.trigger.event.md` - Event commands to run at key moments
 
@@ -566,6 +640,11 @@ recur files "main_command_<name>_*" -d src/ --sep _
 6. **Event-driven** - Run discovery commands at workflow events
 7. **Gap analysis** - Compare file sets to find missing work
 8. **Reference pattern** - Create `.reference.md` files pointing to working implementations
+9. **Search first for debugging** - Use `id/find/callers/callees/trace/trace-stats` before writing eventness docs
+10. **Use `id` for dot-path identifiers** - Prefer `recur id "prefix.**"` over plain text search for hierarchical identifiers
+11. **Stale detection is mandatory** - `.current` + `.complete` overlap means `.current` is stale
+12. **Skim then explore** - 5-minute doc skim prevents dead-end command loops
+13. **Mirror lanes in the same session** - if code changed, add/update docs/tests/automation lane state before ending the session
 
 ## Creating Good Reference Files
 
@@ -736,6 +815,26 @@ cd julia-tests && julia runtests.jl
 recur tree "main" --sep . --sep _ --show-sep
 ```
 
+## Phase Lifecycle Checklist (Portable)
+
+Use this for epics/phases in any project (not just this repo).
+
+**Before phase start:**
+1. Create a `.todo.current.md` for active scope.
+2. Create a `.todo.current.reference.md` only if reusing an existing pattern.
+3. Create lane markers/scripts for verification lanes (tests, automation, DB checks) you will need.
+
+**During phase:**
+1. Run discovery (`**.current`, tree for the epic prefix).
+2. Keep implementation and validation tight (`cargo test`, lane-specific tests/scripts).
+3. Update `.current` with concrete resume context after each significant checkpoint.
+
+**After phase completion:**
+1. Delete `.current*` ephemerals.
+2. Add a concise `.complete.md` summary.
+3. Fold durable findings into persistent `.todo.md` or readme artifacts.
+4. Re-run discovery to confirm cleanup and expose the next visible gap.
+
 ## Cross-Lane Rule (Portable)
 
 Treat code as canonical, then mirror intent across lanes in the same session:
@@ -758,6 +857,21 @@ When using a mirror lane (future/optional), keep the same order:
 
 This prevents documentation-first drift and keeps eventness as durable evidence of real implementation state.
 
+## Julia Verification Lane (Optional)
+
+For data migration/verification-heavy projects, keep Julia scripts as a first-class lane:
+
+- Prefer committed `.jl` scripts over inline shell snippets.
+- Default scripts to read-only checks.
+- Gate mutations behind `--fix`.
+
+```bash
+julia jl/<name>.check.jl
+julia jl/<name>.check.jl --fix
+```
+
+When reading SQL results in Julia, prefer SQL-side null handling (`COALESCE(...)`) to avoid brittle null coercion patterns in script code.
+
 ## Summary
 
 You are a recur expert. You use recur commands to discover state, track work, and maintain external memory through hierarchical file structures. You understand the eventness pattern, separator awareness, and gap analysis. You never try to remember what can be queried.
