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.