chore: promote dev to main for 1.2.0

CHANGELOG.md

@@ -5,7 +5,69 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.2.0] - 2026-08-21
+
+**Scope, stated first because the range and the artifact are not the same thing.**
+
+The work promoted in this release is the range **`v1.1.0..6192e8c5`** — from the 1.1.0 tag to the
+`dev` tip at freeze — which is **42 commits / 14 first-parent units**. The release-prep commit
+that carries this entry sits one beyond that and is deliberately excluded; counting it makes the
+range 43 / 15. Both numbers are true of different ranges, so the range is named rather than left
+to inference.
+
+Units are classified by diffing each against its **first parent**. A merge commit has no
+canonical diff, and `git show <merge> --name-only` returns nothing for these, so the method is
+part of the claim.
+
+**Five of those 14 units are in the published `gitgrip` crate; nine are not.** gr2 is a separate
+Python surface at version `0.1.0` that is not distributed, so its nine units — the propagation
+prototypes, the append/torn-line work, the native daily verbs, and workspace-spec-from-topology —
+are present in this repository and absent from anything `cargo install gitgrip` gives you. The
+entries below cover the five gr1 units only. Read the git range if you want the gr2 work.
+
+### Fixed
+- **`gr pr merge` and `gr checkout` exit nonzero when part of a batch fails** — a multi-repo
+  operation that failed in some repos and succeeded in others previously exited 0, so a caller
+  or CI step reading the exit code saw success over a partial failure.
+
+  **This does not close the exit-code-honesty class, and should not be read as doing so.**
+  The class is tracked in `grip#886`, which records 9+ known instances; two are fixed here.
+  **`gr push` — the most consequential instance, the one that can silently lose work — is
+  untouched by this release.**
+- **`gr link --apply` reports a stale source instead of composing it silently** and
+  **gripspace pins are checked for freshness**.
+
+  **Two measured holes in this remain open** (`grip#891`), and this feature ships with **no
+  user-facing documentation** — `README.md` has no `gr link` section, only a one-line table
+  mention. Link freshness is **not** guaranteed by this release; what changed is that one class
+  of stale composition now reports rather than proceeding quietly.
+
+### Known gaps at this release
+- The new exit-code semantics (`EXIT_REFUSED=2`, operational failure `1`, success `0`) are not
+  documented in `README.md` for either `gr checkout` or `gr pr merge`.
+- `CONTRIBUTING.md` does not mention gr2 anywhere, despite **9 of the 14 first-parent units in
+  `v1.1.0..6192e8c5` touching only `gr2/`** — the same first-parent classification used
+  throughout this entry. A contributor following that document has no path to discovering gr2
+  exists or how to set up its separate Python environment.
+
+  **Two earlier drafts of this line carried a commit-level statistic; both are withdrawn, and
+  the second is the more instructive.** The first said gr2 was "roughly a third of this
+  repository's active commit volume" — no range, no metric, nothing to reproduce. The second
+  replaced it with "22 of 42 commits (52%), measured by first-parent diff," which named a range
+  and a method and was **still wrong, because the number did not come from the method it
+  named**: 22 is `git rev-list --count -- gr2/`, whose path-history simplification silently drops
+  eight merge commits that *do* touch `gr2/` against their first parent. Under the stated method
+  the figure is 30 of 42 (71%). A sourced number can be more misleading than an unsourced one,
+  because citing a method invites trust the number has not earned. The unit measure above needs
+  no footnote, so it is the only one kept.
+
+## [1.1.0] - 2026-08-13
+
+These entries sat under an `[Unreleased]` heading until 2026-08-21. **That heading was false:**
+this work shipped in `v1.1.0`, tagged 2026-08-13 and published to crates.io. Verified by
+checking the feature's own symbols into the `v1.1.0` tree rather than by commit archaeology,
+with a negative control. A reader trusting the old heading would have believed a shipped
+feature was still pending.
 
 ### Fixed
 - **`gr pr merge` no longer defaults to squash** (#829) — with no `--method`, the command queried the host for its allowed methods and took the first of squash > merge > rebase, so on any repo permitting squash the tool actively chose it. A workspace whose policy is merge-commit-only got squashes from its own tooling, and on a private repo — where hosting rulesets are unavailable on most plans — nothing downstream could reject the result. The default is now a real merge commit, configurable via `settings.merge_method` in the manifest. Choosing is the workspace's job; the host is asked only whether the choice is permitted.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gitgrip"
-version = "1.1.0"
+version = "1.2.0"
 edition = "2021"
 rust-version = "1.80"
 description = "Multi-repo workflow tool - manage multiple git repositories as one"

docs/IMPLEMENTATION_PLAN.md

@@ -59,7 +59,7 @@ Pass `--hostname` to `gh` CLI in `src/platform/github.rs` `enable_auto_merge()`
 
 ### Phase 3: Repo iteration helper
 - [x] New `src/cli/repo_iter.rs`: `RepoVisitResult`, `RepoOpSummary`, `for_each_repo()`, `for_each_repo_path()`
-- [ ] Wire into commands — Deferred: most commands accumulate custom state that doesn't fit the simple Success/Skipped/Error enum
+- [ ] Wire into commands — Partially done: `checkout` adopted it (2026-08-21). The remaining commands are blocked on `?` propagation out of the loop, three disagreeing skip taxonomies, and per-arm payload types — not on the enum alone
 
 ### Phase 4-6: Migrate all commands to WorkspaceContext
 - [x] 28/30 commands in main.rs use `load_workspace_context()` (Init, Completions, Bench don't need workspace)

docs/PLAN-p2-maintainability.md

@@ -24,7 +24,9 @@ No conflicts expected — P0/P1 didn't touch `main.rs` or `cli/mod.rs`.
 ```
 cargo build && cargo test && cargo clippy && cargo fmt --check
 ```
-Watch for clippy warnings on unused `repo_iter` imports. If flagged, the `pub` visibility from `cli/mod.rs` → `lib.rs` should suppress it.
+~~Watch for clippy warnings on unused `repo_iter` imports. If flagged, the `pub` visibility from `cli/mod.rs` → `lib.rs` should suppress it.~~
+
+**Struck.** This prescribed silencing the one instrument that would have reported the problem. `pub` does not resolve a dead-code warning, it disables the analysis — an unused private item warns, an unused `pub` item does not — so following this step left `repo_iter` with zero callers and nothing anywhere going red for as long as it existed. A warning is a detector; suppressing it to reach a clean build is not a fix, and writing the suppression down as a step made it the default for whoever came next. If an item has no consumer, give it one or delete it.
 
 ### 3. Commit the refactor
 Stage all 4 files and commit:
@@ -59,7 +61,7 @@ gr pr create -t "refactor: P2 maintainability — WorkspaceContext and load_grip
 | Command signature migration to `&WorkspaceContext` | Would touch every command file + every test; current ctx field extraction in dispatch works fine |
 | Compact dispatch function (Phase 7) | 612-line match for 30 commands is standard; only one dispatch site |
 | sync.rs / release.rs decomposition (Phase 8) | Already have helpers (`sync_single_repo`, `execute_post_sync_hooks`, etc.) |
-| Wiring `for_each_repo()` into commands | Most commands accumulate custom state that doesn't fit the simple Success/Skipped/Error enum |
+| Wiring `for_each_repo()` into commands | Largely accurate, and now measured rather than assumed. Of the 9 command files that hand-roll these counters, `sync`/`pull` do not iterate repos at all, `pr/merge` iterates PRs and awaits, and `push`/`commit`/`forall` propagate `?` out of the loop — which the closure's return type cannot express. `checkout` was the one clean fit and has adopted it. |
 
 ## Files touched
 

gr2/docs/HOOK-EVENT-CONTRACT.md

@@ -197,6 +197,20 @@ and `lease.force_broken` (which fires when a live lease is broken with
 | `workspace.materialized` | `gr2 workspace materialize` or `gr2 apply` | `{repos: [{repo, first_materialize: bool}]}` |
 | `workspace.file_projected` | File link/copy applied | `{repo, kind, src, dest}` |
 
+#### Propagation
+
+| Type | Trigger | Payload |
+|------|---------|---------|
+| `propagation.receipt` | The propagation daemon (`gr2/prototypes/propagation_daemon.py`) completed one operation against its declared managed replica, in any terminal state (acknowledged, refused, partial, unverifiable) | `{summary, state, pending_id, operation_id, source_rev, expected_base, after, replayed, receipt_path}` |
+
+`propagation.receipt` is emitted once per operation; a tick that finds the cursor
+already at the source revision is not an operation and emits nothing. `summary` is
+the one-line notification a channel consumer relays verbatim. `receipt_path` is the
+full path of the receipt file the daemon wrote, an explicit exception to the
+relative-path rule in 3.3: the receipt store lives under the daemon's declared
+`state_dir`, which is not a workspace file and may sit outside `workspace_root`.
+`after` is `null` when the operation did not reach `applied`.
+
 ### 3.3 Payload Conventions
 
 - All paths in payloads are relative to `workspace_root`, never absolute.
@@ -471,6 +485,9 @@ class EventType(str, Enum):
     # Workspace operations
     WORKSPACE_MATERIALIZED = "workspace.materialized"
     WORKSPACE_FILE_PROJECTED = "workspace.file_projected"
+
+    # Propagation (one event per receipt from the propagation daemon)
+    PROPAGATION_RECEIPT = "propagation.receipt"
 ```
 
 ### 7.3 Implementation Location

gr2/prototypes/README.md

@@ -406,3 +406,43 @@ This keeps the cache discussion grounded in evidence:
 - cache remains the optimization
 - the prototype should tell us whether the optimization is material enough to
   justify building it into `apply`
+
+## Propagation State Machine (Prototype 0)
+
+Before any daemon is allowed to move changes between workspaces, the state
+contract for one propagation is proven on synthetic repositories:
+
+```bash
+python3 -m pytest gr2/tests/test_propagation_state_machine.py -q
+```
+
+`gr2/prototypes/propagation_state_machine.py` drives one change through
+`observed -> fetched -> planned -> applied -> verified -> acknowledged`, with
+`refused`, `partial`, and `unverifiable` reachable from any of them. Every
+transition names the observation that established it, and every receipt names
+the exact source and destination revisions. Everything it carries is an opaque
+identifier; it holds no notion of agent or workspace identity and no policy
+content (the allowed directions are a required input with no default).
+
+The tests build a bare source remote and three destinations (a clean replica, a
+dirty authoring clone, an authoring clone that is ahead of the source) and
+prove, each as its own witness:
+
+- killing the sink between each pair of states and replaying applies the change
+  exactly once (measured from the destination's own reflog and the journal)
+- the cursor advances only on `acknowledged`
+- a moved expected base refuses with the observed base in the receipt; nothing
+  is merged, forced, or retried against the new base
+- a dirty or diverged authoring clone is refused and left byte-for-byte
+  untouched (refs, HEAD, index, worktree, reflog)
+- a destination that cannot be read back after the apply verb is recorded as
+  `unverifiable`, never collapsed into `refused` or `applied`, and resolves on
+  replay
+- an acknowledged operation replays as a no-op returning the original outcome;
+  a refused one starts a new attempt, because a refusal describes a moment
+
+It is also the home of a born-red witness for the existing event outbox:
+`read_events()` advances the consumer cursor before the caller performs its
+effect, so a consumer that fails after reading loses the event. The test is
+marked `xfail(strict=True)` and turns the marker into a failure the moment
+acknowledgment moves after the effect.