docs: add git self-sync to persistent agent definitions (Stories 81.1, 81.2, 81.3) (#930)

* docs: add git self-sync to persistent agent definitions (Stories 81.1, 81.2, 81.3)

- merge-queue: add ref refresh as step 0 in polling loop
- pr-shepherd: add ref refresh as step 0 in polling loop
- project-watchdog: add ref refresh before planning doc checks
- arch-watchdog: add optional ref refresh note
- CLAUDE.md: clarify persistent agent exemption from git safety hook
- CLAUDE.md: add /refresh discoverability to Operator Workflow section
- All three story files updated with provenance and implementation notes

Provenance: L3

* docs: update story statuses to Done (PR #930) (Stories 81.1, 81.2, 81.3)

Provenance: L3

Author: arcavenai

CLAUDE.md

@@ -39,6 +39,7 @@ When running multiclaude, the **workspace window** (tmux window 1) is the primar
 - **Communicate with the supervisor** via messaging: `multiclaude message send supervisor "your message here"`
 - **Observe agent activity** read-only: `multiclaude agent attach <name> --read-only`
 - **Check system status** from the workspace: `multiclaude status`
+- **Sync workspace with main:** Use `/refresh` to rebase the workspace worktree onto latest `origin/main`. The workspace worktree is **NOT auto-refreshed** by the daemon (unlike worker worktrees), so run `/refresh` periodically during active multi-agent sessions to avoid working with stale code.
 
 ## CODEOWNERS Protection — MANDATORY
 
@@ -76,6 +77,8 @@ A PreToolUse hook (`scripts/hooks/git-safety.sh`) mechanically enforces git safe
 - `git push origin main/master` — use feature branches, never push directly to main
 - `Co-Authored-By` trailers — forbidden per project policy
 
+**Persistent agent exemption:** The git safety hook only blocks fetch/pull/rebase/merge in **worker worktrees** (paths containing `/.multiclaude/wts/`). Persistent agents (merge-queue, pr-shepherd, project-watchdog, arch-watchdog) sharing the main checkout are **exempt** and SHOULD periodically run `git fetch origin main` to keep local refs current. See individual agent definitions for fetch timing.
+
 **Allowed:** `git add`, `git commit` (signed), `git push` (feature branches), `git status`, `git log`, `git diff`, `git branch`, `git checkout -b`, `git merge --abort`, `git stash`, etc.
 
 ## Story-Driven Development — MANDATORY

agents/arch-watchdog.md

@@ -26,8 +26,14 @@ After spawning, verify with `multiclaude worker list` — you should appear with
 
 **Interval:** Every 20-30 minutes
 
+**Step 0 — Refresh local refs (optional):**
+```bash
+git fetch origin main
+```
+Arch-watchdog primarily uses `gh` CLI (GitHub API), so a stale local ref is less critical than for merge-queue or pr-shepherd. However, fetching before checking architecture docs against latest main ensures comparisons are accurate. If the fetch fails, continue with stale data — do not halt.
+
+**Step 1 — Check recently merged PRs:**
 ```bash
-# Check recently merged PRs
 gh pr list --state merged --limit 10 --json number,title,mergedAt,headRefName
 ```
 

agents/merge-queue.md

@@ -207,6 +207,12 @@ After each merge, review open GitHub issues to check if the merged work incident
 
 On each polling cycle, check the following in order:
 
+0. **Refresh local refs:**
+   ```bash
+   git fetch origin main
+   ```
+   This ensures `origin/main` is current before any checks that depend on it (branch cleanup, scope validation, CI SHA comparisons). If the fetch fails (e.g., network issue), log a warning and continue the cycle with stale data — do not halt.
+
 1. **Open PRs ready for merge:**
    ```bash
    gh pr list --state open --json number,title,mergeable,statusCheckRollup,labels,reviews

agents/pr-shepherd.md

@@ -109,6 +109,12 @@ multiclaude work "Address feedback on PR #<number>: [summary]" --branch <pr-bran
 
 On each polling cycle, check the following in order:
 
+0. **Refresh local refs:**
+   ```bash
+   git fetch origin
+   ```
+   PR shepherd needs current refs for all remote branches (not just main) to accurately detect which PRs need rebasing and to perform conflict resolution. If the fetch fails, log a warning and continue the cycle with stale data — do not halt.
+
 1. **Open PRs with merge conflicts:**
    ```bash
    gh pr list --state open --json number,title,headRefName,mergeable

agents/project-watchdog.md

@@ -132,6 +132,14 @@ HEARTBEAT messages are lightweight triggers — they tell you "now is a good tim
 ## Operational Notes
 
 ### Polling Loop (Every 10-15 Minutes)
+
+**Step 0 — Refresh local refs:**
+```bash
+git fetch origin main
+```
+Ensures `origin/main` is current before checking planning doc drift or comparing story file state against latest main. If the fetch fails, log a warning and continue with stale data — do not halt.
+
+**Step 1 — Check recently merged PRs:**
 ```bash
 gh pr list --state merged --limit 10 --json number,title,mergedAt,headRefName
 ```

docs/stories/81.1.story.md

@@ -1,7 +1,7 @@
 # Story 81.1: Merge-Queue Polling Fetch
 
 **Epic:** 81 — Git Coordination Fixes
-**Status:** Not Started
+**Status:** Done (PR #930)
 **Priority:** P0
 **Estimate:** S (< 1 hour)
 
@@ -42,3 +42,10 @@ Currently, merge-queue never fetches. Over time, its local `origin/main` ref dri
 ## Implementation Notes
 
 > [observation] 2026-04-02 — git safety hook detects worker worktrees via `/.multiclaude/wts/` path pattern. Persistent agents at the main checkout path are exempt from fetch blocking.
+
+> [decision] 2026-04-02 — Added fetch as step 0 (before step 1) in the polling loop, matching AC2's requirement. Used `git fetch origin main` per AC3.
+
+## Provenance
+- **Autonomy Level:** L3 (AI-autonomous)
+- **Implementation Agent:** worker/cool-dolphin
+- **Review:** Human PR review required

docs/stories/81.2.story.md

@@ -1,7 +1,7 @@
 # Story 81.2: Persistent Agent Self-Sync Documentation
 
 **Epic:** 81 — Git Coordination Fixes
-**Status:** Not Started
+**Status:** Done (PR #930)
 **Priority:** P1
 **Estimate:** S (< 1 hour)
 
@@ -43,3 +43,12 @@ However, no persistent agent definition currently instructs the agent to self-sy
 ## Implementation Notes
 
 > [decision] 2026-04-02 — Focus fetch instructions on merge-queue, pr-shepherd, and project-watchdog as the three agents most affected by stale refs. envoy and retrospector are lower priority since they primarily use GitHub API.
+
+> [decision] 2026-04-02 — pr-shepherd uses `git fetch origin` (all refs) since it needs branch refs for rebase operations. merge-queue and project-watchdog use `git fetch origin main` since they only need the main ref.
+
+> [decision] 2026-04-02 — arch-watchdog fetch marked as optional since it primarily uses `gh` CLI. Still included per AC4.
+
+## Provenance
+- **Autonomy Level:** L3 (AI-autonomous)
+- **Implementation Agent:** worker/cool-dolphin
+- **Review:** Human PR review required

docs/stories/81.3.story.md

@@ -1,7 +1,7 @@
 # Story 81.3: Workspace Refresh Discoverability
 
 **Epic:** 81 — Git Coordination Fixes
-**Status:** Not Started
+**Status:** Done (PR #930)
 **Priority:** P1
 **Estimate:** S (< 1 hour)
 
@@ -38,3 +38,10 @@ The workspace worktree (where the human operator works) is created by multiclaud
 ## Implementation Notes
 
 > [observation] 2026-04-02 — /refresh slash command already exists and works. This story is purely about documentation and discoverability.
+
+> [observation] 2026-04-02 — /refresh is defined as a system-level slash command in the multiclaude agent framework, not as a `.claude/commands/` file. AC3 verified — it's available in all agent contexts.
+
+## Provenance
+- **Autonomy Level:** L3 (AI-autonomous)
+- **Implementation Agent:** worker/cool-dolphin
+- **Review:** Human PR review required