tvproductions/gzkit / .agents/skills/git-sync
git-sync
VerifiedRun the guarded repository sync ritual; commit-time hooks enforce the cheap gates and the pre-push hook runs gz check.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.5 KB |
SKILL.md
View on GitHub---
name: git-sync
persona: main-session
description: Run the guarded repository sync ritual; commit-time hooks enforce the cheap gates and the pre-push hook runs gz check.
category: agent-operations
lifecycle_state: active
disable-model-invocation: true
owner: gzkit-governance
last_reviewed: 2026-11-08
metadata:
skill-version: "1.5.0"
model: haiku
---
# SKILL.md
## Git Sync
Run the guarded repository sync ritual with lint/test gates.
## Trigger
- User asks to "git sync" or "push with guards"
- End-of-task reconciliation before handoff
- Branch drift recovery after remote updates
## Behavior
Use the `gz git-sync` command flow (dry-run first, then apply as requested).
## Commit messages (binding)
Every commit's subject says what changed. Operator feedback: *"Every commit must
describe what actually changed."* It was moved into this skill from auto memory
on 2026-11-08 (operator: *"A: skill plus GHI"*). `gz git-sync` has no message
flag. When it commits staged work it writes the generic subject
`chore: update <areas> (gz git-sync)`, so commit the change yourself first, with
a descriptive subject and the trailers `gz validate --commit-trailers` requires,
and run `gz git-sync --apply` on a clean tree to fetch, rebase and push.
GHI #1313 tracks changing the generic default.
## Prerequisites
- Repository is initialized with `gz init`
- Current directory is a git worktree
## Steps
1. Preview planned actions:
`uv run gz git-sync`
2. Execute the standard ritual:
`uv run gz git-sync --apply`
3. Explicit redundant-gate invocation (edge cases only, e.g. verifying
pre-commit config drift):
`uv run gz git-sync --apply --lint --test`
> Both dry-run and apply mode run `git fetch --prune <remote>` before
> reading `ahead`/`behind`, so divergence numbers always reflect current
> remote state — no separate pre-fetch needed (GHI #343). When the
> network is unreachable the dry-run reports the fetch failure as a
> warning and proceeds with cached refs; apply-mode treats it as a
> blocker.
> The pre-commit hook runs the CHEAP gates on every commit — ruff, ty,
> the complexity ceiling (cyclomatic and cognitive), gitleaks, authorship. It does NOT run the unit
> suite: `unittest` is declared `stages: [manual]` in
> `.pre-commit-config.yaml` and fires only on demand
> (`pre-commit run unittest --hook-stage manual`). The tests a change
> touches reach a push through the separate `gz-check-pre-push` hook, which
> runs `gz check --reuse-verified`; the whole unit tier runs in CI
> (GHI #1191). `--lint` and `--test` re-run those gates at
> the `gz` level — redundant for the normal ritual and multi-minute pain.
> Defaults were flipped to `False` to match this reality (airlineops
> parity evolution).
## Examples
### Example 1
**Input**: "git sync"
**Output**: Runs `uv run gz git-sync --apply` (or dry-run first if safety confirmation is needed). Pre-commit hook handles lint/test automatically.
## Append-only JSONL conflicts
The runtime appends to `.gzkit/ledger.jsonl` (and `agent-insights.jsonl`,
`corpus/*.jsonl`) during every session, so two clones in flight conflict over
disjoint tail additions. `uv run gz git-sync --apply` registers a git merge
driver — `uv run gz ledger merge-driver` — that reconciles them as a
**timestamp-ordered union**. Registration is idempotent and per-clone, because
git reads a driver command from local config, which cannot be committed.
**Never hand-edit `.gzkit/ledger.jsonl` to clear a conflict.** That is the
action `AGENTS.md` § Behavior Rules prohibits (the ledger is written only through `gz` commands), and the driver exists so you do not
have to. If the driver exits 1, a side did more than add rows — an ancestor row
was edited or removed, a row carries no sortable `ts`, or the ancestor was
already out of ts order — and it left the conflict for you deliberately. An
addition never lands there, wherever in the file it sits (GHI #1075). Resolve as
a timestamp-ordered union; never append one side to the other, which is what
git's built-in `merge=union` would do and why it is not used here (the ledger is
strictly ts-ordered — `gz validate --ledger`).
## Constraints
- Never use force push in this routine.
- Resolve blockers (divergence, lint/test failures) before retrying.
- Use `uv run` invocation style for project commands.
## Common Rationalizations
These thoughts mean STOP — you are about to push without the guards:
| Thought | Reality |
|---------|---------|
| "Force push, it's just my branch" | The constraint is explicit: never use force push in this routine. "Just my branch" still rewrites history and can desync local clones. Resolve divergence the long way. |
| "Lint is failing on something cosmetic — ship it" | The lint/test gates exist because cosmetic failures often hide real ones. The whole point of the ritual is that you don't get to triage at sync time. Fix or revert. |
| "I'll skip `--lint --test` to be quick" | The bare `--apply` exists for git-only operations. Skipping the quality gates on a code change is the failure mode the ritual was designed to prevent. |
| "Divergence with remote — just rebase and force" | Investigate first. Divergence may mean another agent or another machine pushed work you don't have. Force-pushing destroys it. |
| "Dry-run looks fine, no need to actually run --apply" | Dry-run shows the plan; apply executes it. Walking away after dry-run leaves the local tree out of sync, which the next session inherits. |
| "Pre-commit hook failed — `--no-verify` it" | Hooks are part of the contract. Skipping them with `--no-verify` is the same anti-pattern as skipping `--lint --test`. Diagnose, don't bypass. |
| "I'll commit and sync separately" | The ritual includes the sync step deliberately. Committing without syncing leaves the branch behind on the remote, which is exactly the divergence trap. |
## Red Flags
- Force push appearing anywhere in the routine
- `--no-verify` used on the commit
- Lint or test failures bypassed instead of fixed
- Divergence resolved by reset/force instead of investigation
- Dry-run run without follow-through apply
- Sync run on a tree with uncommitted control-surface drift
> Two hooks are the mandatory gate: the commit-time cheap gates
> (ruff + ty + the complexity gates + guards) and the pre-push `gz check`, which runs every
> validator and the tests the change touches. The whole unit suite runs in
> CI on every code push. Explicit `--lint --test` flags are
> redundant for the normal ritual (see Steps § 3). Omitting them is not a
> red flag — skipping either hook via `--no-verify` is.
## Related Skills
- `lint`
- `test`
- `format`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |