sync and publish name the Rebase-Review Gate by its display name
CI / verify (push) Successful in 6m20s
CI / pwsh (push) Successful in 2m0s
Release / release (push) Successful in 35s

The help and exit-42 cause texts still said "rebase-review gate" after the display
name was settled; the generated reference and CONTRACT row follow.

Files changed:
- CHANGES.md
- VERSION
- docs/reference/commands/git.md
- docs/reference/exit-codes.md
- tools/CONTRACT.md
- tools/chemenu/commands/git_publish.py

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Code committed 2026-10-07 10:30:49 +02:00
1 parent e9f4759727
commit 5915b07383
6 files changed
+26 -25

No files matched your search

+2 -1
View File
@@ -14,7 +14,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
--- ---
## 9.0.0-beta.9 - 2026-10-07 - Gate-Liste: AGENTS.md § Gates ist die eine Liste (mit Rebase-Review Gate), cli_contract.GATES hält sie, docs verify vergleicht beide ## 9.0.0-beta.10 - 2026-10-07 - Rebase-Review Gate: Anzeigename in Hilfe- und Fehlertexten von sync und publish angeglichen
**Author:** Torben Nehmer **Author:** Torben Nehmer
@@ -39,6 +39,7 @@ place only: `instructions/dev/version-parts.md` § The candidate model.
- version bump: Abschlussmeldung nennt Stichpunkt oder Themenabsatz statt pauschal Prosa - version bump: Abschlussmeldung nennt Stichpunkt oder Themenabsatz statt pauschal Prosa
- AGENTS.md routing line and a toc.py docstring describe docs/ as the whole human documentation - AGENTS.md routing line and a toc.py docstring describe docs/ as the whole human documentation
- tools/README.md module tree names reference_doc.py and the fourth view cli_contract renders - tools/README.md module tree names reference_doc.py and the fourth view cli_contract renders
- Rebase-Review Gate: Anzeigename in Hilfe- und Fehlertexten von sync und publish angeglichen
<!-- /wikitool:bumps --> <!-- /wikitool:bumps -->
### Tutorials: installation in English, and a first source to a first answer (#191) ### Tutorials: installation in English, and a first source to a first answer (#191)
+1 -1
View File
@@ -1 +1 @@
9.0.0-beta.9 9.0.0-beta.10
+7 -7
View File
@@ -23,7 +23,7 @@ Fetch `<remote>/<branch>` and bring the local branch up to date with it.
```text ```text
--remote <str> Git remote to reconcile against [default: origin] --remote <str> Git remote to reconcile against [default: origin]
--branch <str> Branch to reconcile [default: main] --branch <str> Branch to reconcile [default: main]
--confirm-rebase TOKEN Clear the rebase-review gate for the exact upstream --confirm-rebase TOKEN Clear the Rebase-Review Gate for the exact upstream
state and file overlap this token was issued for. The state and file overlap this token was issued for. The
token comes from the gate's own refusal output. token comes from the gate's own refusal output.
-h, --help Show this message and exit. -h, --help Show this message and exit.
@@ -38,7 +38,7 @@ tools/wikitool sync --confirm-rebase <token> # re-run after exit 42, once the
**Behaviour** **Behaviour**
- Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (rebase-review gate) when both sides touched the same file. - Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (Rebase-Review Gate) when both sides touched the same file.
- Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase conflict in them - they are merged mechanically: `kb/log.md` becomes the incoming log plus the entries only this side appended, and the catalog and `kb/provenance.md` are regenerated from the merged pages and left as an uncommitted change. A reconcile git can do on its own is unchanged and regenerates nothing. - Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase conflict in them - they are merged mechanically: `kb/log.md` becomes the incoming log plus the entries only this side appended, and the catalog and `kb/provenance.md` are regenerated from the merged pages and left as an uncommitted change. A reconcile git can do on its own is unchanged and regenerates nothing.
- Uncommitted changes that no incoming commit touches do not stop a rebase: they are carried through it (`git rebase --autostash`) and come back unchanged. - Uncommitted changes that no incoming commit touches do not stop a rebase: they are carried through it (`git rebase --autostash`) and come back unchanged.
- Before anything is set aside, the working tree is stored as a commit under `refs/wikitool/reconcile-backup`. A successful reconcile drops it; a failed one restores the working tree and names the ref. - Before anything is set aside, the working tree is stored as a commit under `refs/wikitool/reconcile-backup`. A successful reconcile drops it; a failed one restores the working tree and names the ref.
@@ -64,7 +64,7 @@ tools/wikitool sync --confirm-rebase <token> # re-run after exit 42, once the
- `0` - The remote cannot be reached - reported and skipped, not a failure - `0` - The remote cannot be reached - reported and skipped, not a failure
- `1` - The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored - `1` - The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored
- `1` - An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed - `1` - An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed
- `42` - Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff - `42` - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff
**See also** **See also**
@@ -91,7 +91,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
gate's own refusal output - run without it first to gate's own refusal output - run without it first to
see the file list, show that output to the user, and see the file list, show that output to the user, and
only pass this once they have approved it. only pass this once they have approved it.
--confirm-rebase TOKEN Clear the rebase-review gate raised by the pre-push --confirm-rebase TOKEN Clear the Rebase-Review Gate raised by the pre-push
reconcile step. The token comes from that gate's own reconcile step. The token comes from that gate's own
refusal output - see `tools/wikitool sync`. refusal output - see `tools/wikitool sync`.
--threshold <int> Mass-Update Gate threshold: number of counted files --threshold <int> Mass-Update Gate threshold: number of counted files
@@ -117,7 +117,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
- Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit. - Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit.
- Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before. - Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before.
- Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (rebase-review gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides. - Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (Rebase-Review Gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides.
- Generated files are never an overlap: where they are all that stops the reconcile, it merges them as `sync` does (both sides' log entries kept, the catalog and `kb/provenance.md` regenerated) and carries uncommitted changes no incoming commit touches through the rebase. The proactive reconcile runs before staging, so this publish commits the regenerated files - with `--path` too, see there; on the retry after a rejected push they get a commit of their own before the second push. - Generated files are never an overlap: where they are all that stops the reconcile, it merges them as `sync` does (both sides' log entries kept, the catalog and `kb/provenance.md` regenerated) and carries uncommitted changes no incoming commit touches through the rebase. The proactive reconcile runs before staging, so this publish commits the regenerated files - with `--path` too, see there; on the retry after a rejected push they get a commit of their own before the second push.
- The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused. - The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused.
- With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository). - With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository).
@@ -135,7 +135,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
- Changes files: yes - Changes files: yes
- Idempotent: no - Idempotent: no
- Atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the rebase-review gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit - Atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the Rebase-Review Gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit
- Counts toward the session call budget: yes - Counts toward the session call budget: yes
- Can reach the network: yes - Can reach the network: yes
- Gates: mass-update, publish-remote, rebase-review - see [exit codes and gates](../exit-codes.md) - Gates: mass-update, publish-remote, rebase-review - see [exit codes and gates](../exit-codes.md)
@@ -149,7 +149,7 @@ tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheats
- `1` - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error - `1` - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
- `1` - `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list - `1` - `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list
- `42` - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset - `42` - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
- `42` - Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff - `42` - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
- `42` - Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL - `42` - Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
**See also** **See also**
+2 -2
View File
@@ -33,9 +33,9 @@ What each exit code means, and how a caller reacts to it, is [AGENTS.md § Tool
- [`new`](commands/pages.md#new): new project: The provider cannot create the project itself (Super Productivity's `access: "api"`); the output says what a human has to create - [`new`](commands/pages.md#new): new project: The provider cannot create the project itself (Super Productivity's `access: "api"`); the output says what a human has to create
- [`upload accept`](commands/raw-material-and-uploads.md#upload-accept): Upload Review Gate: `--confirm` is absent or does not match the manifest's current token - [`upload accept`](commands/raw-material-and-uploads.md#upload-accept): Upload Review Gate: `--confirm` is absent or does not match the manifest's current token
- [`sync`](commands/git.md#sync): Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff - [`sync`](commands/git.md#sync): Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff
- [`publish`](commands/git.md#publish): Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset - [`publish`](commands/git.md#publish): Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
- [`publish`](commands/git.md#publish): Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff - [`publish`](commands/git.md#publish): Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
- [`publish`](commands/git.md#publish): Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL - [`publish`](commands/git.md#publish): Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
- [`export guidelines`](commands/guideline-export.md#export-guidelines): Guideline Push Gate: `--push` without `--confirm`, or with a token that does not match the current set of targets - [`export guidelines`](commands/guideline-export.md#export-guidelines): Guideline Push Gate: `--push` without `--confirm`, or with a token that does not match the current set of targets
<!-- /wikitool:reference-exit-codes --> <!-- /wikitool:reference-exit-codes -->
+7 -7
View File
@@ -1910,13 +1910,13 @@ Fetch `<remote>/<branch>` and bring the local branch up to date with it.
- 0 The remote cannot be reached - reported and skipped, not a failure - 0 The remote cannot be reached - reported and skipped, not a failure
- 1 The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored - 1 The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored
- 1 An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed - 1 An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed
- 42 Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff - 42 Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff
**ON FAILURE** **ON FAILURE**
- The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored -> Do not retry and do not force - resolve the conflict manually, then re-run - The automatic rebase hit a real conflict outside the generated files (git failed), or `kb/log.md` was edited rather than appended to; it is aborted cleanly and the working tree restored -> Do not retry and do not force - resolve the conflict manually, then re-run
- An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed -> Show the user the file it names. Once that change is committed or moved out of the way, re-run once - An uncommitted change - or an untracked file - sits on a path the incoming commits also change; nothing was changed -> Show the user the file it names. Once that change is committed or moved out of the way, re-run once
- Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file, generated files aside; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
**NEVER** **NEVER**
@@ -1925,7 +1925,7 @@ Fetch `<remote>/<branch>` and bring the local branch up to date with it.
**NOTES** **NOTES**
- Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (rebase-review gate) when both sides touched the same file. - Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (Rebase-Review Gate) when both sides touched the same file.
- Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase conflict in them - they are merged mechanically: `kb/log.md` becomes the incoming log plus the entries only this side appended, and the catalog and `kb/provenance.md` are regenerated from the merged pages and left as an uncommitted change. A reconcile git can do on its own is unchanged and regenerates nothing. - Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase conflict in them - they are merged mechanically: `kb/log.md` becomes the incoming log plus the entries only this side appended, and the catalog and `kb/provenance.md` are regenerated from the merged pages and left as an uncommitted change. A reconcile git can do on its own is unchanged and regenerates nothing.
- Uncommitted changes that no incoming commit touches do not stop a rebase: they are carried through it (`git rebase --autostash`) and come back unchanged. - Uncommitted changes that no incoming commit touches do not stop a rebase: they are carried through it (`git rebase --autostash`) and come back unchanged.
- Before anything is set aside, the working tree is stored as a commit under `refs/wikitool/reconcile-backup`. A successful reconcile drops it; a failed one restores the working tree and names the ref. - Before anything is set aside, the working tree is stored as a commit under `refs/wikitool/reconcile-backup`. A successful reconcile drops it; a failed one restores the working tree and names the ref.
@@ -1953,7 +1953,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
- effect: write - effect: write
- idempotent: no - idempotent: no
- atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the rebase-review gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit - atomic: No - sequential git operations. Every gate runs before staging, except on the one retry of a rejected push, where the Rebase-Review Gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit
- budget: counted - budget: counted
- network: yes - network: yes
- gates: mass-update, publish-remote, rebase-review - gates: mass-update, publish-remote, rebase-review
@@ -1973,7 +1973,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
- 1 `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error - 1 `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
- 1 `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list - 1 `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list
- 42 Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset - 42 Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
- 42 Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff - 42 Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
- 42 Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL - 42 Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL
**ON FAILURE** **ON FAILURE**
@@ -1984,7 +1984,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
- `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error -> Drop it. The Mass-Update Gate is cleared only with `--confirm <token>` from the gate's own refusal output - `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error -> Drop it. The Mass-Update Gate is cleared only with `--confirm <token>` from the gate's own refusal output
- `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list -> Show the error to the user and stop - a malformed file is not permission, and fixing or deleting it is theirs to do - `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list -> Show the error to the user and stop - a malformed file is not permission, and fixing or deleting it is theirs to do
- Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state - Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
- Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state - Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
- Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL -> Show the user the push URL it names and the allowed ones, and stop. This gate has no token and no flag: only the user resolves it, by adding the URL to that file - Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL -> Show the user the push URL it names and the allowed ones, and stop. This gate has no token and no flag: only the user resolves it, by adding the URL to that file
**NEVER** **NEVER**
@@ -1997,7 +1997,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
- Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit. - Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit.
- Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before. - Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before.
- Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (rebase-review gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides. - Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (Rebase-Review Gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides.
- Generated files are never an overlap: where they are all that stops the reconcile, it merges them as `sync` does (both sides' log entries kept, the catalog and `kb/provenance.md` regenerated) and carries uncommitted changes no incoming commit touches through the rebase. The proactive reconcile runs before staging, so this publish commits the regenerated files - with `--path` too, see there; on the retry after a rejected push they get a commit of their own before the second push. - Generated files are never an overlap: where they are all that stops the reconcile, it merges them as `sync` does (both sides' log entries kept, the catalog and `kb/provenance.md` regenerated) and carries uncommitted changes no incoming commit touches through the rebase. The proactive reconcile runs before staging, so this publish commits the regenerated files - with `--path` too, see there; on the retry after a rejected push they get a commit of their own before the second push.
- The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused. - The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused.
- With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository). - With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository).
+7 -7
View File
@@ -1343,7 +1343,7 @@ def apply_reconcile(outcome: ReconcileOutcome, remote: str, branch: str, command
notes=( notes=(
"Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases " "Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases "
"the local commits on top when both sides moved but touched disjoint files; exits 42 " "the local commits on top when both sides moved but touched disjoint files; exits 42 "
"(rebase-review gate) when both sides touched the same file.", "(Rebase-Review Gate) when both sides touched the same file.",
"Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every " "Files `wikitool` generates (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every "
"`kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are " "`kb/**/INDEX.md`) never count as an overlap and never reach the gate. Where they are "
"what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase " "what stops git - uncommitted ones in the way of a fast-forward or rebase, or a rebase "
@@ -1389,7 +1389,7 @@ def apply_reconcile(outcome: ReconcileOutcome, remote: str, branch: str, command
"out of the way, re-run once", "out of the way, re-run once",
), ),
cli_contract.Failure( cli_contract.Failure(
cause="Rebase-review gate: `<remote>/<branch>` moved and both sides changed the " cause="Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the "
"same file, generated files aside; the output lists the upstream commits, the " "same file, generated files aside; the output lists the upstream commits, the "
"overlapping files and their diff", "overlapping files and their diff",
reaction=cli_contract.token_gate_reaction("--confirm-rebase"), reaction=cli_contract.token_gate_reaction("--confirm-rebase"),
@@ -1417,7 +1417,7 @@ def sync_command(
None, None,
"--confirm-rebase", "--confirm-rebase",
metavar="TOKEN", metavar="TOKEN",
help="Clear the rebase-review gate for the exact upstream state and file overlap this " help="Clear the Rebase-Review Gate for the exact upstream state and file overlap this "
"token was issued for. The token comes from the gate's own refusal output.", "token was issued for. The token comes from the gate's own refusal output.",
), ),
): ):
@@ -1506,7 +1506,7 @@ def commit_regenerated(remote: str, branch: str) -> None:
effect=cli_contract.Effect.WRITE, effect=cli_contract.Effect.WRITE,
idempotent=cli_contract.Idempotent.NO, idempotent=cli_contract.Idempotent.NO,
atomic="No - sequential git operations. Every gate runs before staging, except on the " atomic="No - sequential git operations. Every gate runs before staging, except on the "
"one retry of a rejected push, where the rebase-review gate can exit 42 after the " "one retry of a rejected push, where the Rebase-Review Gate can exit 42 after the "
"commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit", "commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit",
budget=cli_contract.Budget.COUNTED, budget=cli_contract.Budget.COUNTED,
network=cli_contract.Network.YES, network=cli_contract.Network.YES,
@@ -1525,7 +1525,7 @@ def commit_regenerated(remote: str, branch: str) -> None:
"case: the first publish of an instance commits and pushes as before.", "case: the first publish of an instance commits and pushes as before.",
"Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, " "Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, "
"rebases the local commits on top when both sides moved but touched disjoint files, " "rebases the local commits on top when both sides moved but touched disjoint files, "
"and exits 42 (rebase-review gate) when both sides touched the same file. A refused " "and exits 42 (Rebase-Review Gate) when both sides touched the same file. A refused "
"reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact " "reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact "
"upstream state and the set of files touched on both sides.", "upstream state and the set of files touched on both sides.",
"Generated files are never an overlap: where they are all that stops the reconcile, it " "Generated files are never an overlap: where they are all that stops the reconcile, it "
@@ -1626,7 +1626,7 @@ def commit_regenerated(remote: str, branch: str) -> None:
code=42, code=42,
), ),
cli_contract.Failure( cli_contract.Failure(
cause="Rebase-review gate: `<remote>/<branch>` moved and both sides changed the " cause="Rebase-Review Gate: `<remote>/<branch>` moved and both sides changed the "
"same file; the output lists the upstream commits, the overlapping files and their " "same file; the output lists the upstream commits, the overlapping files and their "
"diff", "diff",
reaction=cli_contract.token_gate_reaction("--confirm-rebase"), reaction=cli_contract.token_gate_reaction("--confirm-rebase"),
@@ -1677,7 +1677,7 @@ def publish_command(
None, None,
"--confirm-rebase", "--confirm-rebase",
metavar="TOKEN", metavar="TOKEN",
help="Clear the rebase-review gate raised by the pre-push reconcile step. The token " help="Clear the Rebase-Review Gate raised by the pre-push reconcile step. The token "
"comes from that gate's own refusal output - see `tools/wikitool sync`.", "comes from that gate's own refusal output - see `tools/wikitool sync`.",
), ),
yes: bool = typer.Option( yes: bool = typer.Option(