[feat][post-commit] Tokens-Used를 커밋당 귀속으로 (GF-129)

backlog/decisions/decision-27 - Tokens-Used는-커밋당-토큰량이다-—-델타를-기록하지-않는다-decision-19의-delta-조항-대체.md

@@ -0,0 +1,40 @@
+---
+id: decision-27
+title: Tokens-Used는 커밋당 토큰량이다 — 델타를 기록하지 않는다 (decision-19의 delta 조항 대체)
+date: '2026-10-03 07:20'
+status: accepted
+---
+## Context
+
+`Tokens-Used`는 처음부터 "이 커밋을 만드는 데 든 토큰"을 남기려는 트레일러였다(README:
+"이 커밋에 든 토큰"). 그런데 구현은 "직전 커밋 이후 세션에서 소비된 토큰 전부"(델타)를
+세어 왔고, 문서와 아티팩트도 그걸 "누적이 아니라 델타"라며 설계처럼 설명했다. decision-19는
+여기서 더 나아가 `delta=<구간 전체>`를 트레일러에 함께 남기기로 했다.
+
+2026-10-03 유저 지시: **델타로 측정하지 않는다. 설계 의도는 커밋당 토큰량이다.**
+
+델타는 그 구간의 무관한 대화·탐색·다른 작업을 전부 이 커밋에 얹는다. 커밋을 만들지 않은
+작업의 토큰이 우연히 다음 커밋에 몰리고, 커밋을 자주 하느냐에 따라 값이 달라진다 — 커밋의
+비용이 아니라 커밋 간격을 잰다.
+
+## Decision
+
+**`Tokens-Used`는 이 커밋에 귀속된 응답의 토큰 합이다.** 귀속은 응답의 `tool_use`가 이 커밋이
+바꾼 파일을 실제로 건드렸는지로 판정한다(GF-129).
+
+- 형식은 `Tokens-Used: in=<입력> out=<출력>`이다. 델타는 **어디에도 기록하지 않는다** —
+  decision-19의 `delta=<구간 전체>` 조항을 대체한다.
+- 응답 하나는 한 커밋에만 귀속된다. 직전 커밋 이후 구간이 아니라 세션 전체에서 아직 귀속되지
+  않은 응답을 찾는다 — 그래야 "a 수정 → b 먼저 커밋 → a 커밋" 순서에서 a의 토큰을 놓치지 않는다.
+- 서브에이전트가 한 작업의 토큰도 포함한다(트랜스크립트 `<세션>/subagents/*.jsonl`).
+- 어느 파일도 건드리지 않은 응답(읽기·탐색·대화)은 어느 커밋에도 들어가지 않는다. 커밋당
+  토큰량이라는 정의에서 의도된 결과다.
+
+## Consequences
+
+- 값이 작아지고 커밋 간격에 덜 흔들린다. 대신 "세션이 쓴 토큰 총량"은 트레일러를 다 더해도
+  나오지 않는다 — 탐색 비용은 기록되지 않는다.
+- 귀속 판정은 경로 문자열 대조라 완벽하지 않다. 경로를 쓰지 않고 파일을 바꾸는 명령
+  (예: `sed -i` 대상이 글롭)은 놓칠 수 있다.
+- 기존 커밋의 `Tokens-Used`(단일 숫자, 델타)는 고치지 않는다. 형식이 달라 구별된다.
+- README, doc-3, doc-16, doc-21, 아티팩트 "훅 해부"의 델타 서술을 바꾼다.

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:44'
+updated_date: '2026-10-03 07:30'
 ---
 ## 🚀 설치
 
@@ -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` 델타 계산용 커서(`<세션 ID> <줄 수>`, 세션이 바뀌면 0줄부터, GF-139), 커밋 간 유지됨 |
+| `.gitformat-token-attributed` | `<대상 저장소>/.git/`                | Claude Code 실측 성공 시에만 `post-commit`이 갱신(`unavailable`일 때는 갱신 안 함) | `Tokens-Used`/`Tool-Calls` 귀속 기록(첫 줄 세션 ID, 이후 이미 귀속된 응답 키 — 세션이 바뀌면 새로 시작, GF-129), 커밋 간 유지됨. 예전 델타 커서 `.gitformat-token-cursor`는 더 쓰지 않으며 측정 성공 시 지워짐 |
 | `template/hooks/*`        | 이 git-trail 클론 자신의 `template/` 안 | `install.sh --global` 실행 시                      | 클론 위치를 가리키는 심볼릭 링크, 커밋 안 됨(`.gitignore`)              |
 
 **커밋 자체가 바뀌는 경우**: `post-commit`이 조건에 따라 `git commit --amend`로