# 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.

## 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.