@pmaddire/gcie 0.1.10 → 0.1.13

package/cli/app.py

@@ -143,12 +143,14 @@ def adapt_cmd(
     benchmark_size: int = typer.Option(10, "--benchmark-size"),
     efficiency_iterations: int = typer.Option(5, "--efficiency-iterations"),
     clear_profile: bool = typer.Option(False, "--clear-profile"),
+    adapt_workers: int = typer.Option(0, "--adapt-workers", help="Adaptation evaluation workers (0=auto)"),
 ) -> None:
     result = run_post_init_adaptation(
         repo,
         benchmark_size=benchmark_size,
         efficiency_iterations=efficiency_iterations,
         clear_profile=clear_profile,
+        adapt_workers=(None if adapt_workers <= 0 else adapt_workers),
     )
     typer.echo(json.dumps(result, indent=2))
 
@@ -163,6 +165,7 @@ def setup_cmd(
     adapt: bool = typer.Option(False, "--adapt", help="Run post-init adaptation pipeline after setup"),
     adaptation_benchmark_size: int = typer.Option(10, "--adapt-benchmark-size"),
     adaptation_efficiency_iterations: int = typer.Option(5, "--adapt-efficiency-iterations"),
+    adaptation_workers: int = typer.Option(0, "--adapt-workers", help="Adaptation evaluation workers (0=auto)"),
 ) -> None:
     result = run_setup(
         path,
@@ -173,6 +176,7 @@ def setup_cmd(
         run_adaptation_pass=adapt,
         adaptation_benchmark_size=adaptation_benchmark_size,
         adaptation_efficiency_iterations=adaptation_efficiency_iterations,
+        adaptation_workers=(None if adaptation_workers <= 0 else adaptation_workers),
     )
     typer.echo(json.dumps(result, indent=2))
 
@@ -214,3 +218,4 @@ if __name__ == "__main__":
     app()
 
 
+

package/cli/commands/adaptation.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
 import json
+import os
 import re
 from pathlib import Path
 
@@ -52,7 +54,20 @@ _IGNORED_DIRS = {
     "build",
     "coverage",
 }
-_METHOD_ORDER = ["plain", "plain_gapfill", "plain_rescue", "slices"]
+_METHOD_ORDER = ["plain", "plain_chain", "plain_gapfill", "plain_rescue", "slices"]
+
+
+def _adapt_worker_count(workers: int | None = None) -> int:
+    if workers is not None:
+        return max(1, int(workers))
+    env_value = os.getenv("GCIE_ADAPT_WORKERS", "").strip()
+    if env_value:
+        try:
+            return max(1, int(env_value))
+        except ValueError:
+            pass
+    cpu = os.cpu_count() or 4
+    return max(1, min(8, cpu))
 
 
 def _query_keywords(text: str) -> list[str]:
@@ -127,31 +142,31 @@ def _normalize_scoped_path(plan_path: str, rel_path: str) -> str:
     return f"{base}/{normalized}"
 
 
-def _family_path(expected_files: tuple[str, ...]) -> str:
-    if not expected_files:
-        return "."
-    parent_parts: list[tuple[str, ...]] = []
-    for rel in expected_files:
-        parent = Path(rel).parent
-        if str(parent) in {"", "."}:
-            parent_parts.append(tuple())
-        else:
-            parent_parts.append(tuple(parent.parts))
-
-    common: list[str] = []
-    if parent_parts:
-        shortest = min(len(parts) for parts in parent_parts)
-        for idx in range(shortest):
-            token = parent_parts[0][idx]
-            if all(parts[idx] == token for parts in parent_parts):
-                common.append(token)
-            else:
-                break
-    if common:
-        return Path(*common).as_posix()
-
-    heads = {Path(p).parts[0] for p in expected_files if Path(p).parts}
-    return next(iter(heads)) if len(heads) == 1 else "."
+def _family_path(expected_files: tuple[str, ...]) -> str:
+    if not expected_files:
+        return "."
+    parent_parts: list[tuple[str, ...]] = []
+    for rel in expected_files:
+        parent = Path(rel).parent
+        if str(parent) in {"", "."}:
+            parent_parts.append(tuple())
+        else:
+            parent_parts.append(tuple(parent.parts))
+
+    common: list[str] = []
+    if parent_parts:
+        shortest = min(len(parts) for parts in parent_parts)
+        for idx in range(shortest):
+            token = parent_parts[0][idx]
+            if all(parts[idx] == token for parts in parent_parts):
+                common.append(token)
+            else:
+                break
+    if common:
+        return Path(*common).as_posix()
+
+    heads = {Path(p).parts[0] for p in expected_files if Path(p).parts}
+    return next(iter(heads)) if len(heads) == 1 else "."
 
 def _safe_scope(path: str) -> str:
     if not path or path in {".", "./"}:
@@ -162,39 +177,39 @@ def _safe_scope(path: str) -> str:
     return "."
 
 
-def _plan_query(case) -> tuple[str, str, int | None]:
-    path = _family_path(case.expected_files)
-    if getattr(case, "name", "") == "cli_context_command":
-        return ".", "cli/commands/context.py llm_context/context_builder.py build_context token_budget mandatory_node_ids snippet_selector", 950
-
-    repo_path = Path('.').resolve()
-    cue_terms: list[str] = []
-    for rel in case.expected_files:
-        cue_terms.extend(_extract_query_cues_for_file(repo_path, rel)[:3])
-    cue_terms.extend(_query_keywords(case.query)[:4])
-
-    dedup: list[str] = []
-    seen: set[str] = set()
-    for token in [*case.expected_files, *cue_terms]:
-        key = token.lower()
-        if key in seen:
-            continue
-        seen.add(key)
-        dedup.append(token)
-        if len(dedup) >= 14:
-            break
-    query = " ".join(dedup).strip()
-
-    expected_count = len(case.expected_files)
-    if expected_count >= 3:
-        budget = 1100
-    elif expected_count == 2:
-        budget = 950
-    else:
-        budget = 850
-
-    if getattr(case, "name", "") in {"repository_scanner_filters", "knowledge_index_query_api", "execution_trace_graph", "parser_fallbacks"}:
-        budget = 800
+def _plan_query(case) -> tuple[str, str, int | None]:
+    path = _family_path(case.expected_files)
+    if getattr(case, "name", "") == "cli_context_command":
+        return ".", "cli/commands/context.py llm_context/context_builder.py build_context token_budget mandatory_node_ids snippet_selector", 950
+
+    repo_path = Path('.').resolve()
+    cue_terms: list[str] = []
+    for rel in case.expected_files:
+        cue_terms.extend(_extract_query_cues_for_file(repo_path, rel)[:3])
+    cue_terms.extend(_query_keywords(case.query)[:4])
+
+    dedup: list[str] = []
+    seen: set[str] = set()
+    for token in [*case.expected_files, *cue_terms]:
+        key = token.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        dedup.append(token)
+        if len(dedup) >= 14:
+            break
+    query = " ".join(dedup).strip()
+
+    expected_count = len(case.expected_files)
+    if expected_count >= 3:
+        budget = 1100
+    elif expected_count == 2:
+        budget = 950
+    else:
+        budget = 850
+
+    if getattr(case, "name", "") in {"repository_scanner_filters", "knowledge_index_query_api", "execution_trace_graph", "parser_fallbacks"}:
+        budget = 800
     return path, query, budget
 
 def _case_family(case) -> str:
@@ -229,6 +244,82 @@ def _build_gapfill_query(case, missing_rel: str) -> str:
 
     return " ".join(dedup)
 
+
+def _collect_files_from_payload(scope: str, payload: dict) -> set[str]:
+    return {
+        _normalize_scoped_path(scope, rel)
+        for rel in (_node_to_file(item.get("node_id", "")) for item in payload.get("snippets", []))
+        if rel
+    }
+
+
+def _hop_query_for_pair(case, left: str, right: str) -> str:
+    repo_path = Path('.').resolve()
+    cues: list[str] = []
+    cues.extend(_extract_query_cues_for_file(repo_path, left)[:3])
+    cues.extend(_extract_query_cues_for_file(repo_path, right)[:3])
+    cues.extend(_query_keywords(case.query)[:4])
+
+    dedup: list[str] = []
+    seen: set[str] = set()
+    for token in [left, right, *cues]:
+        key = token.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        dedup.append(token)
+        if len(dedup) >= 12:
+            break
+    return " ".join(dedup)
+
+
+def _evaluate_plain_chain_case(case) -> CaseResult:
+    expected = tuple(case.expected_files)
+    if len(expected) < 3:
+        return _evaluate_plain_case(case, allow_gapfill=False)
+
+    tokens = 0
+    files: set[str] = set()
+    mode = "plain_chain_workflow"
+
+    # Decompose N-file chains into adjacent hops to reduce broad root overfetch.
+    for idx in range(len(expected) - 1):
+        left = expected[idx]
+        right = expected[idx + 1]
+        scope = _safe_scope(_family_path((left, right)))
+        query = _hop_query_for_pair(case, left, right)
+        hop_payload = run_context(scope, query, budget=950, intent=case.intent)
+        tokens += int(hop_payload.get("tokens", 0) or 0)
+        files.update(_collect_files_from_payload(scope, hop_payload))
+
+    missing = [rel for rel in expected if rel not in files]
+    if missing:
+        mode = "plain_chain_workflow_gapfill"
+        for rel in list(missing):
+            # Chain gapfill stays narrow: direct file scope only (no broad fallback).
+            scope = rel if (Path(rel).exists() and Path(rel).is_file()) else _safe_scope(_family_path((rel,)))
+            budget = 500 if rel.endswith('/main.py') or rel == 'main.py' else 700
+            gap_payload = run_context(scope, _build_gapfill_query(case, rel), budget=budget, intent=case.intent)
+            tokens += int(gap_payload.get("tokens", 0) or 0)
+            files.update(_collect_files_from_payload(scope, gap_payload))
+            missing = [m for m in expected if m not in files]
+            if not missing:
+                break
+
+    expected_hits = len(expected) - len(missing)
+    family = _classify_query_family(case.query)
+    return CaseResult(
+        name=case.name,
+        family=family,
+        mode=mode,
+        tokens=tokens,
+        expected_hits=expected_hits,
+        expected_total=len(expected),
+        missing_expected=tuple(missing),
+        context_complete=not missing,
+    )
+
+
 def _evaluate_plain_case(case, *, allow_gapfill: bool = True, aggressive_gapfill: bool = False) -> CaseResult:
     path, query, budget = _plan_query(case)
     path = _safe_scope(path)
@@ -369,6 +460,8 @@ def _evaluate_slices_case(case) -> CaseResult:
 def _evaluate_case_with_method(case, method: str) -> CaseResult:
     if method == "plain":
         return _evaluate_plain_case(case, allow_gapfill=False)
+    if method == "plain_chain":
+        return _evaluate_plain_chain_case(case)
     if method == "plain_gapfill":
         return _evaluate_plain_case(case, allow_gapfill=True, aggressive_gapfill=False)
     if method == "plain_rescue":
@@ -453,6 +546,9 @@ def _generated_cases_for_repo(repo_path: Path, needed: int) -> list[AdaptCase]:
     # Build a diversified sample so adaptation can learn in mixed-layer repos.
     single_target = max(1, needed // 3)
     same_dir_target = max(1, needed // 3)
+    local_target = max(1, needed // 2)
+    if single_target + same_dir_target < local_target:
+        same_dir_target = local_target - single_target
     cross_dir_target = max(1, needed - single_target - same_dir_target)
 
     # 1) singles
@@ -495,23 +591,23 @@ def _generated_cases_for_repo(repo_path: Path, needed: int) -> list[AdaptCase]:
         if cross_added >= cross_dir_target:
             break
 
-    # 4) include some 3-file chains for multi-hop calibration when dataset is larger.
-    if needed >= 12 and len(rows) < needed:
-        chain_budget = max(1, needed // 6)
-        chains_added = 0
-        reps = [item[1] for item in top_items]
-        for idx in range(len(reps) - 2):
-            add_case(
-                f"chain_{idx}",
-                (reps[idx], reps[idx + 1], reps[idx + 2]),
-                intent='refactor',
-            )
-            if len(rows) >= needed:
-                return rows[:needed]
-            chains_added += 1
-            if chains_added >= chain_budget:
-                break
-
+    # 4) include some 3-file chains for multi-hop calibration when dataset is larger.
+    if needed >= 12 and len(rows) < needed:
+        chain_budget = max(1, int(round(needed * 0.12)))
+        chains_added = 0
+        reps = [item[1] for item in top_items]
+        for idx in range(len(reps) - 2):
+            add_case(
+                f"chain_{idx}",
+                (reps[idx], reps[idx + 1], reps[idx + 2]),
+                intent='refactor',
+            )
+            if len(rows) >= needed:
+                return rows[:needed]
+            chains_added += 1
+            if chains_added >= chain_budget:
+                break
+
     # 5) fill remainder with additional nearby pairs
     if len(rows) < needed:
         for idx in range(len(files) - 1):
@@ -548,12 +644,52 @@ def _cheaper_method(method: str) -> str | None:
     return _METHOD_ORDER[idx - 1]
 
 
-def _run_family_policy(cases: list[AdaptCase], family_policy: dict[str, str]) -> tuple[list[CaseResult], dict, dict[str, dict]]:
-    rows: list[CaseResult] = []
-    for case in cases:
+def _evaluate_cases_with_method(cases: list[AdaptCase], method: str, workers: int) -> list[CaseResult]:
+    if not cases:
+        return []
+    if workers <= 1 or len(cases) <= 1:
+        return [_evaluate_case_with_method(case, method) for case in cases]
+
+    slots: list[CaseResult | None] = [None] * len(cases)
+    max_workers = max(1, min(workers, len(cases)))
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        future_map = {
+            pool.submit(_evaluate_case_with_method, case, method): idx
+            for idx, case in enumerate(cases)
+        }
+        for future in as_completed(future_map):
+            slots[future_map[future]] = future.result()
+
+    return [row for row in slots if row is not None]
+
+
+def _run_family_policy(
+    cases: list[AdaptCase],
+    family_policy: dict[str, str],
+    *,
+    workers: int,
+) -> tuple[list[CaseResult], dict, dict[str, dict]]:
+    if not cases:
+        summary = _summarize('policy_run', [])
+        return [], summary, {}
+
+    grouped: dict[str, list[tuple[int, AdaptCase]]] = {}
+    for idx, case in enumerate(cases):
         family = _case_family(case)
         method = family_policy.get(family, 'plain')
-        rows.append(_evaluate_case_with_method(case, method))
+        key = f'{family}|{method}'
+        grouped.setdefault(key, []).append((idx, case))
+
+    ordered: list[CaseResult | None] = [None] * len(cases)
+    for key in sorted(grouped):
+        pairs = grouped[key]
+        _, method = key.split('|', 1)
+        group_cases = [case for _, case in pairs]
+        group_rows = _evaluate_cases_with_method(group_cases, method, workers)
+        for (orig_idx, _), row in zip(pairs, group_rows):
+            ordered[orig_idx] = row
+
+    rows = [row for row in ordered if row is not None]
     summary = _summarize('policy_run', rows)
 
     by_family: dict[str, dict] = {}
@@ -569,45 +705,51 @@ def _run_family_policy(cases: list[AdaptCase], family_policy: dict[str, str]) ->
     return rows, summary, by_family
 
 
-def _select_best_summary(summaries: list[dict]) -> dict:
-    full_hit = [s for s in summaries if s.get("full_hit_rate_pct", 0.0) >= 100.0]
-    if full_hit:
-        return min(full_hit, key=lambda s: (s.get("tokens_per_expected_hit") or 10**9, s.get("tokens_per_query", 10**9)))
-    return max(
-        summaries,
-        key=lambda s: (s.get("target_hit_rate_pct", 0.0), -s.get("tokens_per_query", 10**9)),
-    )
-
-
-def _bootstrap_family_policy(cases: list[AdaptCase], families: list[str]) -> tuple[dict[str, str], list[dict]]:
-    policy: dict[str, str] = {}
-    diagnostics: list[dict] = []
-    for fam in families:
-        fam_cases = [case for case in cases if _case_family(case) == fam]
-        if not fam_cases:
-            policy[fam] = "plain"
-            continue
-
-        method_summaries: list[dict] = []
-        for method in _METHOD_ORDER:
-            rows = [_evaluate_case_with_method(case, method) for case in fam_cases]
-            summary = _summarize(f"bootstrap_{fam}_{method}", rows)
-            summary["method"] = method
-            summary["family"] = fam
-            method_summaries.append(summary)
-
-        best = _select_best_summary(method_summaries)
-        selected_method = str(best.get("method", "plain"))
-        policy[fam] = selected_method
-        diagnostics.append(
-            {
-                "family": fam,
-                "selected_method": selected_method,
-                "selected_summary": best,
-                "candidates": method_summaries,
-            }
-        )
-    return policy, diagnostics
+def _select_best_summary(summaries: list[dict]) -> dict:
+    full_hit = [s for s in summaries if s.get("full_hit_rate_pct", 0.0) >= 100.0]
+    if full_hit:
+        return min(full_hit, key=lambda s: (s.get("tokens_per_expected_hit") or 10**9, s.get("tokens_per_query", 10**9)))
+    return max(
+        summaries,
+        key=lambda s: (s.get("target_hit_rate_pct", 0.0), -s.get("tokens_per_query", 10**9)),
+    )
+
+
+def _bootstrap_family_policy(
+    cases: list[AdaptCase],
+    families: list[str],
+    *,
+    workers: int,
+) -> tuple[dict[str, str], list[dict]]:
+    policy: dict[str, str] = {}
+    diagnostics: list[dict] = []
+    for fam in families:
+        fam_cases = [case for case in cases if _case_family(case) == fam]
+        if not fam_cases:
+            policy[fam] = "plain"
+            continue
+
+        method_summaries: list[dict] = []
+        for method in _METHOD_ORDER:
+            rows = _evaluate_cases_with_method(fam_cases, method, workers)
+            summary = _summarize(f"bootstrap_{fam}_{method}", rows)
+            summary["method"] = method
+            summary["family"] = fam
+            method_summaries.append(summary)
+
+        best = _select_best_summary(method_summaries)
+        selected_method = str(best.get("method", "plain"))
+        policy[fam] = selected_method
+        diagnostics.append(
+            {
+                "family": fam,
+                "selected_method": selected_method,
+                "selected_summary": best,
+                "candidates": method_summaries,
+            }
+        )
+    return policy, diagnostics
+
 def _write_back(repo_path: Path, best: dict, case_source: str, pipeline_status: str, cost_analysis: dict, family_policy: dict[str, str]) -> None:
     cfg_path = repo_path / '.gcie' / 'context_config.json'
     if cfg_path.exists():
@@ -648,12 +790,11 @@ def run_post_init_adaptation(
     benchmark_size: int = 10,
     efficiency_iterations: int = 5,
     clear_profile: bool = False,
+    adapt_workers: int | None = None,
 ) -> dict:
     repo_path = Path(repo).resolve()
 
     # Ensure all relative retrieval/evaluation calls execute in the target repo.
-    import os
-
     os.chdir(repo_path)
     run_index(repo_path.as_posix())
 
@@ -671,8 +812,9 @@ def run_post_init_adaptation(
             'message': 'No repo-usable adaptation cases available.',
         }
 
-    families = sorted({_case_family(case) for case in cases})
-    family_policy, bootstrap_diagnostics = _bootstrap_family_policy(cases, families)
+    workers = _adapt_worker_count(adapt_workers)
+    families = sorted({_case_family(case) for case in cases})
+    family_policy, bootstrap_diagnostics = _bootstrap_family_policy(cases, families, workers=workers)
 
     # Accuracy rounds: promote methods per failing family until lock.
     accuracy_rounds_max = 5
@@ -680,7 +822,7 @@ def run_post_init_adaptation(
     lock_streak = 0
 
     for rnd in range(1, accuracy_rounds_max + 1):
-        rows, summary, by_family = _run_family_policy(cases, family_policy)
+        rows, summary, by_family = _run_family_policy(cases, family_policy, workers=workers)
         round_payload = {
             'round': rnd,
             'family_policy': dict(family_policy),
@@ -714,7 +856,7 @@ def run_post_init_adaptation(
         )
 
     family_policy = dict(selected_accuracy_round['family_policy'])
-    rows, current_summary, by_family = _run_family_policy(cases, family_policy)
+    rows, current_summary, by_family = _run_family_policy(cases, family_policy, workers=workers)
 
     # Efficiency rounds: attempt family-level cheaper method under hard 100% gate.
     efficiency_trials: list[dict] = []
@@ -726,7 +868,7 @@ def run_post_init_adaptation(
                 continue
             trial_policy = dict(family_policy)
             trial_policy[fam] = cheaper
-            _, trial_summary, trial_by_family = _run_family_policy(cases, trial_policy)
+            _, trial_summary, trial_by_family = _run_family_policy(cases, trial_policy, workers=workers)
             trial_payload = {
                 'iteration': idx + 1,
                 'family': fam,
@@ -747,10 +889,10 @@ def run_post_init_adaptation(
             break
 
     # Global candidate snapshots for transparency.
-    slices_rows = [_evaluate_case_with_method(case, 'slices') for case in cases]
-    plain_rows = [_evaluate_case_with_method(case, 'plain') for case in cases]
-    plain_gap_rows = [_evaluate_case_with_method(case, 'plain_gapfill') for case in cases]
-    plain_rescue_rows = [_evaluate_case_with_method(case, 'plain_rescue') for case in cases]
+    slices_rows = _evaluate_cases_with_method(cases, 'slices', workers)
+    plain_rows = _evaluate_cases_with_method(cases, 'plain', workers)
+    plain_gap_rows = _evaluate_cases_with_method(cases, 'plain_gapfill', workers)
+    plain_rescue_rows = _evaluate_cases_with_method(cases, 'plain_rescue', workers)
     slices_summary = _summarize('slices_accuracy_stage', slices_rows)
     plain_summary = _summarize('plain_accuracy_stage', plain_rows)
     plain_gap_summary = _summarize('plain_gapfill_accuracy_stage', plain_gap_rows)
@@ -799,11 +941,12 @@ def run_post_init_adaptation(
         'benchmark_size': len(cases),
         'requested_benchmark_size': int(benchmark_size),
         'efficiency_iterations': int(efficiency_iterations),
+        'adapt_workers': workers,
         'case_source': case_source,
         'family_policy': family_policy,
         'cost_analysis': cost_analysis,
-        'phases': {
-            'bootstrap': bootstrap_diagnostics,
+        'phases': {
+            'bootstrap': bootstrap_diagnostics,
             'accuracy_rounds': accuracy_rounds,
             'selected_accuracy_round': selected_accuracy_round,
             'efficiency_trials': efficiency_trials,
@@ -837,6 +980,11 @@ def run_post_init_adaptation(
 
 
 
+
+
+
+
+
 
 
 

package/cli/commands/setup.py

@@ -1,138 +1,141 @@
-"""Repository setup and teardown helpers for GCIE."""
-
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-from context.architecture_bootstrap import ensure_initialized
-
-from .adaptation import run_post_init_adaptation
-from .index import run_index
-
-
-def _repo_root() -> Path:
-    return Path(__file__).resolve().parents[2]
-
-
-def _copy_if_needed(source: Path, target: Path, *, force: bool) -> str:
-    if not source.exists():
-        return "source_missing"
-    if target.exists() and not force:
-        return "skipped_existing"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
-    return "written"
-
-
-def _is_within(base: Path, target: Path) -> bool:
-    try:
-        target.resolve().relative_to(base.resolve())
-        return True
-    except ValueError:
-        return False
-
-
-def _remove_path(root: Path, target: Path) -> str:
-    if not _is_within(root, target):
-        return "skipped_outside_repo"
-    if not target.exists():
-        return "not_found"
-    if target.is_dir():
-        shutil.rmtree(target)
-        return "removed_dir"
-    target.unlink()
-    return "removed_file"
-
-
-def run_setup(
-    path: str,
-    *,
-    force: bool = False,
-    include_agent_usage: bool = True,
-    include_setup_doc: bool = True,
-    run_index_pass: bool = True,
-    run_adaptation_pass: bool = False,
-    adaptation_benchmark_size: int = 10,
-    adaptation_efficiency_iterations: int = 5,
-) -> dict:
-    """Initialize a repository so GCIE can be used immediately."""
-    target = Path(path).resolve()
-    target.mkdir(parents=True, exist_ok=True)
-
-    config = ensure_initialized(target)
-    gcie_dir = target / ".gcie"
-
-    status: dict[str, object] = {
-        "repo": target.as_posix(),
-        "gcie_dir": gcie_dir.as_posix(),
-        "architecture_initialized": True,
-        "files": {},
-    }
-
-    source_root = _repo_root()
-    copied: dict[str, str] = {}
-
-    if include_agent_usage:
-        copied["GCIE_USAGE.md"] = _copy_if_needed(
-            source_root / "GCIE_USAGE.md",
-            target / "GCIE_USAGE.md",
-            force=force,
-        )
-
-    if include_setup_doc:
-        copied["SETUP_ANY_REPO.md"] = _copy_if_needed(
-            source_root / "SETUP_ANY_REPO.md",
-            target / "SETUP_ANY_REPO.md",
-            force=force,
-        )
-
-    status["files"] = copied
-    status["context_config"] = config
-
-    if run_index_pass:
-        status["index"] = run_index(target.as_posix())
-    else:
-        status["index"] = {"skipped": True}
-
-    if run_adaptation_pass:
-        status["adaptation"] = run_post_init_adaptation(
-            target.as_posix(),
-            benchmark_size=adaptation_benchmark_size,
-            efficiency_iterations=adaptation_efficiency_iterations,
-            clear_profile=True,
-        )
-    else:
-        status["adaptation"] = {"skipped": True}
-
-    return status
-
-
-def run_remove(
-    path: str,
-    *,
-    remove_planning: bool = False,
-    remove_gcie_usage: bool = True,
-    remove_setup_doc: bool = True,
-) -> dict:
-    """Remove GCIE-managed files from a repository."""
-    target = Path(path).resolve()
-    target.mkdir(parents=True, exist_ok=True)
-
-    removed: dict[str, str] = {}
-    removed[".gcie"] = _remove_path(target, target / ".gcie")
-
-    if remove_gcie_usage:
-        removed["GCIE_USAGE.md"] = _remove_path(target, target / "GCIE_USAGE.md")
-
-    if remove_setup_doc:
-        removed["SETUP_ANY_REPO.md"] = _remove_path(target, target / "SETUP_ANY_REPO.md")
-
-    if remove_planning:
-        removed[".planning"] = _remove_path(target, target / ".planning")
-
-    return {
-        "repo": target.as_posix(),
-        "removed": removed,
-        "remove_planning": remove_planning,
+"""Repository setup and teardown helpers for GCIE."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from context.architecture_bootstrap import ensure_initialized
+
+from .adaptation import run_post_init_adaptation
+from .index import run_index
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _copy_if_needed(source: Path, target: Path, *, force: bool) -> str:
+    if not source.exists():
+        return "source_missing"
+    if target.exists() and not force:
+        return "skipped_existing"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+    return "written"
+
+
+def _is_within(base: Path, target: Path) -> bool:
+    try:
+        target.resolve().relative_to(base.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _remove_path(root: Path, target: Path) -> str:
+    if not _is_within(root, target):
+        return "skipped_outside_repo"
+    if not target.exists():
+        return "not_found"
+    if target.is_dir():
+        shutil.rmtree(target)
+        return "removed_dir"
+    target.unlink()
+    return "removed_file"
+
+
+def run_setup(
+    path: str,
+    *,
+    force: bool = False,
+    include_agent_usage: bool = True,
+    include_setup_doc: bool = True,
+    run_index_pass: bool = True,
+    run_adaptation_pass: bool = False,
+    adaptation_benchmark_size: int = 10,
+    adaptation_efficiency_iterations: int = 5,
+    adaptation_workers: int | None = None,
+) -> dict:
+    """Initialize a repository so GCIE can be used immediately."""
+    target = Path(path).resolve()
+    target.mkdir(parents=True, exist_ok=True)
+
+    config = ensure_initialized(target)
+    gcie_dir = target / ".gcie"
+
+    status: dict[str, object] = {
+        "repo": target.as_posix(),
+        "gcie_dir": gcie_dir.as_posix(),
+        "architecture_initialized": True,
+        "files": {},
     }
+
+    source_root = _repo_root()
+    copied: dict[str, str] = {}
+
+    if include_agent_usage:
+        copied["GCIE_USAGE.md"] = _copy_if_needed(
+            source_root / "GCIE_USAGE.md",
+            target / "GCIE_USAGE.md",
+            force=force,
+        )
+
+    if include_setup_doc:
+        copied["SETUP_ANY_REPO.md"] = _copy_if_needed(
+            source_root / "SETUP_ANY_REPO.md",
+            target / "SETUP_ANY_REPO.md",
+            force=force,
+        )
+
+    status["files"] = copied
+    status["context_config"] = config
+
+    if run_index_pass:
+        status["index"] = run_index(target.as_posix())
+    else:
+        status["index"] = {"skipped": True}
+
+    if run_adaptation_pass:
+        status["adaptation"] = run_post_init_adaptation(
+            target.as_posix(),
+            benchmark_size=adaptation_benchmark_size,
+            efficiency_iterations=adaptation_efficiency_iterations,
+            clear_profile=True,
+            adapt_workers=adaptation_workers,
+        )
+    else:
+        status["adaptation"] = {"skipped": True}
+
+    return status
+
+
+def run_remove(
+    path: str,
+    *,
+    remove_planning: bool = False,
+    remove_gcie_usage: bool = True,
+    remove_setup_doc: bool = True,
+) -> dict:
+    """Remove GCIE-managed files from a repository."""
+    target = Path(path).resolve()
+    target.mkdir(parents=True, exist_ok=True)
+
+    removed: dict[str, str] = {}
+    removed[".gcie"] = _remove_path(target, target / ".gcie")
+
+    if remove_gcie_usage:
+        removed["GCIE_USAGE.md"] = _remove_path(target, target / "GCIE_USAGE.md")
+
+    if remove_setup_doc:
+        removed["SETUP_ANY_REPO.md"] = _remove_path(target, target / "SETUP_ANY_REPO.md")
+
+    if remove_planning:
+        removed[".planning"] = _remove_path(target, target / ".planning")
+
+    return {
+        "repo": target.as_posix(),
+        "removed": removed,
+        "remove_planning": remove_planning,
+    }
+

package/package.json

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