repo-scoping/docs/dependency-aware-scope-propagation.md

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:

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.