yield-audit 0.3.2__tar.gz

yield_audit-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -v

yield_audit-0.3.2/.github/workflows/pypi.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+# PyPI trusted publishing (OIDC): the project's pending publisher on
+# pypi.org is configured for this exact workflow filename — no API tokens
+# anywhere. First successful run claims the `yield-audit` project name.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  # required for the OIDC minting the publish action performs
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

yield_audit-0.3.2/.gitignore

@@ -0,0 +1,23 @@
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+# library: lockfile stays local (CI installs via pip)
+uv.lock
+
+# yield-audit local cache
+.yield/

yield_audit-0.3.2/AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md — yield-audit
+
+AI 코딩 에이전트(ZCode, Claude Code 등)가 이 저장소에서 작업할 때의 규약입니다.
+사람 기여자는 먼저 [README.md](README.md)를 읽으세요. 내용이 겹치면 이 문서가 우선합니다.
+렌즈 패키지와 테스트에는 하위 규약이 있습니다: [src/yield_audit/lenses/AGENTS.md](src/yield_audit/lenses/AGENTS.md), [tests/AGENTS.md](tests/AGENTS.md).
+
+## 이 프로젝트가 하는 일
+
+AI 코딩 에이전트(Claude Code)의 로컬 세션 트랜스크립트와 git 이력을 대조해 **성과를 회계**합니다:
+무엇이 살아남았는지(M1 생존율), 무엇이 낭비였는지(M2), 재시도 세금(M3), 채택 작업당 비용(M4),
+캐시 지역성(M5), 검증 공백(M8), AI 리워크율(M11, 코호트 certain/probable/human). 원칙: **완전 로컬, 읽기 전용, 결정적, 런타임 의존성 0**
+(Python ≥3.10 표준라이브러리 + git CLI), **절감 주장 금지 — 측정만**.
+
+## 명령어
+
+```bash
+python3 -m pip install -e '.[dev]'   # 또는 uv pip install -e '.[dev]'
+pytest            # ~3초, 커밋 전 반드시 통과
+ruff check .      # 반드시 클린
+```
+
+스모크 실행은 **픽스처/tmp 저장소에만**:
+
+```bash
+yield-audit audit --repo <tmp fixture repo> --transcripts-dir <tmp fixtures> --now 2026-08-20T00:00:00Z --format json
+```
+
+⚠️ **절대 금지**: 실제 데이터 감사 — `--repo`/`--transcripts-dir`를 `/Users/*/.claude`·`~/.codex`나
+사용자의 실제 프로젝트로 향하면 1.3GB+ 전체 스캔으로 수십 초~수 분이 걸리고 사생활을 침범합니다.
+에이전트가 실데이터 스모크가 필요하면 사용자에게 먼저 물으세요.
+
+## 구조 (데이터 흐름)
+
+```
+cli.py            argparse, 종료코드 0/2, stdout 로케일 방어
+  └─ audit.py     파이프라인 오케스트레이터 — 리포트 dict 조립, 마지막에 deep_sanitize
+       ├─ transcripts/     벤더 어댑터 패키지: base(공통 계약·레지스트리) + claude + codex
+       │                   → events.Session (키 기반 방어적 파싱, 세션 id는 "vendor:<raw>" 네임스페이스)
+       ├─ gitdata.py       읽기 전용 git 래퍼 (스트리밍, blame=SHA 카운터, GIT_* env 제거)
+       ├─ attribute.py     세션↔커밋 매칭 (high/medium 등급, 1/n 분할, 모호 플래그)
+       ├─ cohorts.py       커밋 코호트 라벨 (certain=푸터/probable=세션 조인/human — 근거 등급, 판정 아님)
+       ├─ pricing/costs    공시 요금표(USD/MTok)와 관측 usage 기반 비용
+       ├─ lenses/          M1–M11 측정 렌즈 (순수 함수 — 하위 AGENTS.md 참고)
+       ├─ redact.py        출력 경계: 살균·레닥션·deep_sanitize
+       └─ report.py        console/json/markdown 렌더러
+```
+
+## 필수 규약 (어기다면 버그)
+
+1. **렌즈는 순수 함수** — I/O·시계·난수 금지. `now`와 horizon은 인자로 받는다.
+2. **정직성 라벨** — 모든 리포트 블록에 `measurement`가 있어야 한다:
+   `observed`(기록에서 직접) / `estimate`(관측 × 공시요금) / `proxy`(명시된 대체량).
+   라벨 없는 새 메트릭은 버그로 취급.
+3. **출력 경계** — 트랜스크립트에서 온 모든 문자열은 `redact.py`를 거친다.
+   `run_audit`의 deep_sanitize는 안전망이지 레닥션의 대체품이 아니다
+   (안전망은 이스케이프 제거만 하고, 경로 치환은 필드 단계에서 한다).
+4. **결정성** — 출력에 흐르는 모든 순회는 `sorted()` 먼저. 메트릭에 벽시계 금지
+   (재현은 `--now`). 스키마는 `yieldaudit.report.v1`, 변경은 하위호환(additive)만.
+5. **런타임 의존성 0** — 표준라이브러리 + `git` CLI만. pytest/ruff는 dev에서만.
+6. **서브프로세스 규율** — list argv(셸 금지), `gitdata._clean_env`로 GIT_* 제거,
+   스트림은 stderr=DEVNULL + stdout EOF 후 wait, 프로세스 수는 집계 단위로 캐싱
+   (유닛당 무캐시 호출 금지).
+7. **측정 전용** — 절감 개입은 로드맵(v1.x) 게이트 뒤에. 리포트·문서에 절감 수치 주장 금지.
+
+## 테스트
+
+- `tests/conftest.py`가 고정 날짜의 픽스처 git 저장소와 실제 스키마를 모사한 합성
+  트랜스크립트를 만든다. 타임라인은 conftest 모듈 docstring이 유일한 진실원천.
+- 새 렌즈/메트릭 = 렌즈 단위 테스트 + `test_e2e.py` 골든 단언 추가.
+  골든 수치(13/24 생존율, $0.00643 등)는 픽스처 타임라인에서 유도된 값이므로
+  픽스처 변경 시 docstring과 골든 전부를 함께 갱신.
+- 악성 입력 픽스처( malformed JSONL, Infinity usage, 이스케이프 문자열)는
+  `test_transcripts.py`와 `test_redact.py`에. "리포트에 이스케이프 바이트 0" 보증은
+  `test_e2e.py::test_report_has_no_escape_bytes_anywhere`가 지킨다.
+
+## 릴리스
+
+- 버전은 두 곳을 함께: `src/yield_audit/__init__.py` + `pyproject.toml`.
+- Keep-a-Changelog 형식의 CHANGELOG.md 항목 추가. CI 매트릭스: 3.10–3.14 × 3 OS.
+- PyPI는 미게시 상태 — README 설치 안내는 소스 설치 기준으로 유지.

yield_audit-0.3.2/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to yield-audit are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is
+SemVer.
+
+## [0.3.2] - 2026-09-06
+
+Distribution release: published to PyPI via trusted publishing (OIDC —
+the pending publisher registered on pypi.org for `.github/workflows/
+pypi.yml` claims the name on first run; no API tokens anywhere).
+
+### Changed
+- README is now fully English (the PyPI landing page) with the M11
+  rework-rate one-liner as the headline and a sample console report;
+  the Korean README moved to `README.ko.md`. Install docs switched from
+  source-install to `pip install yield-audit` / `uvx yield-audit`.
+
+### Added
+- `.github/workflows/pypi.yml` — build + `twine check` + publish on
+  `v*` tag push (and manual dispatch).
+
+## [0.3.1] - 2026-09-06
+
+Trust, first-run, and performance fixes from the v0.3.0 review.
+
+### Fixed
+- OpenAI models priced from the table instead of the conservative
+  claude-opus fallback: gpt-5.1 / gpt-5.1-codex (1.25/10/0.125),
+  gpt-5.3-codex (1.75/14/0.175), gpt-5-mini, o3, o4-mini (standard tier,
+  published list prices 2026-09; codex variants share the gpt-5.1 base —
+  no separate listing). Codex sessions' USD figures are no longer
+  inflated ~4x.
+- Empty-state UX: a missing `--transcripts-dir` or absent vendor roots
+  now fail (exit 2) with a `doctor` hint instead of producing a silent
+  empty report; zero matching sessions print a prominent warning line in
+  console/markdown while staying a valid exit-0 measurement.
+
+### Changed — performance
+- Blame prefilter: one `git log --name-only` pass builds a per-path
+  touch map (committer dates, matching snapshot selection). Paths no
+  commit touched inside a measurement window are decided without a
+  single `git blame` process — same values, provably. A merge commit
+  inside a window forces blaming (merge resolutions rewrite lines
+  invisibly to the pass). Shared by M1 and M11 via the blame cache;
+  smoke: 102-commit full-history M11 audit in 0.12s.
+
+## [0.3.0] - 2026-09-05
+
+M11 AI rework rate — the first ADD-transition lens (기획서-AIDD-전환계량.md
+v0.3.0 scope): compares how quickly AI-marked commits get reworked against
+human ones, measured locally from git history alone.
+
+### Added
+- `cohorts.py`: every commit lands in one evidence-graded cohort —
+  `certain` (AI footer in the commit message: `Co-Authored-By: …`,
+  `Generated with …`, 🤖), `probable` (no footer but claimed by a
+  transcript session via the usual attribution join), or `human`.
+  Labels state matching evidence, never authorship verdicts; every
+  cohort percentage ships with the evidence distribution.
+- `lenses/rework.py` (M11): rework = lines a commit added that are no
+  longer present verbatim at the snapshot `--rework-days` (default 14)
+  later — the complement of M1's blame survival, applied to every commit
+  and aggregated by cohort plus an `ai_combined` view. Pending horizons
+  are excluded from rates and counted honestly; `--rework-days 0`
+  disables the lens.
+- Report block `m11_rework` and `parameters.rework_horizon_days`
+  (schema v1, additive); console/markdown renderers gained an M11
+  section; `gitdata.commit_messages` streams full commit messages for
+  footer evidence.
+
+### Changed
+- Fixture repo grew commits C3 (AI-footered, new file) and C4 (human
+  rework of it); M1/attribution goldens are unchanged, window counts
+  updated (commits_in_window 4, unclaimed 3).
+
+## [0.2.0] - 2026-09-05
+
+Vendor-agnostic transcripts: the Claude-only ingest module became an
+adapter registry, and the Codex CLI is scanned alongside Claude Code by
+default. Claude-only audits keep identical measured values (regression:
+all v0.1.2 golden numbers unchanged).
+
+### Added
+- `transcripts/` package with a `TranscriptAdapter` base class (find
+  files + parse one JSON record into `events.Session`) and a registry;
+  adding a vendor is one subclass plus one registry entry.
+- Codex CLI adapter (`~/.codex/sessions` rollout JSONL): session meta /
+  turn context / function calls / token counts, with vendor tool names
+  normalized to the canonical set (shell execution becomes `Bash`,
+  `apply_patch` headers become edited files, exit_code becomes tool
+  errors). Compaction boundaries are not present in this format and stay
+  empty.
+- `--agent {auto,claude,codex}` on `audit` and `doctor` (default `auto`:
+  every registered vendor; missing roots are skipped). An explicit
+  `--transcripts-dir` applies to all selected vendors — adapters skip
+  records that are not their schema, so mixed directories are safe.
+- Session ids are namespaced per vendor (`"claude:<id>"`,
+  `"codex:<id>"`); report keys keep the prefix. Report `parameters` adds
+  `agents_scanned` and `transcripts_roots` (schema v1, additive).
+
+### Changed
+- `run_audit`'s `transcripts_root` accepts `None` (each agent's own
+  default root) and takes a new `agents` argument; `load_sessions`
+  likewise. Ingest internals moved from `transcripts.py` into
+  `transcripts/{base,claude,codex}.py` — the public helpers are
+  re-exported unchanged.
+
+## [0.1.2] - 2026-09-05
+
+Second review round: close the sanitizer bypasses found in v0.1.1's new
+output boundary and harden ingest against hostile transcript values.
+Measured values are unchanged (regression-checked against 0.1.1).
+
+### Fixed — security
+- Session ids are transcript-controlled and reached report keys/cells raw;
+  `_sid` now sanitizes, and `run_audit` deep-sanitizes the finished report
+  (strings and dict keys) so no future field can bypass the boundary.
+- Path redaction's lookbehind is ASCII-only: a Unicode word (e.g. Hangul)
+  before an absolute path no longer suppresses redaction.
+- `~/`-relative paths in commands are redacted to `<path>` like absolute
+  ones; Windows UNC free-text paths are a documented gap.
+- Sanitization now also strips C1 control characters (U+0080-U+009F) and
+  CSI sequences with intermediate bytes.
+
+### Fixed — robustness
+- Bare `Infinity` token counts (accepted by Python's json parser) crashed
+  the run with OverflowError; non-finite values now read as 0.
+- The Windows munged-directory name is separator/colon free, so the
+  prefilter can no longer resolve to an absolute path and scan the
+  repository itself instead of the transcripts.
+- Transcript discovery prunes symlink cycles by (device, inode) instead of
+  looping forever.
+- Blame porcelain parsing ignores tab-prefixed content lines whose first
+  token looks like a SHA.
+
+### Changed
+- Discovery notes (prefilter vs full walk) are surfaced in report notes
+  instead of being invisible.
+- Hygiene: pending count dedupes contested units by (commit, path);
+  survival result annotations reflect share-weighted floats; waste
+  classifies each unit once; dead attribution overlap field removed;
+  version strings aligned to 0.1.2.
+
+## [0.1.1] - 2026-09-05
+
+Post-release review hardening: correctness, performance, and output-boundary
+security. Measured values are unchanged (regression-checked against 0.1.0 on
+a real corpus).
+
+### Fixed — correctness
+- Attribution: contested commits now split across ALL same-grade claimants
+  (previously only exact-overlap ties split; other claimants were silently
+  dropped, and a high-grade tie picked one winner unflagged). Every
+  ambiguity is flagged.
+- Attribution: `shared_files` no longer leaks the last-iterated session's
+  file set into other pairs (regression test added).
+- Waste bounds: the share denominator is now computed from units classified
+  at the *same* horizon, so bounds can never exceed the session cost when
+  horizon differs from the headline.
+- Verification gap: reports both `gap_rate` (never verified) and
+  `gap_rate_strict` (not verified before the last commit).
+- Cache locality: a compaction boundary stamped exactly at the previous
+  call's timestamp now counts as compaction (tie rule).
+- Accepted: sessions with commits but no cost record land in a status
+  instead of vanishing from totals.
+
+### Fixed — performance
+- Survival: file existence is checked via one `git ls-tree -r` per snapshot
+  instead of one `cat-file` per unit×horizon (~10x fewer git processes on
+  commit-heavy repos).
+- Transcripts: sessions are loaded from the repo's munged project directory
+  when present (full-walk fallback preserved) — real-corpus audit went from
+  14.1s to 3.8s on a 1.3GB transcript root.
+- `git log --numstat` and `git blame` stream line-by-line; blame collapses
+  to per-SHA counts instead of retaining full porcelain output.
+- Failure chains capped at 200 in the JSON report with a truncation flag.
+- Cache locality boundary matching is a two-pointer scan, not O(calls×boundaries).
+
+### Fixed — security
+- Output boundary: every transcript-derived string is stripped of ANSI
+  escape and control sequences before rendering (terminal injection).
+- Markdown: chain commands are escaped for table cells/code spans, so a
+  pasted report cannot be broken out of or turned into remote image loads.
+- Chain commands have absolute paths redacted to `<path>` by default
+  (`--show-paths` restores them), matching the README's redaction promise.
+- `parameters.transcripts_root` is home-abbreviated; path redaction handles
+  Windows separators.
+- Git subprocesses run with `GIT_*` environment variables stripped so a
+  stray `GIT_DIR` cannot redirect the audit.
+
+### Fixed — robustness
+- Unparseable commit dates skip the commit with a warning note instead of
+  crashing the run.
+- Float token counts in transcripts (e.g. `4096.0`) truncate instead of
+  reading as zero.
+- `--days` rejects negative values; stdout/stderr are reconfigured to
+  survive non-UTF-8 locales.
+- `core.quotePath=false` keeps non-ASCII file paths intact in numstat.
+
+### Changed
+- Packaging: `license = "Apache-2.0"` (PEP 639) with `license-files`.
+- Transcript discovery follows symlinked directories via `os.walk`.
+
+## [0.1.0] - 2026-09-05
+
+Initial release: outcome accounting for AI coding agents, fully local,
+measurement-only.
+
+### Added
+- Claude Code transcript adapter (JSONL, schema-defensive; sidechains and
+  malformed records skipped).
+- M1 output survival rate with git-blame snapshots at configurable horizons
+  (default 7d headline, 7/30 measured), split by output kind
+  (source/test/docs/config); pending-horizon units reported separately;
+  aggregates weighted by attribution share so contested commits count once.
+- M2 waste cost bounds (removed = lower+upper, >=50% lost = upper only);
+  attribution-share-weighted line-share proxy labeled as such.
+- M3 retry tax: failure chains from repeated normalized Bash commands with
+  errors; interval-based token attribution.
+- M4 accepted-task accounting: cost/tokens per accepted session
+  (survival >= 0.5); accepted/rejected/pending/no_output classes.
+- M5 cache locality: ttl_expiry / prefix_break / compaction classification
+  of cold calls; wasted-vs-cached estimate; compaction excluded by design.
+- M8 verification gap rate plus survival correlation table.
+- Session-commit attribution with high/medium confidence grades, contested
+  commit splitting, and ambiguity flags.
+- Pricing table (2026-09 list prices, prefix matching, conservative
+  fallback for unknown models) with JSON override file.
+- Report formats: console, JSON (`yieldaudit.report.v1`, every block
+  labeled observed/estimate/proxy), markdown; path redaction by default.
+- Graceful degradation on repositories with no commits yet (empty report,
+  no crash).
+- CLI: `yield-audit audit`, `yield-audit doctor`; `--now` for reproducible
+  runs.
+- Tests: deterministic fixture git repository (pinned dates) + synthetic
+  transcripts; unit and end-to-end golden assertions.

yield_audit-0.3.2/HANDOFF.md

@@ -0,0 +1,86 @@
+# HANDOFF — 다음 세션 작업 지시서
+
+- **작성 시점**: 2026-09-05, v0.1.2 (커밋 `2fd3ebc` 기준)
+- **업데이트 2026-09-05**: v0.2.0+v0.3.0 출시(커밋 `43054b5` + Windows 테스트 수정). **P0 완료 — 원격 [ictechgy/yield-audit](https://github.com/ictechgy/yield-audit) public 생성, 첫 CI 3 OS × py3.10/3.12/3.14 전부 그린, 태그 v0.1.2·v0.3.0 push.** 첫 CI에서 기존 테스트의 Windows 경로 버그(munged 이름 치환) 발견·수정됨
+- **전제 상태**: 67 tests 통과 · ruff 클린 · 실데이터 회귀 확인(측정값 불변) · PyPI 미게시
+- **에이전트 규약**: 작업 시작 전 [AGENTS.md](AGENTS.md) 읽기. **절대 실데이터(`/Users/*/.claude`, 실제 프로젝트) 감사 금지** — 픽스처/tmp만.
+
+## 0. 현재 상태 빠른 확인 (5초)
+
+```bash
+pytest -q && ruff check . && git log --oneline | head -5
+# 예상: 67 passed, All checks passed, 최신 커밋 = docs 커밋
+```
+
+문서 지도: README(사용자용) → AGENTS.md(에이전트 규약, 루트+lenses+tests) →
+CHANGELOG(변경 이력) → 기획서-AIDD-전환계량.md(v0.3+ 근거, M11 출시됨) →
+../AI비용-빈영역-오픈소스-기획서.md(v0.2+ 근거) →
+../context-guard-개선-보고서.md(별개 프로젝트 참고용).
+
+## 1. 최우선: 원격 저장소 + 첫 CI 실행 (미해결 P0급)
+
+CI가 CI워크플로 파일만 있고 **한 번도 돌아본 적이 없다**. 로컬은 macOS+py3.14 하나뿐이므로
+3 OS × py 3.10/3.12/3.14 매트릭스에서 처음으로 검증되는 것과 같다.
+
+- [ ] GitHub 원격 생성 후 push (`gh repo create yield-audit --public --source .` 또는 사용자 선호 방식 — 원격 생성은 사용자 승인 필요할 수 있음)
+- [ ] CI 결과 확인. **예상 실패 후보와 대응**:
+  - py3.10 문법 → 전 모듈에 `from __future__ import annotations` 있음(확인됨), 그래도 실패 시 해당 시그니처 수정
+  - Windows: `tests/conftest.py` 픽스처 경로, `munged_project_dir_name`(v0.1.2에서 백슬래시·콜론 처리 완료), blame/ls-tree 동작 차이
+  - actions 태그 핀(@v4/@v5) → 공식 SHA 확인 후 핀 (아직 미적용 — 기억으로 SHA 쓰지 말 것)
+- [ ] 그린이면 `git tag v0.1.2 && git push --tags`
+- [ ] README의 홈페이지/원격 URL이 실제 원격과 일치하는지 갱신 (현재 placeholder)
+
+## 2. 다음 기능 사이클
+
+**v0.2 어댑터 인터페이스 + v0.3.0 M11 리워크율 완료됨**(기획서-AIDD-전환계량.md v0.3.0 스코프:
+cohorts.py 코호트 라벨 + lenses/rework.py + `--rework-days` + 리포트 `m11_rework` 블록).
+남은 v0.3 항목: M12 정착률(blame 스냅샷, `--snapshot` 서브커맨드), v0.4 `aidd` 서브커맨드 통합 리포트.
+
+### 원래 v0.2 항목 (M7/M9/M10은 미착수)
+
+**시작 전 아키텍처 과제가 먼저** — 2차 리뷰의 구조 지적:
+
+- [x] **어댑터 인터페이스 추출** (v0.2.0 완료): `transcripts/` 패키지(base+claude+codex, 레지스트리),
+      `--agent {auto,claude,codex}`, 세션 id `"vendor:<raw>"` 네임스페이스. Gemini 어댑터는
+      스키마 그라운딩 확보 후 같은 방식으로 추가하면 됨(서브클래스 1개 + 레지스트리 등록).
+- [ ] **M7 컨텍스트 사망율**: 읽어들인 파일 내용이 이후 생성물에 미등장하면 "사망"의 결정적 근사.
+      문자열 매칭 기반(정규화 후 포함 검사)으로 시작. 렌즈 계약 준수(순수 함수, measurement 라벨).
+- [ ] **M9 세션 간 반복 지식 비용**: 콘텐츠 해시 기반 크로스세션 중복 과금 측정.
+      전략적 의미: 메모리·벡터 DB 투자 ROI 역산 — 제작자의 별도 벡터 DB 프로젝트와 상호 판매 구조.
+- [ ] **M10 핸드오프 세금**: 서브에이전트 페이로드 측정. 트랜스크립트에 기록된
+      Agent/Task 도구 호출의 부모↔자식 구조 파싱.
+
+각 항목: 단위 테스트 + E2E 골든 + conftest docstring 갱신까지가 완료 정의(tests/AGENTS.md §6).
+
+## 3. 백로그 (우선순위 낮음, 근거 있음)
+
+- [x] PyPI 게시 (v0.3.2) — 신뢰 퍼블리셔(OIDC) `pypi.yml`, 태그 푸시로 게시. README 영어화 + 한국어 README.ko.md 분리, 퀵스타트 `uvx yield-audit` 복원
+- [ ] UNC 경로(`\\host\share`) 자유 텍스트 레닥션 — 현재 README에 문서화된 한계
+- [x] 터치 프리필터(v0.3.1) — path_touch_log 원패스로 무터치 파일 blame 스킵(머지 가드 포함).
+      스냅샷 캐시 일(day) 버킷팅 옵션은 여전히 백로그 — rev-list/ls-tree 절감용
+- [ ] `doctor`에 트랜스크립트 루트 용량·파일수 리포트 추가(사용자가 사전 감사 가능하도록)
+- [ ] v0.3 잔여: M12 정착률(blame 스냅샷, `--snapshot` 서브커맨드), M5 기반 배치 스케줄 조언, M6 개인 라우팅 힌트(옵트인 리플레이) — M11은 0.3.0으로 출시됨(기획서-AIDD의 M11 인간 수정 시간과는 별개 표기 정리 필요 없음, 해당 항목은 M13/M14로 통합 검토)
+
+## 4. 절대 어기지 말 것 (회귀 방지)
+
+1. **절감 수치 주장 금지** — 측정만. 개입 기능은 v1.x 게이트 뒤.
+2. **런타임 의존성 0** 유지 (stdlib + git CLI). dev 의존성은 런타임 import 금지.
+3. **모든 리포트 블록에 `measurement` 라벨** (observed/estimate/proxy).
+4. **트랜스크립트 파생 문자열은 redact.py 경유** — deep_sanitize는 안전망이지 대체품 아님.
+5. **렌즈 순수성** — I/O·시계·난수 금지, 집계는 `attributed_added`(share 가중).
+6. **커밋 전**: `pytest && ruff check .` 통과 + CHANGELOG 항목 + 버전 2곳 동시 bump.
+7. **실데이터 감사 금지** (상단 경고 재확인 — 리뷰 에이전트 2회 타임아웃의 원인이었음).
+
+## 5. 검증된 참고 수치 (회귀 비교용, macOS arm64 / speed 저장소 / --days 90)
+
+| 항목 | 값 |
+|---|---|
+| 실행 시간 | ~3.5s (v0.1.0 대비 14.1s → 개선) |
+| M1 생존율 | 95.4272% (17,276줄) |
+| M2 낭비 구간 | $4.334524 – $19.773222 |
+| M4 채택당 비용 | $841.384684 (채택 1 / no_output 2) |
+| M5 히트율 | 74.9%, cold 0 |
+
+새 버전 배포 전 이 값을 재현해 수치가 변했다면 그 이유를 설명할 수 있어야 한다.
+(단, speed 저장소 자체가 변하면 당연히 달라진다 — 그 경우 raw 값 비교가 아니라
+"같은 커밋 범위에서 재실행"으로 비교.)