Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
refactor(update): docs, decision and generation stages out of run_update (#4022)
Raghav Chamadiyaa8ac48d6fb3c
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex 826eaa2be..3a6df9ed0 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -12,7 +12,6 @@ from __future__ import annotationsimport contextlibimport sysimport time-from collections.abc import Callablefrom dataclasses import dataclass, fieldfrom enum import StrEnumfrom pathlib import Path@@ -54,6 +53,8 @@ from repowise.core.pipeline import PhaseTimings, timedfrom repowise.core.reasoning import REASONING_MODESfrom .config_changes import classify_config_changes+from .decision_passes import _run_decision_evolution as _run_decision_evolution+from .decision_passes import run_decision_passesfrom .incremental import (_build_update_vector_store,_load_stored_function_mod_p80,@@ -65,7 +66,9 @@ from .incremental import (_run_partial_analysis,)from .mode import _resolve_index_only_mode-from .options import UpdateOptions, UpdateRun+from .options import DocsPass, UpdateOptions, UpdateRun+from .page_generation import _generation_warning_handler as _generation_warning_handler+from .page_generation import generate_pages, render_stale_structurefrom .persistence import (_persist_index_only_update,_repair_module_attribution,@@ -80,7 +83,6 @@ from .persistence import (from .reporting import (JsonProgressEmitter,_render_update_report,- make_generation_progress,render_changed_files,render_header,show_full_completion,@@ -89,30 +91,6 @@ from .workspace import _workspace_updatelog = structlog.get_logger(__name__)-#: How far back the hook-efficacy classifier re-reads transcripts on an update.-#: Wider than the update cadence on purpose: a firing near the end of a session-#: has no following tool calls yet, so re-running over the same transcript later-#: is what upgrades an early "ignored" to the truth. Re-classification is-#: idempotent (the ledger id is a hash of the firing's own text).-_EFFICACY_LOOKBACK_SECONDS = 7 * 86400.0---def _generation_warning_handler(- degraded: list[str], *, require_embedding_success: bool-) -> Callable[[str], None]:- """Record generation warnings and make required embedding writes fatal."""-- def _handle(message: str) -> None:- degraded.append(message)- if require_embedding_success:- raise RuntimeError(- "Configuration-triggered page embedding failed; the previous "- "fingerprint was retained so the next update retries."- )-- return _handle--def _fail_on_embed_failure(repo_path: Path, embedder: str | None, embed_failed_pages: int, emitter: Any) -> None:@@ -635,67 +613,6 @@ def _stale_renderer_paths(repo_path, parsed_files) -> list[str]:return []-def _run_decision_evolution(- repo_path: Path,- file_diffs: list,- git_meta_map: dict,- *,- base_ref: str,- head: str | None,- provider: Any,- cost_tracker: Any,- max_concurrency: int,-) -> dict | None:- """Run the update's decision-evolution pass, or ``None`` with no changed file.-- Pass 1 sees only the commits in ``base_ref..head``: older ones were judged- by the update that brought them in. The judge calls are booked as decision- spend, not page generation.- """- changed_set = {fd.path for fd in file_diffs if fd.status in ("added", "modified")}- if not changed_set:- return None-- from repowise.core.analysis.decision_evolution import (- commits_in_range,- run_update_evolution,- update_evidence_by_file,- )-- evidence_by_file = update_evidence_by_file(- file_diffs, git_meta_map, commits_in_range(repo_path, base_ref, head)- )-- async def _run() -> dict:- from repowise.cli.helpers import get_db_url_for_repo- from repowise.core.persistence import (- create_engine,- create_session_factory,- get_session,- init_db,- upsert_repository,- )-- engine = create_engine(get_db_url_for_repo(repo_path))- await init_db(engine)- sf = create_session_factory(engine)- async with get_session(sf) as session:- repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))- res = await run_update_evolution(- session,- repo.id,- changed_files=changed_set,- evidence_by_file=evidence_by_file,- provider=provider,- max_concurrency=max_concurrency,- )- await engine.dispose()- return res-- with cost_tracker.record_as("decision_extraction"):- return run_async(_run())--def _start_run(opts: UpdateOptions) -> UpdateRun:"""Start the run clock and pick the progress output (rich or JSON events)."""# ``run`` is the denominator of every stage row; stages nest and overlap.@@ -1788,6 +1705,286 @@ def _embed_config_pages(vector_store, pages: list) -> None:) from exc+def _docs_update(opts: UpdateOptions, run: UpdateRun) -> UpdateOutcome:+ """Model-backed update: decisions, page generation, persist, then state."""+ repo_path = run.repo_path+ docs = _start_docs_pass(opts, run)+ run_decision_passes(opts, run, docs)+ generate_pages(opts, run, docs)+ render_stale_structure(opts, run, docs)++ # One transaction, outside the contended generation window.+ from repowise.cli.providers import flush_cost_tracker++ flush_cost_tracker(docs.cost_tracker)+ _enrich_knowledge_graph(run, docs)+ _persist_docs(run, docs)+ _rescore_after_persist(run)++ # The persist above only rescanned the changed files.+ if run.scanner_changed:+ with timed(run.timings, "security_rescan"):+ rescan_security_if_changed(repo_path, run.state, run.exclude_patterns)++ _finish_outcome(repo_path, opts.agents_md, run.degraded, timings=run.timings)+ _save_docs_state(run, docs)++ # A pending marker is kept only when it names a newer commit.+ consume_update_pending(repo_path, run.head)+ if not opts.skip_cross_repo_hooks:+ _run_cross_repo_hooks(run)+ return _report_docs_outcome(opts, run, docs)+++def _start_docs_pass(opts: UpdateOptions, run: UpdateRun) -> DocsPass:+ """Generation config, the provider (prompting when allowed) and its cost tracker."""+ # Imported here so index-only updates never pay for the generation layer.+ from repowise.core.generation import GenerationConfig++ cfg = run.cfg+ generation_changed = run.config.generation_changed+ language = cfg.get("language", "en")+ enable_onboarding_cfg = bool(cfg.get("enable_onboarding", True))+ config = GenerationConfig.from_repo_config(+ cfg,+ max_concurrency=opts.concurrency,+ language=language,+ reasoning=resolve_reasoning(opts.reasoning, cfg),+ enable_onboarding=enable_onboarding_cfg,+ wiki_style=cfg.get("wiki_style", "comprehensive"),+ cache_enabled=not generation_changed,+ # Levels 3+ describe the whole repo; a changed-file slice would truncate them.+ file_pages_only=not generation_changed,+ )++ # Prompts for a provider only in an interactive terminal.+ provider = resolve_provider_or_prompt(+ opts.provider_name,+ opts.model,+ run.repo_path,+ reasoning=opts.reasoning,+ interactive=_docs_provider_prompt_allowed(run.emitter),+ )++ # Persist this update's model spend to llm_costs, as init does.+ from repowise.cli.providers import build_cost_tracker++ cost_tracker = build_cost_tracker(+ run.repo_path, run.repo_path.name, no_cost_tracking=opts.no_cost_tracking+ )+ provider._cost_tracker = cost_tracker+ return DocsPass(config=config, provider=provider, cost_tracker=cost_tracker)+++def _enrich_knowledge_graph(run: UpdateRun, docs: DocsPass) -> None:+ """Model enrichment of a refreshed KG (layer names, summaries), as init does."""+ # Also runs on a builder-version bump with an unchanged graph: restored layer+ # names were written against the old layers.+ kg = run.knowledge_graph_result+ if kg is None:+ return+ try:+ from repowise.core.generation.knowledge_graph import enrich_knowledge_graph++ with timed(run.timings, "knowledge_graph.enrich"):+ run.knowledge_graph_result = run_async(+ enrich_knowledge_graph(+ kg_skeleton=kg,+ llm_client=docs.provider,+ graph_builder=run.graph_builder,+ repo_structure=run.repo_structure,+ tech_stack=kg.project.get("tech_stack", []),+ generated_pages=docs.generated_pages,+ reasoning=docs.config.reasoning,+ )+ )+ except Exception as exc:+ console.print(f"[yellow]Knowledge-graph enrichment skipped: {exc}[/yellow]")+ run.degraded.append(f"Knowledge-graph enrichment: {exc}")+++def _persist_docs(run: UpdateRun, docs: DocsPass) -> None:+ """Persist in one transaction: pages fail loudly, derived layers degrade."""+ from .persistence import _persist_full_update++ config = run.config+ _stage(run, "persist")+ with _errors_reported(run), timed(run.timings, "persist"):+ docs.db_total_pages = _persist_full_update(+ repo_path=run.repo_path,+ repo_name=run.repo_path.name,+ generated_pages=docs.generated_pages,+ file_diffs=run.file_diffs,+ git_meta_map=run.persisted_git_meta,+ new_decision_markers=[*docs.new_decision_markers, *docs.session_decisions],+ decision_vector_store=docs.decision_vector_store,+ provider=docs.provider,+ partial_health_report=run.partial_health_report,+ dead_code_report=run.dead_code_report,+ graph_builder=run.graph_builder,+ knowledge_graph_result=run.knowledge_graph_result,+ degraded=run.degraded,+ doc_drift_report=run.doc_drift_report,+ decay_paths=run.affected.decay_only,+ parsed_files=run.parsed_files,+ source_map=run.source_map,+ git_decay_map=run.git_decay_map,+ full_git_summary=(run.full_git_summaries[0] if run.full_git_summaries else None),+ reconcile_full_scope=config.traversal_changed,+ reconcile_full_generation=config.generation_changed,+ require_config_rebuild_success=config.rebuild_required,+ require_decision_persist_success=config.git_changed,+ history_window_changed=config.git_changed,+ timings=run.timings,+ )+++def _rescore_after_persist(run: UpdateRun) -> None:+ """Re-score every file off this run's graph: weekly, or forced by a config or parser change."""+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION++ from .persistence import full_rescore_due, run_decay_health_rescore++ health_changed = run.config.health_changed+ rescored = False+ if health_changed or run.extraction_changed or full_rescore_due(run.state, run.head_ts):+ with timed(run.timings, "rescore"):+ rescored = run_decay_health_rescore(+ run.repo_path, run.graph_builder, run.parsed_files, run.exclude_patterns+ )+ if rescored:+ # No timestamp (git unavailable): keep the existing stamp.+ if run.head_ts is not None:+ run.state["last_full_rescore_at"] = run.head_ts+ run.state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION+ if health_changed and not rescored:+ raise RuntimeError(+ "Configuration-triggered health re-score failed; the previous "+ "fingerprint was retained so the next update retries."+ )+++def _save_docs_state(run: UpdateRun, docs: DocsPass) -> None:+ """Advance both sync pointers and write the run's state."""+ from repowise.cli.helpers import config_fingerprint++ repo_path, state, head = run.repo_path, run.state, run.head+ if run.knowledge_graph_result is not None:+ _export_knowledge_graph(run)++ # Never write a null pointer: the next update would refuse to run.+ if head:+ state["last_sync_commit"] = head+ state["last_docs_commit"] = head+ # The DB total; regeneration upserts existing pages.+ state["total_pages"] = docs.db_total_pages+ state["config_fingerprint"] = config_fingerprint(repo_path)+ state["config_dependency_fingerprints"] = run.config.curr_dependency_fps+ state["renderer_fingerprint"] = _current_renderer_fingerprint(repo_path)+ # Closed at the state write, as on the index-only path.+ run.timings.stop("run")+ state["phase_timings"] = run.timings.totals+ if run.full_git_summaries:+ coverage = getattr(run.full_git_summaries[0], "history_coverage", None)+ if coverage is not None:+ state["git_history_coverage"] = coverage.to_dict()+ else:+ state.pop("git_history_coverage", None)+ # Every row was rewritten under the current rules.+ state[GIT_HISTORY_VERSION_KEY] = GIT_HISTORY_VERSION+ save_state(repo_path, state)+++def _export_knowledge_graph(run: UpdateRun) -> None:+ try:+ from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_json++ save_knowledge_graph_json(run.repo_path, run.knowledge_graph_result)+ run.state["knowledge_graph"] = build_kg_state(run.knowledge_graph_result)+ except Exception as exc:+ console.print(f"[yellow]Knowledge-graph export skipped: {exc}[/yellow]")+ run.degraded.append(f"Knowledge-graph export: {exc}")+++def _run_cross_repo_hooks(run: UpdateRun) -> None:+ """Rebuild the cross-repo layer when this repo is a workspace member."""+ try:+ ws_root = find_workspace_root(run.repo_path)+ if ws_root is not None:+ from repowise.core.workspace import WorkspaceConfig+ from repowise.core.workspace.update import run_cross_repo_hooks++ ws_config = WorkspaceConfig.load(ws_root)+ alias = _workspace_alias(ws_root, ws_config, run.repo_path)+ if alias and len(ws_config.repos) >= 2:+ console.print("Running cross-repo analysis...")+ run_async(run_cross_repo_hooks(ws_config, ws_root, [alias]))+ console.print("[green]Cross-repo analysis updated.[/green]")+ except Exception as exc:+ # Never fails the update, but is not reported as clean either.+ run.degraded.append(f"Cross-repo analysis: {exc}")+++def _workspace_alias(ws_root: Path, ws_config: Any, repo_path: Path) -> str | None:+ """This repo's alias in the workspace config, or None when it is not listed."""+ repo_abs = repo_path.resolve()+ for entry in ws_config.repos:+ if (ws_root / entry.path).resolve() == repo_abs:+ return entry.alias+ return None+++def _report_docs_outcome(opts: UpdateOptions, run: UpdateRun, docs: DocsPass) -> UpdateOutcome:+ """Record the outcome, then the JSON ``done`` event or the completion panel."""+ elapsed = time.monotonic() - run.start+ _record_update_outcome(+ index_only=False,+ changed_count=len(run.file_diffs),+ provider=docs.provider,+ generated_pages=docs.generated_pages,+ )++ if run.emitter is not None:+ _fail_if_embed_failed(run, docs)+ return _emit_done(+ run,+ UpdateOutcome.REGENERATED,+ pages_generated=len(docs.generated_pages),+ cost_usd=docs.cost_tracker.session_cost,+ duration_s=elapsed,+ degraded=run.degraded,+ )+ show_full_completion(+ generated_pages=docs.generated_pages,+ decay_count=len(run.affected.decay_only),+ decisions_changed=(+ len(docs.new_decision_markers) + len(docs.session_decisions) + docs.decisions_evolved+ ),+ provider=docs.provider,+ cost=docs.cost_tracker.session_cost,+ tokens=docs.cost_tracker.session_tokens,+ elapsed=elapsed,+ degraded=run.degraded,+ )+ _render_update_report(+ docs.generated_pages, run.affected, docs.new_decision_markers, elapsed, detail=opts.verbose+ )+ _fail_if_embed_failed(run, docs)+ return UpdateOutcome.REGENERATED+++def _fail_if_embed_failed(run: UpdateRun, docs: DocsPass) -> None:+ if docs.full_stats["embed_failed_pages"]:+ from repowise.cli.providers import resolve_embedder++ _fail_on_embed_failure(+ run.repo_path,+ resolve_embedder(run.cfg.get("embedder")),+ docs.full_stats["embed_failed_pages"],+ run.emitter,+ )++def run_update(path: str | None,provider_name: str | None,@@ -1861,11 +2058,8 @@ def run_update(assert run.repo_path is not None # single mode always sets repo_path_prepare_repo(run.repo_path)- # --- Fast -> full upgrade (--full): a distinct path that reuses the- # persisted graph rather than diffing changed files. Dispatched before any- # incremental change-detection so the normal `repowise update` flow below- # is byte-for-byte unchanged. ---- if full:+ # --full reuses the persisted graph instead of diffing changed files.+ if opts.full:return _full_upgrade(opts, run)_load_sync_base(opts, run)_check_config_and_renderer(run)@@ -1886,16 +2080,14 @@ def run_update(return _no_changed_files(opts, run)if run.config.health_changed:- # Full re-score (not the partial update) so unchanged files pick up the- # new rules/excludes instead of being left stale.console.print("[yellow]Config files changed — re-running health analysis.[/yellow]")if _config_change_only(run):return _config_only_update(opts, run)- render_changed_files(run.file_diffs, verbose=verbose)+ render_changed_files(run.file_diffs, verbose=opts.verbose)_rebuild_index(run)_plan_pages(opts, run)- if dry_run:+ if opts.dry_run:console.print("[yellow]Dry run — no pages regenerated.[/yellow]")return _emit_done(run, UpdateOutcome.DRY_RUN)_analyze_changes(run)@@ -1903,785 +2095,4 @@ def run_update(if run.index_only:return _index_only_update(opts, run)- repo_path = run.repo_path- start = run.start- timings = run.timings- emitter = run.emitter- state = run.state- cfg = run.cfg- base_ref = run.base_ref- head = run.head- curr_dependency_fps = run.config.curr_dependency_fps- traversal_config_changed = run.config.traversal_changed- git_config_changed = run.config.git_changed- health_config_changed = run.config.health_changed- generation_config_changed = run.config.generation_changed- config_rebuild_required = run.config.rebuild_required- extraction_changed = run.extraction_changed- scanner_changed = run.scanner_changed- stale_deterministic_ids = run.stale_deterministic_ids- file_diffs = run.file_diffs- degraded = run.degraded- exclude_patterns = run.exclude_patterns- git_decay_map = run.git_decay_map- full_git_summaries = run.full_git_summaries- head_ts = run.head_ts- parsed_files = run.parsed_files- source_map = run.source_map- graph_builder = run.graph_builder- repo_structure = run.repo_structure- git_meta_map = run.git_meta_map- affected = run.affected- partial_health_report = run.partial_health_report- dead_code_report = run.dead_code_report- doc_drift_report = run.doc_drift_report- persisted_git_meta = run.persisted_git_meta- knowledge_graph_result = run.knowledge_graph_result-- # The generation/LLM layer is only needed past this point — importing it- # above the index-only branch would make every index-only update (the- # post-commit hook's hot path) pay the import for code it never runs.- from repowise.core.generation import ContextAssembler, GenerationConfig, PageGenerator-- language = cfg.get("language", "en")- # Config-driven (saved by `repowise init`); CLI override not surfaced- # on update yet — defaults to on to keep the onboarding collection- # fresh as the codebase evolves.- enable_onboarding_cfg = bool(cfg.get("enable_onboarding", True))- config = GenerationConfig.from_repo_config(- cfg,- max_concurrency=concurrency,- language=language,- reasoning=resolve_reasoning(reasoning, cfg),- enable_onboarding=enable_onboarding_cfg,- # Honor the wiki style chosen at init (or via `repowise restyle`) so pages- # regenerated for changed files match the rest of the wiki's voice.- wiki_style=cfg.get("wiki_style", "comprehensive"),- cache_enabled=not generation_config_changed,- # An incremental update regenerates only the changed files' pages, and- # it feeds generate_all a parsed_files filtered to those files. Levels 3- # and up describe the whole repository from parsed_files, so without- # this a one-commit update would rewrite the codebase map, module and- # overview pages from a truncated view (a module page claiming one file,- # a codebase map with no directories). Stop the ladder after level 2 and- # leave the repo-wide pages for a full run — the same guard the- # deterministic index-only update already uses. `repowise generate`- # refreshes the repo-wide pages correctly, from the complete view.- file_pages_only=not generation_config_changed,- )-- # Resolve the generation provider. If the repo wants docs but was never- # given a provider/key (e.g. it started --index-only and later asked for- # LLM docs, or `repowise update --docs`), onboard the same way init- # does: prompt for provider + key and persist, but only in an interactive- # terminal. Hooks / CI / --progress json keep the clean non-blocking error.- # In the workspace docs flow each member reaches this per-repo run; the- # first prompt sets the key in-process, so later members auto-resolve.- provider = resolve_provider_or_prompt(- provider_name,- model,- repo_path,- reasoning=reasoning,- interactive=_docs_provider_prompt_allowed(emitter),- )-- # Attach a DB-backed CostTracker so every LLM call made during this update- # (decision rescan + page regeneration) is persisted to the `llm_costs`- # table — matching what `repowise init` already does. Without this,- # `repowise costs` only ever reflects the initial index and shows $0 for- # all subsequent updates.- from repowise.cli.providers import build_cost_tracker-- cost_tracker = build_cost_tracker(repo_path, repo_path.name, no_cost_tracking=no_cost_tracking)- provider._cost_tracker = cost_tracker-- # (dead_code_report computed above, before the index-only branch)-- # One row for the decision passes below: the marker re-scan, session- # mining, discovery, injection feedback, hook efficacy and evolution. Each- # is best-effort and most are model calls, so they are read as a group.- timings.start("decisions")-- # Re-scan changed files for inline decision markers- from repowise.core.analysis.decisions.policy import resolve_policy-- decision_policy = resolve_policy(cfg).policy- new_decision_markers: list = []-- # A wider/different history window changes the evidence available to the- # Git archaeology source even when no source file changed. Re-run that- # source against the freshly rebuilt full metadata map so update converges- # with a clean index. Treat a source failure as a required config-rebuild- # failure; otherwise the new fingerprint would suppress the only retry.- if git_config_changed and decision_policy.source_enabled("git_archaeology"):- try:- from repowise.core.analysis.decision_extractor import DecisionExtractor-- history_extractor = DecisionExtractor(- repo_path=repo_path,- provider=provider,- graph=graph_builder.graph(),- git_meta_map=git_meta_map,- parsed_files=parsed_files,- source_map=source_map,- policy=decision_policy,- )- with cost_tracker.record_as("decision_extraction"):- history_report = run_async(- history_extractor.extract_all(enabled_sources={"git_archaeology"})- )- if history_report.failures:- details = "; ".join(- f"{source}: {error}"- for source, error in sorted(history_report.failures.items())- )- raise RuntimeError(details)- new_decision_markers.extend(history_report.decisions)- except Exception as exc:- raise RuntimeError(- "Configuration-triggered Git decision extraction failed; the previous "- "fingerprint was retained so the next update retries."- ) from exc-- # Sub-rows of ``decisions``; each step is best-effort and catches its own- # errors, so a plain start/stop pair brackets it.- timings.start("decisions.rescan")- try:- from repowise.core.analysis.decision_extractor import DecisionExtractor-- changed_paths = [fd.path for fd in file_diffs if fd.status in ("added", "modified")]- # The rescan is the inline_marker source; it was running regardless of- # whether that source was switched off. It also reads uncommitted- # files on purpose: a marker is source text, not history.- if changed_paths and decision_policy.source_enabled("inline_marker"):- extractor = DecisionExtractor(- repo_path=repo_path,- provider=provider,- graph=graph_builder.graph(),- git_meta_map=git_meta_map,- policy=decision_policy,- )- # Label these calls as decision extraction so the Costs page can- # tell them apart from page regeneration (both ride this provider).- with cost_tracker.record_as("decision_extraction"):- new_decision_markers.extend(- run_async(extractor.scan_inline_markers(restrict_to_files=changed_paths))- )- if new_decision_markers and verbose:- console.print(- f"New decision markers found: [green]{len(new_decision_markers)}[/green]"- )- except Exception as exc:- degraded.append(f"Decision re-scan: {exc}")- if verbose:- console.print(f"[yellow]Decision re-scan skipped: {exc}[/yellow]")- timings.stop("decisions.rescan")-- # Session mining, session discovery, injection feedback and hook efficacy.- timings.start("decisions.sessions")-- # Session-sourced decisions: mine agent transcript lines appended since- # the last update, structure new candidates in one batched LLM pass, and- # collect the observation-qualified promotions. They ride the same- # decision upsert as the marker re-scan below. Everything stays local, and- # the lane ships off: `decision source set session --on` enables it.- # The indexed file set bounds what a session-mined record may claim to- # govern: a transcript names scratch files, plan docs and sibling- # checkouts, and only this set knows which paths are this codebase.- indexed_files = frozenset(source_map) if source_map else None- session_decisions: list = []- try:- from repowise.core.sessions.miners.decisions import mine_session_decisions-- if decision_policy.source_enabled("session"):- session_provider = provider if decision_policy.llm_allowed("session") else None- session_decisions = run_async(- mine_session_decisions(- repo_path,- provider=session_provider,- harnesses=decision_policy.harnesses,- collect_discovery_spans=decision_policy.llm_allowed("session_discovery"),- indexed=indexed_files,- )- )- if session_decisions and verbose:- promoted_titles = {d.title for d in session_decisions}- console.print(f"Session decisions promoted: [green]{len(promoted_titles)}[/green]")- except Exception as exc:- degraded.append(f"Session decision mining: {exc}")- if verbose:- console.print(f"[yellow]Session decision mining skipped: {exc}[/yellow]")-- # The broad lane: at most one model call over the prose the pass above- # just read. It runs second because that read is what fills its queue.- try:- from repowise.core.analysis.decisions.discovery import run_update_discovery-- with cost_tracker.record_as("decision_extraction"):- outcome = run_async(- run_update_discovery(- repo_path,- provider=provider,- policy=decision_policy,- indexed=indexed_files,- )- )- session_decisions = [*session_decisions, *outcome.decisions]- if outcome.report.status == "failed":- degraded.append(f"Session discovery: {outcome.report.reason}")- if verbose:- funnel = outcome.report- console.print(- f"Session discovery: {funnel.status}"- + (f" ({funnel.reason})" if funnel.reason else "")- + f" · {funnel.calls} call(s) · {funnel.candidates_grounded} grounded"- + f" · {funnel.spans_deferred} span(s) queued"- )- except Exception as exc:- degraded.append(f"Session discovery: {exc}")- if verbose:- console.print(f"[yellow]Session discovery skipped: {exc}[/yellow]")-- # Usage feedback v1: decisions the augment hooks injected into agent- # sessions are judged against those sessions' mined corrections (followed- # -> staleness relaxes, contradicted -> staleness bumps). Pure SQLite over- # the staging sidecar + decision_records; no LLM.- #- # Gated on the ``session`` source even though it judges injected decisions- # of *every* source: its only evidence is that session's mined user- # corrections, which no other lane writes. With the lane off, every row- # would be judgeable=False and settle as ``unjudgeable`` — and- # ``mark_injection_evaluated`` is terminal, so turning the lane on later- # could never recover them. Inert without the lane, like session discovery.- try:- from repowise.core.sessions.miners.decisions import apply_injection_feedback-- if decision_policy.source_enabled("session"):-- async def _run_injection_feedback() -> dict:- from repowise.cli.helpers import get_db_url_for_repo- from repowise.core.persistence import (- create_engine,- create_session_factory,- get_session,- init_db,- upsert_repository,- )-- url = get_db_url_for_repo(repo_path)- engine = create_engine(url)- await init_db(engine)- sf = create_session_factory(engine)- async with get_session(sf) as session:- repo = await upsert_repository(- session, name=repo_path.name, local_path=str(repo_path)- )- res = await apply_injection_feedback(session, repo.id, repo_path)- await engine.dispose()- return res-- feedback = run_async(_run_injection_feedback())- if verbose and (feedback.get("followed") or feedback.get("contradicted")):- console.print(- f"Injected-decision feedback: [green]{feedback.get('followed', 0)} "- f"followed[/green], [yellow]{feedback.get('contradicted', 0)} "- "contradicted[/yellow]"- )- except Exception as exc:- degraded.append(f"Injection feedback: {exc}")- if verbose:- console.print(f"[yellow]Injection feedback skipped: {exc}[/yellow]")-- # The same feedback question for the non-decision hook surfaces. Those- # firings point at a file or a search result rather than a decision record,- # so they are judged by what the agent did next — which only the transcript- # knows. Scoped to transcripts touched since the last update; the whole- # history is a one-off `repowise hook backfill`.- #- # Gated on the ``session`` source because that switch is documented as what- # stops repowise reading your transcripts, and this reads them. It is the- # privacy boundary, not a statement about what the rows are for, so it fails- # closed: with the lane off the live hook still records its own firings and- # only the replay-filled columns are missing, which `repowise hook backfill`- # fills on demand.- try:- from repowise.core.sessions.efficacy import ingest_transcript_efficacy-- if decision_policy.source_enabled("session"):- classified = ingest_transcript_efficacy(- repo_path, since=time.time() - _EFFICACY_LOOKBACK_SECONDS- )- if verbose and classified:- console.print(f"Hook firings classified: [green]{sum(classified.values())}[/green]")- except Exception as exc:- degraded.append(f"Hook efficacy: {exc}")- if verbose:- console.print(f"[yellow]Hook efficacy classification skipped: {exc}[/yellow]")- timings.stop("decisions.sessions")-- # Count of decision records touched by evolution, surfaced in the panel.- decisions_evolved = 0-- # Build the shared vector store once: reused by the supersession detector- # below and by the decision upsert in _persist (semantic dedup + search).- with timed(timings, "decisions.vector_store"):- decision_vector_store = _build_update_vector_store(- repo_path,- cfg,- degraded,- required=(traversal_config_changed or generation_config_changed),- )-- # --- Two-pass decision evolution (Phase 3C), BEFORE page regeneration ----- # Cross-reference the diff + new commit bodies against existing decisions- # governing the changed files (Pass 1, cheap) then ask the LLM whether each- # survivor is amended/superseded/reaffirmed (Pass 2, gated). Governed pages- # of an evolved decision are folded into ``affected.regenerate`` so they- # re-render in this same run — the cascade-coupling the design calls for.- timings.start("decisions.evolution")- try:- evo = _run_decision_evolution(- repo_path,- file_diffs,- git_meta_map,- base_ref=base_ref,- head=head,- provider=provider,- cost_tracker=cost_tracker,- max_concurrency=config.max_concurrency,- )- if evo is not None:- decisions_evolved = (- evo.get("superseded", 0) + evo.get("amended", 0) + evo.get("reaffirmed", 0)- )- evo_regen = evo.get("regen_files") or set()- if evo_regen:- # page_id == file path for file pages, so adding the governed- # file paths schedules their pages for regeneration.- affected.regenerate = list(- dict.fromkeys([*affected.regenerate, *sorted(evo_regen)])- )- if verbose:- console.print(- f"Decision evolution: [cyan]{evo.get('superseded', 0)} superseded[/cyan], "- f"[cyan]{evo.get('amended', 0)} amended[/cyan], "- f"[green]{evo.get('reaffirmed', 0)} reaffirmed[/green]; "- f"+{len(evo_regen)} governed page(s) queued for regen."- )- except Exception as exc:- degraded.append(f"Decision evolution: {exc}")- if verbose:- console.print(f"[yellow]Decision evolution skipped: {exc}[/yellow]")- timings.stop("decisions.evolution")- timings.stop("decisions")-- # Filter to only affected files- regen_set = set(affected.regenerate)- affected_parsed = [pf for pf in parsed_files if pf.file_info.path in regen_set]- affected_source = {p: s for p, s in source_map.items() if p in regen_set}-- # Load prior pages so the generator can skip the LLM call for any affected- # file whose freshly rendered prompt still hashes to the persisted value.- async def _load_prior() -> dict[str, object]:- from repowise.cli.helpers import get_db_url_for_repo- from repowise.core.persistence import (- create_engine,- create_session_factory,- get_session,- load_prior_pages,- upsert_repository,- )-- url = get_db_url_for_repo(repo_path)- engine = create_engine(url)- sf = create_session_factory(engine)- async with get_session(sf) as session:- repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))- return await load_prior_pages(session, repo.id)-- try:- prior_pages = run_async(_load_prior())- except Exception as exc:- # Without prior pages the prompt-hash skip is off and every affected- # page re-bills; surface that instead of silently paying it.- degraded.append(f"Prior-page reuse: {exc}")- prior_pages = {}-- # Generate affected pages. The vector store (shared with the decision- # pass above) must ride along: without it regenerated pages are never- # re-embedded, so every update silently evicted its pages from semantic- # search — on long-lived repos the LanceDB corpus ended up holding- # decisions and structural pages but zero current file pages.- assembler = ContextAssembler(config, repo_path=repo_path)- generator = PageGenerator(- provider,- assembler,- config,- vector_store=decision_vector_store,- language=config.language,- prior_pages=prior_pages,- repo_path=repo_path,- )- repo_name = repo_path.name-- _stage(run, "generate")-- # Drive a live progress bar (owl spinner + running cost) off generate_all's- # page callbacks, matching init's generation phase. Cost is read from the- # tracker as each page lands so the readout ticks up in real time. In- # json progress mode there is no bar, so the same callbacks emit- # total_known / page_done events on stdout instead.- from contextlib import nullcontext-- completed_pages = 0- total_pages: int | None = None-- def _on_total_known(total: int) -> None:- nonlocal total_pages- total_pages = total- if emitter is not None:- emitter.total_known(total)- else:- gen_progress.update(gen_task, total=total)-- def _on_page_done(_page_id: str) -> None:- nonlocal completed_pages, total_pages- completed_pages += 1- # The total is an up-front estimate (see _announce_total); some page- # categories can't be predicted exactly, so keep it monotonic with the- # real count, so it never renders "43 of 41" (issue #922).- if total_pages is not None and completed_pages > total_pages:- total_pages = completed_pages- if emitter is not None:- emitter.page_done(- completed=completed_pages, total=total_pages, cost_usd=cost_tracker.session_cost- )- else:- gen_progress.update(- gen_task, advance=1, total=total_pages, cost=cost_tracker.session_cost- )-- # Checkpoint each page to the DB as it lands: a crash mid-generation used- # to lose every finished page (persist ran only at the very end), so the- # rerun re-billed all of them. With the row persisted, the rerun's- # prompt-hash skip sees the fresh content and never re-calls the LLM.- from .persistence import PageCheckpointer-- checkpointer = PageCheckpointer(repo_path, repo_name)-- async def _generate_with_checkpoint() -> list:- await checkpointer.start()- try:- return await generator.generate_all(- affected_parsed,- affected_source,- graph_builder,- repo_structure,- repo_name,- on_page_done=_on_page_done,- on_total_known=_on_total_known,- git_meta_map=git_meta_map,- repo_path=repo_path,- on_page_ready=checkpointer.on_page_ready,- on_warning=_generation_warning_handler(- degraded,- require_embedding_success=(- traversal_config_changed or generation_config_changed- ),- ),- )- finally:- await checkpointer.close()-- with make_generation_progress() if emitter is None else nullcontext() as gen_progress:- gen_task = (- gen_progress.add_task("Generating pages...", total=None, cost=0.0)- if gen_progress is not None- else None- )-- try:- with timed(timings, "generate"):- generated_pages = run_async(_generate_with_checkpoint())- except Exception as exc:- if emitter is not None:- emitter.error(str(exc))- raise-- # Reconcile the bar to the pages actually produced. The up-front total- # is an estimate and onboarding slots may gate-skip, leaving it above- # the real count; snap total to completed so the bar reads N of N at- # 100% instead of stalling short (issue #922).- if gen_task is not None:- gen_progress.update(gen_task, total=completed_pages, completed=completed_pages)-- # Surface the FAQ-weighted budget tilt when session demand shaped this run- # (silent when there is no history to weight; human console mode only).-- full_stats = {"embed_failed_pages": generator.embed_failed_pages}- if checkpointer.failure:- degraded.append(f"Per-page crash checkpointing: {checkpointer.failure}")-- # SCC pages are deterministic but describe the complete graph, so the- # changed-file generator above cannot safely refresh them. Render only the- # stale structural ids from the complete repository view with the template- # provider. This performs no model calls and reuses the update's vector- # store so semantic search is refreshed with the page.- if stale_deterministic_ids and not generation_config_changed:- from .deterministic import regenerate_deterministic_page_ids-- with timed(timings, "render.structure"):- generated_pages.extend(- regenerate_deterministic_page_ids(- repo_path=repo_path,- parsed_files=parsed_files,- source_map=source_map,- graph_builder=graph_builder,- repo_structure=repo_structure,- git_meta_map=git_meta_map,- page_ids=stale_deterministic_ids,- cfg=cfg,- concurrency=concurrency,- degraded=degraded,- dead_code_report=dead_code_report,- prior_page_ids=prior_pages,- vector_store=decision_vector_store,- stats_out=full_stats,- )- )-- # Flush the buffered LLM cost rows now that generation is done — a single- # transaction outside the contended generation window (issue #326).- from repowise.cli.providers import flush_cost_tracker-- flush_cost_tracker(cost_tracker)-- # LLM re-enrichment of the refreshed KG (layer naming + summary backfill- # from this run's regenerated pages), mirroring the init pipeline. Runs- # whenever the refresh returned a result, which is the graph shape moving- # *or* KG_BUILDER_VERSION being bumped by a release — the second is a graph- # that did not change, and it still pays here. That is deliberate and it is- # the one cost of the version bump: a wider edge map or a new entry-point- # ranking changes the layers, and layer names the carry-forward restored- # were written against the old ones.- if knowledge_graph_result is not None:- try:- from repowise.core.generation.knowledge_graph import enrich_knowledge_graph-- with timed(timings, "knowledge_graph.enrich"):- knowledge_graph_result = run_async(- enrich_knowledge_graph(- kg_skeleton=knowledge_graph_result,- llm_client=provider,- graph_builder=graph_builder,- repo_structure=repo_structure,- tech_stack=knowledge_graph_result.project.get("tech_stack", []),- generated_pages=generated_pages,- reasoning=config.reasoning,- )- )- except Exception as exc:- console.print(f"[yellow]Knowledge-graph enrichment skipped: {exc}[/yellow]")- degraded.append(f"Knowledge-graph enrichment: {exc}")-- # Persist everything in one transaction (pages fail loudly, derived- # layers degrade into the collected list) — see _persist_full_update.- from .persistence import _persist_full_update-- _stage(run, "persist")- try:- with timed(timings, "persist"):- db_total_pages = _persist_full_update(- repo_path=repo_path,- repo_name=repo_name,- generated_pages=generated_pages,- file_diffs=file_diffs,- git_meta_map=persisted_git_meta,- new_decision_markers=[*new_decision_markers, *session_decisions],- decision_vector_store=decision_vector_store,- provider=provider,- partial_health_report=partial_health_report,- dead_code_report=dead_code_report,- graph_builder=graph_builder,- knowledge_graph_result=knowledge_graph_result,- degraded=degraded,- doc_drift_report=doc_drift_report,- decay_paths=affected.decay_only,- parsed_files=parsed_files,- source_map=source_map,- git_decay_map=git_decay_map,- full_git_summary=(full_git_summaries[0] if full_git_summaries else None),- reconcile_full_scope=traversal_config_changed,- reconcile_full_generation=generation_config_changed,- require_config_rebuild_success=config_rebuild_required,- require_decision_persist_success=git_config_changed,- history_window_changed=git_config_changed,- timings=timings,- )- except Exception as exc:- if emitter is not None:- emitter.error(str(exc))- raise-- # Periodic idle-file health re-score (#728): git_metadata is now fresh in the- # DB, so re-score every file's findings against the decayed inputs. Reuses- # the already-built graph (no second rebuild); gated to ~weekly. Stamped into- # ``state`` below via the final save_state.- from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION-- from .persistence import full_rescore_due, run_decay_health_rescore-- # ``config_changed`` forces the same re-score off this path's graph rather- # than letting the config branch above run a standalone one and return: a- # config edit invalidates every persisted score, and the partial health- # update only reaches the changed files. Reusing this hook is what makes- # falling through cost nothing extra — the graph is already built.- rescored = False- if health_config_changed or extraction_changed or full_rescore_due(state, head_ts):- with timed(timings, "rescore"):- rescored = run_decay_health_rescore(- repo_path, graph_builder, parsed_files, exclude_patterns- )- if rescored:- # Only the time gate reads this stamp, and it treats a non-numeric- # value as "never re-scored". A forced re-score with git unavailable- # has no timestamp to record, so leave a real stamp alone rather than- # writing None over it.- if head_ts is not None:- state["last_full_rescore_at"] = head_ts- state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION- if health_config_changed and not rescored:- raise RuntimeError(- "Configuration-triggered health re-score failed; the previous "- "fingerprint was retained so the next update retries."- )-- # A scanner version bump means every unchanged file's stored findings may- # be stale (#3072): the normal persist above only rescanned the changed- # files. Does its own full parse, since unlike health there is no stored- # structural fact to replay from the DB for a security finding.- if scanner_changed:- with timed(timings, "security_rescan"):- rescan_security_if_changed(repo_path, state, exclude_patterns)-- # ---- Stored read views, then the editor files that quote them ----- _finish_outcome(repo_path, agents_md, degraded, timings=timings)-- # Update state- from repowise.cli.helpers import config_fingerprint-- if knowledge_graph_result is not None:- try:- from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_json-- save_knowledge_graph_json(repo_path, knowledge_graph_result)- state["knowledge_graph"] = build_kg_state(knowledge_graph_result)- except Exception as exc:- console.print(f"[yellow]Knowledge-graph export skipped: {exc}[/yellow]")- degraded.append(f"Knowledge-graph export: {exc}")-- # Never write a null pointer. ``get_head_commit`` returns None whenever- # ``git rev-parse HEAD`` fails, and erasing a good baseline strands the- # store: the next update reads the null as its base and refuses to run.- # #1507 guarded the same write in ``generate``; these are the rest of it.- if head:- state["last_sync_commit"] = head- state["last_docs_commit"] = head- # Real DB total, not an accumulation: regeneration upserts existing pages,- # so adding len(generated_pages) every run inflated the count forever.- state["total_pages"] = db_total_pages- state["config_fingerprint"] = config_fingerprint(repo_path)- state["config_dependency_fingerprints"] = curr_dependency_fps- state["renderer_fingerprint"] = _current_renderer_fingerprint(repo_path)- # Closed at the state write, as the index-only path does, so the two- # paths' ``run`` rows measure the same span.- timings.stop("run")- state["phase_timings"] = timings.totals- if full_git_summaries:- coverage = getattr(full_git_summaries[0], "history_coverage", None)- if coverage is not None:- state["git_history_coverage"] = coverage.to_dict()- else:- state.pop("git_history_coverage", None)- # Every row was rewritten under the current rules.- state[GIT_HISTORY_VERSION_KEY] = GIT_HISTORY_VERSION- save_state(repo_path, state)-- # --- Pending-marker cleanup --------------------------------------------- # Another `repowise update` (from a post-commit hook) may have written a- # ``.update.pending`` marker while we were generating pages. Drop it now- # that we've caught up; it is only kept when it points to a commit strictly- # newer than the one we just indexed.- consume_update_pending(repo_path, head)-- # Trigger cross-repo hooks if this repo is part of a workspace. The- # workspace docs flow suppresses this per-repo and runs the hooks once- # over every updated repo, so the cross-repo layer isn't rebuilt from a- # half-updated set on every member.- try:- ws_root = find_workspace_root(repo_path) if not skip_cross_repo_hooks else None- if ws_root is not None:- from repowise.core.workspace import WorkspaceConfig- from repowise.core.workspace.update import run_cross_repo_hooks-- ws_config = WorkspaceConfig.load(ws_root)- # Find this repo's alias in the workspace config-- repo_abs = repo_path.resolve()- alias = None- for entry in ws_config.repos:- if (ws_root / entry.path).resolve() == repo_abs:- alias = entry.alias- break- if alias and len(ws_config.repos) >= 2:- console.print("Running cross-repo analysis...")- run_async(run_cross_repo_hooks(ws_config, ws_root, [alias]))- console.print("[green]Cross-repo analysis updated.[/green]")- except Exception as exc:- # Cross-repo hooks must never fail the update, but a stale cross-repo- # layer should not masquerade as a fully clean run.- degraded.append(f"Cross-repo analysis: {exc}")-- elapsed = time.monotonic() - start- _record_update_outcome(- index_only=False,- changed_count=len(file_diffs),- provider=provider,- generated_pages=generated_pages,- )-- def _fail_if_embed_failed() -> None:- if full_stats["embed_failed_pages"]:- from repowise.cli.providers import resolve_embedder-- _fail_on_embed_failure(- repo_path,- resolve_embedder(cfg.get("embedder")),- full_stats["embed_failed_pages"],- emitter,- )-- if emitter is not None:- _fail_if_embed_failed()- emitter.done(- ok=True,- pages_generated=len(generated_pages),- cost_usd=cost_tracker.session_cost,- duration_s=elapsed,- degraded=degraded,- outcome=UpdateOutcome.REGENERATED.value,- )- return UpdateOutcome.REGENERATED- show_full_completion(- generated_pages=generated_pages,- decay_count=len(affected.decay_only),- decisions_changed=len(new_decision_markers) + len(session_decisions) + decisions_evolved,- provider=provider,- cost=cost_tracker.session_cost,- tokens=cost_tracker.session_tokens,- elapsed=elapsed,- degraded=degraded,- )- _render_update_report(generated_pages, affected, new_decision_markers, elapsed, detail=verbose)- _fail_if_embed_failed()- return UpdateOutcome.REGENERATED+ return _docs_update(opts, run)diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/decision_passes.py b/packages/cli/src/repowise/cli/commands/update_cmd/decision_passes.pynew file mode 100644index 000000000..f02f6be1b--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/update_cmd/decision_passes.py@@ -0,0 +1,339 @@+"""The decision passes a docs update runs before regenerating pages.++Each is best-effort and shares one ``decisions`` timing row; a failure lands in+the run's degraded list instead of failing the update.+"""++from __future__ import annotations++import time+from pathlib import Path+from typing import Any++from repowise.cli.helpers import console, run_async+from repowise.core.pipeline import timed++from .incremental import _build_update_vector_store+from .options import DocsPass, UpdateOptions, UpdateRun++# Wider than the update cadence: a late firing is re-judged once later calls exist.+_EFFICACY_LOOKBACK_SECONDS = 7 * 86400.0+++def run_decision_passes(opts: UpdateOptions, run: UpdateRun, docs: DocsPass) -> None:+ """Run every decision pass in order; fills the decision fields of *docs*."""+ run.timings.start("decisions")++ from repowise.core.analysis.decisions.policy import resolve_policy++ policy = resolve_policy(run.cfg).policy++ # A history-window change re-runs git archaeology; its failure must fail the+ # run, or the new fingerprint would suppress the only retry.+ if run.config.git_changed and policy.source_enabled("git_archaeology"):+ _rerun_git_archaeology(run, docs, policy)++ run.timings.start("decisions.rescan")+ _rescan_inline_markers(opts, run, docs, policy)+ run.timings.stop("decisions.rescan")++ run.timings.start("decisions.sessions")+ _run_session_passes(opts, run, docs, policy)+ run.timings.stop("decisions.sessions")++ # Shared by evolution and the decision upsert.+ with timed(run.timings, "decisions.vector_store"):+ docs.decision_vector_store = _build_update_vector_store(+ run.repo_path,+ run.cfg,+ run.degraded,+ required=(run.config.traversal_changed or run.config.generation_changed),+ )++ # Before generation: evolved decisions queue their governed pages for this run.+ run.timings.start("decisions.evolution")+ _evolve_decisions(opts, run, docs)+ run.timings.stop("decisions.evolution")+ run.timings.stop("decisions")+++def _rerun_git_archaeology(run: UpdateRun, docs: DocsPass, policy: Any) -> None:+ try:+ from repowise.core.analysis.decision_extractor import DecisionExtractor++ history_extractor = DecisionExtractor(+ repo_path=run.repo_path,+ provider=docs.provider,+ graph=run.graph_builder.graph(),+ git_meta_map=run.git_meta_map,+ parsed_files=run.parsed_files,+ source_map=run.source_map,+ policy=policy,+ )+ with docs.cost_tracker.record_as("decision_extraction"):+ history_report = run_async(+ history_extractor.extract_all(enabled_sources={"git_archaeology"})+ )+ if history_report.failures:+ details = "; ".join(+ f"{source}: {error}" for source, error in sorted(history_report.failures.items())+ )+ raise RuntimeError(details)+ docs.new_decision_markers.extend(history_report.decisions)+ except Exception as exc:+ raise RuntimeError(+ "Configuration-triggered Git decision extraction failed; the previous "+ "fingerprint was retained so the next update retries."+ ) from exc+++def _rescan_inline_markers(+ opts: UpdateOptions, run: UpdateRun, docs: DocsPass, policy: Any+) -> None:+ try:+ from repowise.core.analysis.decision_extractor import DecisionExtractor++ changed_paths = [fd.path for fd in run.file_diffs if fd.status in ("added", "modified")]+ # Reads uncommitted files on purpose: a marker is source text, not history.+ if changed_paths and policy.source_enabled("inline_marker"):+ extractor = DecisionExtractor(+ repo_path=run.repo_path,+ provider=docs.provider,+ graph=run.graph_builder.graph(),+ git_meta_map=run.git_meta_map,+ policy=policy,+ )+ with docs.cost_tracker.record_as("decision_extraction"):+ docs.new_decision_markers.extend(+ run_async(extractor.scan_inline_markers(restrict_to_files=changed_paths))+ )+ if docs.new_decision_markers and opts.verbose:+ console.print(+ f"New decision markers found: [green]{len(docs.new_decision_markers)}[/green]"+ )+ except Exception as exc:+ _skipped(opts, run, "Decision re-scan", "Decision re-scan skipped", exc)+++def _skipped(opts: UpdateOptions, run: UpdateRun, label: str, verbose_label: str, exc) -> None:+ """Record a best-effort pass that failed, and say so under ``--verbose``."""+ run.degraded.append(f"{label}: {exc}")+ if opts.verbose:+ console.print(f"[yellow]{verbose_label}: {exc}[/yellow]")+++def _run_session_passes(+ opts: UpdateOptions, run: UpdateRun, docs: DocsPass, policy: Any+) -> None:+ # The indexed file set bounds which paths a session-mined record may govern.+ indexed_files = frozenset(run.source_map) if run.source_map else None+ _mine_session_decisions(opts, run, docs, policy, indexed_files)+ # Second: the mining pass is what fills discovery's queue.+ _discover_session_decisions(opts, run, docs, policy, indexed_files)+ _apply_injection_feedback(opts, run, policy)+ _classify_hook_efficacy(opts, run, policy)+++def _mine_session_decisions(+ opts: UpdateOptions, run: UpdateRun, docs: DocsPass, policy: Any, indexed_files+) -> None:+ try:+ from repowise.core.sessions.miners.decisions import mine_session_decisions++ if policy.source_enabled("session"):+ session_provider = docs.provider if policy.llm_allowed("session") else None+ docs.session_decisions = run_async(+ mine_session_decisions(+ run.repo_path,+ provider=session_provider,+ harnesses=policy.harnesses,+ collect_discovery_spans=policy.llm_allowed("session_discovery"),+ indexed=indexed_files,+ )+ )+ if docs.session_decisions and opts.verbose:+ promoted_titles = {d.title for d in docs.session_decisions}+ console.print(f"Session decisions promoted: [green]{len(promoted_titles)}[/green]")+ except Exception as exc:+ _skipped(opts, run, "Session decision mining", "Session decision mining skipped", exc)+++def _discover_session_decisions(+ opts: UpdateOptions, run: UpdateRun, docs: DocsPass, policy: Any, indexed_files+) -> None:+ try:+ from repowise.core.analysis.decisions.discovery import run_update_discovery++ with docs.cost_tracker.record_as("decision_extraction"):+ outcome = run_async(+ run_update_discovery(+ run.repo_path,+ provider=docs.provider,+ policy=policy,+ indexed=indexed_files,+ )+ )+ docs.session_decisions = [*docs.session_decisions, *outcome.decisions]+ if outcome.report.status == "failed":+ run.degraded.append(f"Session discovery: {outcome.report.reason}")+ if opts.verbose:+ funnel = outcome.report+ console.print(+ f"Session discovery: {funnel.status}"+ + (f" ({funnel.reason})" if funnel.reason else "")+ + f" · {funnel.calls} call(s) · {funnel.candidates_grounded} grounded"+ + f" · {funnel.spans_deferred} span(s) queued"+ )+ except Exception as exc:+ _skipped(opts, run, "Session discovery", "Session discovery skipped", exc)+++def _apply_injection_feedback(opts: UpdateOptions, run: UpdateRun, policy: Any) -> None:+ """Judge injected decisions against their sessions' corrections (no model)."""+ # Gated on the session lane: its mined corrections are the only evidence, and+ # an evaluation is terminal, so judging with the lane off would settle every+ # row as unjudgeable for good.+ try:+ from repowise.core.sessions.miners.decisions import apply_injection_feedback++ if policy.source_enabled("session"):+ feedback = run_async(_injection_feedback(run.repo_path, apply_injection_feedback))+ if opts.verbose and (feedback.get("followed") or feedback.get("contradicted")):+ console.print(+ f"Injected-decision feedback: [green]{feedback.get('followed', 0)} "+ f"followed[/green], [yellow]{feedback.get('contradicted', 0)} "+ "contradicted[/yellow]"+ )+ except Exception as exc:+ _skipped(opts, run, "Injection feedback", "Injection feedback skipped", exc)+++async def _injection_feedback(repo_path: Path, apply_injection_feedback) -> dict:+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_repository,+ )++ url = get_db_url_for_repo(repo_path)+ engine = create_engine(url)+ await init_db(engine)+ sf = create_session_factory(engine)+ async with get_session(sf) as session:+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))+ res = await apply_injection_feedback(session, repo.id, repo_path)+ await engine.dispose()+ return res+++def _classify_hook_efficacy(opts: UpdateOptions, run: UpdateRun, policy: Any) -> None:+ """Classify hook firings by what the agent did next (reads transcripts)."""+ # The session lane is the privacy boundary for reading transcripts, so this+ # fails closed; `repowise hook backfill` fills the columns on demand.+ try:+ from repowise.core.sessions.efficacy import ingest_transcript_efficacy++ if policy.source_enabled("session"):+ classified = ingest_transcript_efficacy(+ run.repo_path, since=time.time() - _EFFICACY_LOOKBACK_SECONDS+ )+ if opts.verbose and classified:+ console.print(f"Hook firings classified: [green]{sum(classified.values())}[/green]")+ except Exception as exc:+ _skipped(opts, run, "Hook efficacy", "Hook efficacy classification skipped", exc)+++def _evolve_decisions(opts: UpdateOptions, run: UpdateRun, docs: DocsPass) -> None:+ try:+ evo = _run_decision_evolution(+ run.repo_path,+ run.file_diffs,+ run.git_meta_map,+ base_ref=run.base_ref,+ head=run.head,+ provider=docs.provider,+ cost_tracker=docs.cost_tracker,+ max_concurrency=docs.config.max_concurrency,+ )+ if evo is not None:+ _apply_evolution(opts, run, docs, evo)+ except Exception as exc:+ _skipped(opts, run, "Decision evolution", "Decision evolution skipped", exc)+++def _apply_evolution(opts: UpdateOptions, run: UpdateRun, docs: DocsPass, evo: dict) -> None:+ docs.decisions_evolved = (+ evo.get("superseded", 0) + evo.get("amended", 0) + evo.get("reaffirmed", 0)+ )+ evo_regen = evo.get("regen_files") or set()+ if not evo_regen:+ return+ # A file page's id is its path.+ affected = run.affected+ affected.regenerate = list(dict.fromkeys([*affected.regenerate, *sorted(evo_regen)]))+ if opts.verbose:+ console.print(+ f"Decision evolution: [cyan]{evo.get('superseded', 0)} superseded[/cyan], "+ f"[cyan]{evo.get('amended', 0)} amended[/cyan], "+ f"[green]{evo.get('reaffirmed', 0)} reaffirmed[/green]; "+ f"+{len(evo_regen)} governed page(s) queued for regen."+ )+++def _run_decision_evolution(+ repo_path: Path,+ file_diffs: list,+ git_meta_map: dict,+ *,+ base_ref: str,+ head: str | None,+ provider: Any,+ cost_tracker: Any,+ max_concurrency: int,+) -> dict | None:+ """Run decision evolution over ``base_ref..head``, or ``None`` with no changed file."""+ changed_set = {fd.path for fd in file_diffs if fd.status in ("added", "modified")}+ if not changed_set:+ return None++ from repowise.core.analysis.decision_evolution import (+ commits_in_range,+ run_update_evolution,+ update_evidence_by_file,+ )++ evidence_by_file = update_evidence_by_file(+ file_diffs, git_meta_map, commits_in_range(repo_path, base_ref, head)+ )++ async def _run() -> dict:+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_repository,+ )++ engine = create_engine(get_db_url_for_repo(repo_path))+ await init_db(engine)+ sf = create_session_factory(engine)+ async with get_session(sf) as session:+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))+ res = await run_update_evolution(+ session,+ repo.id,+ changed_files=changed_set,+ evidence_by_file=evidence_by_file,+ provider=provider,+ max_concurrency=max_concurrency,+ )+ await engine.dispose()+ return res++ with cost_tracker.record_as("decision_extraction"):+ return run_async(_run())diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/options.py b/packages/cli/src/repowise/cli/commands/update_cmd/options.pyindex 6c364fa0d..a6dc2a4a9 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/options.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/options.py@@ -91,3 +91,21 @@ class UpdateRun:doc_drift_report: Any = Nonepersisted_git_meta: Any = Noneknowledge_graph_result: Any = None+++@dataclass+class DocsPass:+ """State of the model-backed half of a docs update."""++ config: Any+ provider: Any+ cost_tracker: Any+ new_decision_markers: list = field(default_factory=list)+ session_decisions: list = field(default_factory=list)+ # Decision records touched by evolution, surfaced in the completion panel.+ decisions_evolved: int = 0+ decision_vector_store: Any = None+ prior_pages: dict = field(default_factory=dict)+ generated_pages: list = field(default_factory=list)+ full_stats: dict = field(default_factory=dict)+ db_total_pages: int = 0diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/page_generation.py b/packages/cli/src/repowise/cli/commands/update_cmd/page_generation.pynew file mode 100644index 000000000..5f99c94a6--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/update_cmd/page_generation.py@@ -0,0 +1,203 @@+"""Page regeneration for a docs update: the generator run and its progress."""++from __future__ import annotations++from collections.abc import Callable+from contextlib import nullcontext+from typing import Any++from repowise.cli.helpers import run_async+from repowise.core.pipeline import timed++from .options import DocsPass, UpdateOptions, UpdateRun+from .reporting import make_generation_progress+++def _generation_warning_handler(+ degraded: list[str], *, require_embedding_success: bool+) -> Callable[[str], None]:+ """Record generation warnings and make required embedding writes fatal."""++ def _handle(message: str) -> None:+ degraded.append(message)+ if require_embedding_success:+ raise RuntimeError(+ "Configuration-triggered page embedding failed; the previous "+ "fingerprint was retained so the next update retries."+ )++ return _handle+++class _PageProgress:+ """Live progress for generate_all: a bar in rich mode, JSON events otherwise."""++ def __init__(self, emitter: Any, cost_tracker: Any) -> None:+ self.emitter = emitter+ self.cost_tracker = cost_tracker+ self.completed = 0+ self.total: int | None = None+ self.bar: Any = None+ self.task: Any = None++ def on_total_known(self, total: int) -> None:+ self.total = total+ if self.emitter is not None:+ self.emitter.total_known(total)+ else:+ self.bar.update(self.task, total=total)++ def on_page_done(self, _page_id: str) -> None:+ self.completed += 1+ # The total is an estimate; keep it at least the real count.+ if self.total is not None and self.completed > self.total:+ self.total = self.completed+ if self.emitter is not None:+ self.emitter.page_done(+ completed=self.completed,+ total=self.total,+ cost_usd=self.cost_tracker.session_cost,+ )+ else:+ self.bar.update(+ self.task, advance=1, total=self.total, cost=self.cost_tracker.session_cost+ )+++def generate_pages(opts: UpdateOptions, run: UpdateRun, docs: DocsPass) -> None:+ """Regenerate the affected pages, checkpointing each one as it lands."""+ from repowise.core.generation import ContextAssembler, PageGenerator++ regen_set = set(run.affected.regenerate)+ affected_parsed = [pf for pf in run.parsed_files if pf.file_info.path in regen_set]+ affected_source = {p: s for p, s in run.source_map.items() if p in regen_set}++ docs.prior_pages = _load_prior_pages(run)++ # Without the vector store, regenerated pages drop out of semantic search.+ repo_path = run.repo_path+ config = docs.config+ assembler = ContextAssembler(config, repo_path=repo_path)+ generator = PageGenerator(+ docs.provider,+ assembler,+ config,+ vector_store=docs.decision_vector_store,+ language=config.language,+ prior_pages=docs.prior_pages,+ repo_path=repo_path,+ )+ repo_name = repo_path.name++ if run.emitter is not None:+ run.emitter.stage("generate")++ progress = _PageProgress(run.emitter, docs.cost_tracker)++ # Each page is persisted as it lands, so a rerun after a crash re-bills nothing.+ from .persistence import PageCheckpointer++ checkpointer = PageCheckpointer(repo_path, repo_name)++ async def _generate_with_checkpoint() -> list:+ await checkpointer.start()+ try:+ return await generator.generate_all(+ affected_parsed,+ affected_source,+ run.graph_builder,+ run.repo_structure,+ repo_name,+ on_page_done=progress.on_page_done,+ on_total_known=progress.on_total_known,+ git_meta_map=run.git_meta_map,+ repo_path=repo_path,+ on_page_ready=checkpointer.on_page_ready,+ on_warning=_generation_warning_handler(+ run.degraded,+ require_embedding_success=(+ run.config.traversal_changed or run.config.generation_changed+ ),+ ),+ )+ finally:+ await checkpointer.close()++ with make_generation_progress() if run.emitter is None else nullcontext() as gen_progress:+ progress.bar = gen_progress+ progress.task = (+ gen_progress.add_task("Generating pages...", total=None, cost=0.0)+ if gen_progress is not None+ else None+ )++ try:+ with timed(run.timings, "generate"):+ docs.generated_pages = run_async(_generate_with_checkpoint())+ except Exception as exc:+ if run.emitter is not None:+ run.emitter.error(str(exc))+ raise++ # Snap the estimate to the real count so the bar ends at N of N.+ if progress.task is not None:+ gen_progress.update(progress.task, total=progress.completed, completed=progress.completed)++ docs.full_stats = {"embed_failed_pages": generator.embed_failed_pages}+ if checkpointer.failure:+ run.degraded.append(f"Per-page crash checkpointing: {checkpointer.failure}")+++def _load_prior_pages(run: UpdateRun) -> dict[str, object]:+ """Prior pages, so an unchanged prompt hash skips the model call."""+ repo_path = run.repo_path++ async def _load_prior() -> dict[str, object]:+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ load_prior_pages,+ upsert_repository,+ )++ url = get_db_url_for_repo(repo_path)+ engine = create_engine(url)+ sf = create_session_factory(engine)+ async with get_session(sf) as session:+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))+ return await load_prior_pages(session, repo.id)++ try:+ return run_async(_load_prior())+ except Exception as exc:+ run.degraded.append(f"Prior-page reuse: {exc}")+ return {}+++def render_stale_structure(opts: UpdateOptions, run: UpdateRun, docs: DocsPass) -> None:+ """Re-render stale structural pages from the full graph (no model calls)."""+ if not run.stale_deterministic_ids or run.config.generation_changed:+ return+ from .deterministic import regenerate_deterministic_page_ids++ with timed(run.timings, "render.structure"):+ docs.generated_pages.extend(+ regenerate_deterministic_page_ids(+ repo_path=run.repo_path,+ parsed_files=run.parsed_files,+ source_map=run.source_map,+ graph_builder=run.graph_builder,+ repo_structure=run.repo_structure,+ git_meta_map=run.git_meta_map,+ page_ids=run.stale_deterministic_ids,+ cfg=run.cfg,+ concurrency=opts.concurrency,+ degraded=run.degraded,+ dead_code_report=run.dead_code_report,+ prior_page_ids=docs.prior_pages,+ vector_store=docs.decision_vector_store,+ stats_out=docs.full_stats,+ )+ )diff --git a/tests/unit/cli/test_editor_setup.py b/tests/unit/cli/test_editor_setup.pyindex 0546ca65a..1019c9f25 100644--- a/tests/unit/cli/test_editor_setup.py+++ b/tests/unit/cli/test_editor_setup.py@@ -1225,7 +1225,7 @@ def test_claude_refresh_project_files_skips_when_options_disable_file(def test_update_command_uses_editor_refresh_abstraction() -> None:from repowise.cli.commands.update_cmd.command import _finish_outcome, _refresh_editor_stamp- command_source = inspect.getsource(run_update)+ command_source = inspect.getsource(inspect.getmodule(run_update))finish_source = inspect.getsource(_finish_outcome)stamp_source = inspect.getsource(_refresh_editor_stamp)