# Dependency-Aware Scope Propagation

Repository Scoping treats the approved map as a spreadsheet-like dependency
graph. Observed facts are input cells. Evidence and features are local formulas
or reviewable links. Capabilities, abilities, and scope are higher-level claims
that may be curator-owned, mixed, or derived from lower-level support.

## Graph Model

The graph is directed upward toward the single scope root:

```text
observed fact -> evidence/feature -> capability -> ability -> scope
```

Each edge records:

- dependency type, such as `observes`, `supports`, `realizes`, or `summarizes`
- strength, usually copied from evidence strength where available
- source, such as `source_ref`, `approved_evidence`, or
  `approved_characteristic`
- target ownership: `deterministic`, `mixed`, or `curator_owned`
- same-layer flag, used when one capability points at another capability or a
  similar normalization signal appears

Same-layer edges are allowed because real repositories often contain cross-cutting
support. They should still be visible to reviewers because too many same-layer
edges can mean the abstraction levels need cleanup.

## Impact Analysis

Impact analysis compares two analysis runs, collects changed observed facts, and
walks the dependency graph upward. A changed dependency marks downstream items
`stale` and records a reason chain that explains the path from the fact to the
affected characteristic.

Recommended actions are derived from ownership:

- deterministic targets can be recalculated
- mixed and curator-owned targets require review before approved truth changes

The current implementation exposes this through `RegistryService`:

- `build_dependency_graph(repository_id)`
- `analyze_dependency_impact(repository_id, base_run_id, target_run_id)`

The impact result includes changed fact keys, impacted items, reason chains,
maximum propagation depth, breadth, and whether the root scope was affected.

## Review Workflow

The change-review UI shows dependency impact alongside ordinary run diffs. Each
impacted item carries a freshness state, reason chain, propagation depth, and a
recommended action. Curators can accept recalculated candidate text by approving
the target run, keep prior approved claims by leaving the change unapproved, or
edit approved characteristics through the existing manual registry forms.

## Interactive Visualization

The accepted implementation framework for the interactive graph view is
Cytoscape.js. See
`docs/adr-dependency-graph-visualization-framework.md` for the decision and the
tradeoffs against React Flow, D3, and Mermaid.

The first UI implementation exposes `/repos/{repository_id}/dependency-graph`
as a Cytoscape-ready JSON payload and `/ui/repos/{repository_id}/dependency-graph`
as the graph page. The page supports full graph, impact-only, and selected-path
views with a detail panel for selected nodes and edges.

The expanded exploration model is documented in
`docs/dependency-visualization-exploration.md`, including layers, display
states, filter rules, manual overrides, and repository-scoped view profiles.

## Metrics

Propagation depth says how far a source change bubbled up. Propagation breadth
says how many approved items were touched. Scope-level churn is especially
important, but it should be interpreted cautiously: it can reflect healthy
product discovery, an overly broad scope statement, or missing intermediate
characteristics.

## LLM Assistance

Optional LLM-assisted updates can propose recalculated text for stale mixed or
curator-owned characteristics. Those proposals remain candidates until reviewed.
Deterministic scanners still own observed facts, and approved characteristics
remain the registry truth until a curator accepts a replacement.