fix(handoff): user handoff를 워크트리 로컬 파일로 — 병렬 PR 충돌 제거

[hsleedevelop]

요약

docs/<user>/<user>-handoff.md는 gitignore된 .harness/active.json과 그 워크트리의 git log -1을 렌더링한 워크트리 로컬 값인데 추적 파일이라, 같은 user의 병렬 PR(D5)이 머지마다 이 파일에서 충돌했다(실측 3323c6f·fdcffbc·a7c8354). 사용자 결정(선택지 A)대로 같은 경로를 유지하고 추적을 멈춘다.

• 하네스 관리 .gitignore에 docs/*/*-handoff.md — 깊이 2만 매치, task handoff(SSOT)는 계속 추적
• task <name> 활성화(생성·재활성)가 user handoff를 곧바로 기록 — 새 워크트리·clone 진입점 공백 해소
• doctor: 추적 중이거나 무시 줄이 없으면 경고(warn-only) / migrate: .gitignore 줄 보장 + git rm --cached 안내만(인덱스 무변경)
• "handoff 2파일을 다음 커밋에 담는다"(docs(task): post-commit handoff 변경은 단독 커밋 말고 다음 커밋에 담는다 #105 계열) 규범을 task handoff 1파일로 정정 — AGENTS.md·templates/AGENTS.md.hbs(소비자 도달은 init --yes)·commands/harness-task.md·commands/harness-ship.md·docs/ao-worker-rules.md §2·§7·templates/docs/README.md·docs/index.html
• 이 레포 사본(docs/chad/chad-handoff.md·docs/hslee/hslee-handoff.md) 추적 해제
• 설계·선택지 비교·소비자 전수 조사: docs/hslee/user-handoff-parallel-conflict/user-handoff-parallel-conflict-spec.md

테스트

• 신규 tests/user-handoff-untracked.test.mjs 9케이스: 무시 패턴 깊이, 활성화 기록, 같은 user 병렬 브랜치 커밋·sweep 후 머지 무충돌, sweep(docs(task): post-commit handoff 변경은 단독 커밋 말고 다음 커밋에 담는다 #105) 침묵, done 가드(fix(done-guard-subdir-paths): 하위 디렉터리 설치본에서 handoff 제외·체크박스 면제·sweep 판정이 듣지 않던 결함 #109)가 무시 파일로 막히지 않음, 전환 전 저장소의 doctor 경고·migrate 인덱스 무변경, 무시 줄 누락 경고, 다른 *-handoff.md 안내 제외
  • 무시 줄을 빼면 4케이스가 실패함을 확인(회귀 검출력)
• tests/summary.test.mjs 병렬 원장 fixture에 설치본과 같은 무시 줄 추가
• 로컬: npm test 1070 tests / 0 fail, npm run docs:check 최신
• 외부 검증: codex read-only 리뷰 P2 2건 → 조치(artifact ## Reviews)

리스크·후속

• 전환기 1회: 아직 이 파일을 수정한 구 브랜치를 머지하면 modify/delete 충돌 → 삭제 쪽 채택(이 PR의 main 병합에서도 1회 발생·처리). 새 main을 pull한 워크트리에서는 로컬 user handoff가 한 번 지워졌다가 다음 활성화·커밋에 재생성.
• gitignore 문법 한계로 같은 깊이의 다른 신규 *-handoff.md도 무시된다(이미 추적 중인 파일은 영향 없음) — USER_HANDOFF_IGNORE 주석에 명시.
• 버전 범프 없음(릴리스 범위).

🤖 Generated with Claude Code