Merge pull request 'Issue 245: behind is what a plan decided and has not yet done' (#96) from issues/245-the-plan-is-the-truth into main

2026-10-05 13:17:04 +00:00
parent b3e7191ddc 1b9196b807
commit 7497149eed
1 changed files with 14 additions and 5 deletions
@@ -32,10 +32,19 @@ reads behind. The list then says nothing about what needs building: it hides the
 really are behind among the many that are not, and it invites a rebuild of everything, which is not
 a harmless act (above).

+## The operator's direction (2026-10-05)
+
+The only truth is the outcome of the build plan. A plan already decides, from a change, which modules
+it affects: those whose sources changed and those that depend on them, tier by tier. "Behind" means
+a module that a plan has decided to rebuild and has not yet rebuilt or rolled out, and nothing else.
+No second comparison beside the plan is made, whether of commits, of folders or of files, because a
+second answer to the same question is how the two came to disagree.
+
 ## Open questions

-1. Should "behind" compare the module's own sources, its path and whatever its build reads, between
-   the commit it was built from and the repository's head, the way a plan already decides what to
-   rebuild? A module whose files did not change could then simply move its recorded commit forward.
-2. Should `build --behind` use the same comparison, so it can never rebuild an unchanged module?
-3. Should `status` show only the modules an open plan has not yet rebuilt?
+1. Where does `status` read "behind" from today, and what replaces it: the open plans' remaining
+   tiers?
+2. What does a module's recorded commit mean once a plan that leaves it untouched has run? Does it
+   move forward, or does the record stop carrying a commit that only says when it was last built?
+3. Should `build --behind` and `push --behind` take their lists from the same place, so that they can
+   never act on a module no plan named?