Build dependency graph and dependency aware propagation of changes

docs/dependency-aware-scope-propagation.md

@@ -0,0 +1,63 @@
+# 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.

docs/terminology.md

@@ -93,6 +93,18 @@ normalization.
   than disappearing.
 - Classification: a main type plus optional additional attributes that help
   users filter and orient without forcing every item into a single rigid box.
+- Dependency: a directed edge showing that one fact or characteristic affects
+  another. Edges record type, strength, source, ownership, and whether the edge
+  stays within the same layer.
+- Staleness: a freshness state assigned when an upstream dependency changes and
+  a downstream characteristic may no longer be current.
+- Recalculation: an automated refresh of deterministic or mixed derived content
+  after upstream changes. Curator-owned claims should be reviewed before the new
+  value becomes approved registry truth.
+- Propagation rate: the breadth and depth of downstream impact from changed
+  inputs. High propagation can indicate rapid discovery, weak normalization, or
+  brittle conceptual boundaries; it is a signal for review, not a score by
+  itself.
 
 ## Extraction Philosophy