| name | agentic-git-sync |
| description | 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. |
| argument-hint | [optional: spec path, plan path, work id, verification evidence] |
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.mdrules/phase65-delegation.mdrules/head-worktree-sync.mdrules/evidence.mdtemplates/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 前必须：
- 运行
agentic-git-sync promotion validate --request <request.json>，消费其 closed validation output；skill 不得自行解析或拼装 request JSON。
- 在 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。
- 从 validated request 绑定的 frozen metadata 读取
target.remote_ref，且 lease ref 与 refspec actual destination 必须同为 refs/heads/<target-remote-branch>。
- 验证 persisted diagnostic 为
hook_authorization_changed、attempt count 为 1、candidate scope/child snapshot/equivalence/current-session verification/implementation review 全部通过。
- 验证 live remote 和 remote tracking 都仍为 expected-old，并在 push 前证明 expected-old 是 candidate 的严格祖先。
- 运行
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。
- 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 |
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
- 检查 Phase 6.5 ownership。若检测到 confirmed implementation evidence，按
rules/phase65-delegation.md no-op 或 delegate。
- 检查是否存在当前
AGENTS.md、active workflow、active skill contract 或用户指令要求 Git 收口。若没有，返回 inactive。
- 若 closed promotion request 存在，先执行 Candidate Promotion Gate；否则按 ordinary inline / plan 场景状态机分类当前工作。
- 仅对 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 .。
- 只提交可归属到当前工作的 dirty paths，记录 skipped dirty paths。
- 对
plan_completed_integrate，只在结构化成功和验证证据完整时，才把 plan / worktree 分支 merge into the frozen target branch。
- 仅对
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。
- 对非默认分支的安全 capture，如果不需要默认分支集成，结果可以是
local_captured。
- 持久化 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.
