@ictechgy/context-guard 0.4.16 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes for the ContextGuard plugin are documented here.
 
 ## [Unreleased]
 
+- Added a provider-free `context-guard-receipt evaluate phase` surface with
+  closed P2-P6 input/result schemas. It computes shadow/canary/router/adjunct/
+  specialized-track readiness from bounded canonical local records while
+  keeping runtime activation, generalization, provider calls, and savings
+  claims disabled behind the existing sequential phase gates.
+- Changed the discarded v2 Bash canary's fixed marker write from denied shell
+  output redirection to an existing MiniShell-v1-supported `python3 -c` route.
+  Both real hook modes now guard the exact command in provider-free tests, and
+  the offline fake host honors hook denials before creating any marker.
+- Added an explicit `--study-v2-use-existing-login` gate for executable v2
+  provider actions. `prepare` now verifies and pseudonymously binds the exact
+  first-party Claude login plus its owned, non-writable HOME identity without
+  persisting email or organization text. Every provider reservation rechecks
+  that binding, keeps XDG/session paths isolated, excludes credential-shaped
+  environment variables, and omits `CLAUDE_CONFIG_DIR`; `analyze` remains
+  provider- and auth-independent.
+- Bound both discarded v2 Bash-routing canary calls to the same hard `$0.75`
+  per-call Claude CLI budget as each analytic task. The value is part of the
+  immutable canary contract, so prepare/resume rejects drift; the frozen study's
+  218 consumed/reserved identities imply a `$163.50` arithmetic maximum. The
+  CLI enforces each process cap; there is no separate aggregate CLI limiter.
+- Published the sanitized result of the first frozen 12-task live study. The
+  study is explicitly `inconclusive`: one arm-unit exhausted its fixed retry,
+  no favorable subset or correction assessment was analyzed, and no token or
+  cost savings claim is allowed.
+
+## [0.5.1] - 2026-08-19
+
+- Bounded context-pack source, diff, and non-Git traversal input before
+  allocation; made Markdown evidence fences content-derived; and reused one
+  immutable source snapshot across suggest/build so representative pack latency
+  falls from tens of seconds to sub-second without changing ordinary pack bytes.
+- Pinned automatic hook and statusline runtimes instead of trusting ambient
+  `PATH`, Python startup variables, shell startup variables, or executable
+  overrides, while retaining setup-approved OMC integration.
+- Added the backward-compatible Receipt external-approval v2 envelope whose
+  scope truthfully binds manual owner cleanup, plus bounded V4 authorization
+  lock waits, read-only ledger snapshots, cached immutable selection artifacts,
+  and shared V3/V4 failure conformance tests.
+- Preserved sparse token availability in the Mac consumer and added the
+  provider-live test directory to the release gate.
+
+## [0.5.0] - 2026-08-06
+
+- Added the default-off Claude Code `PreToolUse:Bash` reference route. After
+  strong local sanitization, long merged command output can stay in a private
+  project-local Receipt store while the transcript receives a compact,
+  exact-retrieval handle and an executable `context-guard reference` command.
+  Retrieval derives private state internally and pages exact UTF-8 output in
+  fixed 20,000-byte-or-smaller chunks, so resolving a handle cannot replay the
+  complete 10 MB capture in one turn. The legacy trim route and unchanged route
+  remain deterministic fallbacks; source/plugin-only installs cannot enable
+  this npm-only mode.
+- Added the independently versioned `@ictechgy/context-guard-receipt@0.2.0`
+  exact dependency, fixed seven-day reference expiry, bounded authenticated
+  import recovery journal, 10,000,000-byte merged capture ceiling, and
+  expired/revoked reference refusal. Installation and disablement never erase
+  stored artifacts automatically.
+- Added an executable three-arm study across `host_unmodified`, `legacy_trim`,
+  and `bash_reference_v1`, with an explicit `prepare` → `canary` → `run`/`resume`
+  → `analyze` lifecycle. `prepare` binds the CLI and runs local
+  `--version`/`--help` probes without a model request. Provider/model requests
+  occur only during canary and analytic execution. A separate provider-free
+  offline rehearsal exercises the lifecycle with a native fake CLI. The study
+  binds a fixed 12-task corpus and reports the legacy contrast diagnostically;
+  without an independent power model the result is descriptive-only and cannot
+  authorize a savings claim.
+- Added build-once npm candidate manifests, exact cross-package hashes/SRI,
+  paired clean-install discovery smoke, separate trusted publication to
+  `next`, and preflight/rollback-aware promotion to `latest`. No package is
+  published or promoted automatically by this release.
+
 ## [0.4.16] - 2026-08-01
 
 - Sanitizer output-scanning is now one monotonic left-to-right pass. All nine location-prefix consumers previously re-parsed the same optional `path:line:` fragment at every offset, which made lines with few colons quadratic: a single 82,015-byte line took 2.62 s and a 100,014-byte line took 3.98 s. The leading prefix is identified once and the seven unanchored consumers run as fragment-free twins, while the two `^`-anchored header consumers keep their original patterns because they were never a per-offset cost. The same lines now take 64.3 ms and 0.078 s, with doubling ratios of 1.84 to 2.01. Redaction output is byte-identical to the previous implementation, pinned by a differential oracle against a hash-frozen baseline across eleven corpora, three sanitization contexts, both path-display modes, and both shared-state and per-line runs.

package/README.ko.md

@@ -221,6 +221,62 @@ npm exec @ictechgy/context-guard -- --version
 
 `--scope project`는 `AGENTS.md`, `.agents/skills/...`처럼 저장소 안 파일에 적용합니다. `--scope user`는 전체 사용자 환경에 적용하려는 경우에만 의도적으로 사용하세요. 실제 적용에는 `--yes`와 명시적인 `--agent`가 필요하며, 지원되는 쓰기는 되돌리기 기록을 남깁니다.
 
+### Claude Code용 선택적 Bash reference
+
+`bash_reference_v1` 경로는 정확한 프로젝트 로컬 npm 설치에서만 사용할 수
+있습니다. 루트 패키지는 `@ictechgy/context-guard-receipt@0.2.1`을 정확히
+고정합니다. global npm, `npx`, 소스 체크아웃, Homebrew, Claude marketplace
+plugin 배치에서는 기존 Bash trim 동작을 유지하고 setup이 reference 경로를
+사용할 수 없다고 알립니다.
+
+```bash
+npm install --save-exact @ictechgy/context-guard@0.5.1
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --plan
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --yes
+```
+
+기본 비활성인 이 `PreToolUse:Bash` 모드는 강하게 가림 처리된 긴 명령 출력을
+프로젝트의 비공개 Receipt 저장소에 두고 digest에는 짧은 조회 handle만
+넣습니다. Handle은 bearer와 비슷하고 Claude/provider에 보일 수 있으며 발급
+후 정확히 7일 뒤 만료됩니다. Bash 실행 전에 wrapper는 소유자 전용 익명 캡처
+descriptor와 검증된 Receipt broker 하나를 준비합니다. Broker는 코드 로드와
+repository/store/expiry/journal 경계 고정을 끝낸 뒤에만 준비 완료를 알립니다.
+따라서 8,192바이트 공개 임계값보다 작은 출력도 로컬 상태 축을 초기화할 수
+있지만, 이 경우 `ABORT`하고 handle은 내보내지 않습니다. Strong sanitizer,
+정확한 패키지 pin, 절대 Node runtime, broker 준비 또는 최종 등록을 사용할 수
+없으면 감싼 명령의 exit status를 바꾸지 않고 legacy trim으로 돌아갑니다.
+기존 `--artifact-receipt` 캡처와는 동시에 사용할 수 없습니다.
+
+Digest는 handle을 실행 가능한 프로젝트 로컬 조회 명령으로 표시합니다.
+
+```bash
+./node_modules/.bin/context-guard reference <cgr1p-handle>
+```
+
+Handle을 발급한 동일한 물리 프로젝트 root에서 실행하세요. 명령은 비공개
+sibling state 위치를 내부에서 계산하고, 정확한 sanitized UTF-8 출력 중 최대
+20,000바이트 한 페이지만 반환합니다. 남은 바이트가 있으면 diagnostic에 다음
+연속 조회용 `--offset`을 표시하므로 전체 보관 출력을 한 번에 transcript로 쏟지
+않습니다. 잘못되었거나 만료된 handle, 다른 root, stale source, 변경된 패키지,
+잘못된 응답은 payload를 전혀 반환하지 않습니다.
+
+패키지를 제거하기 전에 reference 경로를 먼저 끄세요.
+
+```bash
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --no-bash-reference-v1 --yes --no-diet-scan
+npm uninstall @ictechgy/context-guard
+```
+
+Receipt 상태는 저장소 밖의 비공개 sibling 디렉터리
+`.context-guard-receipt-state-<root-selector-sha256>`에 둡니다. Selector는
+정규화한 root 경로와 device/inode identity를 묶으므로 나란한 저장소끼리
+authority를 공유하지 않습니다. 비활성화와 패키지 제거는 나중의 정확한 재설치나
+별도 사용자 승인 artifact 정리를 위해 이 디렉터리를 보존합니다. 다만 `npm
+uninstall`은 검증된 package-local code와 `node_modules/.bin/context-guard`를
+제거하므로, 정확한 프로젝트 로컬 pair를 다시 설치하기 전에는 reference 조회를
+할 수 없습니다. 이 메커니즘은 큰 Bash 출력의 transcript 입력을 줄일 수 있지만
+고정된 provider token 또는 비용 절감을 보장하지 않습니다.
+
 ## Homebrew 배포 경로
 
 Homebrew는 공유 `ictechgy/tap` tap을 통해 macOS 배포 경로로 사용할 수 있습니다.
@@ -295,6 +351,14 @@ long-command 2>&1 | ./plugins/context-guard/bin/context-guard-artifact store --c
   --manifest-out suggested-pack.json \
   --pack-out context-pack.md \
   --budget-bytes 12000 --json --explain --adaptive-k --symbol-memory
+# 안전한 direct import neighbor를 최대 4개까지 pack에 명시적으로 추가:
+./plugins/context-guard/bin/context-guard-pack auto \
+  --root . --files src/app.py --query "entrypoint 검토" --top 1 \
+  --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
+# 로컬 품질 gate 통과 뒤 heuristic source를 명시적으로 축소:
+./plugins/context-guard/bin/context-guard-pack auto \
+  --root . --query "실패 테스트 검토" --top 8 \
+  --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
 # 또는 명시적인 두 단계로 실행:
 ./plugins/context-guard/bin/context-guard-pack suggest \
   --root . --query "failing tests review" --diff HEAD \
@@ -316,7 +380,9 @@ long-command 2>&1 | ./plugins/context-guard/bin/context-guard-artifact store --c
 - JSON explain에는 bounded `repo_map`이 포함될 수 있습니다. 예시는 sampled byte/token-proxy tree, category-only secret risk count, signature-first hint, explain-only graph rank, 기존 `slice`/symbol 재조회 힌트입니다.
 - repo-map은 manifest, pack 본문, receipt, byte budget을 바꾸지 않고 네트워크·모델 호출·임베딩을 쓰지 않습니다. 토큰 값은 provider-token이나 savings claim이 아닌 추정 `chars_div_4` proxy입니다.
 - `suggest` 또는 `auto`에 `--adaptive-k`를 추가하면 로컬 score distribution, byte-budget fit, clamped score-mass 기반 recall/precision proxy에서 나온 advisory-only top-k shrink/expand metadata를 포함합니다. `--adaptive-k-policy balanced|recall|precision`과 선택적 `--adaptive-k-min-recall-proxy` / `--adaptive-k-min-precision-proxy` gate로 로컬 추천 정책을 고를 수 있고, gate 실패는 metadata-only(`pass|failed`)입니다. adaptive block은 capped selected/omitted evidence와 구조화된 source-verification hint를 포함하지만 추천값을 자동 적용하지 않으며 manifest, pack 본문, receipt, byte budget을 바꾸지 않습니다.
+- `auto --apply-adaptive-k`는 명시적·기본 비활성 pruning 경로입니다. 회귀 gate가 통과할 때만 로컬 추천값을 적용하고, 호출자가 지정한 file/output/test-output 및 diff source는 항상 유지한 채 같은 byte budget으로 다시 build하며 `adaptive_k_application`을 기록합니다. `--adaptive-k`를 내포하지만 provider token/cost 절감 주장을 허용하지 않습니다.
 - `auto`에 `--symbol-memory`를 추가하면 repo-map 기반 symbol/graph advisory metadata와 정확한 `slice` / `read-symbol` 검증 힌트를 포함합니다. 이는 source verification 안내일 뿐이며 manifest, pack 본문, receipt, byte budget을 바꾸지 않습니다.
+- `--apply-symbol-memory`는 명시적·기본 비활성 Graphify식 적용 경로입니다. 일반 추천 뒤 안전한 direct import neighbor slice를 최대 4개 manifest에 추가하고 같은 byte budget으로 pack을 다시 만듭니다. explicit/query seed는 더 높은 우선순위를 유지하고 secret-risk neighbor는 제외하며 exact source/fallback receipt는 보존됩니다. 결과에는 닫힌 `graph_application` 블록이 기록되며 provider token/cost 절감 주장은 하지 않습니다.
 - `--manifest-out`은 `build`가 읽을 수 있는 manifest를 저장하고, `--pack-out`은 렌더링된 팩 본문을 저장합니다.
 - `context-guard-pack suggest`는 더 낮은 수준의 로컬 전용 준비 단계입니다. `--query`, `--diff`, 반복 `--files`, 그리고 `--root` 아래의 선택적 `--output` / `--test-output` 텍스트 파일을 가림 처리한 신호에서 후보 파일과 줄 범위를 순위화한 뒤 `build --manifest`가 바로 읽을 수 있는 manifest를 씁니다.
 - `context-guard-pack build`는 우선순위가 있는 로컬 파일 근거를 렌더링된 UTF-8 바이트 기준 `--budget-bytes` 안의 Markdown 팩으로 조립합니다. JSON 출력은 포함·부분 포함·중복·unsafe·missing·예산 초과로 누락된 source를 기록합니다.
@@ -405,7 +471,7 @@ JSON 출력에는 여러 증거 surface가 포함될 수 있습니다.
 [Sonnet] repo | main | ctx 86% ⚠ | cost $0.123 | cache 80% | reuse 8.0x
 ```
 
-`cache N%`는 최근 일정 범위의 대화 기록에서 관찰된 입력 토큰 중 cache read가 차지하는 비율이며, cache read가 1회 이상 있을 때만 표시됩니다. `reuse X.Yx`는 `cache_read / cache_creation` 값이며, cache read가 양수이고 cache creation이 0이 아닐 때만 표시됩니다. `⚠` 표시는 컨텍스트 사용률이 경고 기준에 도달했을 때 나타나며 기본값은 80%입니다. 프로젝트나 셸에서 `CONTEXT_GUARD_STATUSLINE_CTX_WARN=90`처럼 조정할 수 있습니다.
+`cache N%`는 최근 일정 범위의 대화 기록에서 관찰된 입력 토큰 중 cache read가 차지하는 비율이며, cache read가 1회 이상 있을 때만 표시됩니다. `reuse X.Yx`는 `cache_read / cache_creation` 값이며, cache read가 양수이고 cache creation이 0이 아닐 때만 표시됩니다. `⚠` 표시는 컨텍스트 사용률이 경고 기준에 도달했을 때 나타나며 기본값은 80%입니다. 자동 훅은 격리된 환경에서 실행되므로 `CONTEXT_GUARD_STATUSLINE_CTX_WARN=90`을 설정한 뒤 setup을 다시 실행해 이 안전한 동작 설정을 설치 명령에 고정하세요. Python·shell loader 변수는 전달하지 않습니다.
 
 ### 반복 가능한 벤치마크 실행
 
@@ -545,6 +611,21 @@ context-guard-setup --plan
 
 `context-guard mcp`(또는 `context-guard-mcp`)는 의존성 없는 로컬 stdio MCP 서버입니다. 프로세스 하나는 root와 namespace 하나에 고정되며 compression, sanitization된 artifact 조회, 로컬 통계만 제공합니다. HTTP, SSE, 네트워크, provider, model, proxy, 자동 client 설정 기능은 없습니다. 저장되는 fallback은 원문이 아닌 정확한 sanitization 완료 사본이고 다른 namespace의 artifact는 조회할 수 없습니다. 이 로컬 어댑터는 hosted token/cost 절감을 주장하지 않습니다.
 
+반복 파일·로그 컨텍스트를 명시적으로 다루려면 함께 설치되는 Receipt
+companion을 `context-guard-receipt-mcp --root /absolute/repository`로 실행할
+수 있습니다. `receipt_context` 도구는 사용자가 `eligible`이라고 명시한
+상대 경로만 읽고, byte-benefit router가 유리하다고 판단하면 compact exact
+reference를 반환하며, 반복 조회에는 같은 live reference를 재사용하고 한 번에
+최대 65,536바이트의 exact slice만 가져옵니다. 이 기능은 opt-in이며
+process-local입니다. 선택적 task scope는 task 간 재사용을 막고, 명시적 release는
+context GC를 수행하며, content-free history에는 process-keyed HMAC과 결정만
+남습니다. `receipt_diagnose`는 파일 byte를 반환하지 않고 비적용 shadow
+firewall/router와 prefix 재사용 기반 scout/surgeon 안내를 제공합니다. 명시적
+private `--state-dir`로 같은 binary를 시작하면 action을 실행하지 않는
+authenticated `receipt_twin` 근거 기록만 추가됩니다. 스스로 등록되거나 전체
+prompt를 가로채지 않고, capability가 재시작을 넘어 유지되지 않으며, provider를
+호출하거나 hosted 절감 효과를 주장하지 않습니다.
+
 ## 릴리스 확인
 
 릴리스에 민감한 변경을 배포하거나 머지하기 전에는 동기화 확인과 두 게이트를 모두 실행하세요.

package/README.md

@@ -234,6 +234,66 @@ npm exec @ictechgy/context-guard -- --version
 
 Use `--scope project` for repository files such as `AGENTS.md` and `.agents/skills/...`. Use `--scope user` only when you intentionally want a user-level path; applying user scope requires `--yes` plus an explicit `--agent`, and supported writes record rollback metadata.
 
+### Opt-in Bash references for Claude Code
+
+The `bash_reference_v1` route is available only from an exact, project-local npm
+installation. The root package pins `@ictechgy/context-guard-receipt@0.2.1`; a
+global, `npx`, source-checkout, Homebrew, or Claude marketplace-plugin layout
+keeps the existing Bash trim behavior and setup reports the reference route as
+unavailable.
+
+```bash
+npm install --save-exact @ictechgy/context-guard@0.5.1
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --plan
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --yes
+```
+
+This default-off `PreToolUse:Bash` mode keeps strongly sanitized long command
+output in the private project-local Receipt store and puts only a compact
+retrieval handle in the digest. The handle is bearer-like and can be visible to
+Claude/the provider; it expires exactly seven days after issuance. Before Bash
+starts, the wrapper creates an anonymous owner-only capture descriptor and one
+verified Receipt broker, which preloads code and retains the repository, store,
+expiry, and journal boundaries. Even output below the 8,192-byte disclosure
+threshold can therefore initialize those local axes; it sends `ABORT` and emits
+no handle. If strong sanitization, the exact package pin, the absolute Node
+runtime, broker preparation, or final registration is unavailable, execution
+falls back to legacy trimming without changing the wrapped command's exit
+status. The mode is mutually exclusive with legacy `--artifact-receipt`
+capture.
+
+The digest renders the handle as an executable, project-local retrieval command:
+
+```bash
+./node_modules/.bin/context-guard reference <cgr1p-handle>
+```
+
+Run it from the same physical project root that issued the handle. It derives
+the private sibling state location internally and returns one exact sanitized
+UTF-8 page, capped at 20,000 bytes. When more bytes remain, its diagnostic gives
+the next continuation `--offset`; each page stays bounded, so retrieval cannot dump
+the full retained output into the transcript in one step. Invalid, expired,
+wrong-root, stale-source, changed-package, and malformed references return no
+payload.
+
+Disable the route before uninstalling:
+
+```bash
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --no-bash-reference-v1 --yes --no-diet-scan
+npm uninstall @ictechgy/context-guard
+```
+
+Receipt state is kept outside the repository in a private sibling directory
+named `.context-guard-receipt-state-<root-selector-sha256>`. The selector binds
+the normalized root path and its device/inode identity so sibling repositories
+do not share authority. Disablement and package removal preserve that directory
+for a later exact reinstall or separately authorized artifact cleanup. `npm
+uninstall` removes the verified package-local code and
+`node_modules/.bin/context-guard`, so reference retrieval is unavailable until
+the exact project-local pair is reinstalled. This mechanism can reduce
+transcript input for large Bash output, but it does not guarantee a fixed
+provider-token or cost reduction.
+
 ## Homebrew release path
 
 Homebrew is available through the shared `ictechgy/tap` tap:
@@ -319,6 +379,14 @@ Artifact mode is for capture, sandbox search, and retrieval. It stores sanitized
   --manifest-out suggested-pack.json \
   --pack-out context-pack.md \
   --budget-bytes 12000 --json --explain --adaptive-k --symbol-memory
+# Explicitly add up to four safe direct import neighbors to the pack:
+./plugins/context-guard/bin/context-guard-pack auto \
+  --root . --files src/app.py --query "review entrypoint" --top 1 \
+  --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
+# Explicitly prune heuristic sources after the local quality gates pass:
+./plugins/context-guard/bin/context-guard-pack auto \
+  --root . --query "review failing tests" --top 8 \
+  --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
 # Or run the two explicit steps:
 ./plugins/context-guard/bin/context-guard-pack suggest \
   --root . --query "review failing tests" --diff HEAD \
@@ -340,7 +408,9 @@ A few boundaries are intentional:
 - `--explain` may include bounded `repo_map` metadata: sampled byte/token-proxy tree entries, category-only secret-risk counts, signature-first file hints, explain-only graph ranks, and exact `slice`/symbol retrieval hints.
 - Explain metadata does not change the manifest, pack body, receipt, or byte budget. It does not use network/model/embedding calls, and token values remain local `chars_div_4` proxies rather than provider-token or savings claims.
 - Add `--adaptive-k` to `suggest` or `auto` for advisory-only shrink/expand top-k metadata derived from local score distribution, byte-budget fit, and clamped score-mass recall/precision proxies. Use `--adaptive-k-policy balanced|recall|precision` plus optional `--adaptive-k-min-recall-proxy` / `--adaptive-k-min-precision-proxy` gates to choose a local recommendation policy; gate failures are metadata-only (`pass|failed`). The adaptive block includes capped selected/omitted evidence and structured source-verification hints, never applies the recommendation automatically, and does not change the manifest, pack body, receipt, or byte budget.
+- Add `--apply-adaptive-k` to `auto` for an explicit, default-off pruning pass. It applies the local recommendation only when its regression gates pass, always retains caller-declared file/output/test-output and diff sources, rebuilds inside the same byte budget, and records `adaptive_k_application`. It implies `--adaptive-k` and does not authorize a provider-token or cost-savings claim.
 - Add `--symbol-memory` to `auto` for repo-map-derived symbol/graph advisory metadata with exact `slice` / `read-symbol` verification hints. It is source-verification guidance only and does not change the manifest, pack body, receipt, or byte budget.
+- Add `--apply-symbol-memory` for an explicit, default-off Graphify-style step: after the ordinary suggestion pass, it adds at most four direct import-neighbor slices to the manifest and rebuilds within the same byte budget. Explicit/query seeds keep higher priority, secret-risk neighbors are excluded, the exact source/fallback receipt remains available, and the result records a closed `graph_application` block. This implies symbol-memory output but makes no provider-token or cost claim.
 - `--manifest-out` writes a build-compatible manifest; `--pack-out` saves the rendered pack.
 - `context-guard-pack suggest` is the lower-level additive local-only planning step. It ranks candidate files and line ranges from `--query`, `--diff`, repeated `--files`, and optional sanitized `--output` / `--test-output` files under `--root`, then writes a manifest that `build --manifest` can consume.
 - `context-guard-pack build` assembles prioritized local file evidence into a Markdown body whose rendered UTF-8 bytes stay within `--budget-bytes`. JSON output records included, partial, duplicate, unsafe, missing, and budget-omitted sources.
@@ -460,7 +530,7 @@ These fields can flag likely volatile content near the prompt prefix, stable-pre
 [Sonnet] repo | main | ctx 86% ⚠ | cost $0.123 | cache 80% | reuse 8.0x
 ```
 
-`cache N%` is the cache-read share of observed input-side tokens in the bounded transcript tail and stays hidden until at least one cache read is observed. `reuse X.Yx` is `cache_read / cache_creation` and is shown only when cache read is positive and cache creation is non-zero. The `⚠` marker appears when context usage reaches the warning threshold, defaulting to 80%; set `CONTEXT_GUARD_STATUSLINE_CTX_WARN=90` to tune it for a project or shell.
+`cache N%` is the cache-read share of observed input-side tokens in the bounded transcript tail and stays hidden until at least one cache read is observed. `reuse X.Yx` is `cache_read / cache_creation` and is shown only when cache read is positive and cache creation is non-zero. The `⚠` marker appears when context usage reaches the warning threshold, defaulting to 80%. Automatic hooks run with an isolated environment, so set `CONTEXT_GUARD_STATUSLINE_CTX_WARN=90` and rerun setup to pin that safe behavior setting into the installed command; Python and shell loader variables are never carried through.
 
 ### Run a repeatable benchmark
 
@@ -609,6 +679,21 @@ Do not rely on `PATH` lookup for generated hooks by default. The setup wizard re
 
 `context-guard mcp` (or `context-guard-mcp`) is a dependency-free local stdio MCP server. Each process is fixed to one root and one namespace; it exposes only compression, sanitized artifact retrieval, and local statistics. It has no HTTP, SSE, network, provider, model, proxy, or automatic client-configuration surface. Stored fallback content is an exact sanitized copy, not raw input, and artifacts from another namespace are not retrievable. This local adapter makes no hosted token or cost-savings claim.
 
+For explicit repeated file or log context, the bundled Receipt companion also
+provides `context-guard-receipt-mcp --root /absolute/repository`. Its
+`receipt_context` tool accepts an explicitly eligible relative path, returns a
+compact exact reference when the byte-benefit router says deferral is useful,
+reuses that live reference for repeated reads, and retrieves exact slices of at
+most 65,536 bytes. Optional task scopes prevent cross-task reuse, explicit
+release performs context GC, and the content-free history records only
+process-keyed HMACs and decisions. `receipt_diagnose` adds non-applying shadow
+firewall/router plus prefix-reuse scout/surgeon advice without returning file
+bytes. Starting the same binary with an explicit private `--state-dir` enables
+only `receipt_twin`, which records authenticated revalidation evidence but
+executes no action. The flow remains opt-in: it does not register itself,
+intercept whole prompts, survive capability restart, call a provider, or make a
+hosted savings claim.
+
 ## Release checks
 
 Before publishing or merging release-sensitive changes, run the copy check and both gates:

package/docs/distribution.md

@@ -27,6 +27,106 @@ context-guard setup --agent claude --scope user --plan
 
 Project scope is the default. `context-guard doctor` and `context-guard setup --verify` are read-only health checks. User scope is opt-in and requires an explicit agent for writes. Supported user-scope writes record backups and rollback metadata under `.context-guard/rollback` in the user home directory. Setup resolves packaged/check-out helpers first; `PATH` helper fallback is default-off and requires `--allow-path-helper-fallback` for a trusted install after canonical executable and identity validation.
 
+## Exact npm pair for Bash references
+
+`bash_reference_v1` is a narrower distribution than the ordinary CLI/plugin.
+It accepts only an exact project-local npm topology: root
+`@ictechgy/context-guard@0.5.1` declares
+`@ictechgy/context-guard-receipt: 0.2.1`, and the installed Receipt inventory
+must match the SHA-256 trust anchor embedded in the root policy. Hoisted and
+nested npm dependency layouts are supported; global npm, `npx`, Homebrew,
+source-checkout, arbitrary `PATH`, and marketplace-plugin layouts are refused.
+
+```bash
+npm install --save-exact @ictechgy/context-guard@0.5.1
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --plan
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --bash-reference-v1 --yes
+```
+
+Setup writes the opt-in flag only when the paired topology is present. Doctor
+and source/plugin setup report it as unavailable otherwise and retain the
+legacy Bash trim hook. Runtime discovery never launches Node by name from
+`PATH`: it binds an absolute interpreter from fixed system locations, with a
+GitHub Actions-only Node fallback restricted to fixed hosted-toolcache roots,
+and rechecks the pinned Receipt files before starting one private broker. Before
+Bash starts, every interpreter must be a regular, single-link executable owned
+by root or the current user, executable, and not group- or world-writable. The
+CI workflow validates the canonical hosted Python and Node locations, removes
+group/world write permission from exactly those two ephemeral targets, and then
+runs the same production preflight; `GITHUB_ACTIONS` never weakens this policy.
+The broker has
+already loaded its code and retained the repository, store, expiry, journal,
+and anonymous owner-only capture descriptors. `COMMIT` therefore performs no
+later package-path, interpreter, or Git lookup. Even a below-threshold command
+can initialize the local state axes before the wrapper sends `ABORT`. A missing
+strong sanitizer, changed package, invalid response, timeout, or unavailable
+state yields legacy output, not a reference and not a changed child exit
+status.
+
+An issued digest contains the directly executable retrieval command below; it
+must be run from the same physical project root:
+
+```bash
+./node_modules/.bin/context-guard reference <cgr1p-handle>
+```
+
+The root command never accepts or reveals `--root` or `--state-dir`. It derives
+the deterministic sibling state internally and returns at most one exact
+20,000-byte sanitized UTF-8 page. If more content remains, a compact diagnostic
+provides the next continuation `--offset`. Expansion rechecks the exact package,
+root/source binding, and active seven-day registry entry; any failure emits no
+payload.
+
+The handle is provider-visible bearer material with an exact seven-day expiry.
+State is placed outside the repository in a private sibling named
+`.context-guard-receipt-state-<root-selector-sha256>`; the selector binds the
+normalized root path and device/inode identity. This keeps Receipt state
+physically disjoint from the repository snapshot and separates sibling roots.
+Disablement removes only the hook flag, and npm uninstall removes package code
+but deliberately leaves state/artifacts intact for a later exact reinstall or
+separately authorized cleanup. After uninstall, the verified package-local code
+and `node_modules/.bin/context-guard` are absent, so retrieval is unavailable
+until the exact project-local pair is reinstalled:
+
+```bash
+./node_modules/.bin/context-guard setup --root . --agent claude --scope project --no-bash-reference-v1 --yes --no-diet-scan
+npm uninstall @ictechgy/context-guard
+```
+
+Artifact deletion is not automated; it requires a separate, explicit
+user-authorized retention decision. `--bash-reference-v1` and
+`--artifact-receipt` are mutually exclusive.
+
+## npm candidate, publication, and promotion gates
+
+`.github/workflows/npm-candidate.yml` checks out one exact commit, runs both
+package gates, packs each package exactly once offline, exercises the paired
+tarballs in a clean install, and uploads immutable per-package artifacts. The
+shared candidate manifest binds the commit, exact dependency, Receipt inventory
+digest, policy digest, SHA-256, sha512 SRI, sizes, toolchain, and protocol. The
+workflow refuses a requested commit that differs from its own workflow-source
+commit so the later source and signer attestation digests bind the same revision.
+
+`.github/workflows/npm-publish.yml` downloads an exact artifact by run and
+artifact ID, revalidates the manifest and tarball, verifies GitHub build
+provenance for both the candidate manifest and tarball against the candidate
+source commit plus the exact trusted signer workflow revision, and publishes
+only that tarball to `next`. Publishing the root also
+requires the npm registry's Receipt `dist.integrity` to equal the Receipt bytes
+bound in the same candidate manifest. Publication remains a manual,
+environment-protected operation and is not performed by CI automatically.
+
+`.github/workflows/npm-promote.yml` is a separate manual gate. Before changing
+`latest`, it proves both requested versions are the current reviewed `next`
+pair, verifies the root's exact Receipt dependency, and records the previous
+tags for rollback. One manually approved `npm-pair-promote` environment exposes
+the two package-scoped credentials only to the pair-mutation step. That same
+shell moves Receipt then root and, on failure or ordinary cancellation, attempts
+both compensating tag restores before it exits; no second environment approval
+is needed for compensation. A force-cancel, unavailable npm registry, or
+unavailable promotion credential can still prevent restoration; in that case
+rerun the preflight and restore the recorded previous tags explicitly.
+
 ## Runtime requirements
 
 The helpers are Python/shell scripts packaged through npm and Homebrew as plugin-local `plugins/context-guard/bin` entrypoints plus `plugins/context-guard/lib` helpers; checkout-only `context-guard-kit` sources are not duplicated in the npm tarball. Supported machines need:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.16",
+  "version": "0.5.1",
   "description": "ContextGuard CLI helpers for keeping AI coding agent context focused and local-first.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ictechgy/context-guard#readme",
@@ -12,6 +12,9 @@
     "url": "https://github.com/ictechgy/context-guard/issues"
   },
   "type": "commonjs",
+  "dependencies": {
+    "@ictechgy/context-guard-receipt": "0.2.1"
+  },
   "bin": {
     "context-guard": "plugins/context-guard/bin/context-guard",
     "context-guard-setup": "plugins/context-guard/bin/context-guard-setup",

package/plugins/context-guard/.claude-plugin/plugin.json

@@ -37,5 +37,5 @@
     "gated-experiments",
     "future-roadmap"
   ],
-  "version": "0.4.16"
+  "version": "0.5.1"
 }

package/plugins/context-guard/README.ko.md

@@ -46,6 +46,15 @@ context-guard setup --agent codex --scope project --brief-mode standard --plan
 npx @ictechgy/context-guard --version
 ```
 
+짧은 `bash_reference_v1` Bash 출력 경로는 이 marketplace plugin/소스 배치에서
+의도적으로 활성화되지 않습니다. 정확한 프로젝트 로컬
+`@ictechgy/context-guard@0.5.1` npm 설치와
+`@ictechgy/context-guard-receipt@0.2.1` 의존성이 필요하며, 그 뒤
+`setup --agent claude --scope project --bash-reference-v1`로 명시적으로
+활성화해야 합니다. Plugin setup은 동작하지 않는 reference flag를 설치하지 않고
+legacy trim을 유지하며 경고합니다. 활성화·비활성화, 7일 handle, 상태 보존은
+저장소의 배포 문서를 참고하세요.
+
 이 저장소 루트에서는 경로를 직접 지정해 실행하세요.
 
 ```bash
@@ -78,6 +87,8 @@ context-guard-read-symbol path/to/file.py TargetSymbol
 context-guard-sanitize-output -- rg -n "TOKEN|SECRET" .
 context-guard-sanitize-output -- git diff
 context-guard-pack auto --root . --query "failing tests review" --diff HEAD --manifest-out suggested-pack.json --pack-out context-pack.md --budget-bytes 12000 --json --explain --adaptive-k --adaptive-k-policy recall
+context-guard-pack auto --root . --files src/app.py --query "entrypoint 검토" --top 1 --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
+context-guard-pack auto --root . --query "실패 테스트 검토" --top 8 --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json --no-artifact --delta-from-pack-id 0123456789abcdef0123
 context-guard-pack slice --root . --path README.md --lines 1:40 --json
@@ -99,8 +110,9 @@ context-guard-statusline-merged
 - **컨텍스트 관리 스캐너**는 누락된 `permissions.deny` 가드레일, Bash 출력 축약 훅, 상태표시줄 설정, 넓은 읽기 허용, 비용이 큰 기본 모델/추론 강도, 많은 MCP 서버, 크거나 민감해 보이는 에이전트 규칙 파일, 부피가 크거나 민감해 보이는 로컬 경로에 대한 자문형 context-exclusion 추천을 확인합니다.
 - **대용량 읽기 가드와 심볼 리더**는 파일 전체 읽기 전에 검색, 심볼 구간, 작은 줄 범위 읽기 순서로 에이전트를 안내합니다. Python, JavaScript/TypeScript, Go, Rust 소스 구간 읽기를 지원합니다.
 - **로컬 로그 보관소**는 큰 명령 출력을 기본적으로 `.context-guard/artifacts`에 가림 처리해 저장하고, 줄 번호가 있는 top error, 중복 라인 그룹, 가림 처리된 bounded suggested query, 안정적인 `contextguard-artifact:<id>` 핸들이 담긴 `output_sandbox` 요약 기록이나 요청한 정확한 줄 범위만 반환합니다. `receipt <artifact_id> --json`은 본문 없이 핸들과 재조회 명령만 다시 출력합니다. `get`과 `list`는 리브랜딩 이전의 `.claude-token-optimizer/artifacts` 요약 기록도 읽을 수 있습니다.
-- **예산 기반 컨텍스트 패커**는 우선순위가 있는 로컬 파일 근거를 렌더링된 바이트 예산 안의 Markdown pack으로 조립하고, 포함·부분 포함·누락 source 메타데이터, bounded `.context-guard/packs` 요약 기록, 안전할 때만 정확한 가림 처리 `slice` 명령, 안전하지 않을 때의 `retrieval_omitted_reason`을 남깁니다. 추가된 `auto` 하위 명령은 추천과 pack build를 한 번에 실행하고, `auto --explain`은 manifest, pack 본문, receipt, byte budget을 바꾸지 않으면서 결정적 로컬 선택/build 이유를 짧게 추가합니다. JSON explain의 bounded repo-map은 sampled byte/token-proxy tree, category-only secret risk count, signature-first hint, explain-only graph rank, 기존 `slice`/symbol 재조회 힌트를 제공하지만 pack 선택이나 provider savings claim은 아닙니다. `suggest`는 로컬 query, diff, 명시 파일, 가림 처리된 output/test-output 신호를 `build`와 호환되는 manifest로 순위화하며 네트워크·모델 호출·임베딩·provider 비용 추정은 하지 않습니다. `suggest/auto --adaptive-k`는 `--adaptive-k-policy balanced|recall|precision` 및 선택적 recall/precision proxy gate, capped selected/omitted evidence, 구조화된 source-verification hint를 제공하지만 추천값을 자동 적용하거나 manifest/pack/receipt를 바꾸지 않습니다. 토큰 수는 측정된 provider token 절감이 아니라 추정 `chars_div_4` proxy입니다.
+- **예산 기반 컨텍스트 패커**는 우선순위가 있는 로컬 파일 근거를 렌더링된 바이트 예산 안의 Markdown pack으로 조립하고, 포함·부분 포함·누락 source 메타데이터, bounded `.context-guard/packs` 요약 기록, 안전할 때만 정확한 가림 처리 `slice` 명령, 안전하지 않을 때의 `retrieval_omitted_reason`을 남깁니다. 추가된 `auto` 하위 명령은 추천과 pack build를 한 번에 실행하고, `auto --explain`은 manifest, pack 본문, receipt, byte budget을 바꾸지 않으면서 결정적 로컬 선택/build 이유를 짧게 추가합니다. JSON explain의 bounded repo-map은 sampled byte/token-proxy tree, category-only secret risk count, signature-first hint, explain-only graph rank, 기존 `slice`/symbol 재조회 힌트를 제공하지만 pack 선택이나 provider savings claim은 아닙니다. `suggest`는 로컬 query, diff, 명시 파일, 가림 처리된 output/test-output 신호를 `build`와 호환되는 manifest로 순위화하며 네트워크·모델 호출·임베딩·provider 비용 추정은 하지 않습니다. `suggest/auto --adaptive-k`는 `--adaptive-k-policy balanced|recall|precision` 및 선택적 recall/precision proxy gate, capped selected/omitted evidence, 구조화된 source-verification hint를 제공하지만 추천값을 자동 적용하거나 manifest/pack/receipt를 바꾸지 않습니다. 명시적 `auto --apply-symbol-memory`는 안전한 direct import neighbor slice를 최대 4개 manifest에 추가하고 동일 byte budget으로 다시 build합니다. explicit/query seed의 우선순위를 보존하고 secret-risk neighbor를 제외하며 exact fallback과 닫힌 `graph_application` 근거를 남깁니다. 토큰 수는 측정된 provider token 절감이 아니라 추정 `chars_div_4` proxy입니다.
 - **Tool/MCP schema pruner**는 로컬 tool catalog를 bounded top-k 자문 리포트로 순위화하고, compact 요약 기록과 payload integrity check로 전체 가림 처리된 schema 재조회를 보존합니다. `defer-report`는 core inline tool과 deferred stub/namespace 요약을 나누고 gross deferred-schema 및 net initial-report `chars_div_4` proxy 회계를 보여주지만, deferred tool을 쓰기 전에는 전체 schema를 다시 조회해야 합니다.
+- **적용형 adaptive breadth**는 명시적 `auto --apply-adaptive-k`에서만 동작합니다. 로컬 회귀 gate 통과 뒤 heuristic source를 줄이고 caller가 지정한 file/output/test-output 및 diff source는 항상 보존하며, 같은 byte budget으로 다시 build하고 `adaptive_k_application`을 기록합니다. 로컬 proxy는 provider token/cost 절감 주장을 허용하지 않습니다.
 - **보수적 압축기**는 가림 처리된 stdin을 JSON, diff, 로그, 검색 출력, 코드, 산문으로 분류하고, 관측 바이트 근거와 추정 토큰 proxy를 함께 노출합니다.
 - **정적 cache-score lint와 Anthropic 비용 가드/route advisor**는 `context-guard-cache-score`로 로컬 prompt/request cache layout과 사용자 제공 cache write/read multiplier 기반 amortization 위험을 안내하고, `context-guard cost preflight/observe/ledger/compile`로 호출 전 비용 추정, provider usage 대조, keyed-HMAC cache 위험 기록, 안정적인 prefix 배치 안내를 제공합니다. `context-guard route-advisor`는 caller가 제공한 workload JSON, provider feature 선언, usage telemetry, 외부·로컬 shifted cost를 읽는 local-only passive advisor이며 queue를 시작하거나 provider를 호출하거나 pricing 문서를 새로 가져오거나 provider feature 지식을 authoritative하게 취급하지 않고 total-cost accounting, batchability blocker, route 후보를 출력합니다. 원문 프롬프트를 저장하지 않고 Anthropic/provider prompt cache를 대체하지 않으며, 추천은 matched successful task, 비열등 quality evidence, shifted-cost accounting 없이는 hosted token/cost 절감 주장이 아닙니다.
 - **출력 축약기**는 감싼 명령의 종료 코드를 보존하면서 긴 로그를 줄이고, `--digest markdown` 또는 `--digest json`으로 실행기 실패 정보, 가림 처리된 failure signature, 중복 라인 그룹, 다음 조회 제안이 담긴 요약을 만들 수 있습니다. `--artifact-receipt`를 digest mode와 함께 쓰면 sanitized 전체 출력을 로컬 artifact receipt로 저장하고 `contextguard-artifact:<id>` 핸들과 `context-guard-artifact receipt/get/search ...` 재조회 명령으로 누락된 slice를 다시 확장할 수 있습니다.
@@ -160,6 +172,18 @@ context-guard experiments verify proof-carrying-context --artifact-dir ./artifac
 
 `context-guard mcp`와 `context-guard-mcp`는 의존성 없는 로컬 stdio MCP 자식 프로세스를 실행합니다. 프로세스는 root와 namespace 하나로 격리되고 sanitization된 compression, 정확한 sanitization artifact fallback, 로컬 통계만 제공합니다. HTTP, 네트워크, provider, model, proxy 통합이나 client 설정 변경은 없습니다. artifact는 namespace 사이에서 접근할 수 없고 hosted token/cost 절감도 주장하지 않습니다.
 
+설치된 Receipt companion도
+`context-guard-receipt-mcp --root /absolute/repository`로 명시적으로 실행할 수
+있습니다. `receipt_context` 도구는 사용자가 `eligible`이라고 명시한 상대
+파일·로그를 보수적 byte router가 유리하다고 판단할 때 compact process-local
+exact reference로 저장하고, 같은 live reference를 재사용하며, 한 번에 최대
+65,536바이트의 exact slice를 조회합니다. 선택적 task scope와 명시적 release는
+process-local context GC를 제공하고, content-free history에는 keyed digest와
+결정만 남습니다. `receipt_diagnose`는 비적용 firewall/router와 prefix 재사용
+scout/surgeon 안내를 제공하며, 명시적 private `--state-dir`는 authenticated
+advisory `receipt_twin`만 활성화합니다. 자동 등록, prompt 가로채기, capability의
+재시작 후 지속 저장, provider 호출, hosted 절감 주장은 하지 않습니다.
+
 ## 로컬 배포 테스트
 
 마켓플레이스 저장소 루트에서 실행합니다.

package/plugins/context-guard/README.md

@@ -46,6 +46,15 @@ context-guard setup --agent codex --scope project --brief-mode standard --plan
 npx @ictechgy/context-guard --version
 ```
 
+The compact `bash_reference_v1` Bash-output route is intentionally not
+available from this marketplace-plugin/source layout. It requires an exact
+project-local npm installation of `@ictechgy/context-guard@0.5.0` and its
+`@ictechgy/context-guard-receipt@0.2.0` dependency, then explicit
+`setup --agent claude --scope project --bash-reference-v1`. Plugin setup keeps
+legacy trimming and warns instead of installing a no-op reference flag. See the
+repository distribution guide for activation, disablement, seven-day handle,
+and preserved-state details.
+
 From this repository root, run helpers by path:
 
 ```bash
@@ -84,6 +93,8 @@ context-guard-sanitize-output -- git diff
 context-guard-filter validate --config .context-guard/filter-dsl.json
 context-guard-filter run --config .context-guard/filter-dsl.json -- git status --short
 context-guard-pack auto --root . --query "review failing tests" --diff HEAD --manifest-out suggested-pack.json --pack-out context-pack.md --budget-bytes 12000 --json --explain --adaptive-k --adaptive-k-policy recall --symbol-memory
+context-guard-pack auto --root . --files src/app.py --query "review entrypoint" --top 1 --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
+context-guard-pack auto --root . --query "review failing tests" --top 8 --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json --no-artifact --delta-from-pack-id 0123456789abcdef0123
 context-guard-pack slice --root . --path README.md --lines 1:40 --json
@@ -108,8 +119,9 @@ Opt-in `build`/`auto --sketch-duplicate-veto` applies a rank-stable pre-budget g
 - **Large-read guard and symbol reader** guide the agent from search to symbol slices to small line ranges before attempting a whole-file read. Supported source slices include Python, JavaScript/TypeScript, Go, and Rust.
 - **Declarative output filter** validates user-owned JSON filter files outside package code and applies the first matching line filter only as an explicit `run --config ... -- <command>` wrapper. Invalid configs, no-match commands, filter errors, empty filtered output, and protected `git`/test/lint/`gh` command failures preserve original stdout/stderr and exit code. Filtered mode applies line rules to combined stdout+stderr and writes the filtered result to stdout; `--json-report` diagnostics go to stderr, except protected nonzero passthrough suppresses reports to keep stderr raw. It is local and opt-in, with no savings guarantee.
 - **Artifact store** saves large sanitized command output under `.context-guard/artifacts` by default and returns compact receipts, local sandbox search results, or exact requested slices. JSON receipts include line-numbered top errors, duplicate-line groups, sanitized bounded suggested queries, and an `output_sandbox` envelope with a stable `contextguard-artifact:<id>` handle. `receipt <artifact_id> --json` rehydrates metadata-only handles without content. `search` scans sanitized local artifacts by literal substring, emits capped match/context records, and includes `get --lines START:END` rehydration commands without hosted token/cost savings claims. Custom `--dir` raw paths stay redacted by default; reuse the same `--dir` or opt into `search --show-paths` for a directly executable local command. In suggested `--lines START:END` queries, `--max-lines` is only the returned-line cap for that selected range, not a wider selector. `get`, `list`, and `search` can also read legacy `.claude-token-optimizer/artifacts` receipts.
-- **Budgeted context packer** assembles prioritized local file evidence into a rendered byte-budgeted Markdown pack with included/partial/omitted source metadata, bounded `.context-guard/packs` receipts, exact sanitized `slice` commands when safe, and `retrieval_omitted_reason` when a path/root should not be echoed. The additive `auto` subcommand runs that recommendation and pack build in one step, and `auto --explain` adds compact deterministic local selection/build reasons without changing the manifest, pack body, receipt, or byte budget. JSON explain also includes bounded repo-map metadata: sampled byte/token-proxy tree entries, category-only secret-risk counts, signature-first hints, explain-only graph ranks, and exact `slice`/symbol retrieval hints. `suggest` remains available to rank local query, diff, explicit file, and sanitized output/test-output signals into a build-compatible manifest without network, model, embedding, or provider-cost calls. `suggest/auto --adaptive-k` adds advisory-only shrink/expand top-k metadata from local score distribution, byte-budget fit, and clamped score-mass recall/precision proxies. `--adaptive-k-policy balanced|recall|precision` plus optional recall/precision proxy gates selects the local recommendation policy; gate failures are metadata-only. The adaptive block includes capped selected/omitted evidence and structured source-verification hints, and it never applies the recommendation automatically or changes the manifest, pack body, receipt, or byte budget. `auto --symbol-memory` adds repo-map-derived symbol/graph advisory metadata with exact `slice`/`read-symbol` verification hints and still does not change selection or pack output. Token counts are estimated `chars_div_4` proxies, not measured provider-token savings.
+- **Budgeted context packer** assembles prioritized local file evidence into a rendered byte-budgeted Markdown pack with included/partial/omitted source metadata, bounded `.context-guard/packs` receipts, exact sanitized `slice` commands when safe, and `retrieval_omitted_reason` when a path/root should not be echoed. The additive `auto` subcommand runs that recommendation and pack build in one step, and `auto --explain` adds compact deterministic local selection/build reasons without changing the manifest, pack body, receipt, or byte budget. JSON explain also includes bounded repo-map metadata: sampled byte/token-proxy tree entries, category-only secret-risk counts, signature-first hints, explain-only graph ranks, and exact `slice`/symbol retrieval hints. `suggest` remains available to rank local query, diff, explicit file, and sanitized output/test-output signals into a build-compatible manifest without network, model, embedding, or provider-cost calls. `suggest/auto --adaptive-k` adds advisory-only shrink/expand top-k metadata from local score distribution, byte-budget fit, and clamped score-mass recall/precision proxies. `--adaptive-k-policy balanced|recall|precision` plus optional recall/precision proxy gates selects the local recommendation policy; gate failures are metadata-only. The adaptive block includes capped selected/omitted evidence and structured source-verification hints, and it never applies the recommendation automatically or changes the manifest, pack body, receipt, or byte budget. `auto --symbol-memory` adds repo-map-derived symbol/graph advisory metadata with exact `slice`/`read-symbol` verification hints and still does not change selection or pack output. Explicit `auto --apply-symbol-memory` instead adds at most four safe direct import-neighbor slices, keeps explicit/query seeds at higher priority, excludes secret-risk neighbors, and rebuilds within the same byte budget while retaining exact fallback and a closed `graph_application` record. Token counts are estimated `chars_div_4` proxies, not measured provider-token savings.
 - **Tool/MCP schema pruner** ranks local tool catalogs into bounded top-k advisory reports while preserving full sanitized schema fallback through compact receipts and payload integrity checks. `defer-report` additionally separates core inline tools from deferred stubs/namespaces and reports gross deferred-schema plus net initial-report char/4 proxy accounting; full schemas still must be retrieved before deferred tool use.
+- **Applied adaptive breadth** is available only through explicit `auto --apply-adaptive-k`. It prunes heuristic-selected sources after local regression gates pass, always retains caller-declared file/output/test-output and diff sources, rebuilds within the same byte budget, and records `adaptive_k_application`; local proxies do not authorize provider-token or cost-savings claims.
 - **Conservative compressor** classifies sanitized stdin as JSON, diff, log, search output, code, or prose and shrinks it with observed byte evidence plus estimated token proxies. Add `--protected-policy` for opt-in protected-zone class/count metadata that denies semantic rewrites for code fences, diffs, identifiers, numeric constants, hashes, paths, stack frames, quoted strings, and JSON keys while preserving exact-retrieval guidance. Add `--mode readable` only for sanitized prose previews: it uses deterministic sentence windows, blocks prompt-like/high-risk protected signals, stores no raw protected spans, and does not run learned compressors, models, embeddings, or rerankers.
 - **Static cache-score lint plus Anthropic cost guard and route advisor** provides `context-guard-cache-score` for local prompt/request cache layout checks, with optional user-supplied cache write/read multiplier amortization risk, and `context-guard cost preflight/observe/ledger/compile` for passive pre-call estimates, provider-usage reconciliation, keyed-HMAC cache-risk history, and stable-prefix layout advice. `context-guard route-advisor` is a local-only passive advisor for caller-supplied workload JSON, provider feature declarations, usage telemetry, and shifted external/local costs; it emits total-cost accounting, batchability blockers, and route candidates without starting a queue, calling providers, refreshing pricing docs, or treating provider feature knowledge as authoritative. It stores no raw prompt text, does not replace Anthropic/provider prompt caching, and its recommendations are not hosted token/cost savings claims without matched successful tasks, non-inferior quality evidence, and shifted-cost accounting.
 - **Output trimmer** preserves the wrapped command exit code, trims long logs, and can emit `--digest markdown` or `--digest json` summaries with runner failure facts, sanitized failure signatures, duplicate-line groups, and suggested next queries. Add `--artifact-receipt` with digest mode to store the exact sanitized full output as a local artifact receipt; keep the `contextguard-artifact:<id>` handle and re-expand omitted slices with emitted `context-guard-artifact receipt/get/search ...` commands.
@@ -196,6 +208,19 @@ Cross-agent rule snippets are advisory: the target agent may ignore them, so mea
 
 `context-guard mcp` and `context-guard-mcp` launch a dependency-free local stdio MCP child process. A process is isolated to one root and namespace and exposes only sanitized compression, sanitized exact artifact fallback, and local statistics. It has no HTTP, network, provider, model, or proxy integration and never mutates client configuration. Artifacts are inaccessible across namespaces; no hosted token/cost savings are claimed.
 
+The installed Receipt companion can also be launched explicitly as
+`context-guard-receipt-mcp --root /absolute/repository`. Its
+`receipt_context` tool stores one explicitly eligible relative file or log as a
+compact process-local exact reference when the conservative byte router finds
+that beneficial, reuses the live reference, and reads exact slices of at most
+65,536 bytes. Optional task scopes and explicit release provide process-local
+context GC; content-free history stores only keyed digests and decisions.
+`receipt_diagnose` exposes non-applying firewall/router and prefix-reuse
+scout/surgeon advice, while an explicit private `--state-dir` enables only the
+authenticated advisory `receipt_twin`. It does not auto-register, intercept
+prompts, persist capabilities across restart, call a provider, or make a hosted
+savings claim.
+
 ## Local test before publishing
 
 From the marketplace repository root: