fix: three more #142 command-record mismatches aligned to code (#146)

Files changed:
- CHANGES.md
- VERSION
- kb/CONTRACT.md
- tools/CONTRACT.md
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/lint.py
- tools/chemenu/commands/xref.py
- tools/chemenu/tests/test_cli.py

tools/CONTRACT.md

@@ -125,7 +125,7 @@ instructions verify   read  idempotent     budget:counted              exit:0,1
 instructions list     read  idempotent     budget:counted              exit:0      List the flat instructions with their descriptions.
 docs verify           read  idempotent     budget:counted              exit:0,1    Check the docs that mirror the code.
 docs toc              write idempotent     budget:counted              exit:0      Create, refresh or remove the generated table-of-contents region.
-docs contract         write idempotent     budget:counted              exit:0      Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
+docs contract         write idempotent     budget:counted              exit:0,1    Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
 eval sessions         read  idempotent     budget:exempt               exit:0      List the sessions that have a trace under `reports/telemetry/`.
 eval score            read  idempotent     budget:exempt               exit:0,1    Score one traced session.
 dist export           write idempotent     budget:counted              exit:0,1    Write a contentless, distributable copy of this repo's machinery.
@@ -614,7 +614,7 @@ Declare that A <rel> B.
 
 - effect: write
 - idempotent: yes
-- atomic: No - writes A then B, but both edits are idempotent, and both refusals happen before either write
+- atomic: Yes - a single write to A; B is never touched, and every refusal happens before it
 - budget: counted
 - network: no
 
@@ -1102,7 +1102,7 @@ Run structural lint checks against kb/.
 - Advisory only: `see-also` edges whose reverse direction already carries a specific label - never migration-gated.
 - Advisory only: a collection past the catalog's per-area shard threshold that has no areas to shard, reported with the split its subtype field would produce, and only when that split puts every resulting area at or under the threshold.
 - Advisory only: source pages sitting in the `unclassified` catalog slot.
-- Advisory only: quote-limit overages (>2 blockquoted lines/page).
+- Advisory only: quote-limit overages (>2 blockquotes/page).
 - Prints only the sections that found something and always writes the full report to `reports/Lint Report <date>.md` (or `--markdown`), naming the path. `--full` prints everything; `--json` prints the findings and writes nothing.
 - Exits 0 whatever it finds unless `--fail-on-error` is passed.
 
@@ -1662,7 +1662,7 @@ Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
 
 - effect: write
 - idempotent: no
-- atomic: No - sequential git operations, but every gate runs before staging
+- 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
 - network: yes
 - gates: mass-update, publish-remote, rebase-review
@@ -2249,6 +2249,11 @@ Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
 **EXIT STATUS**
 
 - 0    success
+- 1    `tools/CONTRACT.md` is missing
+
+**ON FAILURE**
+
+- `tools/CONTRACT.md` is missing -> Not transient - restore the file, which carries hand-written prose around the region this command does not generate, then retry
 
 **NEVER**
 

tools/chemenu/commands/docs_verify.py

@@ -1251,7 +1251,11 @@ def toc_command(
         "Dry-run by default (says whether the file would change); `--apply` writes.",
         "`docs verify` checks the result stays current.",
     ),
-    failures=(),
+    failures=(cli_contract.Failure(
+        cause="`tools/CONTRACT.md` is missing",
+        reaction="Not transient - restore the file, which carries hand-written prose around "
+        "the region this command does not generate, then retry",
+    ),),
     examples=(
         "tools/wikitool docs contract",
         "tools/wikitool docs contract --apply",

tools/chemenu/commands/git_publish.py

@@ -1088,7 +1088,9 @@ def sync_command(
     properties=cli_contract.Properties(
         effect=cli_contract.Effect.WRITE,
         idempotent=cli_contract.Idempotent.NO,
-        atomic="No - sequential git operations, but every gate runs before staging",
+        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=cli_contract.Budget.COUNTED,
         network=cli_contract.Network.YES,
         gates=("mass-update", "publish-remote", "rebase-review"),

tools/chemenu/commands/lint.py

@@ -75,7 +75,7 @@ __all__ = [
         "areas to shard, reported with the split its subtype field would produce, and only "
         "when that split puts every resulting area at or under the threshold.",
         "Advisory only: source pages sitting in the `unclassified` catalog slot.",
-        "Advisory only: quote-limit overages (>2 blockquoted lines/page).",
+        "Advisory only: quote-limit overages (>2 blockquotes/page).",
         "Prints only the sections that found something and always writes the full report to "
         "`reports/Lint Report <date>.md` (or `--markdown`), naming the path. `--full` prints "
         "everything; `--json` prints the findings and writes nothing.",

tools/chemenu/commands/xref.py

@@ -153,8 +153,8 @@ def _check_authorised(source: Page, target: Page, label: str) -> None:
     properties=cli_contract.Properties(
         effect=cli_contract.Effect.WRITE,
         idempotent=cli_contract.Idempotent.YES,
-        atomic="No - writes A then B, but both edits are idempotent, and both refusals happen "
-        "before either write",
+        atomic="Yes - a single write to A; B is never touched, and every refusal happens "
+        "before it",
         budget=cli_contract.Budget.COUNTED,
     ),
     notes=(

tools/chemenu/tests/test_cli.py

@@ -343,9 +343,12 @@ def test_stderr_hint_follows_the_error_line_when_streams_are_merged(tmp_path):
 
     `docs contract` against an empty `CHEMENU_ROOT` fails because
     `tools/CONTRACT.md` does not exist there - no fixture kb, no write,
-    nothing to clean up. It is also the one real record with no exit-1 cause
-    of its own (Gitea #146), so this doubles as the real-command check for
-    the `see:` fallback."""
+    nothing to clean up. Its record used to carry no exit-1 cause of its own
+    (Gitea #146), so this used to double as the real-command check for the
+    `see:` fallback; the record now names this cause, so the hint is its own
+    reaction instead - the fallback itself stays covered by
+    `test_render_failure_hint_falls_back_to_a_bare_pointer` in
+    `test_cli_contract.py`, against a fixture record."""
     tools_dir = Path(__file__).resolve().parents[2]
     env = dict(os.environ)
     env["CHEMENU_ROOT"] = str(tmp_path)
@@ -364,4 +367,5 @@ def test_stderr_hint_follows_the_error_line_when_streams_are_merged(tmp_path):
     assert result.returncode == 1
     lines = result.stdout.splitlines()
     assert lines[0] == "ERROR tools/CONTRACT.md is missing."
-    assert lines[1] == "see: wikitool docs contract -h"
+    hint = cli_contract.render_failure_hint(cli_contract.get("docs contract"))
+    assert "\n".join(lines[1:]) == hint