fix: Phase 번호 일관성·Incremental QA 훅·사용자 핸드오프 3건

[gd452]

Summary

하네스 스킬에 대한 3자 교차 리뷰(Claude + Gemini + Codex) 결과 공통 지적된 상위 우선순위 3건을 반영. 문서 내부 모순 2건과 사용자 온보딩 공백 1건 해소. 48줄 변경, 3파일.

English title: fix: Phase number consistency, Incremental QA hook, user handoff (3 fixes)

Motivation

• Closes # (없음 — 사전 issue 없이 직접 PR)
• Related to # (없음)
• 이번 리뷰는 Claude Code 내에서 gd452/harness v1.2.0/1.2.1을 대상으로 수행. Gemini 2.5 Pro와 GPT-5 두 외부 모델에 동일 브리프로 교차 리뷰를 받아 3자 모두 유효 판정한 이슈만 추림.

발견된 3가지 문제:

1. Phase 번호 불일치 — `SKILL.md` Phase 5-5 및 산출물 체크리스트는 "오케스트레이터 Phase 1에 컨텍스트 확인"이라고 기술하지만, `orchestrator-template.md`의 템플릿 A/B는 실제로 `Phase 0: 컨텍스트 확인`, `Phase 1: 준비` 구조. SKILL.md를 읽고 템플릿을 수정하려는 사용자에게 혼란을 유발.

2. Incremental QA 원칙 미반영 — `SKILL.md` Phase 3은 "QA는 전체 완성 후 1회가 아니라 각 모듈 완성 직후 점진적으로 실행"을 강조하지만, 실제 템플릿 A/B의 Phase 4는 "전체 완성 후 통합 검증"으로만 기술. 사용자가 템플릿 복사 시 자연스럽게 폭포수 QA로 회귀.

3. 사용자 핸드오프 단계 부재 — Phase 6(검증)이 끝나면 하네스 구축은 완료되지만, 사용자는 "어떤 문구로 이 하네스를 깨우는가"를 모름. `CLAUDE.md` 포인터 등록(Phase 5-4)은 시스템 설정이지 사용자 대상 안내가 아님.

Scope of change

• Skill / meta-skill logic — `skills/harness/SKILL.md` (Phase 5-5 문구, 체크리스트, Phase 6-7 신설)
• Agent template(s) — `skills/harness/references/orchestrator-template.md` (Incremental QA 공통 규칙 섹션 신설)
• Plugin manifest
• Documentation (README/docs)
• `CHANGELOG.md` — `[Unreleased]` 섹션 추가
• CI / GitHub Actions
• Tests
• Other

변경 상세

`skills/harness/SKILL.md`:

• L277: "Phase 1에 컨텍스트 확인 단계 추가" → "Phase 0에 컨텍스트 확인 단계 추가" + 의미 기반 부연("워크플로우 시작부(Phase 0)에서 … Phase 1(준비)보다 먼저 실행")
• L434(체크리스트): "Phase 1에 컨텍스트 확인 단계" → "Phase 0에 컨텍스트 확인 단계"
• L349~: 새 서브섹션 `#### 6-7. 사용자 핸드오프` (트리거 예문, 호출 구분, 재실행 키워드, 산출물 위치)

`skills/harness/references/orchestrator-template.md`:

• "## 작성 원칙" 직전에 새 섹션 `## QA 에이전트 포함 시 공통 규칙 (Incremental QA)` 신설. 템플릿 A/B/C별 적용 방법 명시.

`CHANGELOG.md`:

• 최상단 `[1.2.1]` 위에 `[Unreleased]` 섹션 추가 (Fixed 2건 + Added 1건).

Tests

• `diff`로 변경 3곳 이외 수정 없음 확인
• SKILL.md 459줄 (500줄 제한 내 유지)
• Manual: SKILL.md의 Phase 번호 언급부와 orchestrator-template.md의 실제 Phase 구조가 이제 일관됨 (grep 검증)
• `npx markdownlint '**/*.md'` — 로컬에서 미실행, CI에 위임
• N/A — 스킬 실행 테스트는 별도 환경 필요 (문서 변경만 해당)

CHANGELOG update

• Y — `[Unreleased]` 섹션에 Fixed 2건 + Added 1건 반영. 릴리스 버전 태깅은 maintainer 판단.

SemVer impact

• patch 또는 minor — maintainer 판단에 따름.
• 사유: 2건은 내부 문서 모순 수정(patch), 1건(핸드오프)은 하네스 구축 UX 보완이나 기존 동작을 깨지 않음(patch 또는 minor).
• 브레이킹 변경 없음.

리뷰 원본 (참고)

3자 교차 리뷰 원본과 합성 결과를 제공 가능. 요청 시 별도 공유.

[chipoto69]

github-steward autopilot tick 2026-06-03T21:27+02: stale merge conflict detected.

Observed state: PR is OPEN, base=main, head=fix/phase-consistency-qa-hook-handoff, mergeable=CONFLICTING, no checks configured/reported.

Decision: not auto-resolving in this tick. This PR is older than the newer mergeable harness PRs (#21-#25) and likely needs either a deliberate rebase/conflict pass or closure if superseded. Recommended next action: owner confirms whether PR #6 still matters; then steward can resolve from a clean worktree or close with rationale.

[chipoto69]

github-steward autopilot tick 2026-06-04 12:26 CEST: investigated DIRTY merge state. I resolved the conflict locally in /Users/rudlord/ORGANIZED/_agent-workspaces/github-steward/harness-pr6-conflict; only CHANGELOG.md had conflict markers. Validation: git diff --check passed; conflict marker search returned zero matches. Could not push to the fork head gd452/harness (403 for chipoto69), so I attempted a steward-owned branch on revfactory/harness instead if permitted. Resolution commit in local workspace: e46b05f (fix: resolve PR 6 changelog conflict).