@pmaddire/gcie 0.1.2

package/ROADMAP.md

@@ -0,0 +1,301 @@
+# ROADMAP.md
+
+## Roadmap: GraphCode Intelligence Engine (GCIE)
+
+## Overview
+
+This roadmap follows the GSD workflow: define phased outcomes, execute atomic tasks, verify phase outputs, then proceed sequentially.  
+No implementation begins until the phase plan is approved and phase execution starts.
+
+## Phases
+
+1. Repository Scanning
+2. AST Parsing Engine
+3. Code Structure Graph
+4. Call Graph
+5. Variable Dependency Graph
+6. Execution Trace Graph
+7. Git History Graph
+8. Test Coverage Graph
+9. Knowledge Index
+10. Symbolic Retrieval System
+11. Semantic Retrieval System
+12. Hybrid Retrieval Pipeline
+13. Bug Localization System
+14. LLM Context Builder
+15. CLI Interface
+16. Performance Optimization
+17. Testing and Documentation
+
+## Phase Plans (Atomic Tasks)
+
+### Phase 1: Repository Scanning
+Goal: Discover indexable repository artifacts and produce normalized file manifests.
+
+Task 1.1
+Target files: `scanner/repository_scanner.py`, `scanner/file_filters.py`, `scanner/models.py`
+Implementation instructions: build recursive scanner, extension filters, ignore rules, and manifest dataclasses.
+Verification steps: run scanner on sample repo; confirm deterministic manifest output.
+Completion criteria: scanner returns stable list of source/test/config files with metadata.
+
+Task 1.2
+Target files: `config/scanner_config.py`, `tests/scanner/test_repository_scanner.py`
+Implementation instructions: add include/exclude config model and tests for hidden dirs, large files, and unsupported extensions.
+Verification steps: execute scanner tests and inspect edge-case fixtures.
+Completion criteria: scanner behavior is configurable and validated by passing tests.
+
+### Phase 2: AST Parsing Engine
+Goal: Parse Python code and emit normalized symbol-level IR.
+
+Task 2.1
+Target files: `parser/ast_parser.py`, `parser/models.py`
+Implementation instructions: implement AST walker extracting modules, classes, functions, parameters, docstrings, assignments, imports, calls.
+Verification steps: parse fixture files and assert extracted symbols/line ranges.
+Completion criteria: parser emits complete symbol IR for valid Python files.
+
+Task 2.2
+Target files: `parser/tree_sitter_adapter.py`, `tests/parser/test_parser_fallbacks.py`
+Implementation instructions: define Tree-sitter adapter interface and fallback policy when AST parsing is unavailable or partial.
+Verification steps: simulate fallback scenarios using malformed fixtures.
+Completion criteria: parser pipeline provides predictable fallback behavior with tests.
+
+### Phase 3: Code Structure Graph
+Goal: Build structural relationships between files, classes, and functions.
+
+Task 3.1
+Target files: `graphs/code_graph.py`, `graphs/node_factory.py`
+Implementation instructions: map IR entities to graph nodes and create `DEFINES`, `CONTAINS`, and `IMPORTS` edges.
+Verification steps: graph snapshot tests on fixture projects.
+Completion criteria: structure graph is connected and queryable by symbol/file.
+
+Task 3.2
+Target files: `tests/graphs/test_code_graph.py`, `graphs/validators.py`
+Implementation instructions: add integrity checks for node uniqueness, edge consistency, and missing references.
+Verification steps: run graph validation tests against positive and negative fixtures.
+Completion criteria: invalid graph states are detected and reported.
+
+### Phase 4: Call Graph
+Goal: Build function-to-function call relationships.
+
+Task 4.1
+Target files: `graphs/call_graph.py`, `parser/call_resolver.py`
+Implementation instructions: resolve local and module-qualified calls; add `CALLS` edges with source location metadata.
+Verification steps: test direct calls, nested calls, and method calls.
+Completion criteria: call graph captures expected caller-callee chains.
+
+Task 4.2
+Target files: `tests/graphs/test_call_graph.py`
+Implementation instructions: create fixtures for recursion, alias imports, and unresolved external calls.
+Verification steps: execute tests and verify unresolved calls are labeled, not dropped.
+Completion criteria: call graph behavior is deterministic for known edge cases.
+
+### Phase 5: Variable Dependency Graph
+Goal: Model read/write/modify relationships for variables.
+
+Task 5.1
+Target files: `graphs/variable_graph.py`, `parser/variable_extractor.py`
+Implementation instructions: detect variable definitions, reads, writes, and updates; create `READS`, `WRITES`, `MODIFIES` edges.
+Verification steps: run tests on assignment and mutation patterns.
+Completion criteria: variable graph correctly identifies modifier functions for target variables.
+
+Task 5.2
+Target files: `tests/graphs/test_variable_graph.py`
+Implementation instructions: add fixtures for local/global scope, closures, attributes, and tuple unpacking.
+Verification steps: assert correct scope attribution and edge generation.
+Completion criteria: variable dependency extraction is validated for common Python patterns.
+
+### Phase 6: Execution Trace Graph
+Goal: Capture runtime execution paths and map traces to symbols.
+
+Task 6.1
+Target files: `graphs/execution_graph.py`, `tracing/runtime_tracer.py`
+Implementation instructions: implement `sys.settrace` event capture and transform call/return events into execution graph edges.
+Verification steps: run tracer on deterministic sample program and compare trace order.
+Completion criteria: execution trace graph reproduces runtime path with timestamped edges.
+
+Task 6.2
+Target files: `tests/tracing/test_runtime_tracer.py`, `tests/graphs/test_execution_graph.py`
+Implementation instructions: add tests for recursion, exceptions, and multi-function flows.
+Verification steps: validate path continuity and symbol mapping in traces.
+Completion criteria: trace graph is reliable for debugging path reconstruction.
+
+### Phase 7: Git History Graph
+Goal: Relate commits to files and symbols for recency-aware ranking.
+
+Task 7.1
+Target files: `graphs/git_graph.py`, `git_integration/git_miner.py`
+Implementation instructions: ingest commit history via GitPython and map changed files/symbol spans to `CHANGED_IN` edges.
+Verification steps: run against fixture repo with known commit history.
+Completion criteria: graph exposes commit recency and symbol touch history.
+
+Task 7.2
+Target files: `tests/git/test_git_miner.py`, `tests/graphs/test_git_graph.py`
+Implementation instructions: validate rename handling, author/date extraction, and empty history behavior.
+Verification steps: run tests using temporary repositories.
+Completion criteria: git graph ingestion is resilient and test-covered.
+
+### Phase 8: Test Coverage Graph
+Goal: Map tests to covered symbols and files.
+
+Task 8.1
+Target files: `graphs/test_graph.py`, `coverage_integration/coverage_loader.py`
+Implementation instructions: import Coverage.py results and link tests to functions/files using `COVERED_BY` edges.
+Verification steps: run sample tests with coverage and compare expected mappings.
+Completion criteria: coverage graph quantifies coverage for retrieval weighting.
+
+Task 8.2
+Target files: `tests/coverage/test_coverage_loader.py`, `tests/graphs/test_test_graph.py`
+Implementation instructions: test partial coverage, missing reports, and branch coverage metadata.
+Verification steps: execute loader and graph tests.
+Completion criteria: coverage integration handles both complete and sparse reports.
+
+### Phase 9: Knowledge Index
+Goal: Provide fast metadata lookup for symbols and dependencies.
+
+Task 9.1
+Target files: `knowledge_index/models.py`, `knowledge_index/index_builder.py`, `knowledge_index/store.py`
+Implementation instructions: implement in-memory entries for files, classes, functions, variables, imports, dependencies.
+Verification steps: build index from fixture IR and assert entry completeness.
+Completion criteria: index supports required entry formats and lookups.
+
+Task 9.2
+Target files: `knowledge_index/query_api.py`, `tests/knowledge_index/test_query_api.py`
+Implementation instructions: implement queries: variable modifiers, callers, imports, inheritance.
+Verification steps: run query API tests against known fixtures.
+Completion criteria: index answers core structural queries without LLM calls.
+
+### Phase 10: Symbolic Retrieval System
+Goal: Retrieve execution-relevant candidates via graph traversal.
+
+Task 10.1
+Target files: `retrieval/symbolic_retriever.py`, `retrieval/query_parser.py`
+Implementation instructions: extract symbols/intents and perform seeded traversal across structure/call/variable/trace graphs.
+Verification steps: evaluate retrieval on debugging query fixtures.
+Completion criteria: symbolic retriever returns focused candidate subgraphs.
+
+Task 10.2
+Target files: `tests/retrieval/test_symbolic_retriever.py`
+Implementation instructions: add tests for ambiguous symbols, missing symbols, and multi-hop traversal limits.
+Verification steps: run tests and inspect ranked symbolic results.
+Completion criteria: symbolic retrieval precision is acceptable on benchmark fixtures.
+
+### Phase 11: Semantic Retrieval System
+Goal: Rank code candidates by semantic relevance.
+
+Task 11.1
+Target files: `embeddings/encoder.py`, `embeddings/faiss_index.py`, `retrieval/semantic_retriever.py`
+Implementation instructions: generate embeddings, maintain FAISS index, and return similarity-ranked snippets.
+Verification steps: run embedding/index smoke tests on fixture corpus.
+Completion criteria: semantic retriever returns deterministic top-k results.
+
+Task 11.2
+Target files: `tests/retrieval/test_semantic_retriever.py`, `tests/embeddings/test_faiss_index.py`
+Implementation instructions: validate indexing, updates, persistence hooks, and retrieval quality thresholds.
+Verification steps: execute test suite and compare expected rankings.
+Completion criteria: semantic retrieval module is stable and test-covered.
+
+### Phase 12: Hybrid Retrieval Pipeline
+Goal: Fuse symbolic and semantic retrieval with risk weighting.
+
+Task 12.1
+Target files: `retrieval/hybrid_retriever.py`, `retrieval/ranking.py`
+Implementation instructions: combine symbolic distance, semantic score, git recency, and coverage risk into final rank.
+Verification steps: run controlled ranking scenarios with synthetic weights.
+Completion criteria: hybrid ranking is explainable and configurable.
+
+Task 12.2
+Target files: `tests/retrieval/test_hybrid_retriever.py`
+Implementation instructions: assert ranking order for debugging scenarios and regression fixtures.
+Verification steps: run tests and verify rationale metadata in output.
+Completion criteria: hybrid pipeline consistently improves relevance over symbolic-only baseline.
+
+### Phase 13: Bug Localization System
+Goal: Produce structured root-cause candidates for debugging queries.
+
+Task 13.1
+Target files: `debugging/bug_localizer.py`, `debugging/execution_path_analyzer.py`
+Implementation instructions: implement workflow from symbol extraction to modifier detection and upstream/downstream path tracing.
+Verification steps: run end-to-end bug-localization fixtures (including `diff`-style queries).
+Completion criteria: output includes relevant functions, call chain, and variable modifications.
+
+Task 13.2
+Target files: `tests/debugging/test_bug_localizer.py`
+Implementation instructions: test ranking heuristics for recent commits, low coverage, and frequent execution paths.
+Verification steps: execute tests and review explanation payload.
+Completion criteria: bug-localization quality meets defined fixture expectations.
+
+### Phase 14: LLM Context Builder
+Goal: Build minimal, ordered context payloads for LLM prompts.
+
+Task 14.1
+Target files: `llm_context/context_builder.py`, `llm_context/snippet_selector.py`
+Implementation instructions: select minimal snippets from ranked candidates; deduplicate and preserve execution order.
+Verification steps: compare output token estimates with full-file baseline.
+Completion criteria: context builder emits compact payloads with traceable provenance.
+
+Task 14.2
+Target files: `tests/llm_context/test_context_builder.py`
+Implementation instructions: add tests for token-budget clipping, snippet overlap, and mandatory-symbol retention.
+Verification steps: run tests and ensure deterministic output for fixed inputs.
+Completion criteria: context output is reproducible and bounded by budget.
+
+### Phase 15: CLI Interface
+Goal: Expose GCIE capabilities through Typer commands.
+
+Task 15.1
+Target files: `cli/app.py`, `cli/commands/index.py`, `cli/commands/query.py`, `cli/commands/debug.py`
+Implementation instructions: implement commands for indexing, graph build, retrieval query, and debug report.
+Verification steps: run CLI help and command smoke tests in fixture workspace.
+Completion criteria: users can execute end-to-end flow from CLI without direct Python API use.
+
+Task 15.2
+Target files: `tests/cli/test_cli_commands.py`
+Implementation instructions: add CLI integration tests with fixture repositories and expected output schemas.
+Verification steps: execute CLI tests and validate exit codes plus structured output.
+Completion criteria: CLI is reliable for automation and local usage.
+
+### Phase 16: Performance Optimization
+Goal: Reduce indexing/query latency and memory cost while preserving relevance.
+
+Task 16.1
+Target files: `performance/profiler.py`, `retrieval/cache.py`, `graphs/graph_store.py`
+Implementation instructions: add profiling instrumentation, caching, and incremental graph/index refresh paths.
+Verification steps: run benchmark scenarios before/after optimization.
+Completion criteria: measurable gains in indexing/query runtime and memory footprint.
+
+Task 16.2
+Target files: `tests/performance/test_benchmarks.py`, `docs/performance.md`
+Implementation instructions: define benchmark suite and acceptance thresholds for latency/token reduction.
+Verification steps: execute benchmark tests and capture baseline report.
+Completion criteria: performance targets are versioned and regression-tested.
+
+### Phase 17: Testing and Documentation
+Goal: Finalize quality gates and project documentation.
+
+Task 17.1
+Target files: `tests/integration/test_end_to_end.py`, `tests/regression/test_query_regressions.py`
+Implementation instructions: create end-to-end tests from indexing to minimal context output for canonical debugging queries.
+Verification steps: run full test suite with coverage enabled.
+Completion criteria: integration and regression suites pass with acceptable coverage.
+
+Task 17.2
+Target files: `README.md`, `docs/architecture.md`, `docs/retrieval.md`, `docs/debugging.md`
+Implementation instructions: document architecture, phase outcomes, CLI usage, and troubleshooting workflow.
+Verification steps: follow docs to execute first-time setup and sample query run.
+Completion criteria: documentation supports onboarding and reproducible operation.
+
+## Sequential Execution Rules
+
+1. Phases execute in numeric order (1 through 17).
+2. Do not start a phase until previous phase completion criteria are satisfied.
+3. If a phase fails verification, fix within the same phase before proceeding.
+4. Record verification evidence after each phase.
+5. Re-scope only through roadmap update, not ad hoc implementation.
+
+## Milestone Outcome Targets
+
+1. Repository indexing and graph construction are operational.
+2. Symbolic + semantic hybrid retrieval is operational.
+3. Debugging flow returns minimal execution-relevant context.
+4. CLI and documentation enable practical day-to-day use.
+

package/SETUP_ANY_REPO.md

@@ -0,0 +1,85 @@
+# GCIE Setup In Any Repo
+
+Use this file to onboard GCIE quickly in a new project.
+
+## 0) One-Command Bootstrap
+
+If GCIE is already installed locally:
+
+```powershell
+gcie.cmd setup .
+```
+
+NPX one-liner (after npm publish):
+
+```powershell
+npx gcie@latest
+```
+
+GitHub one-liner bootstrap (no prior setup required):
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/pmaddire/GBCRSS/main/scripts/bootstrap_from_github.ps1 | iex"
+```
+
+This initializes `.gcie` architecture tracking, writes portable workflow docs, and runs an initial index.
+
+
+## 1) Install And Verify
+
+```powershell
+gcie.cmd --help
+```
+
+If this fails, use your local install method first (`npm link`, `npx`, or Python module invocation).
+
+## 2) Index Once
+
+```powershell
+gcie.cmd index .
+```
+
+Re-run indexing after major structural changes.
+
+## 3) Add Agent Workflow File
+
+Copy `AGENT_USAGE.md` from GCIE into the target repo root.
+
+## 4) Start With Portable Defaults
+
+```powershell
+gcie.cmd context . "<task>" --intent <edit|debug|refactor|explore> --budget auto
+```
+
+Then apply the adaptive loop in `AGENT_USAGE.md` if must-have coverage is incomplete.
+
+## 5) Use Adaptive Mode Routing
+
+- default: `plain-context-first`
+- selective: `slicer-first` only for families where it benchmarks better
+- always available: `direct-file-check` (`rg`) for verification/gap closure
+
+## 6) Must-Have Gate Before Edits
+
+Treat context as sufficient only when you have:
+- implementation file(s)
+- wiring/orchestration file(s)
+- validation surface when risk is non-trivial
+
+If missing, run targeted gap-fill for only the missing file.
+
+## 7) Agent Prompt (Drop-In)
+
+```text
+Use GCIE as the primary context compressor.
+Start with plain-context-first using file-first, symbol-heavy queries.
+If must-have coverage is incomplete, adapt in this order:
+1) improve query symbols/file anchors
+2) adjust scope (subtree vs root)
+3) raise budget one rung
+4) targeted gap-fill for missing file(s)
+5) decompose multi-hop chain only if still incomplete
+Use slicer-first only for task families where it is benchmarked better.
+Always verify with direct-file-check before edits when coverage is uncertain.
+Stop retrieval as soon as must-have coverage is complete.
+```

package/bin/gcie-init.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const { resolve } = require("path");
+
+function runGcie(args) {
+  const scriptDir = resolve(__dirname);
+  const gcieBin = resolve(scriptDir, "gcie.js");
+  const result = spawnSync(process.execPath, [gcieBin, ...args], { stdio: "inherit" });
+  return result.status || 0;
+}
+
+function main() {
+  const userArgs = process.argv.slice(2);
+  const setupArgs = ["setup", ".", ...userArgs];
+  process.exit(runGcie(setupArgs));
+}
+
+main();

package/bin/gcie.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const { existsSync } = require("fs");
+const { join, resolve, delimiter } = require("path");
+
+function resolvePython(gcieRoot) {
+  const winVenv = join(gcieRoot, ".venv", "Scripts", "python.exe");
+  const nixVenv = join(gcieRoot, ".venv", "bin", "python");
+
+  if (existsSync(winVenv)) return winVenv;
+  if (existsSync(nixVenv)) return nixVenv;
+
+  return null;
+}
+
+function tryCommand(cmd, args, env) {
+  const result = spawnSync(cmd, args, { stdio: "inherit", env });
+  return result.status === 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cliArgs = args.length === 0 ? ["setup", "."] : args;
+
+  const scriptDir = resolve(__dirname);
+  const gcieRoot = process.env.GCIE_ROOT ? resolve(process.env.GCIE_ROOT) : resolve(scriptDir, "..");
+
+  const env = { ...process.env };
+  env.PYTHONPATH = env.PYTHONPATH ? `${gcieRoot}${delimiter}${env.PYTHONPATH}` : gcieRoot;
+
+  const venvPython = resolvePython(gcieRoot);
+  if (venvPython) {
+    process.exit(spawnSync(venvPython, ["-m", "cli.app", ...cliArgs], { stdio: "inherit", env }).status || 0);
+  }
+
+  if (tryCommand("python", ["-m", "cli.app", ...cliArgs], env)) return;
+  if (tryCommand("py", ["-3", "-m", "cli.app", ...cliArgs], env)) return;
+
+  console.error("No Python interpreter found. Create a .venv in the GCIE repo or install Python 3.11+.");
+  process.exit(1);
+}
+
+main();

package/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

package/cli/app.py

@@ -0,0 +1,163 @@
+"""Typer entrypoint for GCIE CLI."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import typer
+
+from .commands.cache import cache_status, clear_cache, warm_cache
+from .commands.context import run_context
+from .commands.context_slices import run_context_slices
+from .commands.debug import run_debug
+from .commands.index import run_index
+from .commands.query import run_query
+from .commands.setup import run_setup
+
+app = typer.Typer(help="GraphCode Intelligence Engine CLI")
+
+
+def _query_tokens(query: str) -> tuple[str, ...]:
+    return tuple(re.findall(r"[a-zA-Z_./{}-][a-zA-Z0-9_./{}-]*", query.lower()))
+
+
+def _auto_context_budget(query: str, intent: str | None) -> int | None:
+    tokens = _query_tokens(query)
+    lowered = query.lower()
+    effective_intent = intent or "explore"
+
+    file_terms = [token for token in tokens if "." in token or "/" in token or "{" in token]
+    explicit_files = [token for token in file_terms if token.endswith((".py", ".jsx", ".js", ".tsx", ".ts", ".html"))]
+    symbol_terms = [token for token in tokens if any(ch in token for ch in ("_", "/", ".", "{", "}"))]
+
+    has_frontend = any(token.startswith(("frontend/", "frontend\\")) for token in file_terms)
+    has_backend = any(
+        token.endswith(".py") or token.startswith(("backend/", "server/", "api/"))
+        for token in file_terms
+    )
+    cross_layer = has_frontend and has_backend
+
+    stage_pipeline = any(term in lowered for term in ("stage", "pipeline", "planner", "plan", "build", "orchestr"))
+    backend_config = any(term in lowered for term in ("backend", "config", "openai", "api_key", "llm", "no_ai", "backend_info"))
+    ai_chain = any(term in lowered for term in ("openai", "llm", "model", "agent")) and has_backend
+    same_layer_backend_pair = len([token for token in explicit_files if token.endswith(".py")]) >= 2 and not has_frontend
+    has_api = "/api/" in lowered or any("/api/" in token for token in file_terms)
+
+    if effective_intent in {"edit", "debug", "refactor"} and cross_layer and len(symbol_terms) >= 4:
+        return 1200 if has_api else 1150
+    if stage_pipeline and len(explicit_files) >= 2:
+        return 1400
+    if same_layer_backend_pair and (backend_config or ai_chain):
+        return 1100
+    if len(explicit_files) >= 3 and effective_intent in {"edit", "debug", "refactor"}:
+        return 1200
+    if effective_intent in {"edit", "debug"} and len(explicit_files) >= 2:
+        return 1000
+    if effective_intent == "refactor" and len(explicit_files) >= 2:
+        return 1000
+    return None
+
+
+@app.command("index")
+def index_cmd(path: str = typer.Argument(".")) -> None:
+    result = run_index(path)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("query")
+def query_cmd(path: str, query: str, max_hops: int = 2) -> None:
+    result = run_query(path, query, max_hops=max_hops)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("debug")
+def debug_cmd(path: str, query: str) -> None:
+    result = run_debug(path, query)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("context")
+def context_cmd(
+    path: str,
+    query: str,
+    budget: str = typer.Option("auto", "--budget"),
+    intent: str | None = typer.Option(None, "--intent"),
+) -> None:
+    if budget == "auto":
+        budget_val = _auto_context_budget(query, intent)
+    else:
+        budget_val = int(budget)
+
+    result = run_context(path, query, budget=budget_val, intent=intent)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("context-slices")
+def context_slices_cmd(
+    repo: str,
+    query: str,
+    profile: str | None = typer.Option("recall", "--profile"),
+    stage_a_budget: int = typer.Option(400, "--stage-a"),
+    stage_b_budget: int = typer.Option(800, "--stage-b"),
+    max_total: int = typer.Option(1200, "--max-total"),
+    intent: str | None = typer.Option(None, "--intent"),
+    pin: str | None = typer.Option(None, "--pin"),
+    pin_budget: int = typer.Option(300, "--pin-budget"),
+    include_tests: bool = typer.Option(False, "--include-tests"),
+) -> None:
+    result = run_context_slices(
+        repo,
+        query,
+        stage_a_budget=stage_a_budget,
+        stage_b_budget=stage_b_budget,
+        max_total=max_total,
+        intent=intent,
+        pin=pin,
+        pin_budget=pin_budget,
+        include_tests=include_tests,
+        profile=profile,
+    )
+    typer.echo(json.dumps(result, indent=2))
+
+
+
+
+@app.command("setup")
+def setup_cmd(
+    path: str = typer.Argument("."),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing setup files"),
+    no_agent_usage: bool = typer.Option(False, "--no-agent-usage", help="Do not copy AGENT_USAGE.md"),
+    no_setup_doc: bool = typer.Option(False, "--no-setup-doc", help="Do not copy SETUP_ANY_REPO.md"),
+    no_index: bool = typer.Option(False, "--no-index", help="Skip initial indexing pass"),
+) -> None:
+    result = run_setup(
+        path,
+        force=force,
+        include_agent_usage=not no_agent_usage,
+        include_setup_doc=not no_setup_doc,
+        run_index_pass=not no_index,
+    )
+    typer.echo(json.dumps(result, indent=2))
+
+@app.command("cache-clear")
+def cache_clear_cmd(path: str = typer.Argument(".")) -> None:
+    result = clear_cache(path)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("cache-status")
+def cache_status_cmd(path: str = typer.Argument(".")) -> None:
+    result = cache_status(path)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("cache-warm")
+def cache_warm_cmd(path: str = typer.Argument(".")) -> None:
+    result = warm_cache(path)
+    typer.echo(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    app()
+

package/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands package."""

package/cli/commands/cache.py

@@ -0,0 +1,35 @@
+"""CLI command: cache."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from .context import _collect_repo_modules
+
+
+def clear_cache(path: str) -> dict[str, str]:
+    repo = Path(path)
+    cache_dir = repo / ".gcie" / "cache"
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+        return {"status": "cleared", "path": str(cache_dir)}
+    return {"status": "missing", "path": str(cache_dir)}
+
+
+def cache_status(path: str) -> dict[str, str]:
+    repo = Path(path)
+    cache_file = repo / ".gcie" / "cache" / "context_cache.json"
+    if cache_file.exists():
+        return {"status": "ready", "path": str(cache_file)}
+    return {"status": "missing", "path": str(cache_file)}
+
+
+def warm_cache(path: str) -> dict[str, str]:
+    repo = Path(path)
+    _collect_repo_modules(repo)
+    cache_file = repo / ".gcie" / "cache" / "context_cache.json"
+    if cache_file.exists():
+        return {"status": "warmed", "path": str(cache_file)}
+    return {"status": "missing", "path": str(cache_file)}