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