generated from coulomb/repo-seed
88 lines
3.7 KiB
Markdown
88 lines
3.7 KiB
Markdown
# 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.
|