# Agentic Git Sync

> Use to complete Git closeout when active AGENTS.md instructions, an active workflow or skill contract, or the current user calls for submit, sync, merge, push, or closeout.

- Skill: `dolphinai2026/agentic-git-sync` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add dolphinai2026/agentic-git-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dolphinai2026/agentic-git-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: dolphinai2026 (https://skillmd.com/u/dolphinai2026)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dolphinai2026/agentic-git-sync

---


# Agentic Git Sync

`agentic-git-sync` 是 Git 收口能力，不是通用 Git 禁止规则。以下任一来源需要 Git 收口时，可以主动执行，不要求用户理解或主动驱动 Git：

- 当前生效的 `AGENTS.md` 规则启用 `agentic-git-sync` 或等价 Git 收口工作流。
- 当前 active workflow 或 active skill contract 要求提交、同步、合并、推送或收口。
- 用户当前会话主动要求提交、同步、合并、推送或收口。

skill 仅存在、pack 已安装、plan 成功本身、archive 成功、`record-attempt` 成功或 topic switch，都不是独立激活来源。本 skill 的激活判断只约束是否使用 `agentic-git-sync`；禁令作用域与跨 skill commit 归属遵循 `rules/git-permission-boundaries.md`，不得限制其它 active skills 或 workflows 按自己的 contract 执行 Git 动作。

## Required Context

- `rules/git-permission-boundaries.md`
- `rules/phase65-delegation.md`
- `rules/head-worktree-sync.md`
- `rules/evidence.md`
- `templates/git-sync-evidence.yaml`
- 当前任务摘要、changed paths、spec / plan refs、当前会话 verification evidence。

## Scenario Classification

Branch contract: plan scenario uses the frozen target branch from plan-worktree metadata; non-plan scenario uses the ordinary HEAD/default branch.

执行 Git 动作前，先分类场景：

- `inactive`: 没有激活来源；不执行 Git sync，只报告 ready 状态。
- `phase65_owned`: Phase 6.5 confirmed implementation evidence 拥有该流程；no-op 或 delegate。Phase 6.5 precedence 始终高于本 skill 的其它场景。
- `candidate_promotion_recovery`: Phase 6.5 不匹配，且 active consumer 提供 closed promotion request 时，必须由 `agentic-git-sync promotion validate` 验证 request，再由 `agentic-git-sync promotion evaluate` 给出 action。remote advance alone is insufficient；只有 validated request 和 evaluator action 才能授权 publication。
- `inline_pending_acceptance`: inline 修改存在，工作流已启用，但用户未确认且未切换话题；不 commit / push，等待或询问。
- `inline_accepted_capture`: inline 修改已被用户接受，或工作流启用时用户切换到下一话题且没有未关闭 blocker；提交归属明确路径，如果 ordinary HEAD/default branch changed，则 push its upstream。
- `plan_running`: 非交互 plan 仍在运行，或最终状态未知；不 merge / push。
- `plan_completed_integrate`: 非交互 plan 有结构化成功和验证证据；提交剩余归属明确路径，merge into the frozen target branch，然后 push the frozen target branch through the target-aware lifecycle。
- `plan_failed_no_integrate`: plan 最终失败、最终 watchdog、验证不完整或 review 未通过；不 merge / push，保存 evidence 并报告 failed 或 blocked。
- `blocked_needs_user`: Git 状态不安全，或缺少必要事实；不执行破坏性动作，保存 evidence 并报告 blocker。

## Plan Success Gate

`plan_completed_integrate` 需要同时满足：

- `codex-agentic` exit code 为 `0`。
- 最终 attempt 的 `run.json` 存在。
- 最终状态为 completed，或等价成功且没有终止性失败。
- `verification.status == "complete"`，或 plan 明确要求的验证 evidence 存在且成功。
- `termination_reason` 缺失，或为非阻塞原因。
- run 不是 `watchdog_timeout`、`model_capacity`、`interrupted`、`verification_incomplete` 或 `verification_next_phase_required`。
- plan 要求的 implementation review 已通过，或该 plan 不要求 review。
- dirty paths 能归属到当前 plan、archive 产物或已验证 follow-up fix。

缺少任一事实时，结果只能是 `blocked_needs_user` 或 `plan_failed_no_integrate`，不能 merge / push。

## Hook 升级恢复发布契约

Hook upgrade recovery 只适用于 ordinary local plan execution 中闭合的
`hook_authorization_changed` 事务。`codex-agentic` 必须同时收到显式
`--allow-hook-recovery` 与 `--hook-recovery-policy <canonical-absolute-file>`；skill
存在、diagnostic 出现或环境变量都不能隐式激活恢复。Phase 6.5 precedence 必须先于
本地恢复判断；命中 confirmed implementation evidence 时返回
`recovery_not_applicable` 并按 `rules/phase65-delegation.md` 委托。

恢复链消费两类不可互换的 closed operation：

- trigger operation：`kind=agentic-worktree-hook-operation`、`schema_version=v2`，由
  plan-worktree hook authorization 失败时写入
  `~/.agentic-coding/work/<work-id>/plan-worktree-hook-triggers/<trigger-id>/trigger-operation.json`。
- publication operation：`kind=agentic-worktree-hook-publication-operation`、
  `schema_version=v1`，由 recovery controller 在候选迁移后写入
  `~/.agentic-coding/work/<work-id>/plan-worktree-recovery/<recovery-id>/publication-operation.json`，
  并通过 `trigger_operation_ref` 绑定原 trigger operation。

publication is owned exclusively by `agentic-git-sync`。wrapper、hook runner 和
recovery controller must not push directly；它们只能生成或消费
`publication-request.json` / `publication-result.json`，由本 skill 的
`candidate_promotion_recovery` gate 执行唯一允许的 canonical single-ref argv。
`candidate_published` is not plan completion，不能触发普通 plan completed cleanup、
`record-attempt --status completed` 或 CI handoff。

publication result 进入 `recovery_publication_blocked` 时，retryable blocked state
只允许 raw diagnostic `promotion_push_unknown`、`remote_unobservable`、
`promotion_tracking_stale`，并提供 canonical `--reconcile` retry command。
terminal blocked state 包括 `promotion_lease_rejected`、`promotion_remote_changed`、
`promotion_post_push_mismatch`、`promotion_retry_exhausted`、`promotion_auth_failed`、
`promotion_push_failed`、`promotion_post_check_ambiguous`、
`promotion_post_check_unobservable`、`remote_ref_missing_or_ambiguous`、
`promotion_observation_invalid`，不得提供 resume status 或 retry command。operation
union、引用、候选身份或 artifact observation 不闭合时使用
`recovery_publication_operation_invalid`；blocked result 形状或 diagnostic 不闭合时使用
`recovery_publication_blocked`。

## Candidate Promotion Gate

`candidate_promotion_recovery` 是 reviewed candidate publication 的窄恢复场景，不是普通 plan closeout。真实 push 前必须：

1. 运行 `agentic-git-sync promotion validate --request <request.json>`，消费其 closed validation output；skill 不得自行解析或拼装 request JSON。
2. 在 promotion worktree 中运行 `git rev-parse --show-toplevel`、`git rev-parse --git-common-dir`、`git branch --show-current` 和 `git rev-parse HEAD`。把 git-common-dir 规范化为绝对路径后，四项实际观测必须分别 exactly equal validator output 的 `promotion_worktree_root`、`promotion_git_common_dir`、`promotion_branch` 和 `candidate_sha`；任一失败或不相等都以既有 `promotion_target_mismatch` fail closed，且不得 push。把实际观测持久化为 `promotion_worktree_root`、`promotion_git_common_dir`、`promotion_branch`、`promotion_head_sha`。
3. 从 validated request 绑定的 frozen metadata 读取 `target.remote_ref`，且 lease ref 与 refspec actual destination 必须同为 `refs/heads/<target-remote-branch>`。
4. 验证 persisted diagnostic 为 `hook_authorization_changed`、attempt count 为 1、candidate scope/child snapshot/equivalence/current-session verification/implementation review 全部通过。
5. 验证 live remote 和 remote tracking 都仍为 expected-old，并在 push 前证明 expected-old 是 candidate 的严格祖先。
6. 运行 `agentic-git-sync promotion evaluate --request <request.json> --state <push-state.json> --observation <remote-observation.json>`；只有 `push_once` 或 `retry_same_argv_once` evaluator action 才允许执行 validator 输出的 canonical single-ref argv。`reconcile_published` 直接进入 post-verification，`block` 不得 push。
7. push 后再次通过 evaluator 和 exact remote observation 证明 destination 等于 candidate；成功结果固定为 `candidate_published`。

任一 pre-gate 失败必须以 `push_status=not_attempted`、`result_class=blocked` 停止，并记录首个稳定 diagnostic：`promotion_request_invalid`、`promotion_attempt_invalid`、`promotion_hook_authorization_invalid`、`promotion_target_mismatch`、`promotion_scope_violation`、`promotion_child_snapshot_drift`、`promotion_equivalence_invalid`、`promotion_verification_stale`、`promotion_review_stale`、`promotion_non_fast_forward`、`remote_unobservable`、`remote_ref_missing_or_ambiguous`、`promotion_tracking_stale`、`promotion_remote_changed` 或 `promotion_observation_invalid`。push/evaluator 后续稳定 diagnostic 还包括 `promotion_post_check_unobservable`、`promotion_post_check_ambiguous`、`promotion_post_push_mismatch`、`promotion_lease_rejected`、`promotion_auth_failed`、`promotion_push_failed`、`promotion_push_unknown` 和 `promotion_retry_exhausted`。

### Closed Diagnostic Normalization

skill 只消费 validator/evaluator 的 closed CLI output，must not re-parse the schema。CLI raw diagnostic 到 git-sync evidence `promotion_diagnostic` 的映射固定如下；未列出的 raw code 必须 fail closed 为 `promotion_request_invalid`，不得自由改名：

| CLI raw diagnostic | evidence `promotion_diagnostic` |
| --- | --- |
| `promotion_path_invalid` | `promotion_request_invalid` |
| `promotion_request_invalid` | `promotion_request_invalid` |
| `promotion_evidence_hash_mismatch` | `promotion_request_invalid` |
| `promotion_attestation_invalid` | `promotion_request_invalid` |
| `promotion_attestation_mismatch` | `promotion_request_invalid` |
| `promotion_target_mismatch` | `promotion_target_mismatch` |
| `promotion_hook_authorization_invalid` | `promotion_hook_authorization_invalid` |
| `promotion_observation_invalid` | `promotion_observation_invalid` |
| `remote_unobservable` | `remote_unobservable` |
| `remote_ref_missing_or_ambiguous` | `remote_ref_missing_or_ambiguous` |
| `promotion_tracking_stale` | `promotion_tracking_stale` |
| `promotion_remote_changed` | `promotion_remote_changed` |
| `promotion_post_check_unobservable` | `promotion_post_check_unobservable` |
| `promotion_post_check_ambiguous` | `promotion_post_check_ambiguous` |
| `promotion_post_push_mismatch` | `promotion_post_push_mismatch` |
| `promotion_lease_rejected` | `promotion_lease_rejected` |
| `promotion_auth_failed` | `promotion_auth_failed` |
| `promotion_push_failed` | `promotion_push_failed` |
| `promotion_push_unknown` | `promotion_push_unknown` |
| `promotion_retry_exhausted` | `promotion_retry_exhausted` |

Do not automatically fetch. Do not change the expected-old parent. Do not fall back to an ordinary plan scenario. Remote movement, a newly observed parent, or an incomplete request must remain blocked rather than being reclassified.

## Workflow

1. 检查 Phase 6.5 ownership。若检测到 confirmed implementation evidence，按 `rules/phase65-delegation.md` no-op 或 delegate。
2. 检查是否存在当前 `AGENTS.md`、active workflow、active skill contract 或用户指令要求 Git 收口。若没有，返回 `inactive`。
3. 若 closed promotion request 存在，先执行 Candidate Promotion Gate；否则按 ordinary inline / plan 场景状态机分类当前工作。
4. 仅对 ordinary inline / plan 场景检查 `git status --short`、目标分支、upstream、ahead / behind / diverged 状态和 dirty paths。ordinary plan worktree 必须先应用 `.agentic/plan-worktree.yaml` metadata precedence，并委托 target-aware lifecycle merge/push；ordinary non-plan 场景才使用普通 HEAD/default branch。不要运行 `git add .`。
5. 只提交可归属到当前工作的 dirty paths，记录 skipped dirty paths。
6. 对 `plan_completed_integrate`，只在结构化成功和验证证据完整时，才把 plan / worktree 分支 merge into the frozen target branch。
7. 仅对 `plan_completed_integrate` 按 `rules/head-worktree-sync.md` 的 target-aware lifecycle push the frozen target branch；ordinary non-plan 场景仅在 ordinary HEAD/default branch changed 时 push 其 upstream。push 失败则结果为 `blocked`，不算 `completed`。
8. 对非默认分支的安全 capture，如果不需要默认分支集成，结果可以是 `local_captured`。
9. 持久化 redacted evidence。

Workflow steps 4 and 7 apply only to ordinary scenarios. `candidate_promotion_recovery` must not call `agentic-plan-worktree merge` or its target-aware push path, and it must not merge or clean up. It may execute only the evaluator-authorized canonical single-ref argv, followed by exact post-check and evidence persistence.

读取 local legacy evidence 时，如果只有 `default_branch`，normalize 为 canonical `target_branch`；新 evidence 双写同值 alias。该 legacy evidence normalization 不迁移 Phase 6.5 schema。

## Result Classes

- `completed`: plan 场景 frozen target branch 已提交 / 合并并 push 到 metadata upstream；non-plan 场景 ordinary HEAD/default branch changed 后已 push upstream；其它 capture 也已记录。
- `local_captured`: 归属明确的工作只提交在不要求集成的分支，且未改变 plan frozen target 或 non-plan ordinary HEAD/default branch。
- `inactive`: 没有激活来源；未执行 Git sync。
- `blocked`: 必须执行的 sync 无法安全完成；evidence 已保留。
- `delegated_phase65`: Phase 6.5 拥有该流程。
- `candidate_published`: validated candidate 已通过 strict expected-old CAS 发布并完成 post-check。`candidate_published` is not plan completion；不得归一化为 `completed`。

## Forbidden Actions

- Do not force push or perform non-fast-forward updates. The only allowed lease form is the single-ref `fast_forward_expected_old_lease` emitted by `agentic-git-sync promotion validate` for a fully gated `candidate_promotion_recovery`; `--force`, implicit leases, multi-ref pushes, changed-parent retries, and non-fast-forward ancestry remain forbidden.
- Do not run `git reset --hard`.
- Do not run `git clean`.
- Do not run `git stash`.
- Do not rebase existing history.
- Do not drop commits.
- Do not delete unmerged branches or worktrees.
- Do not trigger Jenkins, GitLab, GitHub Actions, or Control Plane CI APIs.