fix: main 동기화 push에서 hook 예외를 분기 처리

- main과 develop tip이 같을 때 pre-push에서 동기화 publish를 허용
- 관련 hook 문서와 workflow 규칙을 branch-aware 정책으로 정리
- CLI 테스트와 workflow task evidence를 추가하고 closeout을 기록

Author: alexization

.codex/skills/README.md

@@ -11,6 +11,7 @@
 - 내부 런타임 구현은 `scripts/workflow_runtime/`이 가진다.
 - skill은 위 규칙을 복제하지 않고, 한 단계의 handoff와 CLI 진입점만 안내한다.
 - `python3 scripts/workflow.py init`는 runtime surface를 source 기준으로 다시 동기화하고, `doctor`는 drift를 실패로 보고한다.
+- `main` 브랜치의 `develop` 동기화 publish 예외처럼 branch-specific hook 정책은 `docs/hooks.md`와 `.githooks/`가 소유하고, skill은 그 정책을 다시 정의하지 않는다.
 
 ## Active Skill Set
 

.githooks/pre-push

@@ -4,6 +4,15 @@ set -eu
 python3 scripts/workflow.py doctor
 python3 scripts/workflow.py hook pre_command --command-text "git push $*"
 
+current_branch="$(git branch --show-current 2>/dev/null || true)"
+if [ "$current_branch" = "main" ]; then
+  main_tip="$(git rev-parse HEAD 2>/dev/null || true)"
+  develop_tip="$(git rev-parse --verify refs/heads/develop 2>/dev/null || true)"
+  if [ -n "$main_tip" ] && [ "$main_tip" = "$develop_tip" ]; then
+    exit 0
+  fi
+fi
+
 task_id="${WORKFLOW_TASK_ID:-}"
 if [ -n "$task_id" ]; then
   phase_id="${WORKFLOW_PHASE_ID:-}"

AGENTS.md

@@ -47,6 +47,7 @@ NEVER: control plane 문서를 앱 source-of-truth보다 우선시하지 않는
 9. 모든 phase가 완료되면 `review`가 review readiness를 기록한다.
 10. `review --close --user-validation-note ...`만 최종 완료를 닫을 수 있다.
 11. 실패, block, 추가 요구사항이 생기면 `reopen`으로 target phase를 `pending`으로 되돌리고 repair loop를 재개한다.
+12. `pre_push`의 branch-aware 예외는 현재 브랜치가 `main`이고 로컬 `main` tip이 로컬 `develop` tip과 같을 때의 동기화 publish에만 허용한다.
 
 ## TDD Contract
 

docs/hooks.md

@@ -38,6 +38,7 @@
 
 - `pre_review`에서는 active phase에 대한 latest passed verification을 요구한다.
 - `pre_push`에서는 unpushed diff를 기준으로 task를 먼저 해석하고, 그 scope와 겹칠 때 latest passed verification을 요구한다.
+- 단, `.githooks/pre-push`는 현재 브랜치가 `main`이고 로컬 `main` tip이 로컬 `develop` tip과 같으면 task 추론 전에 동기화 publish로 간주하고 통과시킨다.
 - active task가 없더라도 unpushed diff가 정확히 하나의 completed task scope에 매핑되면 그 task를 push gate context로 재사용한다.
 - unpushed diff가 어느 task에도 단일하게 매핑되지 않으면 `pre_push`는 fail-closed 한다.
 
@@ -64,4 +65,4 @@ git hook만으로는 충분하지 않다. 로컬 CLI와 phase runner가 같은 h
 `init`는 `.githooks/pre-commit`, `.githooks/pre-push`, `workflows/system/hooks.json`을 source 기준으로 다시 동기화한다.
 `doctor`는 위 runtime surface가 source와 drift하면 실패하고 `python3 scripts/workflow.py init`를 다시 요구한다.
 `pre_commit`은 active task가 하나로 추론되지 않으면 fail-closed 한다. 이때는 `WORKFLOW_TASK_ID` 또는 `--task-id`로 task binding을 명시해야 한다.
-`pre_push`는 먼저 unpushed diff를 task scope에 매핑한다. scope가 단일 task로 정해지지 않으면 역시 fail-closed 한다.
+`pre_push`는 먼저 현재 브랜치가 `main`인지와 로컬 `main`/`develop` tip 일치를 확인한다. 이 동기화 publish가 아니면 기존처럼 unpushed diff를 task scope에 매핑하고, scope가 단일 task로 정해지지 않으면 fail-closed 한다.

docs/runbook.md

@@ -72,4 +72,5 @@ python3 scripts/workflow.py hook pre_push --command-text "git push origin featur
 ```
 
 `pre_commit`은 active task가 여러 개라면 자동 추론을 중단하고 실패한다. 이 경우 `WORKFLOW_TASK_ID` 또는 `--task-id`로 명시적으로 task binding을 넣는다.
-`pre_push`는 먼저 unpushed diff를 task scope에 매핑한다. active task가 없어도 completed task scope 하나로 매핑되면 그 task를 재사용하고, 단일 task로 정해지지 않으면 실패한다.
+`pre_push`는 먼저 현재 브랜치가 `main`인지와 로컬 `main`/`develop` tip이 같은지 확인한다. 이 조건을 만족하면 `develop` 동기화 publish로 보고 task-bound guard를 건너뛴다.
+그 외 경우에는 기존처럼 unpushed diff를 task scope에 매핑한다. active task가 없어도 completed task scope 하나로 매핑되면 그 task를 재사용하고, 단일 task로 정해지지 않으면 실패한다.

tests/test_workflow_cli.py

@@ -696,6 +696,41 @@ def test_githook_pre_push_blocks_force_push(self) -> None:
             result = self.run_hook_script(root, "pre-push", "origin", "feature", "--force", expected=1)
             self.assertIn("blocked command", result.stdout)
 
+    def test_githook_pre_push_passes_for_main_sync_publish_when_head_matches_develop(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self.init_git_repo(root)
+            self.install_runtime_surface(root)
+            self.run_cli(root, "init")
+
+            self.git_add(root, ".")
+            self.git_commit_no_verify(root, "bootstrap runtime surface")
+            subprocess.run(["git", "branch", "-M", "main"], cwd=root, capture_output=True, text=True, check=True)
+            subprocess.run(["git", "branch", "develop", "HEAD"], cwd=root, capture_output=True, text=True, check=True)
+
+            result = self.run_hook_script(root, "pre-push", "origin", "main")
+            self.assertIn("command allowed", result.stdout)
+            self.assertNotIn("requires explicit --task-id", result.stderr)
+
+    def test_githook_pre_push_keeps_task_guard_when_main_differs_from_develop(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self.init_git_repo(root)
+            self.install_runtime_surface(root)
+            self.run_cli(root, "init")
+
+            self.git_add(root, ".")
+            self.git_commit_no_verify(root, "bootstrap runtime surface")
+            subprocess.run(["git", "branch", "-M", "main"], cwd=root, capture_output=True, text=True, check=True)
+            subprocess.run(["git", "branch", "develop", "HEAD"], cwd=root, capture_output=True, text=True, check=True)
+
+            (root / "notes.txt").write_text("main diverged from develop\n", encoding="utf-8")
+            self.git_add(root, "notes.txt")
+            self.git_commit_no_verify(root, "main diverged")
+
+            result = self.run_hook_script(root, "pre-push", "origin", "main", expected=1)
+            self.assertIn("do not map to a single task", result.stderr)
+
     def test_githook_pre_push_requires_verification_for_unpushed_scope_changes(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
             root = Path(tmp)

workflows/tasks/task-main-branch-hook-exemption/phases.json

@@ -0,0 +1,36 @@
+{
+  "task_id": "task-main-branch-hook-exemption",
+  "generated_at": "2026-04-16T04:36:44+00:00",
+  "phases": [
+    {
+      "id": "phase-1",
+      "title": "branch-aware-main-publish-hook",
+      "goal": "Allow main sync publishes to bypass task-scoped pre-push enforcement only when main tip matches develop tip, while keeping other hook behavior unchanged.",
+      "inputs": [
+        "workflows/tasks/task-main-branch-hook-exemption/spec.md",
+        "docs/hooks.md",
+        "tests/test_workflow_cli.py"
+      ],
+      "allowed_write_paths": [
+        ".githooks/",
+        "docs/",
+        "tests/",
+        ".codex/skills/",
+        "AGENTS.md"
+      ],
+      "acceptance": {
+        "commands": [
+          "python3 -m unittest tests.test_workflow_cli -v",
+          "python3 scripts/workflow.py doctor"
+        ]
+      },
+      "test_policy": {
+        "mode": "require_tests",
+        "evidence": []
+      },
+      "order": 1,
+      "status": "completed",
+      "retry_count": 0
+    }
+  ]
+}

workflows/tasks/task-main-branch-hook-exemption/runs/20260416T044014-921f70aa.json

@@ -0,0 +1,18 @@
+{
+  "id": "20260416T044014-921f70aa",
+  "task_id": "task-main-branch-hook-exemption",
+  "phase_id": "phase-1",
+  "event": "phase_completion",
+  "commands": [
+    {
+      "command": "phase completion",
+      "status": "passed",
+      "output": ".codex/skills/README.md, .githooks/pre-push, AGENTS.md, docs/hooks.md, docs/runbook.md, tests/test_workflow_cli.py, workflows/tasks/task-main-branch-hook-exemption/phases.json, workflows/tasks/task-main-branch-hook-exemption/spec.md, workflows/tasks/task-main-branch-hook-exemption/task.json"
+    }
+  ],
+  "result": "passed",
+  "evidence": [],
+  "error_fingerprint": null,
+  "next_action": "verify",
+  "timestamp": "2026-04-16T04:40:14+00:00"
+}

workflows/tasks/task-main-branch-hook-exemption/runs/20260416T044031-46f9f315.json

@@ -0,0 +1,23 @@
+{
+  "id": "20260416T044031-46f9f315",
+  "task_id": "task-main-branch-hook-exemption",
+  "phase_id": "phase-1",
+  "event": "verification",
+  "commands": [
+    {
+      "command": "python3 -m unittest tests.test_workflow_cli -v",
+      "status": "passed",
+      "output": "test_approve_requires_structured_socratic_log_and_locks_intake (tests.test_workflow_cli.WorkflowCliTest.test_approve_requires_structured_socratic_log_and_locks_intake) ... ok\ntest_check_fails_when_approved_task_points_to_completed_phase (tests.test_workflow_cli.WorkflowCliTest.test_check_fails_when_approved_task_points_to_completed_phase) ... ok\ntest_circuit_breaker_triggers_from_verification_failures (tests.test_workflow_cli.WorkflowCliTest.test_circuit_breaker_triggers_from_verification_failures) ... ok\ntest_dangerous_command_guard_blocks_short_force_push (tests.test_workflow_cli.WorkflowCli..."
+    },
+    {
+      "command": "python3 scripts/workflow.py doctor",
+      "status": "passed",
+      "output": "{\n  \"status\": \"passed\",\n  \"checks\": [\n    \"workflow system hook config is readable\",\n    \"git core.hooksPath points to .githooks\",\n    \"task artifacts are internally consistent\",\n    \"runtime surface matches source\",\n    \"AGENTS constitution is complete\",\n    \"no stale legacy references remain in control-plane files\"\n  ],\n  \"errors\": []\n}"
+    }
+  ],
+  "result": "passed",
+  "evidence": [],
+  "error_fingerprint": null,
+  "next_action": "review",
+  "timestamp": "2026-04-16T04:40:31+00:00"
+}

workflows/tasks/task-main-branch-hook-exemption/runs/20260416T044034-57b90731.json

@@ -0,0 +1,20 @@
+{
+  "id": "20260416T044034-57b90731",
+  "task_id": "task-main-branch-hook-exemption",
+  "phase_id": "phase-1",
+  "event": "review_ready",
+  "commands": [
+    {
+      "command": "review gate",
+      "status": "passed",
+      "output": "latest passed verification: 20260416T044031-46f9f315"
+    }
+  ],
+  "result": "passed",
+  "evidence": [
+    "main==develop 동기화 publish 예외 검토 완료"
+  ],
+  "error_fingerprint": null,
+  "next_action": "user validation",
+  "timestamp": "2026-04-16T04:40:34+00:00"
+}