Open Stage 5: thirteen completion criteria, eight decisions, and a task split out

README.md

@@ -158,7 +158,23 @@ completion criteria (`docs/planning/roadmap.md`):
   velocity/pressure solve -- that's Stage 5.
 
 Stage 5 will solve incompressible flow: a coupled velocity/pressure
-system built from Stage 4's now-real numerical schemes.
+system built from Stage 4's now-real numerical schemes. **Its completion
+criteria were written on 2026-08-28, before its first task started**
+(`docs/planning/status.md` has the live count), per the standing rule
+every stage since Stage 2 has followed
+-- including the reconciliation against `docs/implementation/mvp.md`'s
+own Definition of Done that Stage 5 has owed since 2026-08-22, since
+this is the stage that defines the MVP. Seven design questions were
+raised while drafting them -- five of the seven gaps in the current
+code, verified against it rather than anticipated -- and six were
+decided the same day. The seventh (what carries the momentum
+coefficients a converging pressure-correction loop needs) is
+deliberately left open for TASK-033 to answer with measurements, since
+TASK-027 already showed what deciding that one from an armchair costs.
+Stage 5 starts with TASK-041 (Fluid Configuration Section), split out
+from TASK-031 once those answers made it clear that a task about
+velocity transport had quietly acquired the project's first breaking
+configuration change.
 
 Try the most recent demonstration -- a scalar blob advected and
 diffused across a periodic domain, stepped live:

docs/implementation/mvp.md

@@ -61,6 +61,21 @@ The MVP shall successfully reproduce:
 - Heat diffusion.
 - Lid-driven cavity flow.
 
+**"Heat diffusion" here means the diffusion equation on a transported
+scalar, not a named Temperature field** (recorded 2026-08-28,
+maintainer's call). The distinction was never stated, and the project
+had drifted on it: `docs/planning/implementation-plan.md` and
+`planning/data/demos.yaml` both placed the Heat Diffusion demo at
+Capability Level 3 -- Stage 6, one stage *after* the MVP -- while this
+document required the MVP to reproduce it. Found by the reconciliation
+`docs/planning/roadmap.md`'s Stage 5 Completion Criterion 11 requires
+between this document and that stage's criteria, and decided in favour
+of this document: heat diffusion is the diffusion equation with a
+different name on the field, so PyFlow can run it with no Temperature
+field at all. Stage 6's TASK-035 then adds the named field with
+buoyancy coupling, which is a different claim rather than this one
+repeated. Both other documents were amended in the same change.
+
 ## Definition of Done
 
 - Simulation runs end-to-end.

docs/planning/backlog.md

@@ -1961,6 +1961,20 @@ here.):
         prescribed-velocity boundaries must satisfy global mass
         conservation as a precondition for the system to be solvable at
         all -- currently a documented requirement, not yet a test.
+
+        **Half-closed 2026-08-27, and the other half reassigned
+        2026-08-28.** TASK-027 landed a single correction pass whose
+        criterion is a *measured, bounded reduction* in divergence,
+        checked in isolation -- not divergence-free "after every
+        correction step", which that task verified numerically it could
+        not deliver on a collocated mesh without momentum-equation
+        coefficients no Stage 4 interface could supply (its own Design
+        decision Two). The strong claim this bullet states is now **Stage
+        5 Completion Criterion 3, owned by TASK-033**, where a real
+        velocity and pressure field finally exist to iterate against.
+        The boundary-condition precondition named above is separately
+        closed (the next bullet); what remains open here is the loop's
+        own convergence, and it is scheduled rather than unassigned.
       - **Boundary conditions** -- **done, not Stage 4 -- closed early by
         TASK-019 (Stage 3, 2026-08-23)**, found while drafting Stage 4's
         own Completion Criteria (2026-08-25): the global mass-
@@ -2066,6 +2080,23 @@ here.):
         exist yet and won't until Stage 5 opens. `implementation-plan.md`
         Level 2 now says so explicitly, so whoever drafts them reaches
         for Ghia et al. rather than inventing a fresh reference.
+
+        **Closed 2026-08-28, when Stage 5's Completion Criteria were
+        drafted.** They did reach for Ghia et al., and the two halves of
+        this gap were answered differently, which is why this bullet
+        records both rather than "done": Reynolds number 100 was
+        adopted; **the illustrative 2% was rejected** (maintainer's call).
+        The MVP's advection scheme is first-order upwind, whose numerical
+        diffusion at MVP mesh resolutions is the dominant error term, so
+        a fixed 2% would have been a bar the MVP's own documented
+        numerics are not built to clear -- and a criterion that can only
+        be met by quietly loosening its own number later is not a
+        criterion. Stage 5 Completion Criterion 5 requires convergence
+        instead: error against Ghia's tabulated profiles decreasing
+        monotonically across at least three mesh resolutions, plus the
+        qualitative structure at the finest, with the absolute tolerance
+        stated and defended in the feature file. `implementation-plan.md`
+        Level 2 was amended in the same change.
       - **Flow Around Cylinder's von Kármán/Strouhal correlation was
         already flagged as unclaimed** in `implementation-plan.md`
         before this pass (2026-08-20) -- confirmed still accurate,
@@ -2099,11 +2130,26 @@ here.):
       a future task that genuinely has no natural closed-form case.
 
       *Unblock condition:* the two closed gaps need no further action.
-      Ghia et al.'s tolerance activates when Stage 5's own Completion
-      Criteria are drafted; the cylinder correlation when Stage 8 gets
-      real task numbers; MMS itself stays open as a general-purpose
-      technique for whichever future task turns out to need it, TASK-024
-      no longer being that task.
+      Ghia et al.'s tolerance activated on 2026-08-28 and is now Stage 5
+      Completion Criterion 5, closed above -- as a convergence
+      requirement rather than the illustrative 2%. The cylinder
+      correlation activates when Stage 8 gets real task numbers; MMS
+      itself stays open as a general-purpose technique for whichever
+      future task turns out to need it, TASK-024 no longer being that
+      task. **This item's only remaining open thread is the cylinder
+      correlation**, which is why it is still unticked.
+
+      **A third divergence, found 2026-08-28 by the same Stage 5
+      drafting and closed in the same change:** `docs/implementation/
+      mvp.md`'s Validation section requires the MVP to reproduce heat
+      diffusion, while `implementation-plan.md` and
+      `planning/data/demos.yaml` both placed the Heat Diffusion demo at
+      Capability Level 3 -- one stage after the MVP. Decided
+      (maintainer's call): Level 2 owes it, as a transported scalar
+      rather than a named Temperature field, and it is Stage 5
+      Completion Criterion 8. Recorded here because this item is the
+      project's own catalog of which benchmark is testable where, and it
+      had the demo in the wrong place.
 
 - [x] **`capability-map.md`'s "Analysis" capability's fate: decided
       2026-08-20, maintainer's call -- threaded like Rendering, no

docs/planning/implementation-plan.md

@@ -212,20 +212,42 @@ Unlocks
 Golden Demo
 
 Lid-driven cavity. **The quantitative target has a name and a number,
-recorded here 2026-08-27 though not yet a drafted acceptance
-criterion:** Ghia, Ghia & Shin (1982) publish tabulated centerline
+recorded here 2026-08-27 and drafted into a real acceptance criterion on
+2026-08-28:** Ghia, Ghia & Shin (1982) publish tabulated centerline
 velocity profiles for this exact case at several Reynolds numbers;
 `adr/ADR-007-executable-acceptance-criteria.md`'s own worked example
 already uses "Reynolds number 100... matches Ghia et al. within 2%" to
 illustrate what an executable physics criterion looks like, and
 `docs/glossary.md`'s definition of "Validation" cites the same paper.
-Neither commits Stage 5 to that Reynolds number or that tolerance --
-Stage 5's own Completion Criteria are, per `docs/practices.md`'s own
-rule ("a stage gets completion criteria before its first task"),
-drafted when that Stage opens, not now -- but whoever drafts
-them should reach for Ghia et al. rather than inventing a fresh
-reference, since two other documents already point at it as the obvious
-answer.
+This note previously said neither committed Stage 5 to that Reynolds
+number or that tolerance, and asked whoever drafted that Stage's
+criteria to reach for Ghia et al. rather than invent a fresh reference.
+**They did, and the answer to the tolerance half was no** (`docs/
+planning/roadmap.md`, Stage 5 Completion Criterion 5, 2026-08-28,
+maintainer's call): Reynolds number 100 is adopted, the 2% is not.
+The MVP's advection scheme is first-order upwind, whose numerical
+diffusion at MVP mesh resolutions dominates the error, so a fixed 2%
+would be a bar the MVP's own documented numerics are not built to clear.
+The criterion is convergence instead -- error against Ghia's profiles
+decreasing monotonically across at least three mesh resolutions, plus
+the qualitative structure (primary vortex centre, both secondary corner
+vortices) at the finest -- with the absolute tolerance stated and
+defended in the feature file against the mesh actually used.
+
+**Heat diffusion, added 2026-08-28** -- maintainer's call, taken while
+drafting Stage 5's Completion Criteria and reconciling them against
+`docs/implementation/mvp.md`'s own Definition of Done, which is a
+condition Stage 5 has carried since 2026-08-22. `mvp.md` requires the
+MVP to reproduce three validation cases -- passive scalar transport,
+heat diffusion, lid-driven cavity -- while this document and
+`planning/data/demos.yaml` both placed Heat Diffusion at Level 3, which
+is Stage 6. **Decided: Level 2 owes it, as a scalar.** Heat diffusion
+*is* the diffusion equation on a transported scalar; only the field's
+name differs, and PyFlow can run it with no Temperature field at all.
+Level 3's "Heat transport" (below) is then the named-Temperature
+version with buoyancy coupling -- a genuinely different claim, not this
+one repeated -- the same reuse-at-a-later-Level pattern Taylor-Green
+vortex already follows between Levels 2 and 4.
 
 **Couette flow, added 2026-08-27** (`docs/planning/backlog.md`,
 "physical correctness validation") -- plane shear flow between two
@@ -286,6 +308,15 @@ Heat transport.
 
 Smoke transport.
 
+**"Heat transport" here is the named-Temperature version, not the first
+heat demo** (clarified 2026-08-28, when Level 2 took ownership of Heat
+Diffusion -- see that Level's own note). The distinction is the point of
+this Level: Level 2's Heat Diffusion demo runs the diffusion equation on
+an anonymous transported scalar, which needs no Temperature field at
+all. This Level's claim is that a *named* field with its own physical
+coupling (buoyancy, TASK-035) adds nothing to the engine -- which is
+only demonstrated if the anonymous version already worked.
+
 **Rayleigh-Bénard convection** (added 2026-08-20, same reference as
 above) -- a fluid layer heated from below, once Temperature and Density
 are both unlocked at this Level. Extends the "Thermal buoyancy" demo
@@ -554,7 +585,7 @@ Each Golden Demo permanently validates one or more major capabilities.
 | Field Display | Variables (added 2026-08-22, TASK-017) |
 | Numerics Assembly | Numerical architecture (added 2026-08-23, TASK-021 -- proves the six-component assembly mechanism, not a physical capability; "no CFD yet") |
 | Scalar Transport | Advection |
-| Heat Diffusion | Diffusion |
+| Heat Diffusion | Diffusion (Level 2 as a transported scalar, decided 2026-08-28; reused at Multiple Transported Fields as named-Temperature heat transport) |
 | Couette Flow | Incompressible Navier-Stokes (added 2026-08-27, physical correctness validation) |
 | Poiseuille Flow | Incompressible Navier-Stokes (added 2026-08-20, physical correctness validation) |
 | Lid-Driven Cavity | Pressure-Velocity Coupling |