(#98) 소크라테스 spec coverage와 phase kickoff 계약 강화

* feat: 소크라테스 spec coverage와 phase kickoff 계약 강화

- clarification coverage category와 kickoff gate를 runtime에 추가
- phase bootstrap metadata와 doctor consistency 검증을 보강
- docs, skills, tests, workflow task artifact를 새 계약에 맞춤

* chore: git-ranker 서브모듈 포인터를 리뷰 브랜치에 반영

- workflow task를 reopen하고 follow-up phase로 범위를 재잠금
- git-ranker gitlink를 backend PR #89 커밋으로 맞춤
- review_ready evidence를 다시 남기고 PR 리뷰 준비 상태로 복구

* fix: legacy 빈 inputs phase plan 호환성을 유지

- bootstrap default가 빈 required_reads를 저장하지 않도록 보정
- legacy empty-input phase planning 회귀 테스트를 추가
- PR review follow-up을 task evidence와 함께 다시 review_ready로 기록

Author: alexization

.codex/skills/README.md

@@ -29,8 +29,8 @@
 1. `request-intake`
 2. `socratic-spec-authoring`
 3. `phase-planner`
-4. `boundary-check -> phase-executor -> verification-runner`를 active phase마다 반복
+4. `boundary-check -> phase-executor -> verification-runner`를 active phase마다 반복한다. 단, `task.json.kickoff_required_for_phase`가 active phase와 같으면 새 세션이 먼저 `kickoff`를 실행해야 한다.
 5. 모든 phase가 끝나면 `review-closeout`
 6. 실패, block, follow-up이면 `repair-reopen`
 
-새 workflow에서는 markdown spec과 JSON state를 분리한다. `spec.md`는 사람용 요구사항 초안이고, `approve`가 이를 `task.json.intake`로 잠근다. `task.json`/`phases.json`/`runs/*.json`은 자동화용 canonical source다.
+새 workflow에서는 markdown spec과 JSON state를 분리한다. `spec.md`는 사람용 요구사항 초안이고, `approve`가 이를 `task.json.intake`로 잠근다. 새 spec contract에서는 clarification coverage category를 모두 채워야 승인된다. `task.json`/`phases.json`/`runs/*.json`은 자동화용 canonical source고, phase boundary kickoff proof도 여기 남긴다.

.codex/skills/phase-executor/SKILL.md

@@ -19,10 +19,11 @@ description: 현재 active phase 하나만 실행하고 hook을 통과시켜 pha
 
 ## 작업 방식
 
-1. `python3 scripts/workflow.py run <task-id> --start`로 phase를 시작한다.
-2. phase의 허용 write path 안에서만 구현한다.
-3. phase를 닫을 때는 `python3 scripts/workflow.py run <task-id> --complete --changed-path ...`를 사용한다.
-4. TDD Guard가 막히면 테스트를 추가하거나 `test_policy.mode=evidence_only`와 `test_policy.evidence`를 먼저 보강한다.
+1. `task.json.kickoff_required_for_phase`가 active phase와 같으면 새 세션이 먼저 `python3 scripts/workflow.py kickoff <task-id>`를 실행해 bootstrap proof를 남긴다.
+2. `python3 scripts/workflow.py run <task-id> --start`로 phase를 시작한다.
+3. phase의 허용 write path 안에서만 구현한다.
+4. phase를 닫을 때는 `python3 scripts/workflow.py run <task-id> --complete --changed-path ...`를 사용한다.
+5. TDD Guard가 막히면 테스트를 추가하거나 `test_policy.mode=evidence_only`와 `test_policy.evidence`를 먼저 보강한다.
 
 ## 결과
 

.codex/skills/phase-planner/SKILL.md

@@ -20,12 +20,13 @@ description: 승인된 task를 executable phase 집합으로 쪼개고 `phases.j
 ## 작업 방식
 
 1. task를 작은 phase들로 쪼갠다.
-2. 각 phase에 `allowed_write_paths`, `acceptance.commands`, `test_policy`를 채운 JSON을 작성한다.
+2. 각 phase에 `allowed_write_paths`, `acceptance.commands`, `test_policy`, `required_reads`, `starting_points`, `deliverables`, `completion_signal`을 채운 JSON을 작성한다.
 3. 추가 요구사항으로 spec을 바꿨다면 `approve`를 다시 실행해 intake를 재잠근 뒤 `python3 scripts/workflow.py plan <task-id> --from <phase-json>` 또는 `--stdin`을 실행한다.
 4. `phases.json`은 오직 `plan` 명령만 canonical write owner다.
 
 ## 결과
 
 - `workflows/tasks/<task-id>/phases.json`
 - `task.json.active_phase_id`
+- 다음 세션 kickoff가 읽을 bootstrap metadata
 - 다음 stage: `phase-executor`

.codex/skills/socratic-spec-authoring/SKILL.md

@@ -20,8 +20,8 @@ description: 소크라테스 질문으로 `spec.md`를 잠그고, 사용자 명
 ## 작업 방식
 
 1. 질문으로 request, problem, goals, non-goals, constraints, acceptance를 `spec.md`에 기록한다.
-2. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet으로만 적는다.
-3. blocker가 없어질 때까지 질문 루프를 반복한다.
+2. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet으로만 적고, 새 contract에서는 각 `Q:`에 `[scope]`, `[goal]`, `[non_goal]`, `[constraint]`, `[acceptance]` coverage category를 붙인다.
+3. `status`에서 `coverage_missing`이 비고 unresolved clarification이 없어질 때까지 질문 루프를 반복한다.
 4. placeholder가 남아 있지 않은지 확인한다.
 5. 사용자가 현재 `spec.md` 초안에 명시적으로 동의했을 때만 `python3 scripts/workflow.py approve <task-id> --note ...`를 실행한다.
 6. `approve`가 `spec.md`를 `task.json.intake`로 잠근다는 점을 전제로, 승인 전에는 phase 생성이나 구현을 시작하지 않는다.

.githooks/pre-commit

@@ -1,6 +1,8 @@
 #!/bin/sh
 set -eu
 
+# Phase-boundary kickoff proof is enforced by workflow runtime, not by git hooks.
+
 task_id="${WORKFLOW_TASK_ID:-}"
 if [ -z "$task_id" ]; then
   task_id="$(python3 scripts/workflow.py status --infer-active-task 2>/dev/null || true)"

.githooks/pre-push

@@ -1,6 +1,8 @@
 #!/bin/sh
 set -eu
 
+# Phase-boundary kickoff proof is enforced by workflow runtime, not by git hooks.
+
 python3 scripts/workflow.py doctor
 python3 scripts/workflow.py hook pre_command --command-text "git push $*"
 

AGENTS.md

@@ -37,17 +37,20 @@ NEVER: control plane 문서를 앱 source-of-truth보다 우선시하지 않는
 ## Workflow Contract
 
 1. `new`가 `workflows/tasks/<task-id>/spec.md`와 `task.json` skeleton을 만든다.
-2. 소크라테스 질문으로 `spec.md`를 잠근다. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet만 사용한다.
+2. 소크라테스 질문으로 `spec.md`를 잠근다. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet만 사용하고, 새 spec contract에서는 `[scope]`, `[goal]`, `[non_goal]`, `[constraint]`, `[acceptance]` coverage를 모두 채운다.
 3. 사용자가 동의하면 `approve`가 같은 task 디렉터리의 `spec.md`에 Approval block을 추가하고, `spec.md` 내용을 `task.json.intake`로 잠근 뒤 `task.json`을 `approved`로 전이한다.
 4. 추가 요구사항으로 spec을 다시 잠그면 `approve`를 다시 실행해 `task.json.intake`를 재잠근다.
-5. `plan --from <json>` 또는 `plan --stdin`이 phase 초안을 읽어 `phases.json`으로 적재한다. `spec.md`와 `task.json.intake`가 어긋나 있으면 plan을 시작하지 않는다.
-6. `run --start`가 active phase를 시작한다.
-7. 구현 후 `run --complete --changed-path ...`가 write scope와 TDD guard를 통과해야 한다.
-8. `verify`가 completed phase의 acceptance command를 실행하고 `runs/*.json`에 evidence를 남긴다.
-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에만 허용한다.
+5. `plan --from <json>` 또는 `plan --stdin`이 phase 초안을 읽어 `phases.json`으로 적재한다. 각 phase는 `required_reads`, `starting_points`, `deliverables`, `completion_signal` bootstrap 정보를 가져야 하며, `spec.md`와 `task.json.intake`가 어긋나 있으면 plan을 시작하지 않는다.
+6. phase-1은 `run --start`로 바로 시작할 수 있다.
+7. 이전 phase verification이 통과해 다음 pending phase가 활성화되면, 새 세션이 먼저 `kickoff`를 실행해 bootstrap proof를 남겨야 한다.
+8. 그 다음 `run --start`가 active phase를 시작한다.
+9. 구현 후 `run --complete --changed-path ...`가 write scope와 TDD guard를 통과해야 한다.
+10. `verify`가 completed phase의 acceptance command를 실행하고 `runs/*.json`에 evidence를 남긴다.
+11. verification이 다음 pending phase를 활성화하면 `task.json.kickoff_required_for_phase`를 기록하고 task를 다시 `approved`로 전이한다.
+12. 모든 phase가 완료되면 `review`가 review readiness를 기록한다.
+13. `review --close --user-validation-note ...`만 최종 완료를 닫을 수 있다.
+14. 실패, block, 추가 요구사항이 생기면 `reopen`으로 target phase를 `pending`으로 되돌리고 repair loop를 재개한다. reopened phase가 2번째 이상 phase면 kickoff를 다시 요구한다.
+15. `pre_push`의 branch-aware 예외는 현재 브랜치가 `main`이고 로컬 `main` tip이 로컬 `develop` tip과 같을 때의 동기화 publish에만 허용한다.
 
 ## TDD Contract
 
@@ -68,6 +71,7 @@ python3 scripts/workflow.py new <task-id> --title "..." --primary-repo <repo>
 python3 scripts/workflow.py approve <task-id> --note "..."
 python3 scripts/workflow.py plan <task-id> --from /path/to/phases.json
 python3 scripts/workflow.py plan <task-id> --stdin
+python3 scripts/workflow.py kickoff <task-id>
 python3 scripts/workflow.py run <task-id> --start
 python3 scripts/workflow.py run <task-id> --complete --changed-path ...
 python3 scripts/workflow.py verify <task-id>
@@ -85,6 +89,7 @@ python3 scripts/workflow.py hook pre_push --command-text "..."
 - `init`는 `.githooks/*`와 `workflows/system/hooks.json`을 source 기준으로 다시 동기화하고, `doctor`는 drift를 실패로 취급한다.
 - 실제 실행 엔진은 `scripts/workflow_runtime/cli.py`, `engine.py`, `models.py`, `guards.py`, `doctor.py`, `git_ops.py`가 분담한다.
 - `workflow.py`를 유지하는 이유는 사람과 AI가 하나의 안정적인 명령 surface만 기억하면 되기 때문이다.
+- `status`는 새 spec contract에서 `coverage_missing`과 active phase bootstrap summary를 노출해 다음 세션 시작점을 복원한다.
 
 ## Source Of Truth Order
 

docs/artifact-model.md

@@ -18,17 +18,17 @@ workflows/
 
 ## Artifact Roles
 
-- `workflows/tasks/<task-id>/spec.md`: 사람용 requirement artifact. 요청, 문제, 목표, 비목표, 제약, acceptance, 소크라테스 질문 로그, 승인 기록을 담는다.
-- `workflows/tasks/<task-id>/task.json`: mutable task state이자 승인 시점의 locked intake source다. approval, active phase, latest run, latest verified run, blocked reason, user validation과 `intake`를 담는다.
-- `workflows/tasks/<task-id>/phases.json`: 승인 이후 생성된 executable phase 집합이다. phase 목표, write scope, acceptance command, test policy, retry count를 담는다.
-- `workflows/tasks/<task-id>/runs/*.json`: phase completion, verification, review, reopen evidence다.
+- `workflows/tasks/<task-id>/spec.md`: 사람용 requirement artifact. 요청, 문제, 목표, 비목표, 제약, acceptance, 소크라테스 질문 로그, 승인 기록을 담는다. 새 spec contract에서는 clarification question마다 coverage category를 잠근다.
+- `workflows/tasks/<task-id>/task.json`: mutable task state이자 승인 시점의 locked intake source다. approval, active phase, latest run, latest verified run, kickoff requirement, blocked reason, user validation과 `intake`를 담는다.
+- `workflows/tasks/<task-id>/phases.json`: 승인 이후 생성된 executable phase 집합이다. phase 목표, write scope, acceptance command, test policy, retry count와 다음 세션 kickoff용 bootstrap metadata를 담는다.
+- `workflows/tasks/<task-id>/runs/*.json`: phase completion, phase kickoff, verification, review, reopen evidence다.
 - `workflows/system/hooks.json`: 전역 hook/guard/breaker 정책이다.
 - `workflows/system/circuit-breaker.json`: 반복 실패 fingerprint 메모리다.
 
 ## Spec And Phase Loading Flow
 
 1. `new`가 task 디렉터리와 `spec.md`, `task.json`, `phases.json` skeleton을 만든다.
-2. 소크라테스 질문으로 `spec.md`를 채운다. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet만 허용한다.
+2. 소크라테스 질문으로 `spec.md`를 채운다. `Socratic Clarification Log`는 `Q:`, `A:`, `Decision:` triplet만 허용하고, 새 contract에서는 `[scope]`, `[goal]`, `[non_goal]`, `[constraint]`, `[acceptance]` coverage를 모두 채운다.
 3. 사용자가 현재 spec 초안에 명시적으로 동의하면 `approve`가 같은 `spec.md`에 Approval block을 추가하고, 내용을 `task.json.intake`로 잠근 뒤 `task.json`을 `approved`로 전이한다.
 4. 추가 요구사항으로 spec을 다시 잠그면 `approve`를 다시 실행해 `task.json.intake`를 갱신한다.
 5. `plan --from` 또는 `plan --stdin`이 외부 phase 초안을 읽어 같은 task 디렉터리의 `phases.json`으로 적재한다.
@@ -40,6 +40,7 @@ workflows/
 
 - `id`
 - `title`
+- `contract_version`
 - `state`
 - `primary_repo`
 - `created_at`
@@ -48,6 +49,8 @@ workflows/
 - `active_phase_id`
 - `latest_run_id`
 - `last_verified_run_id`
+- `kickoff_required_for_phase`
+- `last_kickoff_run_id`
 - `blocked_reason`
 - `user_validated`
 - `user_validation_note`
@@ -62,6 +65,7 @@ workflows/
 `intake.clarifications`의 각 항목은 아래 필드를 가진다.
 
 - `question`
+- `category`
 - `answer`
 - `decision`
 - `resolved`
@@ -75,6 +79,10 @@ workflows/
 - `title`
 - `goal`
 - `inputs`
+- `required_reads`
+- `starting_points`
+- `deliverables`
+- `completion_signal`
 - `allowed_write_paths`
 - `acceptance.commands`
 - `test_policy.mode`
@@ -87,6 +95,8 @@ workflows/
 - `require_tests`: 구현 변경이 있으면 대응 테스트 변경이 필요하다.
 - `evidence_only`: 테스트 delta 대신 명시적 evidence 배열을 근거로 허용한다.
 
+`required_reads`, `starting_points`, `deliverables`, `completion_signal`은 다음 phase를 새 세션에서 시작할 때 `task.json`/`phases.json`/`spec.md`만으로 bootstrap할 수 있게 만드는 canonical metadata다.
+
 ## Validation Ownership
 
 - JSON schema 파일은 사용하지 않는다.

docs/hooks.md

@@ -61,6 +61,7 @@
 - `.github/workflows/workflow-control-plane.yml`
 
 git hook만으로는 충분하지 않다. 로컬 CLI와 phase runner가 같은 hook 설정을 읽어야 guard가 유지된다.
+phase boundary의 fresh-session kickoff proof는 git hook이 아니라 workflow runtime이 `kickoff`와 `run --start` 사이에서 직접 강제한다.
 `python3 scripts/workflow.py init`는 로컬 git 저장소의 `core.hooksPath`를 `.githooks`로 맞추고, `doctor`는 이 설정이 빠지면 실패한다.
 `init`는 `.githooks/pre-commit`, `.githooks/pre-push`, `workflows/system/hooks.json`을 source 기준으로 다시 동기화한다.
 `doctor`는 위 runtime surface가 source와 drift하면 실패하고 `python3 scripts/workflow.py init`를 다시 요구한다.

docs/runbook.md

@@ -16,10 +16,10 @@ python3 -m unittest discover -s tests -v
 python3 scripts/workflow.py new task-001 --title "..." --primary-repo git-ranker-workflow
 ```
 
-이후 `workflows/tasks/task-001/spec.md`를 소크라테스 질문으로 잠근다. `Socratic Clarification Log`는 아래처럼 `Q/A/Decision` triplet만 사용한다.
+이후 `workflows/tasks/task-001/spec.md`를 소크라테스 질문으로 잠근다. 새 spec contract에서는 `Socratic Clarification Log`가 아래처럼 coverage category를 포함한 `Q/A/Decision` triplet을 모두 채워야 한다.
 
 ```md
-- Q: phase canonical source는 무엇인가?
+- Q: [scope] phase canonical source는 무엇인가?
 - A: executable plan은 prose가 아니라 JSON이어야 한다.
 - Decision: `phases.json`만 canonical plan으로 쓴다.
 ```
@@ -39,14 +39,18 @@ python3 scripts/workflow.py plan task-001 --from /tmp/task-001-phases.json
 cat /tmp/task-001-phases.json | python3 scripts/workflow.py plan task-001 --stdin
 ```
 
+새 phase JSON은 `required_reads`, `starting_points`, `deliverables`, `completion_signal`을 포함해 다음 세션 kickoff 시작점을 잠가야 한다.
+
 ## 실행과 검증
 
-`verify`는 `run --complete`로 닫힌 phase에 대해서만 실행한다.
+`verify`는 `run --complete`로 닫힌 phase에 대해서만 실행한다. verification이 다음 pending phase를 활성화하면, 그 phase는 새 세션 kickoff를 거쳐야만 시작할 수 있다.
 
 ```bash
 python3 scripts/workflow.py run task-001 --start
 python3 scripts/workflow.py run task-001 --complete --changed-path scripts/workflow.py --changed-path tests/test_workflow_cli.py
 python3 scripts/workflow.py verify task-001
+python3 scripts/workflow.py kickoff task-001
+python3 scripts/workflow.py run task-001 --start
 python3 scripts/workflow.py review task-001 --note "review ready"
 python3 scripts/workflow.py review task-001 --close --user-validation-note "validated"
 ```
@@ -74,3 +78,4 @@ 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`는 먼저 현재 브랜치가 `main`인지와 로컬 `main`/`develop` tip이 같은지 확인한다. 이 조건을 만족하면 `develop` 동기화 publish로 보고 task-bound guard를 건너뛴다.
 그 외 경우에는 기존처럼 unpushed diff를 task scope에 매핑한다. active task가 없어도 completed task scope 하나로 매핑되면 그 task를 재사용하고, 단일 task로 정해지지 않으면 실패한다.
+다음 phase kickoff는 git hook이 아니라 `task.json.kickoff_required_for_phase`와 `phase_kickoff` evidence로 강제된다.