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.

refactor(pipeline): stage decision extraction into session mining and source reporting (#4081)

Raghav Chamadiyaabe12246246e
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index f6aeeb623..968a61ad5 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -422,153 +422,27 @@ async def _run_decision_extraction(
timeout=DECISION_EXTRACTION_TIMEOUT_SECS,
)
- # Session-sourced decisions: a repo indexed for the first time on a
- # machine with existing agent-session history gets them at init, not
- # only from the first update. Appended after extract_all's substring
- # gate on purpose: the miner enforces its own grounding contract, and
- # re-gating without a source_text would wipe its verification. A
- # server-side index has no transcript directory and no-ops here.
- try:
- from repowise.core.sessions.miners.decisions import mine_session_decisions
-
- # Not gated on a provider: the same pass records transcript
- # episodes, which need no model, and gating the read on a key
- # would leave a keyless index with no transcript supply at all.
- # The miner skips its own structuring pass when provider is None,
- # which is also how the policy's LLM switch is enforced here.
- if policy.source_enabled("session"):
- session_provider = llm_client if policy.llm_allowed("session") else None
- session_decisions = await asyncio.wait_for(
- mine_session_decisions(
- repo_path,
- provider=session_provider,
- harnesses=policy.harnesses,
- collect_discovery_spans=policy.llm_allowed("session_discovery"),
- indexed=indexed,
- ),
- timeout=DECISION_EXTRACTION_TIMEOUT_SECS,
- )
- if session_decisions:
- report.decisions.extend(session_decisions)
- report.by_source["session"] = len(session_decisions)
- report.total_found = len(report.decisions)
- except Exception as exc:
- if progress:
- progress.on_message("warning", f"Session decision mining skipped: {exc}")
-
- # The broad lane, after the miner because the miner's single read is
- # what filled its span queue. At most one call, and it reports its own
- # zero so a switched-off source never reads as an empty repository.
+ await _add_session_decisions(
+ repo_path,
+ llm_client=llm_client,
+ policy=policy,
+ report=report,
+ indexed=indexed,
+ progress=progress,
+ )
+ # After the miner: its single read is what filled the discovery span queue.
discovery = await _run_session_discovery(
repo_path, llm_client=llm_client, policy=policy, report=report, indexed=indexed
)
-
if progress:
- # Only the sources that actually found something. On a typical
- # first index most of these are zero, and the line read as
- # "0 ADR · 0 changelog · 0 PR ·" with the real numbers buried.
- bs = report.by_source
- found = [
- f"{bs[source]} {label}"
- for source, label in _DECISION_SOURCE_LABELS
- if bs.get(source)
- ]
- summary = ", ".join(found) if found else ""
- # The per-source counts are taken before the evidence gate and the
- # total after it, so "5 found: 13 from git history, 3 from
- # comments" did not add up. Say which number is which.
- candidates = sum(bs.values())
- headline = (
- f"→ {report.total_found} architectural decisions kept from "
- f"{candidates} candidates"
- if candidates > report.total_found
- else f"→ {report.total_found} architectural decisions found"
+ _report_decision_sources(
+ progress,
+ report,
+ policy=policy,
+ enabled=enabled,
+ discovery=discovery,
+ provider_available=llm_client is not None,
)
- progress.on_message("info", headline + (f": {summary}" if summary else ""))
- # And the sources that produced nothing. Hiding these was what made
- # a source failing outright indistinguishable from a source with
- # honestly nothing to find: every failure inside the extractor is
- # swallowed and reported only through ``logger.warning``, which no
- # default CLI run renders. A repo with no ADR files legitimately
- # scores zero there, so this is not itself a failure report — it is
- # the list you need to have before you can tell the two apart.
- # The labels read "from git history" because they are normally
- # rendered as "5 from git history"; strung together after one
- # "No decisions" they would read "No decisions from inline
- # markers, from ADR files". Drop the preposition and name the
- # sources plainly.
- #
- # ``session`` is in the label table but is not one of the
- # extractor's own sources, so ``source in enabled`` leaves it out
- # of this list — correct, since it is mined separately below.
- #
- # A source that *failed* is listed separately and as a warning.
- # It is not "nothing found": the repo may be full of decisions
- # nobody could read. Same shape the update path already uses for
- # its ``degraded`` list, so both runs report an outage the same
- # way instead of one of them printing a reassuring zero.
- failures = dict(getattr(report, "failures", {}) or {})
- if discovery.report.status == "failed":
- failures["session_discovery"] = discovery.report.reason
- # Sources that never ran, and why. Built first because a source
- # listed here must not also appear as an honest zero below: with no
- # API key the three model-only sources return [] immediately, and
- # reporting that as "nothing found" is the confusion this split
- # exists to remove.
- runtime = {
- rt.key: rt
- for rt in policy.runtime(provider_available=llm_client is not None)
- }
- not_run = {
- key
- for key, rt in runtime.items()
- if rt.togglable and rt.status in ("disabled", "skipped_no_provider")
- }
- # Broad discovery is not one of the extractor's sources, so it
- # would fall out of all three lists on ``source in enabled`` alone.
- # It is always considered, so it lands in exactly one of them. Its
- # own reason overrides the policy's, being the more specific of the
- # two ("no new prose since the last update" is not "switched off").
- considered = set(enabled) | {DISCOVERY_SOURCE}
- if discovery.report.status in ("not_run", "skipped_no_provider"):
- not_run.add(DISCOVERY_SOURCE)
- if discovery.report.reason:
- runtime[DISCOVERY_SOURCE] = replace(
- runtime[DISCOVERY_SOURCE], reason=discovery.report.reason
- )
- # A grounded candidate is a finding even though promotion waits for
- # a second sighting, so discovery is not empty on the run that
- # first finds something.
- staged = discovery.report.candidates_grounded
- empty = [
- label.removeprefix("from ")
- for source, label in _DECISION_SOURCE_LABELS
- if source in considered
- and source not in not_run
- and not bs.get(source)
- and source not in failures
- and not (source == DISCOVERY_SOURCE and staged)
- ]
- if staged:
- progress.on_message(
- "info", f"→ {staged} session-discovery candidate(s) staged for review"
- )
- if empty:
- progress.on_message("info", f"→ Nothing found in: {', '.join(empty)}")
- for source, label in _DECISION_SOURCE_LABELS:
- if source in failures:
- progress.on_message(
- "warning",
- f"Decision source {label.removeprefix('from ')} failed, "
- f"so this run found none there: {failures[source]}",
- )
- skipped = [
- f"{label.removeprefix('from ')} ({runtime[source].reason.rstrip('.')})"
- for source, label in _DECISION_SOURCE_LABELS
- if source in not_run
- ]
- if skipped:
- progress.on_message("info", f"→ Not run: {', '.join(skipped)}")
_phase_done(progress, "decisions")
return report
@@ -577,3 +451,148 @@ async def _run_decision_extraction(
progress.on_message("warning", f"Decision extraction skipped: {exc}")
_phase_done(progress, "decisions")
return None
+
+
+async def _add_session_decisions(
+ repo_path: Path,
+ *,
+ llm_client: Any | None,
+ policy: Any,
+ report: Any,
+ indexed: Container[str] | None,
+ progress: ProgressCallback | None,
+) -> None:
+ """Append agent-session decisions to *report*; a mining failure only warns.
+
+ Appended after ``extract_all``'s substring gate on purpose: the miner enforces
+ its own grounding contract. Not gated on a provider, since the same pass
+ records transcript episodes; the miner skips its model pass when it has none.
+ """
+ try:
+ from repowise.core.sessions.miners.decisions import mine_session_decisions
+
+ if policy.source_enabled("session"):
+ session_provider = llm_client if policy.llm_allowed("session") else None
+ session_decisions = await asyncio.wait_for(
+ mine_session_decisions(
+ repo_path,
+ provider=session_provider,
+ harnesses=policy.harnesses,
+ collect_discovery_spans=policy.llm_allowed("session_discovery"),
+ indexed=indexed,
+ ),
+ timeout=DECISION_EXTRACTION_TIMEOUT_SECS,
+ )
+ if session_decisions:
+ report.decisions.extend(session_decisions)
+ report.by_source["session"] = len(session_decisions)
+ report.total_found = len(report.decisions)
+ except Exception as exc:
+ if progress:
+ progress.on_message("warning", f"Session decision mining skipped: {exc}")
+
+
+def _report_decision_sources(
+ progress: ProgressCallback,
+ report: Any,
+ *,
+ policy: Any,
+ enabled: Any,
+ discovery: DiscoveryOutcome,
+ provider_available: bool,
+) -> None:
+ """Say per source what was found, found nothing, failed, or never ran.
+
+ The four are kept apart so a failed or switched-off source never reads as an
+ honest zero.
+ """
+ bs = report.by_source
+ progress.on_message("info", _decision_headline(report))
+ failures = dict(getattr(report, "failures", {}) or {})
+ if discovery.report.status == "failed":
+ failures["session_discovery"] = discovery.report.reason
+ runtime, not_run = _decision_sources_not_run(policy, discovery, provider_available)
+ # ``session`` is mined outside the extractor, so it is never listed as empty.
+ considered = set(enabled) | {DISCOVERY_SOURCE}
+ # A grounded candidate is a finding even before a second sighting promotes it.
+ staged = discovery.report.candidates_grounded
+ empty = [
+ label.removeprefix("from ")
+ for source, label in _DECISION_SOURCE_LABELS
+ if source in considered
+ and _found_nothing(source, bs, not_run=not_run, failures=failures, staged=staged)
+ ]
+ if staged:
+ progress.on_message(
+ "info", f"→ {staged} session-discovery candidate(s) staged for review"
+ )
+ if empty:
+ progress.on_message("info", f"→ Nothing found in: {', '.join(empty)}")
+ for source, label in _DECISION_SOURCE_LABELS:
+ if source in failures:
+ progress.on_message(
+ "warning",
+ f"Decision source {label.removeprefix('from ')} failed, "
+ f"so this run found none there: {failures[source]}",
+ )
+ skipped = [
+ f"{label.removeprefix('from ')} ({runtime[source].reason.rstrip('.')})"
+ for source, label in _DECISION_SOURCE_LABELS
+ if source in not_run
+ ]
+ if skipped:
+ progress.on_message("info", f"→ Not run: {', '.join(skipped)}")
+
+
+def _found_nothing(
+ source: str, by_source: Any, *, not_run: set[str], failures: dict, staged: Any
+) -> bool:
+ """True when *source* ran, did not fail, and found nothing (staged discovery counts)."""
+ return (
+ source not in not_run
+ and not by_source.get(source)
+ and source not in failures
+ and not (source == DISCOVERY_SOURCE and staged)
+ )
+
+
+def _decision_headline(report: Any) -> str:
+ """Kept-vs-candidate totals plus the sources that found something.
+
+ Per-source counts are taken before the evidence gate and the total after it,
+ so the line names which number is which.
+ """
+ bs = report.by_source
+ found = [f"{bs[source]} {label}" for source, label in _DECISION_SOURCE_LABELS if bs.get(source)]
+ summary = ", ".join(found) if found else ""
+ candidates = sum(bs.values())
+ headline = (
+ f"→ {report.total_found} architectural decisions kept from "
+ f"{candidates} candidates"
+ if candidates > report.total_found
+ else f"→ {report.total_found} architectural decisions found"
+ )
+ return headline + (f": {summary}" if summary else "")
+
+
+def _decision_sources_not_run(
+ policy: Any, discovery: DiscoveryOutcome, provider_available: bool
+) -> tuple[dict[str, Any], set[str]]:
+ """Runtime status per source and the togglable sources that never ran.
+
+ Broad discovery is always considered; its own reason overrides the policy's
+ as the more specific one.
+ """
+ runtime = {rt.key: rt for rt in policy.runtime(provider_available=provider_available)}
+ not_run = {
+ key
+ for key, rt in runtime.items()
+ if rt.togglable and rt.status in ("disabled", "skipped_no_provider")
+ }
+ if discovery.report.status in ("not_run", "skipped_no_provider"):
+ not_run.add(DISCOVERY_SOURCE)
+ if discovery.report.reason:
+ runtime[DISCOVERY_SOURCE] = replace(
+ runtime[DISCOVERY_SOURCE], reason=discovery.report.reason
+ )
+ return runtime, not_run