@pmaddire/gcie 0.1.6 → 0.1.8

package/GCIE_USAGE.md

@@ -288,3 +288,58 @@ query -> scope -> profile/budget escalation -> targeted gap-fill -> rg fallback.
 1. This file is intentionally generalized and adaptive for any repo.
 2. Keep repo-specific tuning in learned overrides and `.gcie` state, not in global defaults.
 3. If in doubt, choose the higher-accuracy path first, then optimize tokens after lock.
+
+## Cross-Repo Adaptation Rules (Required)
+
+Use these rules to keep adaptation portable across repositories.
+
+1. Adaptation case source must be repo-local:
+- Prefer generated cases from actual files in the target repo.
+- Do not rely on hardcoded expected files from another codebase family.
+- If report `case_source` is not repo-local, treat the run as invalid.
+
+2. Accuracy lock is required, but selection must be cost-aware:
+- First gate: `100%` must-have full-hit.
+- If multiple candidates pass `100%`, choose the lowest `tokens_per_expected_hit`.
+- Do not keep `slices` as active default when a `plain` candidate also has `100%` and is cheaper.
+
+3. Near-miss rescue before expensive lock-in:
+- If a cheaper candidate is below lock by one file/family (for example `90%`), run a short rescue cycle before accepting an expensive `100%` candidate:
+  1) targeted gap-fill for missing must-have file(s)
+  2) scope correction (subtree if clustered)
+  3) one budget rung increase
+- Re-evaluate after rescue; prefer the cheaper candidate if it reaches `100%`.
+
+4. Cost sanity guardrail:
+- If selected active candidate is `>40%` more expensive than the cheapest candidate, mark status `accuracy_locked_but_cost_risky` and continue family-level refinement.
+- Keep accuracy lock, but do not finalize global defaults until cost risk is reduced.
+
+5. Family-scoped finalization:
+- Finalize routing per family, not as one global winner.
+- Example: keep `slices` only for families where it is uniquely required for `100%`; use `plain` on families where it is cheaper at equal hit rate.
+
+6. Required report checks each run:
+- `case_source`
+- `full_hit_rate_pct`
+- `tokens_per_query`
+- `tokens_per_expected_hit`
+- token delta between selected candidate and cheapest candidate
+
+## Portable Validation Checklist (Any New Repo)
+
+After running adaptation:
+1. Confirm `status: ok`.
+2. Confirm `case_source: generated_repo_local`.
+3. Confirm `full_hit_rate_pct: 100` for selected final profile.
+4. Compare selected profile vs cheapest candidate:
+- if selected is much more expensive, run one rescue iteration.
+5. Run a 50-query unique validation before trusting defaults broadly.
+
+Commands:
+```powershell
+gcie.cmd adapt . --benchmark-size 10 --efficiency-iterations 5 --clear-profile
+```
+```powershell
+gcie.cmd adapt . --benchmark-size 10 --efficiency-iterations 5
+```
+

package/cli/commands/adaptation.py

@@ -30,7 +30,28 @@ class CaseResult:
     context_complete: bool
 
 
+@dataclass(frozen=True, slots=True)
+class AdaptCase:
+    name: str
+    query: str
+    intent: str
+    baseline_files: tuple[str, ...]
+    expected_files: tuple[str, ...]
+
+
 _WORD_RE = re.compile(r"[A-Za-z0-9_./-]+")
+_SOURCE_EXTS = {".py", ".js", ".jsx", ".ts", ".tsx", ".java", ".go", ".rs", ".cs", ".cpp", ".c", ".h"}
+_IGNORED_DIRS = {
+    ".git",
+    ".gcie",
+    ".planning",
+    ".venv",
+    "node_modules",
+    "__pycache__",
+    "dist",
+    "build",
+    "coverage",
+}
 
 
 def _query_keywords(text: str) -> list[str]:
@@ -252,7 +273,121 @@ def _summarize(label: str, rows: list[CaseResult]) -> dict:
     }
 
 
-def _write_back(repo_path: Path, best: dict) -> None:
+def _collect_source_files(repo_path: Path) -> list[str]:
+    files: list[str] = []
+    for path in repo_path.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(repo_path)
+        if any(part in _IGNORED_DIRS for part in rel.parts):
+            continue
+        if path.suffix.lower() not in _SOURCE_EXTS:
+            continue
+        files.append(rel.as_posix())
+    return sorted(files)
+
+
+def _static_cases_for_repo(repo_path: Path) -> list[AdaptCase]:
+    out: list[AdaptCase] = []
+    for case in list(BENCHMARK_CASES):
+        expected = tuple(case.expected_files)
+        if not expected:
+            continue
+        if not all((repo_path / rel).exists() for rel in expected):
+            continue
+        baseline = tuple(rel for rel in case.baseline_files if (repo_path / rel).exists())
+        if not baseline:
+            baseline = expected
+        out.append(
+            AdaptCase(
+                name=case.name,
+                query=case.query,
+                intent=case.intent,
+                baseline_files=baseline,
+                expected_files=expected,
+            )
+        )
+    return out
+
+
+def _generated_cases_for_repo(repo_path: Path, needed: int) -> list[AdaptCase]:
+    files = _collect_source_files(repo_path)
+    if not files:
+        return []
+
+    by_dir: dict[str, list[str]] = {}
+    for rel in files:
+        parent = str(Path(rel).parent).replace("\\", "/")
+        by_dir.setdefault(parent, []).append(rel)
+
+    rows: list[AdaptCase] = []
+    seen_names: set[str] = set()
+
+    def add_case(name: str, expected: tuple[str, ...], intent: str = "explore") -> None:
+        if len(rows) >= needed:
+            return
+        safe_name = re.sub(r"[^a-zA-Z0-9_]+", "_", name).strip("_").lower() or "case"
+        if safe_name in seen_names:
+            idx = 2
+            while f"{safe_name}_{idx}" in seen_names:
+                idx += 1
+            safe_name = f"{safe_name}_{idx}"
+        seen_names.add(safe_name)
+        symbols = []
+        for rel in expected:
+            stem = Path(rel).stem.lower()
+            symbols.extend([stem, "flow", "wiring"])
+        query = f"{' '.join(expected)} {' '.join(symbols[:6])}".strip()
+        rows.append(
+            AdaptCase(
+                name=safe_name,
+                query=query,
+                intent=intent,
+                baseline_files=expected,
+                expected_files=expected,
+            )
+        )
+
+    # Single-file probes.
+    for rel in files:
+        add_case(f"single_{Path(rel).stem}", (rel,), intent="explore")
+        if len(rows) >= max(needed // 2, 1):
+            break
+
+    # Same-directory pairs.
+    for parent, group in sorted(by_dir.items(), key=lambda item: item[0]):
+        if len(group) < 2:
+            continue
+        group = sorted(group)
+        for idx in range(len(group) - 1):
+            add_case(f"pair_{parent}_{idx}", (group[idx], group[idx + 1]), intent="explore")
+            if len(rows) >= needed:
+                return rows[:needed]
+
+    # Cross-directory pairs if still needed.
+    tops: dict[str, str] = {}
+    for rel in files:
+        top = Path(rel).parts[0] if Path(rel).parts else rel
+        tops.setdefault(top, rel)
+    top_files = list(tops.values())
+    for idx in range(len(top_files) - 1):
+        add_case(f"cross_{idx}", (top_files[idx], top_files[idx + 1]), intent="explore")
+        if len(rows) >= needed:
+            break
+
+    return rows[:needed]
+
+
+def _select_adaptation_cases(repo_path: Path, benchmark_size: int) -> tuple[list[AdaptCase], str]:
+    """Select adaptation cases generated entirely from the target repo."""
+    benchmark_size = max(1, int(benchmark_size))
+    generated = _generated_cases_for_repo(repo_path, benchmark_size)
+    if generated:
+        return generated[:benchmark_size], "generated_repo_local"
+    return [], "none_available"
+
+
+def _write_back(repo_path: Path, best: dict, case_source: str, pipeline_status: str, cost_analysis: dict) -> None:
     cfg_path = repo_path / ".gcie" / "context_config.json"
     if cfg_path.exists():
         try:
@@ -264,10 +399,12 @@ def _write_back(repo_path: Path, best: dict) -> None:
     else:
         cfg = {}
     cfg["adaptation_pipeline"] = {
-        "status": "complete",
+        "status": pipeline_status,
         "best_label": best.get("label"),
         "full_hit_rate_pct": best.get("full_hit_rate_pct"),
         "tokens_per_query": best.get("tokens_per_query"),
+        "case_source": case_source,
+        "cost_analysis": cost_analysis,
         "updated_at": datetime.now(timezone.utc).isoformat(),
     }
     cfg_path.parent.mkdir(parents=True, exist_ok=True)
@@ -290,17 +427,15 @@ def run_post_init_adaptation(
 
         clear_adaptive_profile(repo_path.as_posix())
 
-    cases = list(BENCHMARK_CASES)
+    cases, case_source = _select_adaptation_cases(repo_path, benchmark_size)
     if not cases:
         return {
             "status": "no_benchmark_cases",
             "repo": repo_path.as_posix(),
-            "message": "No benchmark cases available for accuracy-locked adaptation.",
+            "case_source": case_source,
+            "message": "No repo-usable adaptation cases available.",
         }
 
-    benchmark_size = max(1, min(len(cases), int(benchmark_size)))
-    cases = cases[:benchmark_size]
-
     slices_rows = [_evaluate_slices_case(case) for case in cases]
     plain_rows = [_evaluate_plain_case(case, allow_gapfill=False) for case in cases]
     plain_gap_rows = [_evaluate_plain_case(case, allow_gapfill=True) for case in cases]
@@ -327,13 +462,37 @@ def run_post_init_adaptation(
         if trial["full_hit_rate_pct"] >= active["full_hit_rate_pct"] and trial["tokens_per_query"] < active["tokens_per_query"]:
             active = trial
 
-    _write_back(repo_path, active)
+    cheapest = min(candidates, key=lambda item: (item["tokens_per_expected_hit"] or 10**9, item["tokens_per_query"]))
+    token_delta = int(active["total_tokens"] - cheapest["total_tokens"])
+    pct_delta = round((token_delta / max(1, int(cheapest["total_tokens"]))) * 100, 1)
+
+    pipeline_status = "ok"
+    if (
+        active.get("full_hit_rate_pct", 0.0) >= 100.0
+        and active.get("label") != cheapest.get("label")
+        and pct_delta > 40.0
+    ):
+        pipeline_status = "accuracy_locked_but_cost_risky"
+
+    cost_analysis = {
+        "cheapest_label": cheapest.get("label"),
+        "selected_label": active.get("label"),
+        "selected_vs_cheapest_token_delta": token_delta,
+        "selected_vs_cheapest_pct_delta": pct_delta,
+        "risk_threshold_pct": 40.0,
+        "cost_risky": pipeline_status == "accuracy_locked_but_cost_risky",
+    }
+
+    _write_back(repo_path, active, case_source, pipeline_status, cost_analysis)
 
     report = {
-        "status": "ok",
+        "status": pipeline_status,
         "repo": repo_path.as_posix(),
-        "benchmark_size": benchmark_size,
+        "benchmark_size": len(cases),
+        "requested_benchmark_size": int(benchmark_size),
         "efficiency_iterations": int(efficiency_iterations),
+        "case_source": case_source,
+        "cost_analysis": cost_analysis,
         "stages": {
             "accuracy_candidates": [slices_summary, plain_summary, plain_gap_summary],
             "selected_after_accuracy": best,
@@ -348,5 +507,3 @@ def run_post_init_adaptation(
     out_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
     report["report_path"] = out_path.as_posix()
     return report
-
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmaddire/gcie",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "GraphCode Intelligence Engine one-command setup and context CLI",
   "bin": {
     "gcie": "bin/gcie.js",