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.

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.