repo-scoping/workplans/RREG-WP-0008-dependency-aware-scope-propagation.md

---
id: RREG-WP-0008
type: workplan
title: "Dependency-Aware Scope Propagation"
domain: capabilities
repo: repo-scoping
status: done
owner: codex
topic_slug: foerster-capabilities
created: "2026-05-01"
updated: "2026-05-03"
state_hub_workstream_id: "81ec50c4-fe73-41ea-ba5b-2e02be2bed42"
---

# Dependency-Aware Scope Propagation

This workplan explores and implements a spreadsheet-inspired dependency model
for repo-scoping. Facts, evidence, features, capabilities, abilities, and scope
can be treated as interdependent cells in a conceptual graph: when source facts
or lower-level characteristics change, dependent characteristics can be marked
stale, recalculated, or queued for human review.

The goal is not to force every repository into a brittle fully-derived model.
Instead, repo-scoping should distinguish between observed inputs, derived claims,
manual curator decisions, and mixed claims whose confidence depends on both
machine-observed evidence and human judgment.

## Motivation

Repository understanding changes over time. A new route, package, test suite,
configuration file, README section, CLI command, or removed module may affect a
feature directly, a capability indirectly, and an ability or scope only when the
change is conceptually important. Tracking that propagation can make updates
faster, safer, and more explainable.

The propagation rate itself is valuable: repositories where many low-level fact
changes constantly force top-level scope changes may be conceptually immature,
poorly decomposed, or still in rapid product discovery. Repositories where
changes stay local may have a more stable conceptual model.

## Model Dependency Graph

```task
id: RREG-WP-0008-T01
status: done
priority: high
state_hub_task_id: "a7a6080e-a78b-447b-a3a9-0a575f882578"
```

Design a dependency graph that can link facts, evidence, features, capabilities,
abilities, and scope. Capture dependency type, direction, strength, source, and
whether the target is deterministic, curator-owned, or mixed.

Acceptance criteria:
- A documented model explains dependency edges and ownership semantics.
- Same-layer dependencies are allowed but flagged as normalization signals.
- Scope remains the single root characteristic.

## Change Impact Analysis

```task
id: RREG-WP-0008-T02
status: done
priority: high
state_hub_task_id: "0f00ffaf-5685-4327-bb93-b5c78bc97bd1"
```

Compare analysis runs and approved characteristic revisions to identify which
higher-level characteristics are affected by changed facts or changed child
characteristics.

Acceptance criteria:
- Changed facts can produce an impact list of potentially stale evidence,
  features, capabilities, abilities, and scope.
- Impact output explains why each item was affected.
- Unchanged upstream claims are explicitly distinguishable from claims requiring
  review.

## Recalculation And Review Workflow

```task
id: RREG-WP-0008-T03
status: done
priority: high
state_hub_task_id: "29a85e0a-7203-484c-aa5d-94096ab695a9"
```

Define and implement a review workflow for downstream recalculation. Some values
may be automatically updated, while higher-level or curator-owned claims should
be marked stale and presented for approval.

Acceptance criteria:
- Characteristics can carry freshness or staleness state.
- The UI shows impacted items and recommended actions.
- Curators can accept recalculated text, keep the previous claim, or edit it.

## Propagation Metrics

```task
id: RREG-WP-0008-T04
status: done
priority: medium
state_hub_task_id: "99cab29a-d51a-4709-b08c-46414bab8053"
```

Track propagation depth and breadth as signals about conceptual maturity and
model stability.

Acceptance criteria:
- Analysis summaries report how far fact changes bubbled up.
- Repository-level metrics distinguish local churn from scope-level churn.
- Documentation explains how propagation rate should be interpreted cautiously.

## UI Drilldown

```task
id: RREG-WP-0008-T05
status: done
priority: medium
state_hub_task_id: "02147d64-d339-40e2-b88d-406567bfa366"
```

Expose dependency and impact information in the UI as a drilldown from scope to
facts and as an impact view from changed facts upward.

Acceptance criteria:
- Users can inspect why a characteristic is considered current or stale.
- Users can navigate from a changed fact to affected features, capabilities,
  abilities, and scope.
- Evidence remains the bridge between observed facts and interpreted claims.

## Interactive Dependency Graph Visualization

```task
id: RREG-WP-0008-T07
status: done
priority: medium
state_hub_task_id: "a1f57c22-017b-43ef-99b4-99c10a6bccd5"
```

Provide an interactive visualization of the dependency graph so users can inspect
fact-to-scope propagation paths, same-layer normalization signals, stale nodes,
and review recommendations.

Acceptance criteria:
- Users can pan, zoom, and select dependency graph nodes.
- Node styling distinguishes facts, evidence, features, capabilities, abilities,
  and the root scope.
- Edge styling distinguishes dependency type, strength, and same-layer
  normalization signals.
- Users can switch between full graph, impact-only, and selected-path views.
- The implementation framework choice is documented with tradeoffs before UI
  implementation starts in
  `docs/adr-dependency-graph-visualization-framework.md`.

## Documentation And Terminology

```task
id: RREG-WP-0008-T06
status: done
priority: medium
state_hub_task_id: "44b0b992-da74-45b0-970a-2f3786ac3b31"
```

Document dependency-aware scoping as a core concept, including spreadsheet
analogy, derived claims, curator-owned claims, mixed claims, staleness, and
propagation metrics.

Acceptance criteria:
- `docs/terminology.md` defines dependency, staleness, recalculation, and
  propagation rate.
- A design note explains how deterministic and optional LLM-assisted updates fit
  into the dependency model.