[4.12] Task별 .harness 맥락 디렉토리 도입

.agents/skills/harness-work/SKILL.md

@@ -9,11 +9,11 @@ Codex에서 Claude Code `/harness-work`에 해당하는 절차를 직접 수행
 
 ## 절차
 
-1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `.harness/STATE.md`, 최근 `.harness/LESSONS.md`, `tasks/index.json`, `Plans.md`를 읽는다.
+1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `tasks/index.json`, `Plans.md`, 최근 `.harness/LESSONS.md`를 읽는다. 진행 중인 Task가 있으면 `.harness/tasks/<task-key>/STATE.md`도 읽는다.
 2. 수행할 `todo` Task 하나를 고른다. 사용자가 지정한 Task가 있으면 그 Task를 우선한다.
 3. 구현 전 `agents/task-decomposer.md`의 세분화 기준과 `agents/quality-gates.md`의 scope/YAGNI 체크를 확인한다.
 4. 기준 미달이면 구현하지 말고 `$harness-plan` 절차로 하위 Task proposal을 만든다.
-5. 기준 통과 시 `.harness/STATE.md`를 갱신하고 구현한다.
+5. 기준 통과 시 `.harness/tasks/<task-key>/STATE.md`를 갱신하고 구현한다. Task 디렉토리가 없으면 루트 `.harness/*.md` 템플릿을 복사해 만든다.
 6. 작업 중 범위가 커지면 중단하고 `agents/quality-gates.md`의 split 조건과 task-decomposer 기준으로 재분해한다.
 7. 구현 후 `agents/test-agent.md` 절차대로 해당 Task Acceptance 명령과 관련 테스트 스위트를 실행한다.
 8. 검증 실패 시 수정 후 재실행한다.
@@ -26,5 +26,6 @@ Codex에서 Claude Code `/harness-work`에 해당하는 절차를 직접 수행
   `done`으로 갱신하고 `Plans.md`를 재생성한다. GitHub Actions는 Task 상태를
   전환하지 않는다.
 - 새 파일이나 역할 변경은 `.harness/CONTEXT_INDEX.md`에 반영한다.
+- 루트 `.harness/STATE.md`, `HANDOFF.md`, `TASKS.md`, `LOG.md`, `CHECKPOINTS.md`는 템플릿이므로 실제 진행 상태를 쓰지 않는다.
 - ponytail/caveman Codex plugin 자동 동작을 가정하지 않는다. Codex에서는
   `agents/quality-gates.md`를 직접 적용한다.

.harness/CHECKPOINTS.md

@@ -1,28 +1,8 @@
-# CHECKPOINTS.md — 작업 단위 완료 기록
+# CHECKPOINTS.md — Task 완료 지점 템플릿
 
-> 한 작업 단위(보통 Task 하나 또는 커밋 하나)가 끝날 때마다 한 줄 추가.
-> 커밋 해시로 git 이력과 연결한다. 최신이 위.
+> 이 루트 파일은 실제 checkpoint 기록이 아니라 템플릿이다.
+> 새 Task를 시작할 때 `.harness/tasks/<task-key>/CHECKPOINTS.md`로 복사해서 사용한다.
 
 | 일시 | Task | 내용 | 커밋 | 검증 |
 |------|------|------|------|------|
-| 2026-07-08 | 4.11 | rescue-from-main workflow helper 추가 | 미커밋 | Acceptance·frontmatter·init smoke·unittest PASS |
-| 2026-07-04 | - | README·github-integration.md Week 3 반영 갱신 | 930e404 | grep 확인 |
-| 2026-07-04 | 3.12 | 플러그인 SHA 기록 절차 (M8) | 6667307 | Acceptance PASS |
-| 2026-07-04 | 3.11 | ci.yml ci-ok 요약 잡 (M6) | 2b9a6d8 | harness-gh-test 실PR PASS |
-| 2026-07-04 | 3.10 | agents 문서 수행 주체 명시 (M5) | d5117bc | Acceptance PASS |
-| 2026-07-04 | 3.9 | Plans.md anti-pattern 예시 교정 (M2) | 11aa504 | Acceptance PASS |
-| 2026-07-04 | 3.8 | harness.toml 죽은 설정 정리 (M4) | 2dd1d8b | Acceptance PASS |
-| 2026-07-04 | 3.7 | 완료 전환 서술 통일 (M3) | 2594119 | Acceptance PASS |
-| 2026-07-04 | 3.5 | plans-guard depends-check (H3) | 03d185f | harness-gh-test 실PR PASS |
-| 2026-07-04 | 3.4 | plans-guard diff 보호 (H2) | 0c8ea99 | harness-gh-test 실PR 2종 PASS |
-| 2026-07-04 | 3.6 | Plans.md 헤더 검증 선행 파싱 (M1·M7) | 603fcc0 | 정상/컬럼누락 양쪽 검증 PASS |
-| 2026-07-04 | 3.3 | init.sh 초기화 스크립트 (H5) | 15ebe23 | 스크래치 실행 검증 PASS |
-| 2026-07-04 | 3.2 | clean 골격 세트 분리 (H5) | d44a70a | 이력 잔재 0건 확인 |
-| 2026-07-04 | 3.1 | plans-complete branch protection 호환 (H1) | 1ea64da | harness-gh-test 실증 PASS |
-| 2026-07-04 | - | 감사 보고서 + Week 3 Task 12건 추가 | 37e1997 | - |
-| 2026-07-04 | 2.7 | GitHub 연동 E2E 검증 + plans-complete.yml | 2f94273 | 시나리오 A~D 실검증 PASS |
-| 2026-07-03 | 2.6 | DESIGN.md 기획 산출물 추가 (골격+규칙+routine-saas 적용) | 6a51ad0 | Acceptance PASS |
-| 2026-07-03 | 2.1~2.5 | Week 2 dogfooding — routine-saas 기획 파이프라인 통과 | (커밋 금지 지시) | Acceptance 2.1~2.4 PASS |
-| 2026-07-03 | 1.4 | .harness/ 상태 문서 체계 (골격 7종 + CLAUDE.md 규칙) | a4c6ef1 | Acceptance PASS |
-| 2026-07-03 | - | .gitignore 플러그인 산출물 정리 | 9c05093 | git status clean 확인 |
-| 2026-07-03 | 1.3 | task-decomposer + 세분화 게이트 | a32df79 | Acceptance PASS |
+| YYYY-MM-DD | [id] | [완료 지점] | [hash 또는 미커밋] | [검증 결과] |

.harness/CONTEXT_INDEX.md

@@ -1,47 +1,66 @@
 # CONTEXT_INDEX.md — 파일 역할 인덱스
 
 > 토큰 절약용. 세션 재개 시 이 인덱스로 "이번 작업에 필요한 파일"만 골라 읽는다.
+> 루트 `.harness/*.md`는 템플릿이고, 실제 작업 맥락은 `.harness/tasks/<task-key>/`에 있다.
 > 새 파일을 만들거나 기존 파일의 역할이 바뀌면 여기를 갱신한다.
 
-## 항상 먼저 (세션 재개 시)
+## 세션 재개 읽는 순서
 
-| 파일 | 역할 | 읽는 시점 |
+1. `tasks/index.json`에서 `wip` Task 또는 사용자가 지정한 Task를 확인한다.
+2. 해당 Task의 `.harness/tasks/<task-key>/STATE.md`를 읽는다.
+3. 루트 `.harness/LESSONS.md` 최근 항목을 읽는다.
+4. `Plans.md`를 읽어 사람이 보는 snapshot을 확인한다.
+5. 이 파일에서 필요한 추가 문서만 고른다.
+
+## Task별 맥락 디렉토리
+
+| 경로 | 역할 | 읽는 시점 |
 |------|------|-----------|
-| `.harness/STATE.md` | 현재 상태 스냅샷 | 매 세션 시작 |
-| `.harness/LESSONS.md` | 재발 방지 기록 (최근 5개만) | 매 세션 시작 |
-| `Plans.md` | Task 상태 단일 출처 (DoD·Acceptance·Status) | 매 세션 시작 |
+| `.harness/tasks/<task-key>/STATE.md` | 해당 Task의 현재 스냅샷 | Task 재개 시 |
+| `.harness/tasks/<task-key>/LOG.md` | 해당 Task 작업·에러 로그 | 작업 이력/에러 확인 시 |
+| `.harness/tasks/<task-key>/CHECKPOINTS.md` | 해당 Task 완료 지점 기록 | 완료 근거 확인 시 |
+| `.harness/tasks/<task-key>/HANDOFF.md` | 해당 Task 재개 정보 | 세션 재개 직후 |
+| `.harness/tasks/<task-key>/TASKS.md` | 해당 Task 내부 체크리스트 | Task 진행 중 |
+| `.harness/tasks/<task-key>/tasks.index.snapshot.json` | 작업 시작 시점의 `tasks/index.json` 참고본 | 시작 시점 비교가 필요할 때 |
 
-## 필요할 때만
+## 루트 `.harness/` 템플릿과 전역 파일
 
 | 파일 | 역할 | 읽는 시점 |
 |------|------|-----------|
-| `.harness/HANDOFF.md` | 직전 세션 인수인계 | 재개 직후 1회 |
-| `.harness/TASKS.md` | 현재 Task의 세션 체크리스트 | Task 진행 중 |
-| `.harness/LOG.md` | 작업·에러 로그 | 에러 이력 조회 시 |
-| `.harness/CHECKPOINTS.md` | 작업 단위 완료 기록 | 이력 추적 시 |
-| `.harness/events/planning.jsonl` | `/harness-plan` 단계별 감시 로그 (사용자 친화 JSONL) | planning 실패·반영 흐름 추적 시 |
+| `.harness/STATE.md` | Task별 `STATE.md` 복사용 템플릿 | 새 Task 디렉토리 만들 때 |
+| `.harness/HANDOFF.md` | Task별 `HANDOFF.md` 복사용 템플릿 | 새 Task 디렉토리 만들 때 |
+| `.harness/TASKS.md` | Task별 `TASKS.md` 복사용 템플릿 | 새 Task 디렉토리 만들 때 |
+| `.harness/LOG.md` | Task별 `LOG.md` 복사용 템플릿 | 새 Task 디렉토리 만들 때 |
+| `.harness/CHECKPOINTS.md` | Task별 `CHECKPOINTS.md` 복사용 템플릿 | 새 Task 디렉토리 만들 때 |
+| `.harness/LESSONS.md` | 전역 재발 방지 기록 (최근 항목 우선) | 매 세션 시작 |
+| `.harness/CONTEXT_INDEX.md` | 파일 역할·읽는 순서 인덱스 | 세션 재개/파일 역할 확인 시 |
+| `.harness/events/planning.jsonl` | `/harness-plan` 단계별 감시 로그 | planning 실패·반영 흐름 추적 시 |
 | `.harness/shared/planning/latest.json` | 최신 planning run의 context/proposal/report 위치 | 최신 task-decomposer proposal 확인 시 |
 | `.harness/shared/planning/runs/` | run별 context.json·proposed-tasks.json·decomposition-report.md 작업대 | 특정 planning run 감사 시 |
+
+## 필요할 때만
+
+| 파일 | 역할 | 읽는 시점 |
+|------|------|-----------|
 | `CLAUDE.md` | 프로젝트 규칙 (기획·구현·테스트·리뷰·상태 문서) | 규칙 확인 시 |
 | `AGENTS.md` | Codex 진입점. CLAUDE.md 규칙을 Codex 세션에서 동일 절차로 실행하기 위한 호환 지침 | Codex 환경 구성·규칙 확인 시 |
 | `.agents/skills/` | Codex repo-scoped skills (`$grill-me`, `$harness-plan`, `$harness-work`, `$harness-review`, `$harness-progress`, `$harness-sync`, `$branch-checkout`, `$git-push`, `$pr-create`, `$rescue-from-main`) | Codex skill 호출 UX·절차 수정 시 |
 | `.claude/commands/` | Claude Code local custom commands (`/branch-checkout`, `/git-push`, `/pr-create`, `/rescue-from-main`) | Claude command 호출 UX·절차 수정 시 |
-| `harness.toml` | harness 플러그인 설정 ([plan]·[test]·[review]) | 설정 변경 시 |
+| `harness.toml` | harness 플러그인 설정 요약 인덱스 ([plan]·[test]·[review]) | 설정 변경 시 |
 | `BLUEPRINT.md` | 시스템 전체 아키텍처 설명 (읽기용) | 구조 이해 필요 시 |
 | `README.md` | 템플릿 사용법 (외부 사용자용) | 문서 갱신 시 |
-| `agents/quality-gates.md` | Claude/Codex 공통 scope·YAGNI·review·reporting 게이트. ponytail/caveman 원칙을 repo 규칙으로 적용 | 구현·리뷰·Codex skill 절차 수정 시 |
+| `agents/quality-gates.md` | Claude/Codex 공통 scope·YAGNI·review·reporting 게이트 | 구현·리뷰·Codex skill 절차 수정 시 |
 | `agents/task-decomposer.md` | Task 세분화 기준·게이트 정의 | 계획/게이트 실행 시 |
 | `agents/test-agent.md` | 런타임 검증 절차 정의 | worker 완료 후 |
-| `.github/workflows/plans-guard.yml` | header-check·WIP 확인·diff 보호·depends 검증·Acceptance Oracle·세분화 CI (6잡) | CI 수정 시 |
-| `.github/workflows/plans-complete.yml` | 머지 시 cc:WIP→완료 자동 커밋, push 실패 시 PR 폴백 (stale WIP 방지, H1) | CI 수정 시 |
-| `.github/workflows/ci.yml` | 스택 빌드·테스트 + ci-ok 요약 잡(required check 이름 고정) | CI 수정 시 |
+| `.github/workflows/plans-guard.yml` | header-check·WIP 확인·diff 보호·depends 검증·Acceptance Oracle·세분화 CI | CI 수정 시 |
+| `.github/workflows/plans-complete.yml` | 머지 시 cc:WIP→완료 자동 커밋, push 실패 시 PR 폴백 | CI 수정 시 |
+| `.github/workflows/ci.yml` | 스택 빌드·테스트 + ci-ok 요약 잡 | CI 수정 시 |
 | `init.sh` | 새 프로젝트에 이 템플릿 전체(설정+CI+골격) 자동 복사 | 새 프로젝트 적용 시 |
-| `templates/skeleton/` | init.sh가 복사하는 Plans.md·.harness/ 초기 상태 (dogfood 이력 없음) | 골격 자체를 고칠 때 |
-| `docs/PRD.md`, `docs/UserFlow.md`, `docs/Architecture.md` | 기획 산출물 | 기획 참조 시 |
+| `templates/skeleton/` | init.sh가 복사하는 Plans.md·.harness/ 초기 템플릿 구조 | 골격 자체를 고칠 때 |
 | `docs/templates/` | 기획 문서 골격 4종 (PRD·UserFlow·DESIGN·Architecture) | 새 기획 착수 시 |
-| `docs/github-integration.md` | GitHub 연동 상세 가이드 (branch protection·CI 잡 6종·plans-complete 동작) | GitHub 연동 설정 시 |
-| `docs/specs/2026-07-04-template-audit.md` | 템플릿 빈틈 감사 보고서 (H1~H5·M1~M8·L1~L5), Week 3 Task 매핑 근거 (L1~L5는 Plans.md Week 4 Task 4.1~4.6로 전환됨) | 감사 배경 확인 시 |
-| `docs/specs/2026-07-08-codex-claude-quality-gates.md` | ponytail/caveman Claude-only enhancement와 Codex quality-gates 적용 경계 기록 | 품질 게이트 설계 배경 확인 시 |
-| `docs/claude-code-hooks.md` | hooks 미설정 현황 + 권장 hooks 예시, harness.toml [safety.permissions]와 역할 분담 | hooks 추가 검토 시 |
-| `docs/session-recovery.md` | `.harness/` 재개 절차 심화 (파일별 역할·읽는 순서·실제 형식·다중 프로젝트 시나리오) | 세션 복구 절차 상세 확인 시 |
-| `docs/error-memory.md` | `LOG.md`/`LESSONS.md` 작성 규칙·실제 형식·CLAUDE.md 승격 기준 | 에러 기록 규칙 확인 시 |
+| `docs/github-integration.md` | GitHub 연동 상세 가이드 | GitHub 연동 설정 시 |
+| `docs/specs/2026-07-04-template-audit.md` | 템플릿 빈틈 감사 보고서 | 감사 배경 확인 시 |
+| `docs/specs/2026-07-08-codex-claude-quality-gates.md` | Claude/Codex quality gate 경계 기록 | 품질 게이트 설계 배경 확인 시 |
+| `docs/claude-code-hooks.md` | hooks 미설정 현황 + 권장 hooks 예시 | hooks 추가 검토 시 |
+| `docs/session-recovery.md` | `.harness/tasks/` 기반 재개 절차 심화 | 세션 복구 절차 상세 확인 시 |
+| `docs/error-memory.md` | Task별 `LOG.md`와 전역 `LESSONS.md` 작성 규칙 | 에러 기록 규칙 확인 시 |

.harness/HANDOFF.md

@@ -1,32 +1,21 @@
-# HANDOFF.md — 다음 세션 인수인계
+# HANDOFF.md — Task 인수인계 템플릿
 
-> 세션 종료(또는 끊김 대비) 시점에 갱신. 다음 세션이 전체 파일을 다시 읽지 않고
-> 여기 적힌 최소 파일만 읽고 바로 이어가게 하는 것이 목적.
+> 이 루트 파일은 실제 인수인계가 아니라 템플릿이다.
+> 새 Task를 시작할 때 `.harness/tasks/<task-key>/HANDOFF.md`로 복사해서 사용한다.
 
 ## 다음 세션이 먼저 읽을 최소 파일
 
-1. `.harness/STATE.md` — 현재 상태
-2. `.harness/LESSONS.md` — 최근 5개 항목
-3. `Plans.md` — Task 상태 (cc:WIP 행 확인)
+1. `.harness/tasks/<task-key>/STATE.md`
+2. `.harness/LESSONS.md` 최근 항목
+3. `tasks/index.json`
+4. `Plans.md`
+5. `.harness/CONTEXT_INDEX.md`에서 필요한 파일
 
 ## 재개 지점
 
-- Week 3 전 Task(3.1~3.12) 완료 + 커밋 + push까지 끝난 상태. 진행 중인
-  작업 없음.
-- 이번 세션에서 발견한 새 사실(문서에 반영 완료, 여기는 참고용 요약):
-  - branch protection 켜진 private repo는 GitHub Free 플랜에서 API 자체가
-    403 — H1 실증을 위해 harness-gh-test를 잠깐 public 전환했다가 검증 후
-    원복함(사용자 승인받음).
-  - plans-complete의 PR 폴백이 동작하려면 저장소 설정 2개가 별도로 켜져야
-    함(Actions PR 생성 허용, Allow auto-merge) — 둘 다 기본값 꺼짐, 실증
-    중 실제로 막혀서 발견. `plans-complete.yml` 주석에 명시함.
-- 다음 세션에서 판단할 것: Week 4 스코프 — 남은 후보는 template-audit.md의
-  L1~L5(백로그, granularity vague_re 오탐, test-agent pretest 오매칭 등)와
-  M8에서 명시한 대로 "SHA 강제 핀"은 여전히 미지원(YAGNI 보류 상태 유지 중).
+- [어디서 이어가면 되는지 기록]
 
 ## 주의사항
 
-- Task 상태는 Plans.md가 단일 출처 — `.harness/TASKS.md`에 Task 상태를 복제하지 말 것.
-- harness-gh-test repo는 private + branch protection 해제 상태로 복원됨 —
-  다시 H1류 검증이 필요하면 이 순서(public 전환 승인 → protection 설정
-  승인 → 검증 → 전부 원복)를 다시 밟을 것, 자동화하지 말고 매번 확인받을 것.
+- Task 상태의 단일 출처는 `tasks/index.json`이다.
+- 루트 `.harness/*.md` 템플릿에 실제 진행 상태를 기록하지 않는다.