guard: freshness-block message gives the exact remediation syntax (3.8.6)

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.8.6] - 2026-07-06
+
+### Changed
+- **Guard: the freshness-block message now hands over the exact remediation instead of a riddle.** `GIT_FRESHNESS_MESSAGE` used to say *"run `git fetch --all --prune` … then inspect branch status"*, which left agents guessing — they would use a `$VAR` path (not resolved by the static parser) or a fetch that errored on an unreachable mirror, and burn many turns flailing. The message now spells out the working form verbatim: a **literal-path** fetch chained in the **same command** as the write (`git -C "/abs" fetch --all --prune && git -C "/abs" commit …`), and names the silent-failure gotchas (`$VAR` path not resolved; pipe/redirect in the fetch part; a fetch that exits non-zero because `--all` hit a keyless mirror — use `fetch origin --prune`). No behavior change; message text only.
+
 ## [3.8.5] - 2026-07-05
 
 ### Fixed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omind"
-version = "3.8.5"
+version = "3.8.6"
 description = "Reproduce the OMI/Obsidian memory integration for AI agents, plus a local web app to view, edit, and add memory entries."
 readme = "README.md"
 requires-python = ">=3.10"

src/omind/__init__.py

@@ -2,4 +2,4 @@
 # Copyright 2026 Aaron K. Clark
 """omind — OMI/Obsidian memory tooling for AI agents."""
 
-__version__ = "3.8.5"
+__version__ = "3.8.6"

src/omind/guard.py

@@ -63,9 +63,14 @@
     "this turn; a generic project-memory consult is not enough."
 )
 GIT_FRESHNESS_MESSAGE = (
-    "repo work requires a same-turn freshness check before review/edit/test/commit/push: "
-    "run `git fetch --all --prune` or `git pull --ff-only`, then inspect branch status. "
-    "For a repo outside the cwd, `git -C <repo> fetch --all --prune` freshens that repo."
+    "repo work requires a same-turn freshness check before review/edit/test/commit/push. "
+    "Put a LITERAL-path fetch in the SAME command as the write, chained with && — e.g.:\n"
+    '  git -C "/abs/path/to/repo" fetch --all --prune && git -C "/abs/path/to/repo" commit -am "..."\n'
+    "(same shape for push / a git write; for `gh pr create`, prefix it with the literal-path fetch too). "
+    "Gotchas that make it silently fail: (1) the path must be a LITERAL absolute path — a $VAR is not "
+    "resolved by the static parser; (2) no pipe/redirect in the fetch part; (3) the fetch must succeed "
+    "(exit 0) — if `--all` hits an unreachable mirror (e.g. a Codeberg remote with no key loaded), use "
+    "`fetch origin --prune` so it doesn't error out and fail to register."
 )
 GLOBAL_MUTATION_MESSAGE = (
     "global config/hook/bootstrap mutation requires explicit user authorization in the "