fix: upstream merge - preserve gitignored local data, refuse a merge git never opened (4.5.0-beta.3, #30)
CI / verify (push) Successful in 57s
Release / release (push) Successful in 35s

Files changed:
- CHANGES.md
- VERSION
- docs/ownership-and-templates.md
- instructions/gates.md
- instructions/private-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/tests/test_upstream_cmd.py
This commit is contained in:
2026-09-04 07:35:00 +02:00
parent d2b1719a4b
commit 1b5ffea854
8 changed files with 259 additions and 32 deletions
+19
View File
@@ -42,6 +42,25 @@ Keeping the boundary at the file level, rather than trying to merge changes with
file, means an upgrade never has to guess which lines are "stack" and which are "instance" -
the file itself already answers that.
## Why the boundary is a predicate rather than a list
For a while the boundary was written down as a list of paths - once in `dist_cmd.py`, once in
the merge procedure a private instance was told to run by hand, and once in the check that
procedure ended with. Three copies of one fact, which is the shape [AGENTS.md](../AGENTS.md)
invariant 8 exists to forbid, and they drifted exactly as predicted: the hand-run procedure was
still naming three paths after the collection contracts had moved to the instance's side of the
line, so it discarded upstream changes to files it had never heard of, while its own final check
excluded the same three paths and therefore reported success.
`chemenu/ownership.py` replaced the lists with one question - is this path, under a content
stage, the stack's or the instance's? - answered by shape rather than by enumeration:
`<stage>/CONTRACT.md`, and anything ending `.template`. Both consumers ask it, so `dist export`
and `wikitool upstream merge` cannot disagree, and a machinery file added under a content stage
tomorrow is recognised by both without either being edited. The deeper point is not the
deduplication: a list has to be maintained by whoever remembers it exists, and the failure mode
when nobody does is silence, because a path the list has never heard of simply looks like
content.
## Why a `.template`, not just an absent file
The mechanism for instance-owned content is a `.template` file the distribution ships instead