@pmaddire/gcie 0.1.7 → 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

@@ -387,7 +387,7 @@ def _select_adaptation_cases(repo_path: Path, benchmark_size: int) -> tuple[list
     return [], "none_available"
 
 
-def _write_back(repo_path: Path, best: dict, case_source: str) -> None:
+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:
@@ -399,11 +399,12 @@ def _write_back(repo_path: Path, best: dict, case_source: str) -> 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)
@@ -461,15 +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, case_source)
+    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": 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,

package/package.json

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