feat(#1954): flag undeclared coupling between same-wave plans (#3237)

* test(#1954): failing-first contract for plan-checker undeclared-coupling check

* feat(#1954): flag undeclared coupling between same-wave plans

* docs(#1954): backfill changeset pr number

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-09 10:35:27 -04:00
committed by GitHub
parent 70e50eb1b2
commit c75ce93be9
6 changed files with 359 additions and 10 deletions

View File

@@ -210,6 +210,42 @@ issue:
fix_hint: "Plan 02 depends on 03, but 03 depends on 02"
```
## Dimension 3b: Undeclared / Temporal Coupling
**Question:** Do two same-wave plans depend on each other through shared mutable state or
execution order without declaring it? Dimension 3 checks *declared* edges and the wave guard
checks `files_modified` overlap; neither sees an undeclared edge, which under parallel
execution becomes an intermittent failure nobody can attribute.
**Scope: PLAN pairs, not tasks.** Tasks inside one plan run sequentially and cannot race.
Compare same-wave plan pairs over the union of their tasks' `<files>` and `<action>`.
**FLAG only when ALL THREE hold** (coupling that is strong *and* non-local — Connascence of
Execution; strong-but-local coupling inside one plan is fine):
1. both plans sit in the same wave, and
2. neither declares `depends_on` on the other, and
3. their actions name a *specific* shared mutable resource (config key, table/row, migration,
env var, singleton, cache) with at least one WRITER, or one names a prerequisite the other
produces.
**Do NOT flag:** both sides only READ it, or it is immutable; the pair already overlaps in
`files_modified` (report that once, on the file axis); the plans sit in a different wave, which
already orders them; two tasks inside one plan; a vague same-subsystem claim naming no
resource; incompatible *transformations* of one entity — that is Dimension 9.
**Severity: ALWAYS WARNING, never a blocker.** Coupling is sometimes intentional; the finding
lets the planner declare the edge, move a plan to a later wave, or justify the pair.
```yaml
issue:
dimension: dependency_correctness
severity: warning
description: "Plans 02 and 03 are both Wave 1 with no depends_on, but 02 writes config key
auth.session_ttl and 03 reads it"
plans: ["02", "03"]
fix_hint: "Declare depends_on, move 03 to a later wave, or justify either order"
```
## Dimension 4: Key Links Planned
**Question:** Are artifacts wired together, not just created in isolation?
@@ -1036,6 +1072,7 @@ Plan verification complete when:
- [ ] Requirement coverage checked (all requirements have tasks)
- [ ] Task completeness validated (all required fields present)
- [ ] Dependency graph verified (no cycles, valid references)
- [ ] Undeclared/temporal coupling checked (same-wave plan pairs, advisory)
- [ ] Key links checked (wiring planned, not just artifacts)
- [ ] Scope assessed (within context budget)
- [ ] must_haves derivation verified (user-observable truths)