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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RREG-WP-0008	workplan	Dependency-Aware Scope Propagation	capabilities	repo-scoping	done	codex	foerster-capabilities	2026-05-01	2026-05-03	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

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

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

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

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

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

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

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.