Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(indexing): make fast and full scope truthful (#2246)

Raghav Chamadiyae0986cdb0777
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 1a007becf..002308e5d 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -266,7 +266,9 @@ See [WORKTREES.md](../scale/WORKTREES.md).
**First-time indexing:** `update --workspace` runs full first-time indexing for workspace entries that have no `.repowise/` dir yet (previously skipped with `"not_indexed"`). The pipeline runs index-only, no LLM cost, and writes a state.json marker. Doc generation then follows on the next update once the repo has an index: pass `--docs` (or set its `docs_enabled`) and it regenerates pages like any other member.
-**Upgrading a fast index to full (`--full`):** a repo first indexed with `repowise init --mode fast` has the full dependency graph + metrics persisted, but only the *essential* git tier (last commits, no per-file blame or co-change) and no LLM docs. `repowise update --full` upgrades it **incrementally**: it backfills the git tier to FULL (per-file blame + repo-wide co-change) using a resumable, checkpointed worker, then generates the docs that fast mode skipped. Crucially, it **reuses the persisted graph**, the dependency graph is rehydrated from SQL rather than re-parsed and re-resolved, so the expensive import/call/heritage resolution and centrality computation the fast index already did are not repeated. This is measurably cheaper than re-running a full `init`. The backfill is resumable: if it is interrupted, re-running `repowise update --full` picks it up. A provider is required (the fast index made no LLM calls), so pass `--provider`/`--model` or have one configured. It does not build the vector store, so run `repowise reindex` afterwards if you want semantic search. Single-repo only; it errors if run in workspace mode.
+**Upgrading a fast index to full (`--full`):** a repo first indexed with `repowise init --mode fast` has the full dependency graph + metrics persisted, but only the *essential* git tier (last commits, no per-file blame or co-change) and no model-written docs. `repowise update --full` upgrades it **incrementally**: it backfills the git tier to FULL using a resumable checkpoint, reuses the persisted graph, generates the missing prose, rebuilds full-text search, embeds pages when the resolved embedder is available, and recomputes health against FULL history. The command records the transition before work and checkpoints each completed stage; failure or cancellation leaves the prior scope truthful and a retryable upgrade instead of stamping the repository full early. Persisted provider/model/embedder choices are reused when valid, overrides remain explicit, and estimated model cost is shown before paid generation. If embedding is unavailable the completed scope says so and gives the exact recovery command, `repowise reindex`; it never implies semantic search was built. Single-repo only; it errors in workspace mode.
+
+`state.json:index_scope` is the canonical machine-readable description used by `status --format json`, `/api/repos`, generated agent guidance, and MCP `_meta.index_scope`. It separately records run mode, content provenance (`none`, `template`, or `model`), Git tier, configured commit cap, achieved Git-history coverage, configured/effective file-page caps, eligible/generated/omitted file-page counts, unavailable/skipped analysis, search availability, provider choices, and upgrade state. Older indexes project missing facts as `unknown`/`null`; a configured cap is never reported as achieved coverage and a missing analysis result is never reported as a clean result.
**Examples:**
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index 7ff712d2c..3f79a6bf9 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -1713,12 +1713,9 @@ def init_command(
# One flag, one meaning: --no-editor-setup now suppresses the project-local
# writes as well as the global registration. The paths come back so the
# completion panel can name what landed in the working tree.
- files_written = write_editor_project_files(
- console,
- repo_path,
- options=editor_options,
- no_editor_setup=not editor_setup,
- )
+ # Render after state persistence below so generated guidance reads the same
+ # canonical index_scope that status/API/MCP expose.
+ files_written: list[Path] = []
register_editor_clients(console, repo_path, no_editor_setup=not editor_setup)
# Inherit the workspace's distill rewrite-hook verdict NOW, before the
@@ -1758,6 +1755,59 @@ def init_command(
base_state["run_mode"] = run_mode
base_state["git_tier"] = git_tier_for_run_mode(run_mode)
apply_git_history_coverage_state(base_state, result)
+ from repowise.core.generation.selection import count_documentable_files
+ from repowise.core.index_scope import file_page_scope, stamp_index_scope
+
+ _scope_embedder = embedder_name_resolved if not effective_index_only else _index_only_embedder
+ _unavailable = []
+ if getattr(result, "health_report", None) is None:
+ _unavailable.append("health")
+ _skipped = ["generation"] if run_mode == "fast" else []
+ stamp_index_scope(
+ base_state,
+ {"commit_limit": resolved_commit_limit, "max_file_pages": max_file_pages},
+ run_mode=run_mode,
+ content_provenance={"none": "none", "deterministic": "template", "llm": "model"}[
+ _docs_mode
+ ],
+ git_tier=git_tier_for_run_mode(run_mode),
+ git_commit_cap=resolved_commit_limit,
+ file_pages={
+ "configured_cap": max_file_pages,
+ **(
+ result.generation_scope
+ if getattr(result, "generation_scope", None)
+ else file_page_scope(
+ configured_cap=max_file_pages,
+ eligible=count_documentable_files(result.parsed_files),
+ generated_pages=result.generated_pages,
+ )
+ ),
+ },
+ analysis={"unavailable": _unavailable, "skipped": _skipped},
+ provider={
+ "name": provider.provider_name if provider is not None else None,
+ "model": provider.model_name if provider is not None else None,
+ "embedder": _scope_embedder,
+ "reused": False,
+ "model_cost_possible": _docs_mode == "llm",
+ },
+ search={
+ "full_text": "available" if result.generated_pages else "unavailable",
+ "semantic": (
+ "available"
+ if result.generated_pages and _scope_embedder and _scope_embedder != "mock"
+ else "unavailable"
+ ),
+ "next_command": "repowise reindex" if result.generated_pages else None,
+ },
+ upgrade={
+ "status": "pending" if _docs_mode != "llm" else "not_applicable",
+ "retryable": _docs_mode != "llm",
+ "completed_stages": [],
+ "next_stage": "git_backfill" if run_mode == "fast" else "generation",
+ },
+ )
# Record whether submodules were indexed so `repowise update` rebuilds
# the graph with the same boundary semantics (same pattern as git_tier:
# missing → False keeps legacy behavior for old state files).
@@ -1835,10 +1885,18 @@ def init_command(
commit_limit=commit_limit,
resolved_commit_limit=resolved_commit_limit,
resolved_reasoning=resolved_reasoning,
+ max_file_pages=max_file_pages,
include_submodules=include_submodules,
save_key=save_key,
)
+ files_written = write_editor_project_files(
+ console,
+ repo_path,
+ options=editor_options,
+ no_editor_setup=not editor_setup,
+ )
+
_record_init_outcome(
result=result,
effective_index_only=effective_index_only,
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
index 74ff17f17..c8231956c 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
@@ -330,6 +330,8 @@ def run_repo_generation(
# is what persistence reads however the block exits.
preserved_page_ids: set[str] = set()
result.preserved_page_ids = preserved_page_ids
+ generation_scope: dict[str, int | None] = {}
+ result.generation_scope = generation_scope
with Progress(*columns, console=console) as gen_progress:
gen_callback: Any = RichProgressCallback(gen_progress, console)
@@ -368,6 +370,7 @@ def run_repo_generation(
else None
),
test_run=test_run,
+ selection_out=generation_scope,
)
)
if warnings is not None:
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
index 8daa7b6b0..c0c4d65c1 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -29,6 +29,7 @@ from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_
from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.docs_mode import docs_mode_state_fields
from repowise.core.generation.models import count_stub_fallbacks
+from repowise.core.index_scope import file_page_scope, stamp_index_scope
from repowise.core.repo_config import config_dependency_fingerprints
logger = structlog.get_logger(__name__)
@@ -339,6 +340,54 @@ def apply_git_history_coverage_state(state: dict[str, Any], result: Any) -> None
state["git_history_coverage"] = coverage.to_dict()
+def _stamp_full_init_scope(
+ state: dict[str, Any],
+ result: Any,
+ provider: Any,
+ *,
+ resolved_commit_limit: int,
+ max_file_pages: int | None,
+ embedder_name_resolved: str,
+) -> None:
+ """Attach the canonical scope receipt for a successful model-backed init."""
+ from repowise.core.generation.selection import count_documentable_files
+
+ unavailable = [] if getattr(result, "health_report", None) is not None else ["health"]
+ if getattr(result, "generation_scope", None):
+ pages = result.generation_scope
+ elif hasattr(result, "parsed_files"):
+ pages = file_page_scope(
+ configured_cap=max_file_pages,
+ eligible=count_documentable_files(result.parsed_files),
+ generated_pages=result.generated_pages,
+ )
+ else:
+ pages = {"effective_cap": None, "eligible": None, "generated": None, "omitted": None}
+ stamp_index_scope(
+ state,
+ {"commit_limit": resolved_commit_limit, "max_file_pages": max_file_pages},
+ run_mode="standard",
+ content_provenance="model",
+ git_tier="full",
+ git_commit_cap=resolved_commit_limit,
+ file_pages={"configured_cap": max_file_pages, **pages},
+ analysis={"unavailable": unavailable, "skipped": []},
+ provider={
+ "name": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name_resolved,
+ "reused": False,
+ "model_cost_possible": True,
+ },
+ search={
+ "full_text": "available",
+ "semantic": "unavailable" if embedder_name_resolved == "mock" else "available",
+ "next_command": "repowise reindex" if embedder_name_resolved == "mock" else None,
+ },
+ upgrade={"status": "not_applicable", "retryable": False, "completed_stages": []},
+ )
+
+
def save_full_state_and_config(
*,
repo_path: Path,
@@ -351,6 +400,7 @@ def save_full_state_and_config(
commit_limit: int | None,
resolved_commit_limit: int,
resolved_reasoning: str,
+ max_file_pages: int | None = None,
include_submodules: bool = False,
save_key: bool = True,
) -> None:
@@ -393,6 +443,14 @@ def save_full_state_and_config(
state["run_mode"] = "standard"
state["git_tier"] = "full"
apply_git_history_coverage_state(state, result)
+ _stamp_full_init_scope(
+ state,
+ result,
+ provider,
+ resolved_commit_limit=resolved_commit_limit,
+ max_file_pages=max_file_pages,
+ embedder_name_resolved=embedder_name_resolved,
+ )
# Same pattern as git_tier: `repowise update` reads this back so its
# graph rebuild keeps the init run's submodule boundary semantics.
state["include_submodules"] = include_submodules
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
index d65a082ed..732649dc0 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
@@ -11,7 +11,7 @@ import time
from pathlib import Path
from typing import Any
-from repowise.cli.helpers import console
+from repowise.cli.helpers import console, load_config, load_state
from repowise.cli.ui import (
ERR,
OK,
@@ -140,6 +140,9 @@ def show_completion(
result is the panel above it.
"""
elapsed = time.monotonic() - start
+ from repowise.core.index_scope import resolve_index_scope
+
+ _scope = resolve_index_scope(load_state(Path(repo_path)), load_config(Path(repo_path)))
_graph_final = result.graph_builder.graph()
_dc_unreachable = sum(
@@ -188,10 +191,22 @@ def show_completion(
# languages and graph size appeared once in the "Analysis Complete"
# interstitial, minutes and one cost prompt earlier.
_index_rows: list[tuple[str, str]] = [
+ (
+ "Scope",
+ f"{_scope['run_mode']} · {_scope['content_provenance']} · git {_scope['git_tier']}",
+ ),
("Files indexed", f"{result.file_count:,}"),
("Symbols", f"{result.symbol_count:,}"),
("Languages", _lang_summary_final),
]
+ if _scope["file_pages"]["eligible"] is not None:
+ _fp = _scope["file_pages"]
+ _index_rows.append(
+ (
+ "File pages",
+ f"{_fp['generated']}/{_fp['eligible']} generated · {_fp['omitted']} omitted",
+ )
+ )
_structure_rows: list[tuple[str, str]] = [
(
"Graph",
@@ -335,9 +350,7 @@ def _show_generation_checks(result: Any) -> None:
except Exception as exc:
# A first index that could not check itself must not read like one that
# checked itself clean. The run still exits 0; the wiki is written.
- console.print(
- f"[{ERR}]Generation checks did not run:[/] {type(exc).__name__}: {exc}"
- )
+ console.print(f"[{ERR}]Generation checks did not run:[/] {type(exc).__name__}: {exc}")
def show_workspace_completion(
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 70413b8e2..0d56b4a3f 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -363,7 +363,7 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
derive_environment_facts=True,
)
)
- console.print(
+ console.print(
f" [{OK}]✓[/] {result.file_count:,} files, {result.symbol_count:,} symbols"
)
except Exception as exc:
@@ -504,6 +504,75 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
if repo_phase_timings:
state["phase_timings"] = repo_phase_timings
apply_git_history_coverage_state(state, result)
+ from repowise.core.generation.selection import count_documentable_files
+ from repowise.core.index_scope import file_page_scope, stamp_index_scope
+
+ scope_config = load_config(repo.path)
+ configured_cap = resolve_max_file_pages(config=scope_config)
+ scope_embedder = (
+ det_embedder
+ if docs_mode == "deterministic"
+ else ctx.embedder_name_resolved
+ if docs_mode == "llm"
+ else None
+ )
+ state["run_mode"] = ctx.run_mode
+ state["git_tier"] = "essential" if ctx.run_mode == "fast" else "full"
+ unavailable = [] if getattr(result, "health_report", None) is not None else ["health"]
+ stamp_index_scope(
+ state,
+ {**scope_config, "commit_limit": ctx.resolved_commit_limit},
+ run_mode=ctx.run_mode,
+ content_provenance={"none": "none", "deterministic": "template", "llm": "model"}[docs_mode],
+ git_tier=state["git_tier"],
+ git_commit_cap=ctx.resolved_commit_limit,
+ file_pages={
+ "configured_cap": configured_cap,
+ **(
+ result.generation_scope
+ if getattr(result, "generation_scope", None)
+ else (
+ file_page_scope(
+ configured_cap=configured_cap,
+ eligible=count_documentable_files(result.parsed_files),
+ generated_pages=result.generated_pages,
+ )
+ if hasattr(result, "parsed_files")
+ else {
+ "effective_cap": None,
+ "eligible": None,
+ "generated": None,
+ "omitted": None,
+ }
+ )
+ ),
+ },
+ analysis={
+ "unavailable": unavailable,
+ "skipped": ["generation"] if ctx.run_mode == "fast" else [],
+ },
+ provider={
+ "name": repo_provider.provider_name if repo_provider is not None else None,
+ "model": repo_provider.model_name if repo_provider is not None else None,
+ "embedder": scope_embedder,
+ "reused": False,
+ "model_cost_possible": docs_mode == "llm",
+ },
+ search={
+ "full_text": "available" if result.generated_pages else "unavailable",
+ "semantic": (
+ "available"
+ if result.generated_pages and scope_embedder not in {None, "mock"}
+ else "unavailable"
+ ),
+ "next_command": "repowise reindex" if result.generated_pages else None,
+ },
+ upgrade={
+ "status": "pending" if docs_mode != "llm" else "not_applicable",
+ "retryable": docs_mode != "llm",
+ "completed_stages": [],
+ },
+ )
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
state["knowledge_graph"] = build_kg_state(kg)
diff --git a/packages/cli/src/repowise/cli/commands/status_cmd.py b/packages/cli/src/repowise/cli/commands/status_cmd.py
index 25332789c..981e0be48 100644
--- a/packages/cli/src/repowise/cli/commands/status_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/status_cmd.py
@@ -15,6 +15,7 @@ from repowise.cli.helpers import (
db_configured,
get_db_url_for_repo,
get_repowise_dir,
+ load_config,
load_state,
reconcile_schema_best_effort,
resolve_command_target,
@@ -23,6 +24,7 @@ from repowise.cli.helpers import (
from repowise.cli.output import emit_json, format_option, notice_console
from repowise.cli.ui.brand import format_bytes
from repowise.core.docs_mode import resolve_docs_mode
+from repowise.core.index_scope import resolve_index_scope
# ---------------------------------------------------------------------------
# Workspace status
@@ -362,6 +364,7 @@ def _workspace_rows(target: CommandTarget) -> list[dict]:
"symbols": None,
"pages": None,
"docs_mode": None,
+ "index_scope": None,
"storage_bytes": None,
"head": None,
"stale": None,
@@ -376,11 +379,13 @@ def _workspace_rows(target: CommandTarget) -> list[dict]:
is_stale, current_head, behind = check_repo_staleness(
abs_path, entry.last_commit_at_index
)
+ repo_state = load_state(abs_path)
row.update(
files=file_count,
symbols=symbol_count,
pages=page_count,
- docs_mode=resolve_docs_mode(load_state(abs_path)),
+ docs_mode=resolve_docs_mode(repo_state),
+ index_scope=resolve_index_scope(repo_state, {}),
storage_bytes=_index_storage_bytes(repowise_dir),
head=current_head,
stale=is_stale,
@@ -560,6 +565,7 @@ def status_command(path: str | None, workspace: bool, no_workspace: bool, fmt: s
return
state = load_state(repo_path)
+ scope = resolve_index_scope(state, load_config(repo_path))
storage_bytes = _index_storage_bytes(repowise_dir)
db_path = repowise_dir / "wiki.db"
has_db = db_path.exists() or db_configured()
@@ -585,6 +591,7 @@ def status_command(path: str | None, workspace: bool, no_workspace: bool, fmt: s
"page_total": sum(counts.values()),
"page_tokens": total_db_tokens,
"health": _query_health(repo_path),
+ "index_scope": scope,
}
)
return
@@ -602,6 +609,39 @@ def status_command(path: str | None, workspace: bool, no_workspace: bool, fmt: s
state_table.add_row("Model", state.get("model", "—") or "—")
state_table.add_row("Total tokens", f"{state.get('total_tokens', 0):,}")
state_table.add_row("Index storage", format_bytes(storage_bytes))
+ state_table.add_row(
+ "Scope",
+ f"{scope['run_mode']} · {scope['content_provenance']} · git {scope['git_tier']}",
+ )
+ coverage = scope["git_history_coverage"]
+ if coverage:
+ measured = coverage.get(
+ "files_with_history", coverage.get("files_measured", coverage.get("files_indexed", "?"))
+ )
+ eligible = coverage.get("files_eligible", coverage.get("eligible_files", "?"))
+ state_table.add_row(
+ "Git coverage", f"{measured}/{eligible} files (cap {scope['git_commit_cap']})"
+ )
+ fp = scope["file_pages"]
+ if fp["eligible"] is not None:
+ configured = "unlimited" if fp["configured_cap"] == 0 else fp["configured_cap"]
+ if configured is None:
+ configured = "auto"
+ effective = "unlimited" if fp["effective_cap"] is None else fp["effective_cap"]
+ state_table.add_row(
+ "File pages",
+ f"{fp['generated']}/{fp['eligible']} generated · {fp['omitted']} omitted · "
+ f"cap {effective} (configured {configured})",
+ )
+ if scope["analysis"]["unavailable"]:
+ state_table.add_row(
+ "Unavailable analysis",
+ ", ".join(scope["analysis"]["unavailable"]),
+ )
+ if scope["analysis"]["skipped"]:
+ state_table.add_row("Intentionally skipped", ", ".join(scope["analysis"]["skipped"]))
+ if scope["upgrade"]["status"] not in ("unknown", "not_applicable", "complete"):
+ state_table.add_row("Full upgrade", scope["upgrade"]["status"])
console.print(state_table)
if not has_db:
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index b199b53e1..62bb4b0b0 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -314,7 +314,8 @@ def _surface_reindex_recommendation(repo_path, verdict, *, emitter: Any, dry_run
"Upgrade an index with a model: backfill the git tier ESSENTIAL -> "
"FULL if it was built with `--mode fast`, and write the subsystem pages "
"with a provider on a wiki that has none yet. Incremental: reuses the "
- "persisted graph instead of re-parsing and re-resolving it. "
+ "persisted graph, records resumable stage progress, reuses persisted "
+ "provider/embedder choices, and previews model cost before generation. "
"Single-repo only."
),
)
@@ -436,12 +437,15 @@ def _render_full_upgrade_dry_run(
"""Describe a full upgrade without resolving providers or touching the store."""
state = load_state(repo_path)
config = load_config(repo_path)
+ from repowise.core.index_scope import resolve_index_scope
+
+ scope = resolve_index_scope(state, config)
planned_provider = (
provider_name or config.get("provider") or state.get("provider") or "auto-detect"
)
planned_model = model or config.get("model") or state.get("model") or "provider default"
- current_git_tier = str(state.get("git_tier") or "essential").upper()
+ current_git_tier = scope["git_tier"].upper()
recorded_pages = state.get("total_pages")
page_label = f"{recorded_pages:,}" if isinstance(recorded_pages, int) else "unknown"
@@ -449,7 +453,13 @@ def _render_full_upgrade_dry_run(
console.print(f" Provider: [cyan]{planned_provider}[/cyan] / [cyan]{planned_model}[/cyan]")
console.print(f" Git tier: [cyan]{current_git_tier}[/cyan] -> [cyan]FULL[/cyan]")
console.print(f" Pages currently recorded: [cyan]{page_label}[/cyan]")
- console.print(" The whole-repository wiki would be generated. No changes made.")
+ console.print(
+ f" Persisted scope: [cyan]{scope['run_mode']} / {scope['content_provenance']}[/cyan]"
+ )
+ console.print(
+ " The whole-repository wiki would be generated after an explicit cost preview; "
+ "completed stages are resumable. No changes made."
+ )
def _renderer_inputs(repo_path):
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index 9ac80dde5..06d34af6e 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -17,7 +17,7 @@ from typing import Any
import structlog
-from repowise.cli.helpers import console, head_commit_ts, run_async, save_state
+from repowise.cli.helpers import console, head_commit_ts, load_config, run_async, save_state
from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.pipeline import PhaseTimings, timed
@@ -508,6 +508,20 @@ def _persist_index_only_update(
if timings is not None:
timings.stop("run")
new_state["phase_timings"] = timings.totals
+ from repowise.core.index_scope import resolve_index_scope, stamp_index_scope
+
+ scope = resolve_index_scope(new_state, load_config(repo_path))
+ unavailable = set(scope["analysis"]["unavailable"])
+ unavailable.update(str(step) for step in failed_steps)
+ stamp_index_scope(
+ new_state,
+ load_config(repo_path),
+ git_history_coverage=new_state.get("git_history_coverage"),
+ analysis={
+ "unavailable": sorted(unavailable),
+ "skipped": scope["analysis"]["skipped"],
+ },
+ )
save_state(repo_path, new_state)
elapsed = time.monotonic() - start
from .reporting import show_index_only_completion
@@ -992,9 +1006,7 @@ async def _persist_full_update_async(
purge_proposed_decisions_by_source,
)
- await purge_proposed_decisions_by_source(
- session, repo_id, "git_archaeology"
- )
+ await purge_proposed_decisions_by_source(session, repo_id, "git_archaeology")
decision_dicts: list[dict] = []
if new_decision_markers:
@@ -1516,6 +1528,11 @@ def _run_full_health_rescore(
if timings is not None:
timings.stop("run")
new_state["phase_timings"] = timings.totals
+ from repowise.core.index_scope import stamp_index_scope
+
+ stamp_index_scope(
+ new_state, load_config(repo_path), analysis={"unavailable": [], "skipped": []}
+ )
save_state(repo_path, new_state)
elapsed = time.monotonic() - start
console.print(f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s")
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index c286ab246..80c7778fb 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -46,6 +46,7 @@ from repowise.cli.helpers import (
)
from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.docs_mode import docs_mode_state_fields
+from repowise.core.index_scope import file_page_scope, stamp_index_scope
from repowise.core.update_lock import release_update_lock, try_acquire_update_lock
@@ -128,7 +129,7 @@ async def _backfill_git(
*,
commit_limit: int | None,
follow_renames: bool,
-) -> dict[str, dict]:
+) -> tuple[dict[str, dict], dict[str, Any] | None]:
"""Promote the git tier to FULL via the resumable backfill worker.
Returns the ``file_path → git-metadata`` map for the freshly-indexed FULL
@@ -175,7 +176,11 @@ async def _backfill_git(
f"Git tier upgraded to FULL: [cyan]{summary.files_indexed}[/cyan] files "
"(per-file blame + co-change)."
)
- return {m["file_path"]: m for m in git_results if m.get("file_path")}
+ coverage = getattr(summary, "history_coverage", None)
+ return (
+ {m["file_path"]: m for m in git_results if m.get("file_path")},
+ coverage.to_dict() if coverage is not None else None,
+ )
async def _run_upgrade(
@@ -188,7 +193,8 @@ async def _run_upgrade(
follow_renames: bool,
embedder_name: str | None,
yes: bool,
-) -> list[Any]:
+ checkpoint: Any | None = None,
+) -> tuple[list[Any], int, dict[str, Any]]:
"""Drive the full upgrade and return the generated pages."""
from repowise.cli.helpers import get_db_url_for_repo
from repowise.core.generation.cost_tracker import CostTracker
@@ -216,13 +222,15 @@ async def _run_upgrade(
repo_id = repo.id
# 2. Backfill the git tier ESSENTIAL -> FULL (resumable via JobStore).
- git_meta_map = await _backfill_git(
+ git_meta_map, history_coverage = await _backfill_git(
sf,
repo_id,
repo_path,
commit_limit=commit_limit,
follow_renames=follow_renames,
)
+ if checkpoint:
+ checkpoint("git_backfill", git_history_coverage=history_coverage)
# 3. Rehydrate the graph from SQL — no parse, no resolution, no recompute.
async with get_session(sf) as session:
@@ -264,10 +272,12 @@ async def _run_upgrade(
embedder = None
vector_store = None
+ embedding_error: str | None = None
try:
embedder = build_embedder(resolve_embedder(embedder_name), repo_path)
vector_store = build_vector_store(repo_path, embedder)
except Exception as exc:
+ embedding_error = str(exc)
console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")
# Generate with init's persistence wrapper: pages are written to the DB the
@@ -300,6 +310,7 @@ async def _run_upgrade(
console=console,
) as upgrade_progress:
gen_callback = RichProgressCallback(upgrade_progress, console)
+ generation_scope: dict[str, int | None] = {}
generated_pages = await run_generation_with_persistence(
repo_path=repo_path,
repo_name=repo_path.name,
@@ -315,7 +326,19 @@ async def _run_upgrade(
progress=gen_callback,
cost_tracker=cost_tracker,
generation_config=config,
+ selection_out=generation_scope,
+ )
+ from repowise.core.generation.models import count_stub_fallbacks
+
+ stub_fallbacks = count_stub_fallbacks(generated_pages)
+ if stub_fallbacks:
+ await engine.dispose()
+ raise RuntimeError(
+ f"Model generation returned {stub_fallbacks} fallback page(s); "
+ "the prior index remains active and the upgrade can be retried"
)
+ if checkpoint:
+ checkpoint("generation")
# Flush buffered cost rows now generation is done (best-effort).
await cost_tracker.flush()
@@ -334,13 +357,11 @@ async def _run_upgrade(
try:
from datetime import UTC, datetime
- from repowise.core.generation.models import count_stub_fallbacks
from repowise.core.persistence.crud import upsert_generation_job
now = datetime.now(UTC)
# See init_cmd/persistence.py: a stub the provider failure put up
# has a row but no prose, so it is not a completed page.
- stub_fallbacks = count_stub_fallbacks(generated_pages)
job = await upsert_generation_job(
session,
repository_id=repo_id,
@@ -366,8 +387,11 @@ async def _run_upgrade(
summary=page.summary,
target_path=page.target_path,
)
- except Exception:
- pass # FTS indexing is best-effort
+ except BaseException:
+ await engine.dispose()
+ raise
+ if checkpoint:
+ checkpoint("search")
# 7. Recompute + persist code health against the now-FULL git tier.
# The fast index persisted ESSENTIAL-tier findings only, so the blame /
@@ -427,7 +451,13 @@ async def _run_upgrade(
f"[cyan]{len(health_report.findings)}[/cyan] findings."
)
except Exception as exc:
- console.print(f"[yellow]Health recompute skipped: {exc}[/yellow]")
+ await engine.dispose()
+ raise RuntimeError(f"FULL-tier health recompute failed: {exc}") from exc
+ if health_report is None:
+ await engine.dispose()
+ raise RuntimeError("FULL-tier health recompute returned no report")
+ if checkpoint:
+ checkpoint("health")
# The repo's real page count, not this run's. An upgrade regenerates rather
# than appends, and it does not necessarily cover every page the repo
@@ -453,7 +483,32 @@ async def _run_upgrade(
total_pages = len(generated_pages)
await engine.dispose()
- return generated_pages, total_pages
+ from repowise.core.generation.selection import count_documentable_files
+
+ return (
+ generated_pages,
+ total_pages,
+ {
+ "git_history_coverage": history_coverage,
+ "file_pages": {
+ "configured_cap": getattr(config, "max_file_pages", None),
+ **(
+ generation_scope
+ or file_page_scope(
+ configured_cap=getattr(config, "max_file_pages", None),
+ eligible=count_documentable_files(parsed_files),
+ generated_pages=generated_pages,
+ )
+ ),
+ },
+ "search": {
+ "full_text": "available",
+ "semantic": "available" if vector_store is not None else "unavailable",
+ "next_command": "repowise reindex" if vector_store is None else None,
+ },
+ "embedding_error": embedding_error,
+ },
+ )
def upgrade_to_full(
@@ -489,6 +544,14 @@ def upgrade_to_full(
# Provider is required — the fast index made no LLM calls, so the repo may
# not have one configured yet. resolve_provider surfaces a clear error.
provider = resolve_provider(provider_name, model, repo_path=repo_path)
+ persisted_provider = state.get("provider") or cfg.get("provider")
+ persisted_model = state.get("model") or cfg.get("model")
+ provider_reused = (
+ provider_name is None
+ and model is None
+ and persisted_provider == provider.provider_name
+ and persisted_model == provider.model_name
+ )
config = GenerationConfig.from_repo_config(
cfg,
@@ -546,8 +609,71 @@ def upgrade_to_full(
# (success, cost-gate Abort, or unexpected failure) rather than at process
# exit — atexit would leave the lock held for the rest of the CLI process.
try:
+ completed_stages = list(
+ state.get("full_upgrade", {}).get("completed_stages", [])
+ if isinstance(state.get("full_upgrade"), dict)
+ else []
+ )
+
+ def _checkpoint(stage: str, **fields: Any) -> None:
+ current = load_state(repo_path)
+ stages = list(
+ current.get("full_upgrade", {}).get("completed_stages", [])
+ if isinstance(current.get("full_upgrade"), dict)
+ else []
+ )
+ if stage not in stages:
+ stages.append(stage)
+ order = ["git_backfill", "generation", "search", "health"]
+ next_stage = next((item for item in order if item not in stages), "finalize")
+ current["full_upgrade"] = {
+ "status": "running",
+ "retryable": True,
+ "completed_stages": stages,
+ "next_stage": next_stage,
+ "provider": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ }
+ if fields.get("git_history_coverage") is not None:
+ current["git_history_coverage"] = fields["git_history_coverage"]
+ stamp_index_scope(current, cfg, upgrade=current["full_upgrade"])
+ save_state(repo_path, current)
+
+ # Durable before any backfill or model work. A killed process therefore
+ # leaves an honest resumable transition while the prior index_scope
+ # continues to describe the usable index.
+ state["full_upgrade"] = {
+ "status": "running",
+ "retryable": True,
+ "completed_stages": completed_stages,
+ "next_stage": next(
+ (
+ item
+ for item in ["git_backfill", "generation", "search", "health"]
+ if item not in completed_stages
+ ),
+ "finalize",
+ ),
+ "provider": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ }
+ stamp_index_scope(
+ state,
+ cfg,
+ upgrade=state["full_upgrade"],
+ provider={
+ "name": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ "reused": provider_reused,
+ "model_cost_possible": True,
+ },
+ )
+ save_state(repo_path, state)
try:
- generated_pages, total_pages = run_async(
+ upgrade_result = run_async(
_run_upgrade(
repo_path,
provider,
@@ -557,21 +683,65 @@ def upgrade_to_full(
follow_renames=follow_renames,
embedder_name=embedder_name,
yes=yes,
+ checkpoint=_checkpoint,
)
)
+ if len(upgrade_result) == 2: # compatibility for third-party/test wrappers
+ generated_pages, total_pages = upgrade_result
+ outcome = {
+ "git_history_coverage": None,
+ "file_pages": {
+ "configured_cap": resolve_max_file_pages(config=cfg),
+ "effective_cap": None,
+ "eligible": None,
+ "generated": None,
+ "omitted": None,
+ },
+ "search": {
+ "full_text": "unknown",
+ "semantic": "unknown",
+ "next_command": None,
+ },
+ "embedding_error": None,
+ }
+ else:
+ generated_pages, total_pages, outcome = upgrade_result
except click.Abort:
# Declined at the cost gate. The git backfill that ran before it is
# kept (it costs nothing to keep and everything to redo), and the
# persisted docs mode is left alone so the repo keeps whatever wiki it
# already had.
- console.print("[yellow]Nothing generated.[/yellow] The index is unchanged.")
+ current = load_state(repo_path)
+ transition = current.get("full_upgrade", {})
+ transition.update(status="resumable", retryable=True)
+ current["full_upgrade"] = transition
+ stamp_index_scope(current, cfg, upgrade=transition)
+ save_state(repo_path, current)
+ console.print("[yellow]Nothing generated.[/yellow] The prior index remains usable.")
return
+ except BaseException as exc:
+ current = load_state(repo_path)
+ transition = current.get("full_upgrade", {})
+ transition.update(
+ status="resumable"
+ if isinstance(exc, (KeyboardInterrupt, SystemExit))
+ else "failed",
+ retryable=True,
+ error=type(exc).__name__,
+ )
+ current["full_upgrade"] = transition
+ stamp_index_scope(current, cfg, upgrade=transition)
+ save_state(repo_path, current)
+ raise
# Flip persisted state to full so subsequent `repowise update` runs the
# normal incremental LLM path rather than offering upgrade.
state["last_sync_commit"] = head
state.update(docs_mode_state_fields("llm"))
state["git_tier"] = "full"
+ state["run_mode"] = "standard"
+ if outcome["git_history_coverage"] is not None:
+ state["git_history_coverage"] = outcome["git_history_coverage"]
state["total_pages"] = total_pages
# Record who wrote the pages. Without this, `repowise status` on a repo
# upgraded this way reports its provider and model as unknown, which reads
@@ -590,6 +760,32 @@ def upgrade_to_full(
# from the current analyzer. Without the stamp the next plain `update`
# would read a stale version and pay a redundant full re-score.
state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
+ state["full_upgrade"] = {
+ "status": "complete",
+ "retryable": False,
+ "completed_stages": ["git_backfill", "generation", "search", "health", "finalize"],
+ "next_stage": None,
+ }
+ stamp_index_scope(
+ state,
+ cfg,
+ run_mode="standard",
+ content_provenance="model",
+ git_tier="full",
+ git_commit_cap=commit_limit if isinstance(commit_limit, int) else 500,
+ git_history_coverage=outcome["git_history_coverage"],
+ file_pages=outcome["file_pages"],
+ analysis={"unavailable": [], "skipped": []},
+ upgrade=state["full_upgrade"],
+ provider={
+ "name": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ "reused": provider_reused,
+ "model_cost_possible": True,
+ },
+ search=outcome["search"],
+ )
save_state(repo_path, state, full_index=True)
if embedder_name and embedder_name != cfg.get("embedder"):
from repowise.cli.helpers import save_config_partial
@@ -601,5 +797,10 @@ def upgrade_to_full(
f"[bold green]Upgrade complete[/bold green] in {elapsed:.1f}s — "
f"{len(generated_pages)} pages generated, git tier now FULL."
)
+ if outcome["search"]["semantic"] != "available":
+ console.print(
+ "[yellow]Semantic search is unavailable.[/yellow] Set an embedder key and run "
+ "[bold]repowise reindex[/bold] (embedding calls only; no model calls)."
+ )
finally:
release_update_lock(repo_path)
diff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.py
index c8555c208..bb40a4c33 100644
--- a/packages/core/src/repowise/core/generation/editor_files/data.py
+++ b/packages/core/src/repowise/core/generation/editor_files/data.py
@@ -128,6 +128,7 @@ class EditorFileData:
# Rendered MCP tool table (single source: tool_table.py). A data field
# rather than a Jinja global so any environment can render the template.
tool_table_md: str = field(default_factory=lambda: _render_tool_table())
+ index_scope: dict = field(default_factory=dict)
# ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
index 1275f2e93..88f539152 100644
--- a/packages/core/src/repowise/core/generation/editor_files/fetcher.py
+++ b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
@@ -21,6 +21,7 @@ from repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_
from repowise.core.analysis.health.trends import DECLINE_LOOKBACK, hotspot_trend
from repowise.core.entry_candidacy import conventional_entry_stems
from repowise.core.generation.entry_points import rank_entry_points
+from repowise.core.index_scope import load_index_scope, resolve_index_scope
from repowise.core.persistence import crud
from repowise.core.persistence.models import (
DecisionRecord,
@@ -92,8 +93,12 @@ class EditorFileDataFetcher:
code_health=await self._get_code_health(),
kg_layers=kg_layers,
kg_tour=kg_tour,
+ index_scope=self._get_index_scope(),
)
+ def _get_index_scope(self) -> dict:
+ return load_index_scope(self._repo_path) or resolve_index_scope({})
+
# ------------------------------------------------------------------
# Private helpers
# ------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index 057c779aa..1ff156db0 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -141,6 +141,10 @@ class Selection:
# so the cost estimator and scope resolution keep costing nothing.
concept_groups: list[ConceptGroup] = field(default_factory=list)
layer_labels: dict[str, str] = field(default_factory=dict)
+ # File-page volume ledger: candidate population before the cap, and the
+ # cap that actually sliced it. These are reporting facts, not selectors.
+ eligible_file_pages: int = 0
+ effective_file_page_cap: int | None = None
def counts(self) -> dict[str, int]:
"""Per-page-type counts of the pages this run will emit.
@@ -305,7 +309,7 @@ def _passes_importance_floor(path: str) -> bool:
def _build_file_candidates(
inputs: SelectionInputs,
-) -> list[tuple[float, str]]:
+) -> tuple[list[tuple[float, str]], int, int | None]:
"""Return ``[(score, file_path), ...]`` for code files, descending."""
max_pr = max(inputs.pagerank.values(), default=0.0)
max_bet = max(inputs.betweenness.values(), default=0.0)
@@ -346,9 +350,11 @@ def _build_file_candidates(
cap = getattr(inputs.config, "max_file_pages", None)
if cap is None:
cap = auto_file_page_cap(len(scored))
+ eligible = len(scored)
+ effective_cap = cap or None
if not cap: # None (nothing to do) or 0 (explicitly unlimited)
- return scored
- return scored[: max(1, cap)]
+ return scored, eligible, effective_cap
+ return scored[: max(1, cap)], eligible, effective_cap
def _build_symbol_candidates(
@@ -773,7 +779,7 @@ def select_pages(inputs: SelectionInputs) -> Selection:
Deterministic given identical inputs. Safe to call from both the generator
and the cost estimator.
"""
- files = _build_file_candidates(inputs)
+ files, eligible_file_pages, effective_file_page_cap = _build_file_candidates(inputs)
symbols = _build_symbol_candidates(inputs)
concepts = _build_module_groups(inputs)
modules = concepts.scored
@@ -791,6 +797,8 @@ def select_pages(inputs: SelectionInputs) -> Selection:
infra_paths=[p for _, p in infras],
scc_groups=[g for _, g in sccs],
emit_repo_overview=True,
+ eligible_file_pages=eligible_file_pages,
+ effective_file_page_cap=effective_file_page_cap,
)
log.info("page_selection.complete", counts=sel.counts())
return sel
diff --git a/packages/core/src/repowise/core/generation/templates/agents_md.j2 b/packages/core/src/repowise/core/generation/templates/agents_md.j2
index cb15e38e5..10629ba9c 100644
--- a/packages/core/src/repowise/core/generation/templates/agents_md.j2
+++ b/packages/core/src/repowise/core/generation/templates/agents_md.j2
@@ -1,6 +1,10 @@
## Codebase Intelligence for {{ data.repo_name }} (Repowise)
Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}{% if data.indexed_commit %} (commit {{ data.indexed_commit }}){% endif %}{% if data.avg_confidence %}. Confidence: {{ (data.avg_confidence * 100) | int }}%.{% endif %}
+{% if data.index_scope %}
+Scope: {{ data.index_scope.run_mode }} index · {{ data.index_scope.content_provenance }} content · {{ data.index_scope.git_tier }} Git{% if data.index_scope.file_pages.omitted is not none and data.index_scope.file_pages.omitted %} · {{ data.index_scope.file_pages.omitted }} eligible file pages omitted{% endif %}. Missing or unavailable evidence is not a negative finding. {% if data.index_scope.upgrade.status in ['pending', 'resumable', 'failed'] %}Run `repowise update --full` to continue the model-backed upgrade (cost is previewed before generation).{% endif %}
+Machine-readable scope: `{{ data.index_scope | tojson }}`
+{% endif %}
### How to work in this repo
diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2
index 59fddbedb..044521123 100644
--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2
+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2
@@ -1,6 +1,10 @@
## Codebase Intelligence for {{ data.repo_name }} (Repowise)
Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}{% if data.indexed_commit %} (commit {{ data.indexed_commit }}){% endif %}{% if data.avg_confidence %}. Confidence: {{ (data.avg_confidence * 100) | int }}%.{% endif %}
+{% if data.index_scope %}
+Scope: {{ data.index_scope.run_mode }} index · {{ data.index_scope.content_provenance }} content · {{ data.index_scope.git_tier }} Git{% if data.index_scope.file_pages.omitted is not none and data.index_scope.file_pages.omitted %} · {{ data.index_scope.file_pages.omitted }} eligible file pages omitted{% endif %}. Missing or unavailable evidence is not a negative finding. {% if data.index_scope.upgrade.status in ['pending', 'resumable', 'failed'] %}Run `repowise update --full` to continue the model-backed upgrade (cost is previewed before generation).{% endif %}
+Machine-readable scope: `{{ data.index_scope | tojson }}`
+{% endif %}
### How to work in this repo
diff --git a/packages/core/src/repowise/core/index_scope.py b/packages/core/src/repowise/core/index_scope.py
new file mode 100644
index 000000000..197f7af79
--- /dev/null
+++ b/packages/core/src/repowise/core/index_scope.py
@@ -0,0 +1,182 @@
+"""Canonical, backward-compatible projection of an index's actual scope.
+
+Writers persist this object in ``state.json:index_scope``. Readers always go
+through :func:`resolve_index_scope`, which also gives legacy state a stable,
+conservative shape: missing evidence is ``unknown``/``None``, never inferred as
+complete from a configured limit or from the absence of a finding.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+INDEX_SCOPE_VERSION = 1
+
+
+def load_index_scope(repo_path: str | Path) -> dict[str, Any] | None:
+ """Load a repository's scope; return ``None`` when no readable state exists."""
+ repowise_dir = Path(repo_path) / ".repowise"
+ try:
+ state = json.loads((repowise_dir / "state.json").read_text(encoding="utf-8"))
+ except (OSError, TypeError, ValueError):
+ return None
+
+ try:
+ import yaml
+ except ImportError:
+ return resolve_index_scope(state)
+ try:
+ config = yaml.safe_load((repowise_dir / "config.yaml").read_text(encoding="utf-8")) or {}
+ except (OSError, TypeError, ValueError, yaml.YAMLError):
+ config = {}
+ return resolve_index_scope(state, config)
+
+
+def _choice(value: Any, choices: set[str]) -> str:
+ return value if isinstance(value, str) and value in choices else "unknown"
+
+
+def _number(value: Any) -> int | None:
+ return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None
+
+
+def _string(value: Any) -> str | None:
+ return value if isinstance(value, str) and value else None
+
+
+def resolve_index_scope(
+ state: Mapping[str, Any] | None,
+ config: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Return the one machine-readable scope contract for every output surface."""
+ state = state if isinstance(state, Mapping) else {}
+ config = config if isinstance(config, Mapping) else {}
+ stored = state.get("index_scope")
+ scope = deepcopy(stored) if isinstance(stored, Mapping) else {}
+
+ explicit_docs_mode = state.get("docs_mode")
+ provenance = {
+ "none": "none",
+ "deterministic": "template",
+ "llm": "model",
+ }.get(explicit_docs_mode, "unknown")
+
+ pages = scope.get("file_pages") if isinstance(scope.get("file_pages"), Mapping) else {}
+ configured_cap = pages.get("configured_cap")
+ if configured_cap is None and "max_file_pages" in config:
+ configured_cap = _number(config.get("max_file_pages"))
+
+ provider = scope.get("provider") if isinstance(scope.get("provider"), Mapping) else {}
+ search = scope.get("search") if isinstance(scope.get("search"), Mapping) else {}
+ analysis = scope.get("analysis") if isinstance(scope.get("analysis"), Mapping) else {}
+ upgrade = state.get("full_upgrade")
+ if not isinstance(upgrade, Mapping):
+ upgrade = scope.get("upgrade") if isinstance(scope.get("upgrade"), Mapping) else {}
+
+ run_mode = _choice(state.get("run_mode", scope.get("run_mode")), {"fast", "standard"})
+ git_tier = _choice(state.get("git_tier", scope.get("git_tier")), {"essential", "full"})
+ if isinstance(stored, Mapping):
+ provenance = _choice(
+ scope.get("content_provenance", provenance), {"none", "template", "model"}
+ )
+
+ unavailable = analysis.get("unavailable", [])
+ degraded = state.get("degraded", [])
+ if isinstance(unavailable, list) and isinstance(degraded, list):
+ unavailable = [*unavailable, *degraded]
+ skipped = analysis.get("skipped", [])
+ return {
+ "version": INDEX_SCOPE_VERSION,
+ "run_mode": run_mode,
+ "content_provenance": provenance,
+ "git_tier": git_tier,
+ "git_commit_cap": _number(scope.get("git_commit_cap", config.get("commit_limit"))),
+ "git_history_coverage": (
+ deepcopy(state.get("git_history_coverage"))
+ if isinstance(state.get("git_history_coverage"), Mapping)
+ else deepcopy(scope.get("git_history_coverage"))
+ if isinstance(scope.get("git_history_coverage"), Mapping)
+ else None
+ ),
+ "file_pages": {
+ "configured_cap": configured_cap,
+ "effective_cap": _number(pages.get("effective_cap")),
+ "eligible": _number(pages.get("eligible")),
+ "generated": _number(pages.get("generated")),
+ "omitted": _number(pages.get("omitted")),
+ },
+ "analysis": {
+ "unavailable": sorted({str(v) for v in unavailable})
+ if isinstance(unavailable, list)
+ else [],
+ "skipped": sorted({str(v) for v in skipped}) if isinstance(skipped, list) else [],
+ },
+ "upgrade": {
+ "status": _choice(
+ upgrade.get("status"),
+ {"pending", "running", "resumable", "failed", "complete", "not_applicable"},
+ ),
+ "retryable": upgrade.get("retryable")
+ if isinstance(upgrade.get("retryable"), bool)
+ else None,
+ "completed_stages": list(upgrade.get("completed_stages", []))
+ if isinstance(upgrade.get("completed_stages"), list)
+ else [],
+ "next_stage": _string(upgrade.get("next_stage")),
+ },
+ "provider": {
+ "name": _string(provider.get("name", state.get("provider"))),
+ "model": _string(provider.get("model", state.get("model"))),
+ "embedder": _string(provider.get("embedder", config.get("embedder"))),
+ "reused": provider.get("reused") if isinstance(provider.get("reused"), bool) else None,
+ "model_cost_possible": provider.get("model_cost_possible")
+ if isinstance(provider.get("model_cost_possible"), bool)
+ else None,
+ },
+ "search": {
+ "full_text": _choice(search.get("full_text"), {"available", "unavailable", "pending"}),
+ "semantic": _choice(search.get("semantic"), {"available", "unavailable", "pending"}),
+ "next_command": _string(search.get("next_command")),
+ },
+ }
+
+
+def stamp_index_scope(
+ state: dict[str, Any],
+ config: Mapping[str, Any] | None = None,
+ **updates: Any,
+) -> dict[str, Any]:
+ """Merge *updates* into and persist the canonical projection in ``state``."""
+ scope = resolve_index_scope(state, config)
+ for key, value in updates.items():
+ if isinstance(value, Mapping) and isinstance(scope.get(key), Mapping):
+ scope[key] = {**scope[key], **value}
+ else:
+ scope[key] = value
+ state["index_scope"] = scope
+ return scope
+
+
+def file_page_scope(
+ *, configured_cap: int | None, eligible: int, generated_pages: list[Any] | None
+) -> dict[str, int | None]:
+ """Build configured/effective/achieved file-page figures for one run."""
+ from repowise.core.generation.selection import auto_file_page_cap
+
+ generated = sum(1 for page in (generated_pages or []) if page.page_type == "file_page")
+ effective = configured_cap
+ if configured_cap is None:
+ effective = auto_file_page_cap(eligible)
+ elif configured_cap == 0:
+ effective = None
+ return {
+ "configured_cap": configured_cap,
+ "effective_cap": effective,
+ "eligible": eligible,
+ "generated": generated,
+ "omitted": max(0, eligible - generated),
+ }
diff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.py
index 05dcfd497..cb580d6b0 100644
--- a/packages/core/src/repowise/core/persistence/crud/pages.py
+++ b/packages/core/src/repowise/core/persistence/crud/pages.py
@@ -308,11 +308,21 @@ async def load_prior_pages(
"""
# Import lazily — keeps persistence independent of generation models at
# module-load time.
+ from repowise.core.generation.models import STUB_FALLBACK_ERROR
from repowise.core.generation.page_generator import PriorPage
result = await session.execute(select(Page).where(Page.repository_id == repository_id))
prior: dict[str, Any] = {}
for row in result.scalars():
+ try:
+ metadata = json.loads(row.metadata_json or "{}")
+ except (TypeError, ValueError):
+ metadata = {}
+ # A failed provider response is unfinished paid work, not a cache hit.
+ # Reusing it drops the failure marker when GeneratedPage is rebuilt and
+ # can let a resumed upgrade stamp placeholder prose as model-written.
+ if STUB_FALLBACK_ERROR in metadata:
+ continue
prior[row.id] = PriorPage(
source_hash=row.source_hash,
model_name=row.model_name,
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index 6a9371b8c..1e2f94579 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -53,6 +53,7 @@ async def run_generation(
only_page_ids: set[str] | None = None,
preserved_page_ids: set[str] | None = None,
test_run: bool = False,
+ selection_out: dict[str, Any] | None = None,
) -> list[Any]:
"""Run LLM-powered page generation.
@@ -101,9 +102,7 @@ async def run_generation(
# separate phase (init's generate_docs=False flow) — the flag's documented
# purpose is to cap the *generation* work, and this is where that happens.
if test_run:
- parsed_files = limit_to_top_pagerank(
- parsed_files, graph_builder, n=TEST_RUN_FILE_LIMIT
- )
+ parsed_files = limit_to_top_pagerank(parsed_files, graph_builder, n=TEST_RUN_FILE_LIMIT)
if progress:
progress.on_message("warning", f"Test run: limiting to {len(parsed_files)} files")
@@ -214,6 +213,17 @@ async def run_generation(
timings=getattr(progress, "table", None),
on_warning=on_warning,
)
+ selection = getattr(generator, "selection", None)
+ if selection_out is not None and selection is not None:
+ selection_out.update(
+ eligible=selection.eligible_file_pages,
+ effective_cap=selection.effective_file_page_cap,
+ # A resumed run may reuse already-persisted file pages rather than
+ # returning them in ``generated_pages``. Selection is the durable
+ # contract: after a successful phase every selected file has a page.
+ generated=len(selection.file_page_paths),
+ )
+ selection_out["omitted"] = max(0, selection_out["eligible"] - selection_out["generated"])
# Onboarding summary — count generated slots and surface which ones
# were gated out so the user can see the curated collection's state.
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index 2f413e2a2..b8198ecaa 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -22,6 +22,8 @@ from datetime import UTC, datetime
from pathlib import Path
from typing import Any
+from repowise.core.index_scope import load_index_scope
+
MCP_CONTRACT_VERSION = 1
# Only warn about age when we have no other signal AND the index is genuinely
@@ -101,6 +103,13 @@ def read_state_sync_commit(local_path: str | None) -> str | None:
return commit if isinstance(commit, str) and commit else None
+def read_index_scope(local_path: str | None) -> dict[str, Any] | None:
+ """Read the canonical persisted scope, or a conservative legacy projection."""
+ if not local_path:
+ return None
+ return load_index_scope(local_path)
+
+
def resolve_indexed_commit(head_commit: str | None, local_path: str | None) -> str | None:
"""Best available "commit the index reflects" for a repo.
@@ -347,6 +356,9 @@ def build_meta(
out["cached"] = True
if repository is not None:
out.update(freshness_from_repo(repository, targets=targets))
+ scope = read_index_scope(getattr(repository, "local_path", None))
+ if scope is not None:
+ out["index_scope"] = scope
out.update(_embedder_meta())
out.update(_release_meta())
if extra:
diff --git a/packages/server/src/repowise/server/schemas/repository.py b/packages/server/src/repowise/server/schemas/repository.py
index 846416d78..130b0b66d 100644
--- a/packages/server/src/repowise/server/schemas/repository.py
+++ b/packages/server/src/repowise/server/schemas/repository.py
@@ -9,6 +9,7 @@ from pathlib import Path
from pydantic import BaseModel, field_validator
from repowise.core.docs_mode import DocsMode
+from repowise.core.index_scope import load_index_scope
class RepoCreate(BaseModel):
@@ -70,22 +71,27 @@ class RepoResponse(BaseModel):
# built at.
run_mode: str | None = None
git_tier: str | None = None
+ # Canonical versioned projection shared with CLI status and MCP metadata.
+ index_scope: dict | None = None
# Set on POST /api/repos responses when registration auto-enqueued the
# first index; clients attach to /api/jobs/{id}/stream with it.
initial_job_id: str | None = None
@classmethod
def from_orm(cls, obj: object) -> RepoResponse:
+ local_path = obj.local_path # type: ignore[attr-defined]
+ scope = load_index_scope(local_path) if local_path else None
return cls(
id=obj.id, # type: ignore[attr-defined]
name=obj.name, # type: ignore[attr-defined]
url=obj.url, # type: ignore[attr-defined]
- local_path=obj.local_path, # type: ignore[attr-defined]
+ local_path=local_path,
default_branch=obj.default_branch, # type: ignore[attr-defined]
head_commit=obj.head_commit, # type: ignore[attr-defined]
settings=json.loads(obj.settings_json), # type: ignore[attr-defined]
created_at=obj.created_at, # type: ignore[attr-defined]
updated_at=obj.updated_at, # type: ignore[attr-defined]
+ index_scope=scope,
)
diff --git a/tests/unit/cli/test_full_upgrade_state.py b/tests/unit/cli/test_full_upgrade_state.py
new file mode 100644
index 000000000..cf93ee132
--- /dev/null
+++ b/tests/unit/cli/test_full_upgrade_state.py
@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.cli.commands import upgrade_flow
+from repowise.cli.helpers import load_state, save_state
+
+
+def _repo(tmp_path: Path) -> Path:
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ subprocess.run(["git", "init"], cwd=repo, capture_output=True, check=True)
+ (repo / ".repowise").mkdir()
+ save_state(
+ repo,
+ {
+ "last_sync_commit": "old",
+ "run_mode": "fast",
+ "git_tier": "essential",
+ "docs_mode": "none",
+ },
+ )
+ return repo
+
+
+def _provider(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ upgrade_flow,
+ "resolve_provider",
+ lambda *a, **k: SimpleNamespace(provider_name="mock", model_name="mock-model"),
+ )
+ monkeypatch.setattr(upgrade_flow, "try_acquire_update_lock", lambda *a, **k: None)
+ monkeypatch.setattr(upgrade_flow, "release_update_lock", lambda *a, **k: None)
+
+
+def test_upgrade_failure_keeps_prior_scope_and_is_retryable(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ repo = _repo(tmp_path)
+ _provider(monkeypatch)
+
+ async def fail(*args, **kwargs):
+ kwargs["checkpoint"]("generation")
+ raise RuntimeError("health broke")
+
+ monkeypatch.setattr(upgrade_flow, "_run_upgrade", fail)
+ with pytest.raises(RuntimeError, match="health broke"):
+ upgrade_flow.upgrade_to_full(
+ repo,
+ provider_name=None,
+ model=None,
+ reasoning=None,
+ concurrency=1,
+ yes=True,
+ )
+
+ state = load_state(repo)
+ assert state["run_mode"] == "fast"
+ assert state["git_tier"] == "essential"
+ assert state["docs_mode"] == "none"
+ assert state["full_upgrade"]["status"] == "failed"
+ assert state["full_upgrade"]["retryable"] is True
+ assert "generation" in state["full_upgrade"]["completed_stages"]
+
+
+def test_upgrade_stamps_full_only_after_all_stages(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ repo = _repo(tmp_path)
+ prior = load_state(repo)
+ prior.update(provider="mock", model="mock-model")
+ save_state(repo, prior)
+ _provider(monkeypatch)
+
+ async def succeed(*args, **kwargs):
+ for stage in ("git_backfill", "generation", "search", "health"):
+ kwargs["checkpoint"](stage)
+ return (
+ [],
+ 0,
+ {
+ "git_history_coverage": {"files_eligible": 2, "files_measured": 2},
+ "file_pages": {
+ "configured_cap": 1,
+ "effective_cap": 1,
+ "eligible": 2,
+ "generated": 1,
+ "omitted": 1,
+ },
+ "search": {
+ "full_text": "available",
+ "semantic": "unavailable",
+ "next_command": "repowise reindex",
+ },
+ "embedding_error": "no embedder",
+ },
+ )
+
+ monkeypatch.setattr(upgrade_flow, "_run_upgrade", succeed)
+ upgrade_flow.upgrade_to_full(
+ repo,
+ provider_name=None,
+ model=None,
+ reasoning=None,
+ concurrency=1,
+ yes=True,
+ )
+ scope = load_state(repo)["index_scope"]
+ assert scope["run_mode"] == "standard"
+ assert scope["content_provenance"] == "model"
+ assert scope["git_tier"] == "full"
+ assert scope["file_pages"]["omitted"] == 1
+ assert scope["search"]["semantic"] == "unavailable"
+ assert scope["upgrade"]["status"] == "complete"
+ assert scope["provider"]["reused"] is True
+
+
+def test_upgrade_cancellation_keeps_retryable_checkpoint(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ repo = _repo(tmp_path)
+ _provider(monkeypatch)
+
+ async def cancel(*args, **kwargs):
+ kwargs["checkpoint"]("git_backfill")
+ kwargs["checkpoint"]("generation")
+ raise SystemExit(130)
+
+ monkeypatch.setattr(upgrade_flow, "_run_upgrade", cancel)
+ with pytest.raises(SystemExit):
+ upgrade_flow.upgrade_to_full(
+ repo,
+ provider_name=None,
+ model=None,
+ reasoning=None,
+ concurrency=1,
+ yes=True,
+ )
+
+ state = load_state(repo)
+ assert state["docs_mode"] == "none"
+ assert state["full_upgrade"]["status"] == "resumable"
+ assert state["full_upgrade"]["retryable"] is True
+ assert state["full_upgrade"]["next_stage"] == "search"
diff --git a/tests/unit/core/test_index_scope.py b/tests/unit/core/test_index_scope.py
new file mode 100644
index 000000000..b30e52f23
--- /dev/null
+++ b/tests/unit/core/test_index_scope.py
@@ -0,0 +1,51 @@
+from types import SimpleNamespace
+
+from repowise.core.index_scope import file_page_scope, resolve_index_scope, stamp_index_scope
+
+
+def test_legacy_scope_does_not_invent_completeness() -> None:
+ scope = resolve_index_scope({"docs_enabled": True, "total_pages": 12}, {"commit_limit": 500})
+ assert scope["run_mode"] == "unknown"
+ assert scope["content_provenance"] == "unknown"
+ assert scope["git_tier"] == "unknown"
+ assert scope["git_commit_cap"] == 500
+ assert scope["git_history_coverage"] is None
+ assert scope["file_pages"]["generated"] is None
+ assert scope["search"]["semantic"] == "unknown"
+
+
+def test_scope_keeps_configured_caps_separate_from_achieved_counts() -> None:
+ state = {"run_mode": "fast", "git_tier": "essential", "docs_mode": "none"}
+ stamp_index_scope(
+ state,
+ {"commit_limit": 500, "max_file_pages": 2},
+ file_pages=file_page_scope(
+ configured_cap=2,
+ eligible=5,
+ generated_pages=[SimpleNamespace(page_type="file_page") for _ in range(2)],
+ ),
+ git_history_coverage={"files_eligible": 5, "files_measured": 3},
+ )
+ scope = resolve_index_scope(state, {"commit_limit": 999})
+ assert scope["git_commit_cap"] == 500
+ assert scope["git_history_coverage"]["files_measured"] == 3
+ assert scope["file_pages"] == {
+ "configured_cap": 2,
+ "effective_cap": 2,
+ "eligible": 5,
+ "generated": 2,
+ "omitted": 3,
+ }
+
+
+def test_scope_surfaces_degraded_features_as_unavailable() -> None:
+ scope = resolve_index_scope(
+ {
+ "index_scope": {"analysis": {"unavailable": ["health"], "skipped": []}},
+ "degraded": ["Execution flow: parser failed"],
+ }
+ )
+ assert scope["analysis"]["unavailable"] == [
+ "Execution flow: parser failed",
+ "health",
+ ]
diff --git a/tests/unit/generation/test_editor_file_base.py b/tests/unit/generation/test_editor_file_base.py
index 6a63844a2..2dd92ae6c 100644
--- a/tests/unit/generation/test_editor_file_base.py
+++ b/tests/unit/generation/test_editor_file_base.py
@@ -66,6 +66,28 @@ def test_render_contains_repo_name(gen):
assert "test-repo" in result
+def test_render_contains_machine_readable_index_scope(gen):
+ import dataclasses
+
+ data = dataclasses.replace(
+ _minimal_data(),
+ index_scope={
+ "run_mode": "fast",
+ "content_provenance": "none",
+ "git_tier": "essential",
+ "file_pages": {"eligible": 5, "generated": 0, "omitted": 5},
+ "analysis": {"unavailable": [], "skipped": ["generation"]},
+ "upgrade": {"status": "pending"},
+ },
+ )
+ result = gen.render(data)
+ assert "Scope: fast index · none content · essential Git" in result
+ assert "5 eligible file pages omitted" in result
+ assert '"eligible": 5' in result
+ assert '"generated": 0' in result
+ assert "repowise update --full" in result
+
+
def _health_block(
maintainability_average: float | None,
performance_average: float | None = None,
diff --git a/tests/unit/generation/test_stub_fallback_never_overwrites.py b/tests/unit/generation/test_stub_fallback_never_overwrites.py
index 1aaf5899d..2d4c5a88f 100644
--- a/tests/unit/generation/test_stub_fallback_never_overwrites.py
+++ b/tests/unit/generation/test_stub_fallback_never_overwrites.py
@@ -16,7 +16,7 @@ from sqlalchemy import select
from repowise.core.generation.models import STUB_FALLBACK_ERROR
from repowise.core.persistence import create_engine, create_session_factory, get_session
-from repowise.core.persistence.crud import upsert_page, upsert_repository
+from repowise.core.persistence.crud import load_prior_pages, upsert_page, upsert_repository
from repowise.core.persistence.crud.pages import upsert_pages_from_generated
from repowise.core.persistence.database import init_db
from repowise.core.persistence.models import Page, PageVersion
@@ -239,6 +239,17 @@ async def test_stub_is_still_written_when_the_page_is_new(session_factory):
assert page.provider_name == "template"
+async def test_stub_is_not_reused_as_a_completed_model_page(session_factory):
+ async with get_session(session_factory) as session:
+ repo = await upsert_repository(session, name="demo", local_path="/demo")
+ await upsert_pages_from_generated(session, [_stub("module_page:src/retry")], repo.id)
+
+ async with get_session(session_factory) as session:
+ prior = await load_prior_pages(session, repo.id)
+
+ assert "module_page:src/retry" not in prior
+
+
async def test_stub_members_do_not_retire_the_page_whose_generation_failed(
session_factory,
):
diff --git a/tests/unit/server/mcp/test_meta_freshness.py b/tests/unit/server/mcp/test_meta_freshness.py
index a21c059c3..be23f7c8a 100644
--- a/tests/unit/server/mcp/test_meta_freshness.py
+++ b/tests/unit/server/mcp/test_meta_freshness.py
@@ -63,6 +63,22 @@ def test_no_git_signal_omits_index_behind_entirely(tmp_path, monkeypatch):
assert "index_behind" not in out
+def test_build_meta_exposes_the_persisted_index_scope(tmp_path, monkeypatch):
+ repowise_dir = tmp_path / ".repowise"
+ repowise_dir.mkdir()
+ (repowise_dir / "state.json").write_text(
+ '{"run_mode":"fast","git_tier":"essential","docs_mode":"none"}',
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(_meta, "read_live_head", lambda p: None)
+
+ out = _meta.build_meta(repository=_repo(tmp_path))
+
+ assert out["index_scope"]["run_mode"] == "fast"
+ assert out["index_scope"]["content_provenance"] == "none"
+ assert out["index_scope"]["git_history_coverage"] is None
+
+
def test_served_target_changed_warns(tmp_path, monkeypatch):
monkeypatch.setattr(_meta, "read_live_head", lambda p: _LIVE)
_prime(tmp_path, frozenset({"src/a.py"}))
diff --git a/tests/unit/server/test_repos_status.py b/tests/unit/server/test_repos_status.py
index c71d759e2..8563503a0 100644
--- a/tests/unit/server/test_repos_status.py
+++ b/tests/unit/server/test_repos_status.py
@@ -7,6 +7,7 @@ the presence of a local .repowise/wiki.db file.
from __future__ import annotations
+import json
import tempfile
from pathlib import Path
@@ -19,6 +20,35 @@ from repowise.core.persistence.models import GraphNode
from repowise.core.workspace.config import RepoEntry, WorkspaceConfig
+async def test_repo_response_exposes_canonical_index_scope(
+ client: AsyncClient, session: AsyncSession
+) -> None:
+ repo_dir = Path(tempfile.mkdtemp()) / "scoped-repo"
+ repowise_dir = repo_dir / ".repowise"
+ repowise_dir.mkdir(parents=True)
+ (repowise_dir / "state.json").write_text(
+ json.dumps(
+ {
+ "run_mode": "fast",
+ "git_tier": "essential",
+ "docs_mode": "none",
+ "git_history_coverage": {"eligible_files": 4, "files_with_history": 3},
+ }
+ ),
+ encoding="utf-8",
+ )
+ repo = await upsert_repository(session, name="scoped-repo", local_path=str(repo_dir))
+ await session.commit()
+
+ response = await client.get("/api/repos")
+
+ scoped = next(row for row in response.json() if row["id"] == repo.id)["index_scope"]
+ assert scoped["run_mode"] == "fast"
+ assert scoped["content_provenance"] == "none"
+ assert scoped["git_history_coverage"]["files_with_history"] == 3
+
+
@pytest.mark.asyncio
async def test_registered_unindexed_repo_reports_needs_index(
client: AsyncClient, session: AsyncSession