feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153)
CI / verify (push) Successful in 5m19s
CI / pwsh (push) Successful in 1m55s
Release / release (push) Successful in 36s

Files changed:
- .gitea/workflows/ci.yml
- .gitea/workflows/release.yml
- AGENTS.md
- CHANGES.md
- DEVELOPMENT.md
- EVALS.md
- INSTALL.md
- README.md
- VERSION
- docs/ownership-and-templates.md
- instructions/CONTRACT.md
- instructions/bootstrap.md
- instructions/dev/dev-setup.md
- instructions/dev/stack-dev/SKILL.md
- instructions/gates.md
- instructions/ingest-large-tree.md
- instructions/kb-profiles.md
- instructions/mcp-read-server.md
- instructions/migrations/3.0.0-authoring-conventions.md
- instructions/preflight.md
- instructions/private-instance.md
- instructions/session-setup.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/upstream_cmd.py
- tools/chemenu/commands/work_cmd.py
- tools/chemenu/config.py
- tools/chemenu/ownership.py
- tools/chemenu/tests/test_cli.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_instructions_shell.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/tests/test_preflight_pwsh.py
- tools/chemenu/tests/test_run_budget.py
- tools/chemenu/tests/test_upstream_cmd.py
- tools/chemenu/toc.py
- tools/preflight.ps1
- tools/preflight.sh
This commit is contained in:
torben committed 2026-10-01 22:12:09 +02:00
1 parent d0f08d1fba
commit a6d07f97c4
46 files changed
+1314 -1936

No files matched your search

+29 -3
View File
@@ -18,6 +18,7 @@ overwriting them would silently erase a choice someone made on purpose.
- [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file)
- [Where the file boundary used to strain](#where-the-file-boundary-used-to-strain)
- [The consequence in practice](#the-consequence-in-practice)
- [Why an instance comes only from a release](#why-an-instance-comes-only-from-a-release)
<!-- /wikitool:toc -->
## Two different kinds of truth
@@ -66,9 +67,10 @@ 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
`<stage>/CONTRACT.md`, and anything ending `.template`. Every consumer asks it - at the time,
`dist export` and a `wikitool upstream merge` that took the hand-run procedure's place; since
that path was removed, the export alone - so no two of them can disagree, and a machinery file
added under a content stage tomorrow is recognised without any of them 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.
@@ -179,3 +181,27 @@ categories, and make a locally changed file a decision someone takes deliberatel
one an upgrade takes for them. The template-sourced files were filled in once, by a person, for
a reason, and nothing about a newer release of the stack's mechanics gives it standing to
override that.
## Why an instance comes only from a release
Everything above depends on one file every instance carries: the `.wikitool-release.json` its
release wrote. It is the base `dist upgrade` classifies against, the marker that turns telemetry
off for someone who never asked for it, and the record of which stack version the instance runs.
An instance that starts anywhere else starts without that base, and every later step has to
reconstruct the boundary by other means.
For a while there were four ways in: a release, a `dist export` from a checkout of the origin
repository, a clone of that repository, and a private clone that kept the origin as a git
`upstream` and took stack updates by merging. The last two never had the stamp, so they needed
the boundary a second way. The clone took the origin's demo corpus, demo persona and development
skills with it and had to be emptied by hand, and the instruction for doing so neither said what
had to survive nor fitted into the iteration budget. The merge path needed its own
ownership-aware command, `upstream merge`, which shipped two data-destroying bugs before it was
right, and still left a checkout with two remotes and no stamp. None of the four was in use when
they were cut down to one in 8.0.0.
What is left is a single shape. A release is an export packed as a tarball, installed into an
empty folder - or an empty clone of the instance's own repository - by a script attached to the
same release. `dist export` remains, as the tool that builds a release and tests what one would
ship, not as a way to install. A clone of the origin repository remains too, as the place the
stack is developed, and is never an instance.