diff --git a/workplans/RREG-WP-0008-dependency-aware-scope-propagation.md b/workplans/RREG-WP-0008-dependency-aware-scope-propagation.md new file mode 100644 index 0000000..2a4c544 --- /dev/null +++ b/workplans/RREG-WP-0008-dependency-aware-scope-propagation.md @@ -0,0 +1,149 @@ +--- +id: RREG-WP-0008 +type: workplan +title: "Dependency-Aware Scope Propagation" +domain: capabilities +repo: repo-scoping +status: active +owner: codex +topic_slug: foerster-capabilities +created: "2026-05-01" +updated: "2026-05-01" +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: todo +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: todo +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: todo +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: todo +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: todo +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. + +## Documentation And Terminology + +```task +id: RREG-WP-0008-T06 +status: todo +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.