projecta-rrr 1.21.8 → 1.21.10

package/CHANGELOG.md

@@ -4,7 +4,109 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [1.21.8] - 2026-04-18
+## [1.21.10] - 2026-04-18
+
+**semantic_search injection waves 2 + 3.**
+
+Completes the token-saving rollout started in v1.21.9. Waves 2 and 3 target
+commands that auditor identified as MED priority but still carry significant
+token cost in practice — milestone audits, gap planning, roadmap creation,
+project research, and the planner agent itself.
+
+### Added
+
+- **semantic_search in `rrr-planner` agent.** Planner previously grepped
+  CONTEXT.md and ROADMAP sections during task breakdown — now prefers
+  ~500-token semantic_search for "existing implementations", "similar
+  patterns", "existing code shape" queries.
+
+- **semantic_search reference in 4 more commands:** `/rrr:audit-milestone`,
+  `/rrr:plan-milestone-gaps`, `/rrr:create-roadmap`, `/rrr:research-project`.
+  These don't run every session but they dominate milestone boundaries —
+  typical burn 12-22K each before this change.
+
+- **`semantic-search-preference.md` domain-query patterns (wave 3).**
+  10-row table: tech stack, architecture, similar implementation, error
+  root-cause, requirement coverage, auth/security, data model, test
+  coverage, API surface, config. With suggested k per query. Purpose:
+  stop Claude from grepping for "middleware" when a better-phrased
+  semantic_search would nail it in one call.
+
+### Status after waves 1-3
+
+Commands using semantic_search: **13 of 23** (was 5). The 10 remaining
+untouched commands do minimal code exploration (<5K tokens each) —
+diminishing returns beyond here.
+
+Agents using semantic_search: **5 of ~15** — the five highest-burn ones
+(rrr-codebase-mapper, rrr-phase-researcher, rrr-executor, rrr-debugger,
+rrr-planner). These carry ~80% of agent-side exploration cost.
+
+### Next (v1.22.0)
+
+Webhook-driven re-index infrastructure (GitHub App single-URL webhook +
+local post-commit hook → local MCP). Closes the "stale index" gap — today
+reindex only runs on cron or manual sync_repo. Needs a phase plan; not a
+patch.
+
+## [1.21.9] - 2026-04-18
+
+**Token-efficient RRR: semantic_search injection wave 1 + hosted worker hardening.**
+
+After indexing 59 repos across the team, audit revealed RRR commands/agents were
+doing Read/Grep/Glob chains when semantic_search could return ranked chunks at
+5-20x lower token cost. Wave 1 ships the highest-ROI injections. Also bundles
+four hosted-worker patches discovered during batch indexing.
+
+### Added
+
+- **semantic_search in 4 high-burn agents.** `rrr-codebase-mapper`,
+  `rrr-phase-researcher`, `rrr-executor`, `rrr-debugger` now have
+  `mcp__rrr-search-hosted__semantic_search` + `mcp__rrr-search__semantic_search`
+  in their tool frontmatter. These five agents carried the bulk of RRR's
+  code-exploration token cost (15-60K tokens per run each); semantic_search
+  replaces most of that with ~500-token ranked chunks.
+
+- **semantic_search reference in 4 high-leverage commands.**
+  `/rrr:map-codebase`, `/rrr:research-phase`, `/rrr:brownfield-audit`,
+  `/rrr:debug` now `@rrr/references/semantic-search-preference.md` in their
+  execution_context. Previously only 5 commands had the reference
+  (`progress`, `plan-phase`, `execute-phase`, `discuss-phase`, `verify-work`).
+
+- **Full audit at `/tmp/rrr-token-audit.md`** (one-shot; not committed).
+  Identifies 10 remaining HIGH/MED-priority injection points for waves 2-3.
+
+### Changed
+
+- **Hosted worker default budget: 5M → 100M tokens per repo / 30d.**
+  (`rrr/hosted-mcp/src/worker/lib/token-budget.js:22`.) Real-world repos
+  like `superintelligence` (9M tokens) and `Internjobs` (25M tokens) were
+  tripping the 5M cap. 100M fits all observed repos with headroom; remains
+  overridable per repo via `.rrr-search.json` `budget_tokens`.
+
+- **Voyage batch cap: 100K → 80K tokens; estimator 3.5 → 2.8 chars/token.**
+  (`rrr/hosted-mcp/src/worker/lib/voyage-embedder.js:96-97`.) The old
+  char-based estimator undercounted — batches passing the 100K cap were
+  arriving at Voyage at 124-130K tokens and hitting the 120K hard limit
+  on repos like `OpenHands` and `gooseworks-skills`. Tighter cap + matched
+  estimator resolves this.
+
+- **`index_repo` owner/repo regex allows dots.**
+  (`rrr/hosted-mcp/src/mcp/tools/index-repo.js:101`.) The previous
+  `([^/.]+?)` would fail to parse repos like `PA-Ai-Team/MALA.dev.git`,
+  silently falling back to `slug/slug` — causing a 404 on clone. New
+  pattern `(.+?)(?:\.git)?$` handles dots in repo names correctly.
+
+### Fixed
+
+- **Git clone fallback for non-`main` default branches.**
+  (`rrr/hosted-mcp/src/worker/lib/github-clone.js:158-178`.) Repos whose
+  default branch is `master` (or anything non-`main`) were failing clone
+  with `fatal: Remote branch main not found in upstream origin`. Added
+  a catch-and-retry: on branch-not-found, re-clone without `--branch`
+  flag (git uses the remote's default branch automatically).
+
+
 
 **End-to-end verified on a second repo. Multiple worker bootstrap fixes.**
 

package/agents/rrr-codebase-mapper.md

@@ -2,7 +2,7 @@
 name: rrr-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 model: sonnet
-tools: Read, Bash, Grep, Glob, Write
+tools: Read, Bash, Grep, Glob, Write, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: cyan
 ---
 

package/agents/rrr-debugger.md

@@ -2,7 +2,7 @@
 name: rrr-debugger
 description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /rrr:debug orchestrator.
 model: inherit
-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: orange
 ---
 

package/agents/rrr-executor.md

@@ -2,7 +2,7 @@
 name: rrr-executor
 description: Executes RRR plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 model: inherit
-tools: Read, Write, Edit, Bash, Grep, Glob
+tools: Read, Write, Edit, Bash, Grep, Glob, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: yellow
 ---
 

package/agents/rrr-phase-researcher.md

@@ -2,7 +2,7 @@
 name: rrr-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by rrr-planner. Spawned by /rrr:plan-phase orchestrator.
 model: sonnet
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: cyan
 ---
 

package/agents/rrr-planner.md

@@ -2,7 +2,7 @@
 name: rrr-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /rrr:plan-phase orchestrator.
 model: sonnet
-tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
+tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: green
 ---
 

package/commands/rrr/audit-milestone.md

@@ -19,6 +19,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 
 <execution_context>
 @~/.claude/rrr/references/principles.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/brownfield-audit.md

@@ -37,6 +37,7 @@ Audit brownfield repositories to detect scattered planning documents, classify t
 @~/.claude/rrr/references/principles.md
 @~/.claude/rrr/references/scan-exclusions.md
 @~/.claude/rrr/lib/phase-paths.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <scan_ignored_paths>

package/commands/rrr/create-roadmap.md

@@ -40,6 +40,7 @@ Roadmaps define what work happens in what order. Phases map to requirements.
 @~/.claude/rrr/templates/roadmap.md
 @~/.claude/rrr/templates/state.md
 @~/.claude/rrr/references/goal-backward.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/debug.md

@@ -9,6 +9,10 @@ allowed-tools:
   - AskUserQuestion
 ---
 
+<execution_context>
+@rrr/references/semantic-search-preference.md
+</execution_context>
+
 <objective>
 Debug issues using scientific method with subagent isolation.
 

package/commands/rrr/map-codebase.md

@@ -21,6 +21,7 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 
 <execution_context>
 @~/.claude/rrr/workflows/map-codebase.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/plan-milestone-gaps.md

@@ -22,6 +22,7 @@ One command creates all fix phases — no manual `/rrr:add-phase` per gap.
 @~/.claude/rrr/references/principles.md
 @~/.claude/rrr/workflows/plan-phase.md
 @~/.claude/rrr/lib/phase-paths.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/research-phase.md

@@ -8,6 +8,10 @@ allowed-tools:
   - Task
 ---
 
+<execution_context>
+@rrr/references/semantic-search-preference.md
+</execution_context>
+
 <objective>
 Research how to implement a phase. Spawns rrr-phase-researcher agent with phase context.
 

package/commands/rrr/research-project.md

@@ -23,6 +23,10 @@ For new projects, use /rrr:new-project instead.
 Deprecated: 2026-01-16
 -->
 
+<execution_context>
+@rrr/references/semantic-search-preference.md
+</execution_context>
+
 <objective>
 Research domain ecosystem. Spawns 4 parallel rrr-project-researcher agents for comprehensive coverage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.21.8",
+  "version": "1.21.10",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js",

package/rrr/references/semantic-search-preference.md

@@ -23,6 +23,25 @@ When exploring the codebase to answer "what does X do?", "where is Y configured?
 - **Relevance:** semantic_search ranks by cosine similarity + RRF fusion with ripgrep; grep returns alphabetically.
 - **Cross-file synthesis:** top-K often spans multiple files — one call answers "how X works" that would otherwise need 3-5 greps.
 
+## Domain-Specific Queries
+
+Start with the right query phrasing — semantic_search ranks by meaning, not keywords. Pick the pattern closest to your intent:
+
+| Scenario | Query pattern | k |
+|---|---|---|
+| Tech stack discovery | `"technology stack" "frameworks" "dependencies" "build tools"` | 10 |
+| Architecture / module layout | `"system architecture" "module organization" "data flow"` | 10 |
+| Find similar implementation | `"implementation pattern for X" "existing code example"` | 5 |
+| Error root-cause (logs + code) | `"error pattern" "failure signature" "root cause indicators"` | 20 |
+| Requirement coverage | `"requirement implementation" "feature coverage" "missing pieces"` | 10 |
+| Auth / security surfaces | `"authentication flow" "token validation" "permission check"` | 10 |
+| Data model / schema | `"schema definition" "table design" "entity relationships"` | 10 |
+| Test coverage gaps | `"test cases" "validation" "edge case handling"` | 10 |
+| API surface | `"endpoints" "request handlers" "route definitions"` | 10 |
+| Config / environment | `"configuration" "environment variables" "settings"` | 5 |
+
+**Rule of thumb:** one semantic_search (k=5-10, ~500 tokens) before any Grep/Read chain on an unknown area. If the top hits answer the question, stop. If not, narrow with a second query — still cheaper than brute-force grep.
+
 ## Discovery
 
 Check availability once at workflow start: