v2.7.3 to v3.0.0

- description: "Workspace git-sync guard: detects unsynced repos, records session-attributed local handoff receipts, and batches private project-context commits for explicit remote handoff or day-end. Reports through confidentiality-safe channels."

- version: "2.7.3"

- Large manifests use one NUL-delimited status snapshot, exact literal selection,

- and NUL-delimited input for exact-file commits and resets. Command-line limits do not justify widening

- ownership, splitting one checkpoint into partial commits, or dropping entries.

-

- ## The Problem

-

- AI coding assistants and project-management tooling create and modify files continuously. A stopped task needs lightweight same-machine recovery immediately, while another computer needs a deliberate publication boundary. Treating both cases as an automatic commit creates noisy history and network latency; treating neither creates invisible local-only state. Tools that write files *outside* agent sessions (a project console writing status markers, manual edits) need the same attribution contract.

-

- v1 of this skill detected stranded state and alerted with a count ("N repositories have unsynced changes"). Two failures emerged in practice:

-

- 1. **The alert was unactionable — and leaky if made actionable.** A count says nothing useful; speaking repo names would fix that, but repo/workspace names are often client names, and audio reaches whoever is nearby or on an unmuted call. Notification banners leak the same way during screen-shares.

- 2. **The alert fired on machine-fixable states.** Most unsynced state is exactly what automation should heal at the next sensible checkpoint. Alerting humans about machine-fixable problems trains them to ignore alerts.

-

- ## The Architecture — three layers

-

- | Layer | Component | Job |

- |-------|-----------|-----|

- | Detector | `repo_sync_check.py` (scan) | Find dirty / ahead / behind / detached repos under a workspace root |

- | Messenger | `repo_sync_check.py` (output) | Generic audio/banner ping + detailed report files + console tile data |

- | Checkpointer | `checkpoint_sync.py` | Record local handoffs; batch exact context paths at explicit remote-sync events |

-

- End state: same-computer client switching is filesystem-local and fast.

- Cross-computer publication is batched and explicit. The synthesis-console shows

- ambient status, and alerts remain rare and actionable.

-

- ## Confidentiality rule for alert surfaces (ABSOLUTE)

-

- **Audio (`say`, alert sounds) and macOS notification banners never carry repo names, workspace names, or client names — only counts and a pointer ("details are in your synthesis console").** This holds at all times, not only while screen-sharing: presence detection is unreliable, and one leak outweighs the convenience. Identifying detail belongs exclusively in pull channels the user deliberately opens:

-

- - `~/.synthesis/repo-guard/last-report.txt` / `last-report.json` / `history.jsonl` — written on every scan

- - `~/.synthesis/repo-guard/checkpoint-state.json` — written on every checkpoint run

- - the synthesis-console sync tile / page, which renders both

-

- **Mute toggle:** all audible output (speech AND alert sounds) is suppressed while `~/.synthesis/quiet-audio` exists. synthesis-console exposes this as a header button; `touch`/`rm` the file works too. Muting loses nothing — reports and tile stay current.

-

- ## Detection vs. commit — scoping rules

-

- `repo_sync_check.py` **detects and never modifies** — correct scope: every repo in the workspace.

-

- There are two separate readiness transitions:

-

- 1. **Local handoff:** PostToolUse records structured edits by one client session; paired shell snapshots add net-new formatter, generator, and bulk-rewrite output without claiming unchanged pre-existing dirty paths. Stop writes an atomic receipt with branch, HEAD, file state, and content hashes. It performs no Git commit and no network call. If the client is interrupted before Stop, the pending manifest makes the work LOCAL_RECOVERABLE on the same filesystem.

- 2. **Remote handoff:** the flush-pending command batches only private project-context paths into exact-path commits. Source paths remain owned by their repository workflow and must already be clean and equal to their upstream before manifests retire.

-

- ## The checkpointer: local by default, remote by explicit event

-

- `checkpoint_sync.py` runs at workflow events:

-

- - **AI-tool Stop:** writes a local receipt when that client session has

- attributed repository changes. A Stop with no attributed repository changes

- is a cheap no-op because there is no new file state to preserve.

- - **After a console cockpit write:** `--repo <written-file> --now` records

- a local producer manifest and receipt.

- - **Day-end / mac-sync:** `--flush-pending` publishes exact private-context

- paths after the owning workflows publish any source paths.

-

- **Deliberately not a launchd or cron job.** Wall-clock mutation can race

- repositories across machines. Local receipts follow edit events; remote

- mutation occurs only when the user invokes cross-machine sync or as part of

- day-end. Read-only console polling remains safe.

-

- ### The auto-sync class + runtime guard

-

- Config `~/.synthesis/checkpoint-sync.yaml` (copy `checkpoint-sync.example.yaml`) lists the class by explicit path and glob. Membership criteria: private knowledge/context repos (personal ai-knowledge repos, `*-<person>-private` workspace repos, daily plans). A configured checkout's isolated git worktrees inherit membership through their shared git-common-dir identity. Never source-code repos, never shared/public repos.

-

- **The runtime remote guard is independent of config:** a repo is touched only if EVERY push remote starts with an allowed prefix (your private GitHub namespace). A glob that accidentally matches a repo with a client/org remote is excluded at run time, every time — config declares intent; the guard verifies reality. Empty `allowed_remote_prefixes` fails closed.

-

- ### Safety properties

-

- - Stop never commits, pushes, fetches, stages, or changes branches.

- - Shell attribution compares pre/post Git state and fails closed when its

- pre-tool snapshot is absent, unsafe, or belongs to another session.

- - Remote publication orders exact-path context commit, fetch, then

- fast-forward push. Existing staged or dirty files outside the manifest

- remain untouched.

- - Manifest writers, Stop receipts, remote flushes, and worktree retirement use

- one lifecycle lock. Retirement pins a freshly fetched remote-tracking

- commit, fsyncs a resumable intent before removal, invalidates old receipts,

- and completes idempotently after interruption. A missing worktree without

- this proof is reported as a `stranded` entry that blocks readiness (see

- below) rather than silently attributed elsewhere. Deleted files and child

- directories within a verified live repository are recorded as missing,

- without restoring them or discarding their pending attribution. Resolution

- refuses symlink ancestry, unavailable worktree inventory and a missing

- registered nested worktree rather than borrowing the enclosing repository.

- - A distinct commit author identifies batched remote-context commits.

- - Divergence leaves the exact commit and manifest local and reports the

- block. Never rebase or force-push.

- - Pre-commit hooks run normally. Never bypass them.

- - Source paths and remotely publishable context paths are distinct fields

- in each client-session manifest.

- - A first commit on a feature branch publishes that exact branch with an

- upstream.

- - Active and stale Git index locks are reported and never deleted.

- - A successful edit leaves a manifest even if Stop never runs. Remote

- publication retains manifests until source and context paths are verified

- upstream-current.

-

- ### Stranded entries and per-repository retirement

-

- A manifest entry is **stranded** when its path is missing, its nearest

- existing ancestor sits outside every git working tree, and so the first

- missing component beneath that ancestor is a worktree root that no longer

- exists — a worktree removed before any retirement intent or Stop receipt could

- name it. Stop and flush report it as `stranded`, name the missing worktree

- root, and name the one accepted remedy. Other repositories in the same

- manifest are still evaluated. A deleted file whose repository still resolves

- is not stranded; it stays `deleted-or-missing`. Classification needs git's

- answer: when `git rev-parse` cannot run for the nearest existing ancestor (a

- timeout, no binary) the entry is `failed` as `stranded classification

- unavailable`, never `stranded`, and nothing is drop-eligible; when git refuses

- a live repository (a safe.directory refusal, a damaged gitdir) the `.git`

- entry visible in the ancestor chain keeps the existing handling. A transient

- git failure never discards a live repository's pending attribution.

-

- - Evidence outranks assertion. When a retirement intent names the worktree,

- the remedy is `--complete-worktree-retirement INTENT` (prepared) or the

- intent's own verified head through `--reconcile-retired-worktree`

- (completed). When this session's retained receipt names it with a

- local-ready head, the remedy is `--reconcile-retired-worktree WORKTREE

- --retirement-session ID` while that receipt is LOCAL_READY and still binds

- the current manifest digest; a receipt the manifest outgrew (edits accreted

- after Stop wrote it) names the receipt's own head through

- `--retirement-head` instead, which retires only what that head proves.

- Stop leaves that receipt unchanged so the evidence survives.

- - With neither, the entry is drop-eligible:

- `--flush-session ID --drop-stranded --assert "<why the work is known published>"`.

- The drop recomputes the stranded set at run time, refuses if the worktree

- root exists again, writes an append-only record to

- `~/.synthesis/repo-guard/retired-pending/<manifest>-stranded-<UTC>.json`

- (session, dropped paths, nearest existing ancestor, missing worktree root,

- whether an intent or receipt named it, any repository whose HEAD tracks the

- same relative path with its blob oid, the assertion, the acting identity,

- the timestamp), then rewrites the manifest without those entries and

- continues the normal flush. A blank `--assert` (whitespace or invisible

- format characters only) is refused. `--dry-run`

- reports the drop and writes nothing. Existing ledger records are never

- replaced.

- - Every flush that is not a dry run retires the entries of each repository

- whose result is `clean`, `committed-pushed`, `pushed-stranded`

- (earlier commits pushed now) or `source-remote-ready`, and deletes the

- manifest only once it is empty. The `retired-repositories` result names

- what was retired.

- - Blocked repositories get a per-path pass instead of keeping every entry:

- paths that are clean with HEAD contained in the remote retire; dirty

- paths whose bytes match the manifest's attribution hash (or predate

- hashes) stay committable; dirty paths another session overwrote are

- skipped from the commit, reported, and kept; paths whose attributed

- bytes provably landed on the origin retire even while dirty. On a

- claim-refused root the commit is retried with only the committable

- subset. Guard-rejected and lock-active roots retire nothing, source

- entries keep root granularity, and dry runs report the would-commit /

- would-retire / would-skip sets without writing. A long-lived session

- therefore stops accreting already-published work onto a manifest one

- foreign path keeps alive.

-

- ---

-

- ## Quick Start

-

- ```bash

- # Scan ~/workspaces, write reports, print text summary

- ./repo_sync_check.py

-

- # Machine-readable scan (console tile source)

- ./repo_sync_check.py --json --quiet

-

- # Generic attention ping if dirty (mute-aware)

- ./repo_sync_check.py --speak --notify --dirty-only

-

- # Preview pending remote publication

- ./checkpoint_sync.py --dry-run

-

- # Record a same-machine Stop receipt

- ./checkpoint_sync.py --hook --quiet --notify

-

- # Record a just-written producer file locally

- ./checkpoint_sync.py --repo ~/workspaces/example/daily-plans/today.md --now

-

- # Publish pending project context after source repos are upstream-current

- ./checkpoint_sync.py --flush-pending

-

- # Publish and retire one exact session without inspecting unrelated sessions

- ./checkpoint_sync.py --flush-session <session-id>

-

- # Drop stranded entries (removed worktree, no retained evidence) under a recorded assertion

- ./checkpoint_sync.py --flush-session <session-id> --drop-stranded --assert "merged to main on 2026-08-31"

- ```

-

- ### Exit codes (both scripts)

-

- | Code | repo_sync_check.py | checkpoint_sync.py |

- |------|--------------------|--------------------|

- | 0 | all clean & synced | requested readiness reached |

- | 1 | repos need attention | alerts raised (detail in state file) |

- | 2 | error | error |

-

- ### What the detector reports

-

- | Condition | Marker |

- |-----------|--------|

- | Uncommitted changes (modified/staged/untracked) | `[dirty]` + file list + fix hint |

- | Unpushed commits | `[ahead]` + count |

- | Unpulled commits | `[behind]` + count |

- | Detached HEAD | `[detached]` |

- | Git errors | `[error]` |

-

- ---

-

- ## AI Tool Integration

-

- ### Claude Code (`~/.claude/settings.json`)

-

- Turn-end remediation of the current session's attributed context paths plus

- optional session-end verification:

-

- ```json

- {

- "hooks": {

- "Stop": [

- { "hooks": [ { "type": "command",

- "command": "python3 <synthesis-repo-guard-root>/checkpoint_sync.py --hook --quiet --notify",

- "timeout": 120 } ] }

- ],

- "SessionEnd": [

- { "hooks": [ { "type": "command",

- "command": "python3 <synthesis-repo-guard-root>/repo_sync_check.py --dirty-only --speak --notify",

- "timeout": 60 } ] }

- ]

- }

- }

- ```

-

- ### OpenAI Codex (`~/.codex/hooks.json`, with `features.hooks = true`)

-

- ```json

- { "hooks": { "Stop": [ { "hooks": [ { "type": "command",

- "command": "python3 <synthesis-repo-guard-root>/checkpoint_sync.py --hook --quiet --notify",

- "timeout": 120 } ] } ] } }

- ```

-

- Each client session has its own hashed pending manifest under

- `~/.synthesis/repo-guard/pending/`. Multiple agents can therefore coexist

- without one hook committing, publishing, or overwriting another session's files.

-

- For projects that adopt `CURRENT_STATE.json`, the plugin's provider-neutral

- Stop gate composes this file-level evidence with synthesis project management's

- semantic checkpoint. A clean project handoff receipt is issued only when the

- current coordination seat, project id, Git identity, durable-file hashes, and

- recorded source heads all match. An interrupted task still relies on the

- pending manifest and reports `LOCAL_RECOVERABLE`; it is never mislabeled clean.

-

- ### Cursor (`.cursor/settings.json`)

-

- ```json

- { "task.onEnd": "python3 /path/to/checkpoint_sync.py --hook --quiet --notify" }

- ```

-

- ### synthesis-console (command center)

-

- - **Always-on sync tile:** polls `repo_sync_check.py --json --quiet` (read-only; lid-safe) and renders `checkpoint-state.json` outcomes.

- - **Quiet-audio toggle button:** creates/removes `~/.synthesis/quiet-audio`.

- - **"Sync now" button:** `checkpoint_sync.py --no-throttle`, an explicit remote-context handoff alias.

- - **Producer receipts:** after writing a plan marker, the console records local state with `--repo <file> --now`.

-

- ### Scheduled execution — read-only only

-

- If a tool supports no hooks at all, a scheduled **detector** run (`repo_sync_check.py --quiet`, reports only, no audio flags) is acceptable — it's read-only and interruption-safe. Do **not** schedule `checkpoint_sync.py`: mutation stays event-driven (see design rationale above). The console tile's polling normally makes scheduled detection unnecessary.

-

- ---

-

- ## Relationship to Other Skills

-

- - **synthesis-mac-sync** — the full multi-machine sync operation (config files, credentials, all repos, with user approval). Repo-guard keeps same-machine work recoverable; mac-sync owns the explicit cross-machine publication transition.

- - **synthesis-context-lifecycle / synthesis-daily-rituals** — those skills keep local project state current during work and publish it through remote handoff or day-end. `repo_sync_check.py` is the final day-end verification gate.

-

- ---

-

- ## Command Reference

-

- ```

- repo_sync_check.py [--workspace W] [--max-depth N] [--quiet] [--json]

- [--dirty-only] [--alert] [--speak] [--notify]

- [--report-dir D] [--no-report]

-

- checkpoint_sync.py [--config C] [--repo PATH] [--hook] [--now]

- [--flush-pending | --flush-session SESSION_ID

- [--drop-stranded --assert TEXT]]

- [--no-throttle] [--dry-run]

- [--prepare-worktree-retirement PATH

- --retirement-repository REPO --retirement-head SHA

- --retirement-remote REMOTE --retirement-base REMOTE_REF]

- [--complete-worktree-retirement INTENT]

- [--reconcile-retired-worktree PATH

- --retirement-repository REPO

- (--retirement-head SHA | --retirement-session SESSION_ID)

- --retirement-remote REMOTE --retirement-base REMOTE_REF]

- [--quiet] [--json]

- [--speak] [--notify]

- ```

- - `--speak/--notify/--alert` are generic + mute-aware on both scripts.

- - `checkpoint_sync --repo` records one configured producer path locally; it does not commit or use the network.

- - `--hook` consumes the calling session's JSON hook payload and never falls

- back to a workspace-wide mutation. `--flush-pending` is the explicit

- remote-context transition; `--no-throttle` is its console compatibility alias.

- - `--flush-session` applies the same remote-readiness gates to one manifest

- selected by its exact session id. It does not read, validate, publish, or

- delete any other session manifest. Use it when unrelated pending work must

- remain recoverable while one fully published session transitions to

- `REMOTE_READY`.

- - `--drop-stranded --assert TEXT` is valid only with `--flush-session`. It

- retires drop-eligible stranded entries after recording the operator's

- assertion in the retired-pending ledger; see "Stranded entries and

- per-repository retirement" above.

- - `--retirement-session` derives a removed worktree's historical head from

- this native session's retained local receipt. It verifies the manifest

- digest, attributed bytes/deletions and file modes, and remote ancestry;

- it never substitutes current file existence for preservation evidence.

- Only that session's manifest is changed. The retirement transaction retains

- exact post-images for crash recovery and preserves evidence for remaining

- worktrees. Missing older evidence is an explicit recovery gap. See

- [checkpoint closure recovery](../synthesis-project-management/references/checkpoint-closure-recovery.md).

- ---

- ## Design Principles

- 1. **Zero AI and zero external dependencies** — Python stdlib + git CLI (PyYAML used if present, minimal built-in parser otherwise)

- 2. **LLM-agnostic** — same scripts for Claude Code, Codex, Cursor, console, or manual use

- 3. **Detector never modifies; Stop is local-only; remote publication modifies only exact guarded context paths**

- 4. **Identifying names (repo, workspace, client) never on audio/banner surfaces** — counts and pointers only

- 5. **Remote mutation is explicit or day-end; only reads may poll**

- 6. **Fail closed, never force** — empty guard config disables; divergence/hook-failures stop and alert

- 7. **Composable** — exit codes, JSON output, shared state files

- ## Changelog

- - **2.5.0 (2026-09-11):** classifies manifest entries beneath a removed,

- unrecorded worktree as `stranded` instead of aborting the whole manifest;

- adds `--flush-session ID --drop-stranded --assert TEXT` with an append-only

- retired-pending ledger; retires published repositories' entries per flush

- so blocked repositories no longer keep already-published work pending.

- - **2.3.0 (2026-08-23):** adds a fail-closed exact-session remote handoff that

- retires one verified manifest without coupling it to unrelated pending

- sessions; preserves global flush behavior and fsyncs successful manifest

- retirement.

- - **2.2.0 (2026-08-14):** makes retirement a lifecycle-locked, remote-pinned,

- fsynced, resumable transaction across manifests and receipts; resumes with

- the intent's exact content-addressed reconciler and compare-binds optional

- remote branch deletion to the verified head; keeps unexplained missing and

- unpublished paths fail-closed.

- - **2.1.1 (2026-08-14):** clarifies that a clean no-edit task needs no empty receipt and that remote readiness compares complete branch heads rather than project-path history.

- - **2.1.0 (2026-08-14):** separates local and remote readiness. Stop records atomic client-session receipts without Git or network mutation; interruption leaves a recoverable manifest; explicit remote handoff batches exact private-context paths only after source paths are upstream-current. Adds worktree identity, first-branch publication, generic commit messages, staged-index isolation, and integration fixtures.

- - **2.0.0 (2026-07-08):** three-layer redesign. Generic-only audio/banner (confidentiality rule), `~/.synthesis/quiet-audio` mute flag, report files + history, remediation hints, new `checkpoint_sync.py` (event-driven auto-commit/push: runtime remote guard, quiescence, shared throttle, ff-only push, distinct author, stale-lock detection), synthesis-console integration contract, scheduled-mutation explicitly disallowed. Origin: 2026-07-08 design review (lesson: alert-channel confidentiality + event-driven checkpoints).

- - **1.1.0:** detector + count-only audio alerts.

- ### Exact publication feedback

- The remote flush owner records an exact-session publication receipt only after

- remote verification and a check that the attributed paths equal the published

- commit. The receipt binds the original manifest bytes, native session, exact

- path set, file bytes/modes, commit, upstream and remote identity. Stop consumes

- that receipt offline with a two-second total bound. `VERIFIED_REMOTE_READY`

- means the prior owner verification still matches current local evidence;

- `live_remote_rechecked: false` makes the observation boundary explicit. It

- never grants new publication authority. Missing, foreign, stale, corrupt,

- over-budget or later-attributed evidence produces `UNKNOWN`, not “unpublished.”

- The legacy global last-handoff file is not publication proof.