[fix][post-commit] Tokens-Used 세션별 커서와 응답 단위 계상 (GF-139)

backlog/docs/doc-1 - 설치-가이드.md

@@ -3,7 +3,7 @@ id: doc-1
 title: 설치 가이드
 type: guide
 created_date: '2026-09-19 05:27'
-updated_date: '2026-10-03 03:16'
+updated_date: '2026-10-03 03:40'
 ---
 ## 🚀 설치
 
@@ -45,7 +45,7 @@ cd ~/my-project
 | 파일/디렉터리             | 위치                                     | 언제                                               | 비고                                                                    |
 | ------------------------- | ---------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
 | `.gitformat-verified`     | `<대상 저장소>/.git/`                    | `pre-commit` 통과 시 생성, `post-commit`이 곧 삭제 | 커밋 사이에 남지 않는 임시 마커                                         |
-| `.gitformat-token-cursor` | `<대상 저장소>/.git/`                    | Claude Code 실측 성공 시에만 `post-commit`이 갱신(`unavailable`일 때는 갱신 안 함) | `Tokens-Used`/`Tool-Calls` 델타 계산용 커서(누적 줄 수), 커밋 간 유지됨 |
+| `.gitformat-token-cursor` | `<대상 저장소>/.git/`                    | Claude Code 실측 성공 시에만 `post-commit`이 갱신(`unavailable`일 때는 갱신 안 함) | `Tokens-Used`/`Tool-Calls` 델타 계산용 커서(`<세션 ID> <줄 수>`, 세션이 바뀌면 0줄부터, GF-139), 커밋 간 유지됨 |
 | `template/hooks/*`        | 이 git-logbook 클론 자신의 `template/` 안 | `install.sh --global` 실행 시                      | 클론 위치를 가리키는 심볼릭 링크, 커밋 안 됨(`.gitignore`)              |
 
 **커밋 자체가 바뀌는 경우**: `post-commit`이 조건에 따라 `git commit --amend`로

backlog/docs/doc-16 - 토큰·툴콜-측정-방법과-한계.md

@@ -3,7 +3,7 @@ id: doc-16
 title: 토큰·툴콜 측정 방법과 한계
 type: specification
 created_date: '2026-09-25 19:34'
-updated_date: '2026-09-25 19:46'
+updated_date: '2026-10-03 03:39'
 ---
 # 토큰·툴콜 측정 방법과 한계
 
@@ -33,6 +33,26 @@ apiBlockIndex=3  content=['tool_use']  usage합=87932
 3. 그룹의 `tool_use` 블록은 **모든 줄에서 모은다**(한 응답의 도구 호출이 여러 줄에 흩어져
    있다). 이 목록으로 귀속 여부를 판정한다
 
+## 현재 post-commit 구현 (GF-139 핫픽스)
+
+아래 "귀속 필터"와 "기록 형식"은 GF-129가 `prepare-commit-msg`로 옮기며 들일 목표 설계다.
+지금 `post-commit`은 귀속 필터 없이 직전 커밋 이후 구간 전체를 합산해 `Tokens-Used: <N>`
+한 값으로 남긴다. 다만 두 가지는 GF-139에서 먼저 고쳤다.
+
+- **응답 단위 계상.** 위 알고리즘 1·2단계를 그대로 적용한다. `(requestId, message.id)`가
+  같은 assistant 줄은 `usage`를 한 번만 더하고, 둘 중 하나라도 없는 줄은 줄 단위로 더한다.
+  `Tool-Calls`는 모든 줄의 `tool_use` 블록을 센다.
+- **세션별 커서.** `.git/.gitformat-token-cursor`는 `<세션 ID> <줄 수>` 한 줄이다(개행 없음).
+  트랜스크립트는 세션마다 새 파일이라 줄 수만 저장하면 새 세션의 짧은 파일을 이전 세션의
+  줄 수로 읽어 첫 커밋이 0이 됐다. 세션 ID가 다르거나, 숫자만 든 예전 형식이거나, 손상됐으면
+  0줄부터 센다.
+- **커밋 경계를 걸친 응답.** 응답 하나의 줄이 커서 앞뒤로 나뉘면 앞 커밋이 이미 그 `usage`를
+  더했다. 그래서 같은 세션이면 커서 앞 구간의 응답 키를 먼저 모아 두고, 뒤 커밋에서는 그
+  키의 `usage`를 다시 더하지 않는다.
+
+형식 변경(`in`/`out`/`delta`)과 귀속 필터는 GF-129에 남아 있다. GF-129는 위 세 가지를
+`prepare-commit-msg`로 옮길 때 함께 가져가야 한다.
+
 ## 귀속 필터
 
 쌓인 턴 중 **이 커밋과 관계있는 턴만 골라내는 체**다. 기준은 하나 — 그 턴의 도구 호출이

backlog/tasks/gf-129 - 토큰·툴콜-측정을-응답-단위-중복-제거와-커밋-귀속으로-재작성.md

@@ -4,7 +4,7 @@ title: 토큰·툴콜 측정을 응답 단위 중복 제거와 커밋 귀속으
 status: To Do
 assignee: []
 created_date: '2026-09-25 19:33'
-updated_date: '2026-09-25 21:43'
+updated_date: '2026-10-03 03:39'
 labels:
   - hooks
   - trailers
@@ -58,3 +58,13 @@ type: bug
 - [ ] #2 ruff check 통과
 - [ ] #3 이 저장소 자신의 커밋이 새 훅으로 정상 생성되는지 확인
 <!-- DOD:END -->
+
+## Comments
+
+<!-- COMMENTS:BEGIN -->
+author: @claude
+created: 2026-10-03 03:39
+---
+GF-139 핫픽스로 AC#1(응답 단위 계상: (requestId, message.id)가 같은 assistant 줄은 usage를 한 번만 더함)을 post-commit에 먼저 적용했다. 세션별 커서(.git/.gitformat-token-cursor = '<세션 ID> <줄 수>', 세션 불일치·예전 숫자 형식이면 0줄부터)와, 커서 경계를 걸친 응답의 중복 방지(커서 앞 구간의 응답 키를 먼저 모음)도 함께 들어갔다. 이 작업을 prepare-commit-msg로 옮길 때 세 가지를 모두 가져가야 한다. 형식 변경(in/out/delta)과 귀속 필터는 그대로 GF-129 범위다. 상세는 doc-16 '현재 post-commit 구현' 절.
+---
+<!-- COMMENTS:END -->

backlog/tasks/gf-139 - Tokens-Used-핫픽스-—-세션별-커서와-응답-단위-중복-제거.md

@@ -0,0 +1,80 @@
+---
+id: GF-139
+title: Tokens-Used 핫픽스 — 세션별 커서와 응답 단위 중복 제거
+status: Done
+assignee:
+  - '@claude'
+created_date: '2026-10-03 03:30'
+updated_date: '2026-10-03 03:42'
+labels:
+  - hooks
+  - bug
+dependencies: []
+references:
+  - decision-5
+  - decision-19
+documentation:
+  - backlog/docs/doc-16 - 토큰·툴콜-측정-방법과-한계.md
+priority: high
+type: bug
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Tokens-Used 값이 두 방향으로 틀리고 있다(2026-10-03 실측).
+
+첫째, 세션이 바뀌면 첫 커밋이 0으로 찍힌다. post-commit은 트랜스크립트에서 이미 읽은 줄 수를 저장소에 커서 하나(.git/.gitformat-token-cursor)로만 저장하는데, 트랜스크립트는 세션마다 새 파일이다. 새 세션의 짧은 파일을 이전 세션의 줄 수(927)로 읽으면 새 줄이 없다고 판단해 0이 된다. 커밋 7fef01e가 이렇게 0으로 남았다. GF-129에 없는 버그다.
+
+둘째, 0이 아닐 때는 2~3배 부풀려진다. 트랜스크립트는 API 응답 하나를 content 블록마다 한 줄씩 기록하고, 각 줄이 같은 usage를 반복해서 들고 있다. 지금 구현은 줄마다 더한다. 이번 세션 실측으로 assistant 215줄이 응답 109개였다. 이건 GF-129 AC#1과 같은 문제다.
+
+GF-129는 GF-127→GF-128 재설계 뒤로 묶여 있어서, 값이 틀린 채로 커밋이 계속 쌓인다. 그래서 지금 post-commit에서 두 버그만 먼저 고친다. Tokens-Used 형식 변경(in/out/delta)과 커밋 귀속은 GF-129에 그대로 남긴다.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 커서 파일에 세션 ID와 줄 수를 함께 저장하고, 세션 ID가 다르면 트랜스크립트 0줄부터 집계한다
+- [x] #2 예전 형식(숫자만) 커서는 세션 불일치로 취급해 0줄부터 집계한다
+- [x] #3 (requestId, message.id)가 같은 assistant 줄은 usage를 한 번만 더한다
+- [x] #4 requestId나 message.id가 없는 줄은 지금처럼 줄 단위로 더한다
+- [x] #5 Tool-Calls는 지금처럼 모든 줄의 tool_use 블록을 센다
+- [x] #6 새 세션 첫 커밋, 중복 줄, 예전 커서 형식을 다루는 테스트를 추가하고 기존 테스트의 커서 기대값을 새 형식에 맞춘다
+- [x] #7 doc-16에 세션별 커서와 응답 단위 계상을 반영하고, GF-129 AC#1이 이 핫픽스로 선반영됐다고 코멘트를 남긴다
+<!-- AC:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 python3 -m unittest discover -s tests 전체 통과
+- [x] #2 ruff check 통과
+- [x] #3 실제 커밋의 Tokens-Used가 트랜스크립트를 응답 단위로 따로 합산한 값과 일치하는지 확인
+<!-- DOD:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. 테스트 먼저(TDD): 새 세션 첫 커밋, 같은 (requestId, message.id) 줄 1회 계상, 키 없는 줄 줄 단위, 예전 숫자 커서, 커서 경계를 걸친 응답 중복 방지
+2. hooks/post-commit의 measure_claude_code_token_usage()/aggregate_usage() 수정 — 커서 형식 '<session_id> <줄 수>'
+3. 기존 테스트의 커서 기대값 갱신
+4. doc-16 갱신, GF-129 코멘트
+5. 실제 커밋으로 값 대조 (구현은 서브에이전트, 검토·커밋 확인은 메인)
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+구현(서브에이전트, TDD):
+- 테스트 먼저(a096f1d): 새 세션 첫 커밋 / 예전 숫자 커서 / 같은 (requestId, message.id) 줄 1회 계상 / id 없는 줄 줄 단위 / 커서 경계를 걸친 응답 중복 방지 5건 추가, 기존 커서 기대값을 'fake-session <N>'으로 갱신. 구현 전 실행 시 11건 중 8건 실패 확인.
+- 구현(482fd24): hooks/post-commit의 aggregate_usage(lines, seen_keys)와 measure_claude_code_token_usage()만 수정. 커서 형식 '<세션 ID> <줄 수>'(개행 없음), 마지막 공백 기준 rsplit로 파싱. 세션 불일치·숫자만·손상 → 0줄부터. 같은 세션이면 커서 앞 구간을 aggregate_usage로 돌려 응답 키만 모으고(합산은 버림) 새 구간에서 그 키의 usage를 건너뜀. 앞 구간 파싱 실패도 transcript-parse-failed로 배치 실패 처리. 같은 응답의 usage는 첫 줄 값을 씀.
+- 결과: python3 -m unittest discover -s tests → Ran 98 tests, OK. ruff check hooks/ tests/ + python 훅 → All checks passed.
+- 실커밋 482fd24의 커서: '<세션 UUID> 1353' 형식으로 기록됨(Tokens-Used: 25915492, 이 값은 이번 세션의 첫 커밋 이후 구간 전체 합). DoD#3(응답 단위 별도 합산과 대조)은 메인에서 확인 필요.
+- doc-16에 '현재 post-commit 구현 (GF-139 핫픽스)' 절 추가, GF-129에 선반영 코멘트 남김.
+- 범위 밖 발견: doc-1 설치 가이드 표의 .gitformat-token-cursor 설명이 '(누적 줄 수)'로 남아 있음 — 손대지 않음.
+
+메인 검증: 코드 리뷰(aggregate_usage·measure_claude_code_token_usage 두 함수만 변경, 실패 처리 유지). GF-139 테스트 5건 포함 전체 98개 통과, ruff 통과. DoD#3: 커밋 8ffc7ee의 커서 구간(1353→1391줄)을 트랜스크립트에서 응답 단위로 따로 합산 = 813,177 토큰 / 3 호출, 트레일러 값과 일치(줄 단위였다면 1,893,217). 서브에이전트 커밋 482fd24도 서브에이전트가 같은 방식으로 일치 확인(25,915,492). doc-1의 커서 설명도 새 형식으로 갱신. 알려진 한계: 서브에이전트의 토큰은 부모 트랜스크립트에 없어 서브에이전트가 만든 커밋은 0으로 남는다(doc-16에 기존 기재).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+post-commit의 Tokens-Used 측정에서 두 버그를 고쳤다. 커서를 '<세션 ID> <줄 수>'로 저장해 새 세션 첫 커밋이 0이 되던 문제를 없앴고, (requestId, message.id) 단위로 usage를 한 번만 더해 2~3배 과대계상을 없앴다(커밋 경계를 걸친 응답 포함). 테스트 5건 추가, 전체 98개·ruff 통과, 실제 커밋 8ffc7ee 값이 독립 합산과 일치. 형식 변경과 커밋 귀속은 GF-129에 남김.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/drafts/draft-23 - git-trail로-개명하고-개념-지도-문서를-만든다.md → backlog/tasks/gf-140 - git-trail로-개명하고-개념-지도-문서를-만든다.md

@@ -1,14 +1,20 @@
 ---
-id: DRAFT-23
+id: GF-140
 title: git-trail로 개명하고 개념 지도 문서를 만든다
-status: Draft
+status: To Do
 assignee: []
 created_date: '2026-10-03 03:31'
-updated_date: '2026-10-03 03:31'
+updated_date: '2026-10-03 03:35'
 labels:
   - docs
   - naming
 dependencies: []
+references:
+  - decision-25
+  - decision-24
+documentation:
+  - backlog/docs/doc-3 - AI-귀속-트레일러-레퍼런스.md
+  - backlog/docs/doc-20 - GitHub-원격-강제-설정-관리-—-rulesets와-저장소-설정.md
 priority: medium
 type: docs
 ---