agentic-git-sync

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.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

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.